@marimo-team/islands 0.25.3-dev18 → 0.25.3-dev181

package/src/core/ai/__tests__/staged-cells.test.ts

@@ -7,7 +7,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { cellId } from "@/__tests__/branded";
 import { CellId } from "@/core/cells/ids";
 import { getCellEditorView } from "../../cells/cells";
-import { updateEditorCodeFromPython } from "../../codemirror/language/utils";
+import { prepareCellCodeUpdate } from "../../codemirror/language/cell-code";
 import {
   stagedAICellsAtom,
   stagedGenerationInProgressAtom,
@@ -21,7 +21,7 @@ const { stagedGenerationAtom, createActions, reducer, initialState } =
   visibleForTesting;
 
 // Mock the dependencies
-const mockCreateNewCell = vi.fn();
+const mockCreateCell = vi.fn();
 const mockUpdateCellCode = vi.fn();
 const mockDeleteCellCallback = vi.fn();
 
@@ -34,14 +34,16 @@ const mockCellHandle = {
   },
 };
 
+vi.mock("../../cells/actions", () => ({
+  useCellActions: () => ({
+    createCell: mockCreateCell,
+    updateCellCode: mockUpdateCellCode,
+  }),
+}));
 vi.mock("../../cells/cells", async () => {
   const { atom } = await import("jotai");
   return {
     notebookAtom: atom({ cellData: {}, cellIds: { inOrderIds: [] } }),
-    useCellActions: () => ({
-      createNewCell: mockCreateNewCell,
-      updateCellCode: mockUpdateCellCode,
-    }),
     cellHandleAtom: vi.fn(() => ({
       read: vi.fn(() => mockCellHandle),
     })),
@@ -57,8 +59,8 @@ vi.mock("@/core/network/requests", () => ({
   getRequestClient: () => ({ sendRun: vi.fn() }),
 }));
 
-vi.mock("../../codemirror/language/utils", () => ({
-  updateEditorCodeFromPython: vi.fn(),
+vi.mock("../../codemirror/language/cell-code", () => ({
+  prepareCellCodeUpdate: vi.fn(() => ({ effects: [] })),
 }));
 
 // Mock CellId.create
@@ -261,11 +263,9 @@ describe("staged-cells", () => {
       const returnedCellId = result.current.createStagedCell(testCode);
 
       expect(returnedCellId).toBe(mockCellId);
-      expect(mockCreateNewCell).toHaveBeenCalledWith({
-        cellId: "__end__",
+      expect(mockCreateCell).toHaveBeenCalledWith({
         code: testCode,
-        before: false,
-        newCellId: mockCellId,
+        id: mockCellId,
       });
     });
 
@@ -330,7 +330,7 @@ describe("staged-cells", () => {
 
       // Verify it was created and added
       expect(createdCellId).toBe(mockCellId);
-      expect(mockCreateNewCell).toHaveBeenCalled();
+      expect(mockCreateCell).toHaveBeenCalled();
 
       let state = store.get(stagedAICellsAtom);
       expect(state.has(mockCellId)).toBe(true);
@@ -401,8 +401,8 @@ describe("staged cell generation", () => {
     result.current.beginStagedCellGeneration();
 
     // No cell or cell update should have been called
-    expect(mockCreateNewCell).not.toHaveBeenCalled();
-    expect(updateEditorCodeFromPython).not.toHaveBeenCalled();
+    expect(mockCreateCell).not.toHaveBeenCalled();
+    expect(prepareCellCodeUpdate).not.toHaveBeenCalled();
     expect(store.get(stagedGenerationInProgressAtom)).toBe(true);
   });
 
@@ -610,11 +610,9 @@ describe("staged cell generation", () => {
       },
     });
 
-    expect(mockCreateNewCell).toHaveBeenCalledWith({
-      cellId: "__end__",
+    expect(mockCreateCell).toHaveBeenCalledWith({
       code: "print('```')",
-      before: false,
-      newCellId: "mock-cell-id",
+      id: "mock-cell-id",
     });
   });
 
@@ -636,16 +634,16 @@ describe("staged cell generation", () => {
       },
     });
 
-    expect(mockCreateNewCell).toHaveBeenCalledWith(
+    expect(mockCreateCell).toHaveBeenCalledWith(
       expect.objectContaining({
         code: "value = 1",
-        newCellId: "first-cell",
+        id: "first-cell",
       }),
     );
-    expect(mockCreateNewCell).toHaveBeenCalledWith(
+    expect(mockCreateCell).toHaveBeenCalledWith(
       expect.objectContaining({
         code: "value",
-        newCellId: "second-cell",
+        id: "second-cell",
       }),
     );
   });
@@ -683,10 +681,13 @@ describe("staged cell generation", () => {
       },
     });
 
-    expect(mockCreateNewCell).toHaveBeenCalledTimes(2);
+    expect(mockCreateCell).toHaveBeenCalledTimes(2);
     expect(store.get(stagedAICellsAtom).has(cellId("first-cell"))).toBe(true);
     expect(store.get(stagedAICellsAtom).has(cellId("second-cell"))).toBe(true);
-    expect(updateEditorCodeFromPython).toHaveBeenCalledTimes(2);
+    expect(prepareCellCodeUpdate).toHaveBeenCalledTimes(2);
+    expect(
+      mockCellHandle.current.editorViewOrNull.dispatch,
+    ).toHaveBeenCalledTimes(2);
   });
 
   it("should update notebook state when the cell editor is not mounted", () => {

package/src/core/ai/context/providers/datasource.ts

@@ -98,8 +98,12 @@ export class DatasourceContextProvider extends AIContextProvider<DatasourceConte
   public formatContext(item: DatasourceContextItem): string {
     const data = item.data;
     // Remove certain fields that are not needed in the context
-    const { name, display_name, source, ...filteredDatasource } =
-      data.connection;
+    const {
+      name,
+      display_name: _displayName,
+      source: _source,
+      ...filteredDatasource
+    } = data.connection;
 
     let datasource = filteredDatasource;
     const isInternalEngine = INTERNAL_SQL_ENGINES.has(name as ConnectionName);

package/src/core/ai/staged-cells.ts

@@ -14,12 +14,9 @@ import {
   notebookCellsCompletionSchema,
 } from "./completion-output";
 import { maybeAddMarimoImport } from "../cells/add-missing-import";
-import {
-  type CreateNewCellAction,
-  getCellEditorView,
-  useCellActions,
-} from "../cells/cells";
-import { updateEditorCodeFromPython } from "../codemirror/language/utils";
+import { getCellEditorView } from "../cells/cells";
+import { type CreateCell, useCellActions } from "../cells/actions";
+import { prepareCellCodeUpdate } from "../codemirror/language/cell-code";
 import type { JotaiStore } from "../state/jotai";
 import type { EditType } from "./tools/edit-notebook-tool";
 
@@ -98,18 +95,13 @@ interface UpdateStagedCellAction {
 /** Manage staged cells without assuming which AI workflow owns them. */
 export function useStagedCells(store: JotaiStore) {
   const { addStagedCell, removeStagedCell } = useStagedAICellsActions();
-  const { createNewCell, updateCellCode } = useCellActions();
+  const { updateCellCode, createCell } = useCellActions();
   const deleteCellCallback = useDeleteCellCallback();
 
   const createStagedCell = (code: string): CellId => {
     const newCellId = CellId.create();
     addStagedCell({ cellId: newCellId, edit: { type: "add_cell" } });
-    createNewCell({
-      cellId: "__end__",
-      code,
-      before: false,
-      newCellId: newCellId,
-    });
+    createCell({ code, id: newCellId });
     return newCellId;
   };
 
@@ -124,7 +116,12 @@ export function useStagedCells(store: JotaiStore) {
 
     const editorView = getCellEditorView(cellId);
     if (editorView) {
-      updateEditorCodeFromPython(editorView, code);
+      const update = prepareCellCodeUpdate(editorView.state, code, {
+        initialize: true,
+      });
+      if (update) {
+        editorView.dispatch(update);
+      }
     } else {
       updateCellCode({ cellId, code, formattingChange: false });
     }
@@ -147,7 +144,7 @@ export function useStagedCells(store: JotaiStore) {
 /** Owns the lifecycle of cells created by one structured completion flow. */
 export function useStagedCellGeneration(store: JotaiStore) {
   const stagedCellActions = useStagedCells(store);
-  const { createNewCell } = useCellActions();
+  const { createCell } = useCellActions();
   const ownedGeneration = useRef<OwnedStagedGeneration | null>(null);
   // Ownership lives in a ref, so subscribe to its backing atoms to rerender
   // consumers when completion or per-cell acceptance changes.
@@ -175,7 +172,7 @@ export function useStagedCellGeneration(store: JotaiStore) {
       status: "in_progress",
       reconciler: new StagedCellReconciler({
         ...stagedCellActions,
-        createNewCell,
+        createCell,
       }),
     };
     store.set(stagedGenerationAtom, {
@@ -297,7 +294,7 @@ interface StagedCellReconcilerActions {
   deleteStagedCell: (cellId: CellId) => void;
   removeStagedCell: (cellId: CellId) => void;
   addStagedCell: (payload: { cellId: CellId; edit: Edit }) => void;
-  createNewCell: (opts: CreateNewCellAction) => void;
+  createCell: CreateCell;
 }
 
 class StagedCellReconciler {
@@ -386,7 +383,7 @@ class StagedCellReconciler {
 
     const cellId = maybeAddMarimoImport({
       autoInstantiate: false,
-      createNewCell: this.actions.createNewCell,
+      createCell: this.actions.createCell,
       fromCellId: this.createdCells[0]?.cellId,
       before: true,
     });

package/src/core/ai/tools/__tests__/edit-notebook-tool.test.ts

@@ -8,7 +8,6 @@ import { MockNotebook } from "@/__mocks__/notebook";
 import { cellId } from "@/__tests__/branded";
 import { notebookAtom } from "@/core/cells/cells";
 import type { CellId } from "@/core/cells/ids";
-import { updateEditorCodeFromPython } from "@/core/codemirror/language/utils";
 import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
 import { MultiColumn } from "@/utils/id-tree";
 import { cellConfigExtension } from "../../../codemirror/config/extension";
@@ -22,11 +21,6 @@ vi.mock("@/components/editor/links/cell-link", () => ({
   scrollAndHighlightCell: vi.fn(),
 }));
 
-// Mock updateEditorCodeFromPython
-vi.mock("@/core/codemirror/language/utils", () => ({
-  updateEditorCodeFromPython: vi.fn(),
-}));
-
 function createMockEditorView(code: string): EditorView {
   return new EditorView({
     state: EditorState.create({
@@ -70,7 +64,7 @@ describe("EditNotebookTool", () => {
   let cellId3: CellId;
   let toolContext: {
     addStagedCell: ReturnType<typeof vi.fn>;
-    createNewCell: ReturnType<typeof vi.fn>;
+    createCell: ReturnType<typeof vi.fn>;
     prepareForRun: ReturnType<typeof vi.fn>;
     sendRun: ReturnType<typeof vi.fn>;
     store: ReturnType<typeof getDefaultStore>;
@@ -87,7 +81,7 @@ describe("EditNotebookTool", () => {
         const current = store.get(stagedAICellsAtom);
         store.set(stagedAICellsAtom, new Map(current).set(cellId, edit));
       }),
-      createNewCell: vi.fn(),
+      createCell: vi.fn(),
       prepareForRun: vi.fn(),
       sendRun: vi.fn().mockResolvedValue(null),
       store,
@@ -140,10 +134,7 @@ describe("EditNotebookTool", () => {
       );
 
       expect(result.status).toBe("success");
-      expect(vi.mocked(updateEditorCodeFromPython)).toHaveBeenCalledWith(
-        editorView,
-        newCode,
-      );
+      expect(editorView.state.doc.toString()).toBe(newCode);
 
       // Check that cell was staged
       const stagedCells = store.get(stagedAICellsAtom);
@@ -166,10 +157,7 @@ describe("EditNotebookTool", () => {
       );
 
       expect(result2.status).toBe("success");
-      expect(vi.mocked(updateEditorCodeFromPython)).toHaveBeenCalledWith(
-        editorView,
-        "x = 3",
-      );
+      expect(editorView.state.doc.toString()).toBe("x = 3");
 
       const stagedCells2 = store.get(stagedAICellsAtom);
       expect(stagedCells2.has(cellId1)).toBe(true);
@@ -206,7 +194,7 @@ describe("EditNotebookTool", () => {
 
       // Should NOT stage the cell or update the editor
       expect(toolContext.addStagedCell).not.toHaveBeenCalled();
-      expect(vi.mocked(updateEditorCodeFromPython)).not.toHaveBeenCalled();
+      expect(editorView.state.doc.toString()).toBe(code);
 
       // No staged cells
       const stagedCells = store.get(stagedAICellsAtom);

package/src/core/ai/tools/__tests__/run-cells-tool.test.ts

@@ -29,7 +29,7 @@ describe("RunStaleCellsTool", () => {
   let cellId3: CellId;
   let toolContext: {
     addStagedCell: ReturnType<typeof vi.fn>;
-    createNewCell: ReturnType<typeof vi.fn>;
+    createCell: ReturnType<typeof vi.fn>;
     prepareForRun: ReturnType<typeof vi.fn>;
     sendRun: ReturnType<typeof vi.fn>;
     store: ReturnType<typeof getDefaultStore>;
@@ -39,7 +39,7 @@ describe("RunStaleCellsTool", () => {
     store = getDefaultStore();
     toolContext = {
       addStagedCell: vi.fn(),
-      createNewCell: vi.fn(),
+      createCell: vi.fn(),
       prepareForRun: vi.fn(),
       sendRun: vi.fn().mockResolvedValue(null),
       store,

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

@@ -1,7 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { z } from "zod";
-import type { CreateNewCellAction } from "@/core/cells/cells";
+import type { CreateCell } from "@/core/cells/actions";
 import type { CellId } from "@/core/cells/ids";
 import type { ExecuteCellsRequest } from "@/core/network/types";
 import type { JotaiStore } from "@/core/state/jotai";
@@ -20,9 +20,11 @@ export type StatusValue = "success" | "error" | "warning";
  * @example
  * throw new ToolExecutionError(
  *   "Failed to fetch data",
- *   "FETCH_ERROR",
- *   true,
- *   "Check your network connection"
+ *   {
+ *     code: "FETCH_ERROR",
+ *     isRetryable: true,
+ *     suggestedFix: "Check your network connection",
+ *   }
  * );
  */
 export class ToolExecutionError extends Error {
@@ -33,10 +35,17 @@ export class ToolExecutionError extends Error {
 
   public constructor(
     message: string,
-    code = "TOOL_ERROR",
-    isRetryable = false,
-    suggestedFix?: string,
-    meta?: Record<string, unknown>,
+    {
+      code = "TOOL_ERROR",
+      isRetryable = false,
+      suggestedFix,
+      meta,
+    }: {
+      code?: string;
+      isRetryable?: boolean;
+      suggestedFix?: string;
+      meta?: Record<string, unknown>;
+    } = {},
   ) {
     super(message);
     this.name = "ToolExecutionError";
@@ -104,7 +113,7 @@ export interface ToolDescription {
 export interface ToolNotebookContext {
   store: JotaiStore;
   addStagedCell: (payload: { cellId: CellId; edit: Edit }) => void;
-  createNewCell: (payload: CreateNewCellAction) => void;
+  createCell: CreateCell;
   prepareForRun: (payload: { cellId: CellId }) => void;
   sendRun: (request: ExecuteCellsRequest) => Promise<null>;
 }

package/src/core/ai/tools/edit-notebook-tool.ts

@@ -3,13 +3,10 @@
 import type { EditorView } from "@codemirror/view";
 import { z } from "zod";
 import { scrollAndHighlightCell } from "@/components/editor/links/cell-link";
-import {
-  type CellPosition as NotebookCellPosition,
-  type NotebookState,
-  notebookAtom,
-} from "@/core/cells/cells";
+import { type NotebookState, notebookAtom } from "@/core/cells/cells";
+import type { CreateCellOptions } from "@/core/cells/actions";
 import { CellId } from "@/core/cells/ids";
-import { updateEditorCodeFromPython } from "@/core/codemirror/language/utils";
+import { prepareCellCodeUpdate } from "@/core/codemirror/language/cell-code";
 import type { CellColumnId } from "@/utils/id-tree";
 import { stagedAICellsAtom } from "../staged-cells";
 import {
@@ -86,7 +83,7 @@ export class EditNotebookTool implements AiTool<
     { edit }: EditNotebookInput,
     toolContext: ToolNotebookContext,
   ): Promise<ToolOutputBase> => {
-    const { addStagedCell, createNewCell, store } = toolContext;
+    const { addStagedCell, createCell, store } = toolContext;
 
     switch (edit.type) {
       case "update_cell": {
@@ -94,19 +91,17 @@ export class EditNotebookTool implements AiTool<
         const cellId = position.cellId as CellId | undefined;
 
         if (!cellId) {
-          throw new ToolExecutionError(
-            "Cell ID is required for update_cell",
-            "CELL_ID_REQUIRED_FOR_UPDATE_CELL",
-            true,
-            "Provide a cell ID to update",
-          );
+          throw new ToolExecutionError("Cell ID is required for update_cell", {
+            code: "CELL_ID_REQUIRED_FOR_UPDATE_CELL",
+            isRetryable: true,
+            suggestedFix: "Provide a cell ID to update",
+          });
         } else if (!code) {
-          throw new ToolExecutionError(
-            "Code is required for update_cell",
-            "CODE_REQUIRED_FOR_UPDATE_CELL",
-            true,
-            "Provide the new code to update the cell",
-          );
+          throw new ToolExecutionError("Code is required for update_cell", {
+            code: "CODE_REQUIRED_FOR_UPDATE_CELL",
+            isRetryable: true,
+            suggestedFix: "Provide the new code to update the cell",
+          });
         }
 
         const notebook = store.get(notebookAtom);
@@ -119,7 +114,12 @@ export class EditNotebookTool implements AiTool<
 
         // If previous edit was from a new cell, just replace editor code with the new code
         if (existingStagedCell?.type === "add_cell") {
-          updateEditorCodeFromPython(editorView, code);
+          const update = prepareCellCodeUpdate(editorView.state, code, {
+            initialize: true,
+          });
+          if (update) {
+            editorView.dispatch(update);
+          }
           break;
         }
 
@@ -139,15 +139,20 @@ export class EditNotebookTool implements AiTool<
           edit: { type: "update_cell", previousCode: previousCode },
         });
 
-        updateEditorCodeFromPython(editorView, code);
+        const update = prepareCellCodeUpdate(editorView.state, code, {
+          initialize: true,
+        });
+
+        if (update) {
+          editorView.dispatch(update);
+        }
 
         break;
       }
       case "add_cell": {
         const { position, code } = edit;
 
-        let notebookPosition: NotebookCellPosition = "__end__";
-        let before = false;
+        let placement: CreateCellOptions = {};
         const newCellId = CellId.create();
         const notebook = store.get(notebookAtom);
 
@@ -157,51 +162,54 @@ export class EditNotebookTool implements AiTool<
             if (!cellId) {
               throw new ToolExecutionError(
                 "Cell ID is required for add_cell with relative position",
-                "TOOL_ERROR",
-                true,
-                "Provide a cell ID to add the cell before",
+                {
+                  code: "TOOL_ERROR",
+                  isRetryable: true,
+                  suggestedFix: "Provide a cell ID to add the cell before",
+                },
               );
             }
 
             if (position.before === undefined) {
               throw new ToolExecutionError(
                 "Before is required for add_cell with relative position",
-                "TOOL_ERROR",
-                true,
-                `Provide a boolean value for before, true to add before cell ${cellId}, false to add after the cell`,
+                {
+                  code: "TOOL_ERROR",
+                  isRetryable: true,
+                  suggestedFix: `Provide a boolean value for before, true to add before cell ${cellId}, false to add after the cell`,
+                },
               );
             }
 
             this.validateCellIdExists(cellId, notebook);
-            notebookPosition = cellId;
-            before = position.before;
+            placement = position.before
+              ? { before: cellId }
+              : { after: cellId };
             break;
           }
-          case "column_end": {
+          case "column_end":
             if (!position.columnIndex) {
               throw new ToolExecutionError(
                 "Column index is required for add_cell with column_end position",
-                "TOOL_ERROR",
-                true,
-                "Provide a column index to add the cell at the end of",
+                {
+                  code: "TOOL_ERROR",
+                  isRetryable: true,
+                  suggestedFix:
+                    "Provide a column index to add the cell at the end of",
+                },
               );
             }
 
-            const columnId = this.getColumnId(position.columnIndex, notebook);
-            notebookPosition = { type: "__end__", columnId };
+            placement = {
+              endOf: this.getColumnId(position.columnIndex, notebook),
+            };
             break;
-          }
+
           case "notebook_end":
-            // Use default: notebookPosition = "__end__"
             break;
         }
 
-        createNewCell({
-          cellId: notebookPosition,
-          before,
-          code,
-          newCellId,
-        });
+        createCell({ ...placement, code, id: newCellId });
 
         addStagedCell({
           cellId: newCellId,
@@ -218,12 +226,11 @@ export class EditNotebookTool implements AiTool<
         const cellId = position.cellId as CellId | undefined;
 
         if (!cellId) {
-          throw new ToolExecutionError(
-            "Cell ID is required for delete_cell",
-            "CELL_ID_REQUIRED_FOR_DELETE_CELL",
-            true,
-            "Provide a cell ID to delete",
-          );
+          throw new ToolExecutionError("Cell ID is required for delete_cell", {
+            code: "CELL_ID_REQUIRED_FOR_DELETE_CELL",
+            isRetryable: true,
+            suggestedFix: "Provide a cell ID to delete",
+          });
         }
 
         const notebook = store.get(notebookAtom);
@@ -255,12 +262,11 @@ export class EditNotebookTool implements AiTool<
   private validateCellIdExists(cellId: CellId, notebook: NotebookState) {
     const cellIds = notebook.cellIds;
     if (!cellIds.getColumns().some((column) => column.idSet.has(cellId))) {
-      throw new ToolExecutionError(
-        "Cell not found",
-        "CELL_NOT_FOUND",
-        false,
-        "Check which cells exist in the notebook",
-      );
+      throw new ToolExecutionError("Cell not found", {
+        code: "CELL_NOT_FOUND",
+        isRetryable: false,
+        suggestedFix: "Check which cells exist in the notebook",
+      });
     }
   }
 
@@ -272,12 +278,12 @@ export class EditNotebookTool implements AiTool<
     const columns = cellIds.getColumns();
 
     if (columnIndex < 0 || columnIndex >= columns.length) {
-      throw new ToolExecutionError(
-        "Column index is out of range",
-        "COLUMN_INDEX_OUT_OF_RANGE",
-        true,
-        "Choose a column index between 0 and the number of columns in the notebook (0-based)",
-      );
+      throw new ToolExecutionError("Column index is out of range", {
+        code: "COLUMN_INDEX_OUT_OF_RANGE",
+        isRetryable: true,
+        suggestedFix:
+          "Choose a column index between 0 and the number of columns in the notebook (0-based)",
+      });
     }
     return columns[columnIndex].id;
   }
@@ -289,12 +295,11 @@ export class EditNotebookTool implements AiTool<
     const cellHandles = notebook.cellHandles;
     const cellHandle = cellHandles[cellId].current;
     if (!cellHandle?.editorView) {
-      throw new ToolExecutionError(
-        "Cell editor not found",
-        "CELL_EDITOR_NOT_FOUND",
-        false,
-        "Internal error, ask the user to report this error",
-      );
+      throw new ToolExecutionError("Cell editor not found", {
+        code: "CELL_EDITOR_NOT_FOUND",
+        isRetryable: false,
+        suggestedFix: "Internal error, ask the user to report this error",
+      });
     }
     return cellHandle.editorView;
   }

package/src/core/ai/tools/registry.ts

@@ -73,9 +73,11 @@ export class FrontendToolRegistry {
         const strError = z.prettifyError(inputResponse.error);
         throw new ToolExecutionError(
           `Tool ${toolName} returned invalid input: ${strError}`,
-          "INVALID_ARGUMENTS",
-          true,
-          "Please check the arguments and try again.",
+          {
+            code: "INVALID_ARGUMENTS",
+            isRetryable: true,
+            suggestedFix: "Please check the arguments and try again.",
+          },
         );
       }
       const args = inputResponse.data;
@@ -110,12 +112,15 @@ export class FrontendToolRegistry {
       // 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,
+          code: "TOOL_ERROR",
+          isRetryable: false,
+          suggestedFix:
+            "Check the error message and try again with valid arguments.",
+          meta: {
+            args: rawArgs,
+            errorType: error?.constructor?.name ?? typeof error,
+          },
         },
       );
       return {

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

@@ -50,13 +50,12 @@ export class TestFrontendTool implements AiTool<Input, Output> {
   public 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 },
-      );
+      throw new ToolExecutionError("Name cannot be empty", {
+        code: "INVALID_INPUT",
+        isRetryable: false,
+        suggestedFix: "Please provide a non-empty name",
+        meta: { field: "name", received: name },
+      });
     }
 
     return {