@marimo-team/islands 0.25.3-dev141 → 0.25.3-dev143

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 {

package/src/core/attachments/__tests__/toast.test.tsx

@@ -0,0 +1,58 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+// @vitest-environment jsdom
+
+import { act, render, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Toaster } from "@/components/ui/toaster";
+import { clearToasts, toast, useToast } from "@/components/ui/use-toast";
+import { agentToast } from "../toast";
+
+describe("agent notifications", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    clearToasts();
+  });
+
+  afterEach(() => {
+    act(() => {
+      clearToasts();
+      vi.runOnlyPendingTimers();
+    });
+    vi.useRealTimers();
+  });
+
+  it.each([
+    { variant: undefined, duration: 3000 },
+    { variant: "danger" as const, duration: 5000 },
+  ])("expires while the window is blurred: %j", ({ variant, duration }) => {
+    const { result } = renderHook(useToast);
+    render(<Toaster />);
+    act(() => agentToast({ title: "Agent notice", variant }));
+    act(() => window.dispatchEvent(new Event("blur")));
+    act(() => vi.advanceTimersByTime(duration - 1));
+    expect(result.current.toasts[0].open).toBe(true);
+    act(() => vi.advanceTimersByTime(1));
+    expect(result.current.toasts[0].open).toBe(false);
+  });
+
+  it("preserves pause behavior for ordinary notifications", () => {
+    const { result } = renderHook(useToast);
+    render(<Toaster />);
+    act(() => toast({ title: "Ordinary notice", duration: 3000 }));
+    act(() => window.dispatchEvent(new Event("blur")));
+    act(() => vi.advanceTimersByTime(5000));
+    expect(result.current.toasts[0].open).toBe(true);
+  });
+
+  it("does not let an older timer dismiss a newer notification", () => {
+    const { result } = renderHook(useToast);
+    act(() => agentToast({ title: "First" }));
+    act(() => vi.advanceTimersByTime(1000));
+    act(() => agentToast({ title: "Second" }));
+    act(() => vi.advanceTimersByTime(2000));
+    expect(result.current.toasts[0].title).toBe("Second");
+    expect(result.current.toasts[0].open).toBe(true);
+    act(() => vi.advanceTimersByTime(1000));
+    expect(result.current.toasts[0].open).toBe(false);
+  });
+});

package/src/core/attachments/state.ts

@@ -0,0 +1,18 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom } from "jotai";
+import type { Attachment } from "@marimo-team/client/protocol";
+import { notebookReplicaAtom } from "@/core/websocket/state";
+
+export type { Attachment } from "@marimo-team/client/protocol";
+
+export const agentAttachmentsAtom = atom((get) => {
+  const notebook = get(notebookReplicaAtom);
+  return (notebook ? get(notebook.attachmentsAtom) : []).filter(
+    (attachment) => attachment.kind === "agent",
+  );
+});
+
+export function attachmentLabel(attachment: Attachment): string {
+  return attachment.name || "Agent";
+}

package/src/core/attachments/toast.ts

@@ -0,0 +1,15 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { toast } from "@/components/ui/use-toast";
+
+export function agentToast(
+  options: Pick<
+    Parameters<typeof toast>[0],
+    "title" | "variant" | "description"
+  >,
+) {
+  const duration = options.variant === "danger" ? 5000 : 3000;
+  const { dismiss } = toast({ ...options, duration });
+  // Agent notices must also expire while the user focuses the agent terminal.
+  window.setTimeout(dismiss, duration);
+}

package/src/core/cells/__tests__/__snapshots__/cells.test.ts.snap

@@ -139,6 +139,7 @@ exports[`cell reducer > can initialize stdin > second stdin requested 1`] = `
     {
       "channel": "stdin",
       "data": "what is your name?",
+      "id": 2,
       "mimetype": "text/plain",
       "response": "Marimo!",
       "timestamp": 2,
@@ -146,6 +147,7 @@ exports[`cell reducer > can initialize stdin > second stdin requested 1`] = `
     {
       "channel": "stdin",
       "data": "how old are you?",
+      "id": 3,
       "mimetype": "text/plain",
       "timestamp": 3,
     },
