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 structured errors to frontend tools (#6748)
Joaquin Coromina47699a9739de
diff --git a/frontend/src/components/chat/chat-utils.ts b/frontend/src/components/chat/chat-utils.tsindex 4f26519602..b758a663cf 100644--- a/frontend/src/components/chat/chat-utils.ts+++ b/frontend/src/components/chat/chat-utils.ts@@ -127,7 +127,7 @@ export async function handleToolCall({addToolResult({tool: toolCall.toolName,toolCallId: toolCall.toolCallId,- output: response,+ output: response.result || response.error,});} else {// Invoke the backend/mcp tooldiff --git a/frontend/src/core/ai/tools/__tests__/registry.test.ts b/frontend/src/core/ai/tools/__tests__/registry.test.tsindex 1b4e19f6d9..e5fa2af4d2 100644--- a/frontend/src/core/ai/tools/__tests__/registry.test.ts+++ b/frontend/src/core/ai/tools/__tests__/registry.test.ts@@ -13,11 +13,16 @@ describe("FrontendToolRegistry", () => {it("invokes a tool with valid args and validates input/output", async () => {const registry = new FrontendToolRegistry([new TestFrontendTool()]);- const result = await registry.invoke("test_frontend_tool", {+ const response = await registry.invoke("test_frontend_tool", {name: "Alice",});- expect(result).toMatchObject({+ // Check InvokeResult wrapper+ expect(response.tool_name).toBe("test_frontend_tool");+ expect(response.error).toBeNull();++ // Check the actual tool output+ expect(response.result).toMatchObject({status: "success",data: {greeting: "Hello: Alice",@@ -26,19 +31,25 @@ describe("FrontendToolRegistry", () => {});// Verify timestamp is present and valid- const output = result as { data: { timestamp: string } };+ const output = response.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 () => {const registry = new FrontendToolRegistry([new TestFrontendTool()]);- const err = (await registry.invoke("test_frontend_tool", {})) as Record<- string,- unknown- >;- expect(err.status).toBe("error");- expect(err.code).toBe("TOOL_ERROR");+ const response = await registry.invoke("test_frontend_tool", {});++ // Check InvokeResult wrapper+ expect(response.tool_name).toBe("test_frontend_tool");+ expect(response.result).toBeNull();+ expect(response.error).toBeDefined();+ expect(typeof response.error).toBe("string");++ // Verify error message contains expected prefix+ expect(response.error).toContain("Error invoking tool ToolExecutionError:");+ expect(response.error).toContain('"code":"TOOL_ERROR"');+ expect(response.error).toContain('"is_retryable":false');});it("returns tool schemas with expected shape and memoizes the result", () => {diff --git a/frontend/src/core/ai/tools/base.ts b/frontend/src/core/ai/tools/base.tsindex a33600d92e..e81b1b9802 100644--- a/frontend/src/core/ai/tools/base.ts+++ b/frontend/src/core/ai/tools/base.ts@@ -8,6 +8,51 @@ import type { CopilotMode } from "./registry";*/export type StatusValue = "success" | "error" | "warning";+/**+ * Structured error for tool execution failures.+ * Mirrors the ToolExecutionError dataclass from marimo/_ai/_tools/utils/exceptions.py+ *+ * @example+ * throw new ToolExecutionError(+ * "Failed to fetch data",+ * "FETCH_ERROR",+ * true,+ * "Check your network connection"+ * );+ */+export class ToolExecutionError extends Error {+ readonly code: string;+ readonly isRetryable: boolean;+ readonly suggestedFix?: string;+ readonly meta?: Record<string, unknown>;++ constructor(+ message: string,+ code = "TOOL_ERROR",+ isRetryable = false,+ suggestedFix?: string,+ meta?: Record<string, unknown>,+ ) {+ super(message);+ this.name = "ToolExecutionError";+ this.code = code;+ this.isRetryable = isRetryable;+ this.suggestedFix = suggestedFix;+ this.meta = meta;+ }++ toStructuredString(): string {+ const stringError = JSON.stringify({+ message: this.message,+ code: this.code,+ is_retryable: this.isRetryable,+ suggested_fix: this.suggestedFix,+ meta: this.meta ?? {},+ });+ return `Error invoking tool ${this.name}: ${stringError}`;+ }+}+/*** Base interface for tool output responses.* Mirrors the SuccessResult dataclass from marimo/_ai/_tools/types.pydiff --git a/frontend/src/core/ai/tools/registry.ts b/frontend/src/core/ai/tools/registry.tsindex 38dee1137d..8897b6051f 100644--- a/frontend/src/core/ai/tools/registry.ts+++ b/frontend/src/core/ai/tools/registry.ts@@ -3,7 +3,7 @@import type { components } from "@marimo-team/marimo-api";import { Memoize } from "typescript-memoize";import { type ZodObject, z } from "zod";-import type { AiTool } from "./base";+import { type AiTool, ToolExecutionError } from "./base";import { TestFrontendTool } from "./sample-tool";export type AnyZodObject = ZodObject<z.ZodRawShape>;@@ -11,6 +11,12 @@ export type AnyZodObject = ZodObject<z.ZodRawShape>;// eslint-disable-next-line @typescript-eslint/no-explicit-anytype StoredTool = AiTool<any, any>;+interface InvokeResult<TName> {+ tool_name: TName;+ result: unknown;+ error: string | null;+}+/** should be the same as marimo/_config/config.py > CopilotMode */type ToolDefinition = components["schemas"]["ToolDefinition"];@@ -43,7 +49,7 @@ export class FrontendToolRegistry {async invoke<TName extends string>(toolName: TName,rawArgs: unknown,- ): Promise<unknown> {+ ): Promise<InvokeResult<TName>> {const tool = this.getToolOrThrow(toolName);const handler = tool.handler;const inputSchema = tool.schema;@@ -69,17 +75,37 @@ export class FrontendToolRegistry {`Tool ${toolName} returned invalid output: ${strError}`,);}- const output = response.data;- return output;- } catch (error) {+ const result = response.data;return {- status: "error",- code: "TOOL_ERROR",- message: error instanceof Error ? error.message : String(error),- suggestedFix: "Try again with valid arguments.",- meta: {+ tool_name: toolName,+ result,+ error: null,+ };+ } catch (error) {+ // Handle structured errors+ if (error instanceof ToolExecutionError) {+ return {+ tool_name: toolName,+ result: null,+ error: error.toStructuredString(),+ };+ }++ // Handle unknown/generic errors+ const genericError = new ToolExecutionError(+ error instanceof Error ? error.message : String(error),+ "TOOL_ERROR",+ false,+ "Check the error message and try again with valid arguments.",+ {args: rawArgs,+ errorType: error?.constructor?.name ?? typeof error,},+ );+ return {+ tool_name: toolName,+ result: null,+ error: genericError.toStructuredString(),};}}diff --git a/frontend/src/core/ai/tools/sample-tool.ts b/frontend/src/core/ai/tools/sample-tool.tsindex bf8ab82630..8e1f93a52e 100644--- a/frontend/src/core/ai/tools/sample-tool.ts+++ b/frontend/src/core/ai/tools/sample-tool.ts@@ -1,7 +1,12 @@/* Copyright 2024 Marimo. All rights reserved. */import { z } from "zod";-import { type AiTool, type ToolOutputBase, toolOutputBaseSchema } from "./base";+import {+ type AiTool,+ ToolExecutionError,+ type ToolOutputBase,+ toolOutputBaseSchema,+} from "./base";import type { CopilotMode } from "./registry";const description = `@@ -41,6 +46,17 @@ export class TestFrontendTool implements AiTool<Input, Output> {readonly mode: CopilotMode[] = ["ask"];async handler({ name }: Input): Promise<Output> {+ // Example: Validate input and throw ToolExecutionError on invalid data+ if (!name.trim()) {+ throw new ToolExecutionError(+ "Name cannot be empty",+ "INVALID_INPUT",+ false,+ "Please provide a non-empty name",+ { field: "name", received: name },+ );+ }+return {status: "success",data: {