improvement: add detailed output metadata to frontend tools (#6720)

## 📝 Summary

<!--
Provide a concise summary of what this pull request is addressing.

If this PR fixes any issues, list them here by number (e.g., Fixes
#123).
-->
This adds detailed output to the frontend tools framework mirroring the
output structure of tools in the backend.

## 🔍 Description of Changes

<!--
Detail the specific changes made in this pull request. Explain the
problem addressed and how it was resolved. If applicable, provide before
and after comparisons, screenshots, or any relevant details to help
reviewers understand the changes easily.
-->
- Introduces ToolOutputBase interface and schema to align frontend tools
with the backend's SuccessResult pattern from
marimo/_ai/_tools/types.py.
- Updates sample-tool to use this structure
- Updates tests to use this structure so they won't break

## 📋 Checklist

- [x] I have read the [contributor
guidelines](https://github.com/marimo-team/marimo/blob/main/CONTRIBUTING.md).
- [ ] For large changes, or changes that affect the public API: this
change was discussed or approved through an issue, on
[Discord](https://marimo.io/discord?ref=pr), or the community
[discussions](https://github.com/marimo-team/marimo/discussions) (Please
provide a link if applicable).
- [x] I have added tests for the changes made.
- [x] I have run the code and verified that it works as expected.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: bjoaquinc

frontend/src/core/ai/tools/__tests__/registry.test.ts

@@ -13,8 +13,22 @@ describe("FrontendToolRegistry", () => {
 
   it("invokes a tool with valid args and validates input/output", async () => {
     const registry = new FrontendToolRegistry([new TestFrontendTool()]);
-    const ok = await registry.invoke("test_frontend_tool", { name: "Alice" });
-    expect(ok).toEqual({ message: "Hello: Alice" });
+    const result = await registry.invoke("test_frontend_tool", {
+      name: "Alice",
+    });
+
+    expect(result).toMatchObject({
+      status: "success",
+      data: {
+        greeting: "Hello: Alice",
+      },
+      next_steps: expect.arrayContaining([expect.any(String)]),
+    });
+
+    // Verify timestamp is present and valid
+    const output = result as { data: { timestamp: string } };
+    expect(output.data.timestamp).toBeDefined();
+    expect(typeof output.data.timestamp).toBe("string");
   });
 
   it("returns a structured error on invalid args", async () => {

frontend/src/core/ai/tools/base.ts

@@ -1,8 +1,43 @@
 /* Copyright 2024 Marimo. All rights reserved. */
 
-import type { z } from "zod";
+import { z } from "zod";
 import type { CopilotMode } from "./registry";
 
+/**
+ * Status value for tool responses, mirroring status value in marimo/_ai/_tools/types.py
+ */
+export type StatusValue = "success" | "error" | "warning";
+
+/**
+ * Base interface for tool output responses.
+ * Mirrors the SuccessResult dataclass from marimo/_ai/_tools/types.py
+ *
+ * Tool outputs should extend this interface to include standardized
+ * metadata like next_steps, messages, and status information.
+ */
+export interface ToolOutputBase {
+  status?: StatusValue;
+  auth_required?: boolean;
+  next_steps?: string[];
+  action_url?: string;
+  message?: string;
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Base Zod schema for tool outputs.
+ *
+ * Tool output schemas should extend this using .extend() to add their specific fields.
+ */
+export const toolOutputBaseSchema = z.object({
+  status: z.enum(["success", "error", "warning"]).optional(),
+  auth_required: z.boolean().optional(),
+  next_steps: z.array(z.string()).optional(),
+  action_url: z.string().optional(),
+  message: z.string().optional(),
+  meta: z.record(z.string(), z.unknown()).optional(),
+});
+
 /**
  * Contract for a frontend tool.
  *

frontend/src/core/ai/tools/sample-tool.ts

@@ -1,7 +1,7 @@
 /* Copyright 2024 Marimo. All rights reserved. */
 
 import { z } from "zod";
-import type { AiTool } from "./base";
+import { type AiTool, type ToolOutputBase, toolOutputBaseSchema } from "./base";
 import type { CopilotMode } from "./registry";
 
 const description = `
@@ -11,26 +11,46 @@ Args:
 - name (string): The name to include in the greeting.
 
 Returns:
-- { message: string } — The greeting message, e.g., "Hello: Alice".
+- Output with data containing the greeting message.
 `;
 
 interface Input {
   name: string;
 }
 
-interface Output {
-  message: string;
+interface GreetingData {
+  greeting: string;
+  timestamp: string;
 }
 
-/** A sample frontend tool that returns "hello world" */
+interface Output extends ToolOutputBase {
+  data: GreetingData;
+}
+
+/** A sample frontend tool that demonstrates real tool output structure */
 export class TestFrontendTool implements AiTool<Input, Output> {
   readonly name = "test_frontend_tool";
   readonly description = description;
   readonly schema = z.object({ name: z.string() });
-  readonly outputSchema = z.object({ message: z.string() });
+  readonly outputSchema = toolOutputBaseSchema.extend({
+    data: z.object({
+      greeting: z.string(),
+      timestamp: z.string(),
+    }),
+  });
   readonly mode: CopilotMode[] = ["ask"];
 
-  async handler({ name }: Input) {
-    return { message: `Hello: ${name}` };
+  async handler({ name }: Input): Promise<Output> {
+    return {
+      status: "success",
+      data: {
+        greeting: `Hello: ${name}`,
+        timestamp: new Date().toISOString(),
+      },
+      next_steps: [
+        "You can now proceed with your next task",
+        "Try calling another tool if needed",
+      ],
+    };
   }
 }