A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
improvement: add detailed output metadata to frontend tools (#6720)
Joaquin Corominaad3ae41485d2
diff --git a/frontend/src/core/ai/tools/__tests__/registry.test.ts b/frontend/src/core/ai/tools/__tests__/registry.test.tsindex 8604724235..1b4e19f6d9 100644--- a/frontend/src/core/ai/tools/__tests__/registry.test.ts+++ b/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 () => {diff --git a/frontend/src/core/ai/tools/base.ts b/frontend/src/core/ai/tools/base.tsindex 0e2c4c366f..a33600d92e 100644--- a/frontend/src/core/ai/tools/base.ts+++ b/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.*diff --git a/frontend/src/core/ai/tools/sample-tool.ts b/frontend/src/core/ai/tools/sample-tool.tsindex 454ff3f7d2..bf8ab82630 100644--- a/frontend/src/core/ai/tools/sample-tool.ts+++ b/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",+ ],+ };}}