@@ -189,6 +191,7 @@ exports[`cell reducer > can initialize stdin > stdin answered 1`] = `
     {
       "channel": "stdin",
       "data": "what is your name?",
+      "id": 2,
       "mimetype": "text/plain",
       "response": "Marimo!",
       "timestamp": 2,
@@ -233,6 +236,7 @@ exports[`cell reducer > can initialize stdin > stdin requested 1`] = `
     {
       "channel": "stdin",
       "data": "what is your name?",
+      "id": 2,
       "mimetype": "text/plain",
       "timestamp": 2,
     },

package/src/core/cells/__tests__/cell.test.ts

@@ -219,6 +219,45 @@ describe("transitionCell serialization", () => {
   });
 });
 
+describe("transitionCell console output ids", () => {
+  const output = (
+    data: string,
+    channel: OutputMessage["channel"] = "stdout",
+  ): OutputMessage => ({
+    channel,
+    mimetype: "text/plain",
+    data,
+    timestamp: 0,
+  });
+
+  it("assigns increasing ids to appended outputs", () => {
+    let cell = createCellRuntimeState({ status: "running" });
+    cell = transitionCell(cell, { console: output("a") } as CellMessage);
+    cell = transitionCell(cell, {
+      console: output("b", "stderr"),
+    } as CellMessage);
+    expect(cell.consoleOutputs.map((o) => o.id)).toEqual([1, 2]);
+  });
+
+  it("continues from the surviving maximum after a collapse", () => {
+    let cell = createCellRuntimeState({ status: "running" });
+    cell = transitionCell(cell, { console: output("a") } as CellMessage);
+    cell = transitionCell(cell, { console: output("b") } as CellMessage);
+    expect(cell.consoleOutputs.map((o) => o.id)).toEqual([1]);
+    cell = transitionCell(cell, {
+      console: output("c", "stderr"),
+    } as CellMessage);
+    expect(cell.consoleOutputs.map((o) => o.id)).toEqual([1, 2]);
+  });
+
+  it("assigns ids when the kernel replaces the whole console", () => {
+    const cell = transitionCell(createCellRuntimeState({ status: "running" }), {
+      console: [output("a"), output("b", "stderr")],
+    } as CellMessage);
+    expect(cell.consoleOutputs.map((o) => o.id)).toEqual([1, 2]);
+  });
+});
+
 describe("transitionCell stdin resolution", () => {
   describe.each([
     {

package/src/core/cells/__tests__/cells.test.ts

@@ -789,6 +789,58 @@ describe("cell reducer", () => {
     `);
   });
 
+  it("keeps error evidence after an edit and a new queued run", () => {
+    const code = "raise ValueError('old failure')";
+    const output: OutputMessage = {
+      channel: "marimo-error",
+      mimetype: "application/vnd.marimo+error",
+      data: [
+        {
+          type: "exception",
+          msg: "old failure",
+          exception_type: "ValueError",
+          raising_cell: null,
+          traceback: "<pre>ValueError: old failure</pre>",
+        },
+      ],
+      code,
+      timestamp: 1,
+    };
+    actions.handleCellMessage({
+      cell_id: firstCellId,
+      output,
+      console: {
+        channel: "stderr",
+        mimetype: "application/vnd.marimo+traceback",
+        data: "<pre>ValueError: old failure</pre>",
+        code,
+        timestamp: 1,
+      },
+      status: "idle",
+      stale_inputs: null,
+      timestamp: 1,
+    });
+    actions.updateCellCode({
+      cellId: firstCellId,
+      code: "print('new code')",
+      formattingChange: false,
+    });
+    actions.prepareForRun({ cellId: firstCellId });
+    actions.handleCellMessage({
+      cell_id: firstCellId,
+      output: null,
+      console: null,
+      status: "queued",
+      stale_inputs: null,
+      timestamp: 2,
+    });
+    const runtime = state.cellRuntime[firstCellId];
+    expect(state.cellData[firstCellId].lastCodeRun).toBe("print('new code')");
+    expect(runtime.output).toEqual(output);
+    expect(runtime.consoleOutputs[0].code).toBe(code);
+    expect(runtime.consoleOutputs[0].data).toContain("old failure");
+  });
+
   it("can run cell and receive cell messages", () => {
     // HAPPY PATH
     /////////////////
@@ -1527,7 +1579,9 @@ describe("cell reducer", () => {
       response: secret,
     });
 
-    expect(cells[0].consoleOutputs).toEqual([{ ...prompt, response: "" }]);
+    expect(cells[0].consoleOutputs).toEqual([
+      { ...prompt, id: 1, response: "" },
+    ]);
     expect(JSON.stringify(cells[0].consoleOutputs)).not.toContain(secret);
   });
 

package/src/core/cells/__tests__/collapseConsoleOutputs.test.ts

@@ -2,6 +2,7 @@
 
 import { describe, expect, it } from "vitest";
 import { StatefulOutputMessage } from "@/components/editor/output/ansi-reduce";
+import type { ConsoleOutputMessage } from "@/core/cells/types";
 import type { OutputMessage } from "@/core/kernel/messages";
 import {
   collapseConsoleOutputs,
@@ -279,6 +280,59 @@ describe("collapseConsoleOutputs", () => {
     expect(result[0].data).toContain("Streaming output truncated");
   });
 
+  it("keeps the first id when collapsing outputs", () => {
+    const consoleOutputs = [
+      {
+        mimetype: "text/plain",
+        channel: "output",
+        data: "Hello ",
+        timestamp: 0,
+        id: 7,
+      },
+      {
+        mimetype: "text/plain",
+        channel: "output",
+        data: "World",
+        timestamp: 0,
+        id: 8,
+      },
+    ] satisfies ConsoleOutputMessage[];
+    const result = collapseConsoleOutputs(consoleOutputs);
+    expect(result).toHaveLength(1);
+    expect(result[0].data).toBe("Hello World");
+    expect((result[0] as ConsoleOutputMessage).id).toBe(7);
+  });
+
+  it("keeps ids on outputs that survive truncation", () => {
+    const consoleOutputs = [
+      {
+        mimetype: "text/plain",
+        channel: "output",
+        data: "one\ntwo",
+        timestamp: 0,
+        id: 1,
+      },
+      {
+        mimetype: "text/plain",
+        channel: "stderr",
+        data: "three\nfour",
+        timestamp: 0,
+        id: 2,
+      },
+      {
+        mimetype: "text/plain",
+        channel: "output",
+        data: "five",
+        timestamp: 0,
+        id: 3,
+      },
+    ] satisfies ConsoleOutputMessage[];
+    const result = collapseConsoleOutputs(consoleOutputs, 3);
+    const ids = result.map((output) => (output as ConsoleOutputMessage).id);
+    expect(result[0].data).toContain("Streaming output truncated");
+    expect(ids).toEqual([undefined, 2, 3]);
+  });
+
   describe("ANSI escape sequences", () => {
     it("should handle cursor movement with collapse", () => {
       const consoleOutputs: OutputMessage[] = [

package/src/core/cells/__tests__/error-report.test.ts

@@ -0,0 +1,139 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+import { cellId } from "@/__tests__/branded";
+import type { MarimoError } from "@/core/kernel/messages";
+import { buildErrorReport, ERROR_MESSAGE_INSTRUCTIONS } from "../error-report";
+
+const CELL_ID = cellId("failed-cell");
+
+describe("buildErrorReport", () => {
+  it("preserves plain traceback text without treating angle brackets as HTML", () => {
+    const traceback =
+      '  File "<cell>", line 1\nValueError: expected <value> & got <other>';
+    expect(
+      buildErrorReport(CELL_ID, { traceback, tracebackFormat: "text" }).output,
+    ).toEqual({
+      type: "error",
+      instructions: ERROR_MESSAGE_INSTRUCTIONS,
+      message: "ValueError: expected <value> & got <other>",
+      traceback,
+    });
+  });
+  it("owns the instruction to repair the live notebook", () => {
+    const report = buildErrorReport(CELL_ID, {
+      errors: [{ type: "syntax", msg: "invalid code" }],
+    });
+    expect(report.output.instructions).toEqual("Fix this notebook error.");
+  });
+
+  it("keeps repair intent visible before oversized evidence", () => {
+    const report = buildErrorReport(CELL_ID, {
+      code: "# long code\n".repeat(10_000),
+      errors: [
+        {
+          type: "exception",
+          exception_type: "ValueError",
+          msg: "long error ".repeat(10_000),
+          raising_cell: null,
+          traceback: `<pre>Traceback\n${"long frame\n".repeat(10_000)}</pre>`,
+        },
+      ],
+    });
+    const serialized = JSON.stringify(report);
+
+    expect(serialized.length).toBeGreaterThan(8192);
+    expect(serialized.slice(0, 256)).toContain(
+      '"instructions":"Fix this notebook error."',
+    );
+  });
+
+  it("retains every message and complete traceback without display limits", () => {
+    const traceback = `Traceback\n${"long frame\n".repeat(10_000)}ValueError: bad <value>`;
+    const errors: MarimoError[] = [
+      {
+        type: "exception",
+        msg: "bad <value>",
+        exception_type: "ValueError",
+        raising_cell: null,
+        traceback: `<pre>${traceback.replaceAll("<", "&lt;").replaceAll(">", "&gt;")}</pre>`,
+      },
+      { type: "syntax", msg: "another error" },
+    ];
+    expect(buildErrorReport(CELL_ID, { code: "failed()", errors })).toEqual({
+      type: "cell-output",
+      cell_id: CELL_ID,
+      code: "failed()",
+      output: {
+        type: "error",
+        instructions: ERROR_MESSAGE_INSTRUCTIONS,
+        message: "bad <value>\nanother error",
+        traceback,
+      },
+    });
+  });
+
+  it("leaves source unknown for a restored legacy exception", () => {
+    expect(
+      buildErrorReport(CELL_ID, {
+        errors: [
+          {
+            type: "exception",
+            exception_type: "exception",
+            msg: "legacy error",
+            raising_cell: null,
+            traceback: null,
+          },
+        ],
+      }),
+    ).toEqual({
+      type: "cell-output",
+      cell_id: CELL_ID,
+      output: {
+        type: "error",
+        instructions: ERROR_MESSAGE_INSTRUCTIONS,
+        message: "legacy error",
+      },
+    });
+  });
+
+  it("preserves empty captured code", () => {
+    expect(
+      buildErrorReport(CELL_ID, {
+        code: "",
+        errors: [{ type: "syntax", msg: "invalid code" }],
+      }),
+    ).toEqual({
+      type: "cell-output",
+      cell_id: CELL_ID,
+      code: "",
+      output: {
+        type: "error",
+        instructions: ERROR_MESSAGE_INSTRUCTIONS,
+        message: "invalid code",
+      },
+    });
+  });
+
+  it("keeps separate structured tracebacks in order", () => {
+    const errors: MarimoError[] = ["first", "second"].map((message) => ({
+      type: "exception",
+      exception_type: "ValueError",
+      raising_cell: null,
+      msg: message,
+      traceback: `<pre>Traceback\nValueError: ${message}</pre>`,
+    }));
+    expect(buildErrorReport(CELL_ID, { errors })).toEqual({
+      type: "cell-output",
+      cell_id: CELL_ID,
+      output: {
+        type: "error",
+        instructions: ERROR_MESSAGE_INSTRUCTIONS,
+        message: "first\nsecond",
+        traceback:
+          "Traceback\nValueError: first\n\nTraceback\nValueError: second",
+      },
+    });
+  });
+});

package/src/core/cells/__tests__/notebook-outline.test.ts

@@ -0,0 +1,113 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { createStore } from "jotai";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { MockNotebook } from "@/__mocks__/notebook";
+import { cellId } from "@/__tests__/branded";
+import {
+  createNotebookActions,
+  notebookAtom,
+  notebookOutline,
+  notebookReducer,
+} from "../cells";
+import { exportedForTesting } from "../document-changes";
+import type { Outline } from "../outline";
+
+const first = cellId("first");
+const second = cellId("second");
+const firstOutline: Outline = {
+  items: [{ name: "First", level: 1, by: { id: "first" } }],
+};
+const secondOutline: Outline = {
+  items: [{ name: "Second", level: 2, by: { id: "second" } }],
+};
+
+function setup() {
+  const store = createStore();
+  store.set(
+    notebookAtom,
+    MockNotebook.notebookState({
+      cellData: { [first]: { code: "x = 1" }, [second]: {} },
+      cellRuntime: {
+        [first]: { outline: firstOutline },
+        [second]: { outline: secondOutline },
+      },
+    }),
+  );
+  const actions = createNotebookActions((action) =>
+    store.set(notebookAtom, (state) => notebookReducer(state, action)),
+  );
+  return { store, actions };
+}
+
+afterEach(() => {
+  exportedForTesting.cancelPendingChanges();
+});
+
+describe("notebookOutline", () => {
+  it("does not notify outline subscribers when cell code changes", () => {
+    const { store, actions } = setup();
+    const initial = store.get(notebookOutline);
+    const listener = vi.fn();
+    const unsubscribe = store.sub(notebookOutline, listener);
+
+    actions.updateCellCode({
+      cellId: first,
+      code: "x = 2",
+      formattingChange: false,
+    });
+
+    expect(store.get(notebookOutline)).toBe(initial);
+    expect(listener).not.toHaveBeenCalled();
+    unsubscribe();
+  });
+
+  it("updates headings when runtime outlines change or are removed", () => {
+    const { store } = setup();
+    const updated: Outline = {
+      items: [{ name: "Updated", level: 1, by: { id: "updated" } }],
+    };
+
+    for (const outline of [updated, null]) {
+      store.set(notebookAtom, (state) => ({
+        ...state,
+        cellRuntime: {
+          ...state.cellRuntime,
+          [first]: { ...state.cellRuntime[first], outline },
+        },
+      }));
+      expect(store.get(notebookOutline)).toEqual({
+        items: [...(outline?.items ?? []), ...secondOutline.items],
+      });
+    }
+  });
+
+  it("keeps headings in cell order after moving and deleting cells", () => {
+    const { store, actions } = setup();
+    actions.moveCell({ cellId: second, before: true });
+    expect(store.get(notebookOutline)).toEqual({
+      items: [...secondOutline.items, ...firstOutline.items],
+    });
+
+    actions.deleteCell({ cellId: second });
+    expect(store.get(notebookOutline)).toEqual(firstOutline);
+  });
+
+  it("notifies subscribers when output is replaced with the same headings", () => {
+    const { store } = setup();
+    const listener = vi.fn();
+    const unsubscribe = store.sub(notebookOutline, listener);
+
+    store.set(notebookAtom, (state) => ({
+      ...state,
+      cellRuntime: {
+        ...state.cellRuntime,
+        [first]: { ...state.cellRuntime[first], outline: { ...firstOutline } },
+      },
+    }));
+
+    // Consumers must reconnect to replacement heading elements in the DOM.
+    expect(listener).toHaveBeenCalledOnce();
+    unsubscribe();
+  });
+});