Skip to content

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.

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.ts
index 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 tool
diff --git a/frontend/src/core/ai/tools/__tests__/registry.test.ts b/frontend/src/core/ai/tools/__tests__/registry.test.ts
index 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.ts
index 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.py
diff --git a/frontend/src/core/ai/tools/registry.ts b/frontend/src/core/ai/tools/registry.ts
index 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-any
type 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.ts
index 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: {