@marimo-team/islands 0.25.3-dev14 → 0.25.3-dev140

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/state.ts

@@ -1,17 +1,14 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import type { components } from "@marimo-team/marimo-api";
 import { atom } from "jotai";
-import { isConnectedAtom } from "@/core/network/connection";
+import type { Attachment } from "@marimo-team/client/protocol";
+import { notebookReplicaAtom } from "@/core/websocket/state";
 
-export type Attachment = components["schemas"]["Attachment"];
+export type { Attachment } from "@marimo-team/client/protocol";
 
-export const attachmentsAtom = atom<Attachment[]>([]);
 export const agentAttachmentsAtom = atom((get) => {
-  if (!get(isConnectedAtom)) {
-    return [];
-  }
-  return get(attachmentsAtom).filter(
+  const notebook = get(notebookReplicaAtom);
+  return (notebook ? get(notebook.attachmentsAtom) : []).filter(
     (attachment) => attachment.kind === "agent",
   );
 });

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

@@ -1579,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__/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();
+  });
+});

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

@@ -46,10 +46,17 @@ describe("notebookStateFromSession", () => {
 
   const createNotebookCell = (
     id: string,
-    code: string | null = null,
-    name: string | null = null,
-    config: NotebookCell["config"] | null = null,
-    code_hash: string | null = null,
+    {
+      code = null,
+      name = null,
+      config = null,
+      code_hash = null,
+    }: {
+      code?: string | null;
+      name?: string | null;
+      config?: NotebookCell["config"] | null;
+      code_hash?: string | null;
+    } = {},
   ): NotebookCell => ({
     id,
     code,
@@ -87,7 +94,7 @@ describe("notebookStateFromSession", () => {
 
     it("logs error when session and notebook have different cells", () => {
       const session = createSession([createSessionCell("cell-1")]);
-      const notebook = createNotebook([createNotebookCell("cell-2")]);
+      const notebook = createNotebook([createNotebookCell("cell-2", {})]);
 
       const result = notebookStateFromSession(session, notebook);
 
@@ -328,7 +335,10 @@ describe("notebookStateFromSession", () => {
   describe("notebook only scenarios", () => {
     it("creates state from notebook with single cell", () => {
       const notebook = createNotebook([
-        createNotebookCell("cell-1", "print('hello')", "my_cell"),
+        createNotebookCell("cell-1", {
+          code: "print('hello')",
+          name: "my_cell",
+        }),
       ]);
       const result = notebookStateFromSession(null, notebook);
 
@@ -356,11 +366,15 @@ describe("notebookStateFromSession", () => {
 
     it("creates state from notebook with custom config", () => {
       const notebook = createNotebook([
-        createNotebookCell("cell-1", "code", "name", {
-          hide_code: true,
-          disabled: true,
-          column: 1,
-          expand_output: true,
+        createNotebookCell("cell-1", {
+          code: "code",
+          name: "name",
+          config: {
+            hide_code: true,
+            disabled: true,
+            column: 1,
+            expand_output: true,
+          },
         }),
       ]);
       const result = notebookStateFromSession(null, notebook);
@@ -464,7 +478,10 @@ describe("notebookStateFromSession", () => {
         ),
       ]);
       const notebook = createNotebook([
-        createNotebookCell("cell-1", "print('hello')", "my_cell"),
+        createNotebookCell("cell-1", {
+          code: "print('hello')",
+          name: "my_cell",
+        }),
       ]);
       const result = notebookStateFromSession(session, notebook);
 
@@ -495,8 +512,8 @@ describe("notebookStateFromSession", () => {
         createSessionCell("cell-2"),
       ]);
       const notebook = createNotebook([
-        createNotebookCell("cell-2"),
-        createNotebookCell("cell-1"),
+        createNotebookCell("cell-2", {}),
+        createNotebookCell("cell-1", {}),
       ]);
 
       const result = notebookStateFromSession(session, notebook);
@@ -514,8 +531,8 @@ describe("notebookStateFromSession", () => {
         createSessionCell("cell-2"),
       ]);
       const notebook = createNotebook([
-        createNotebookCell("cell-1"),
-        createNotebookCell("cell-2"),
+        createNotebookCell("cell-1", {}),
+        createNotebookCell("cell-2", {}),
       ]);
 
       const result = notebookStateFromSession(session, notebook);
@@ -669,12 +686,42 @@ describe("notebookStateFromSession", () => {
       };
       // Create notebook cells with code values 'a' through 'f'
       const notebookCells = [
-        createNotebookCell("cell-a", "a", null, null, hashes.a),
-        createNotebookCell("cell-b", "b", null, null, hashes.b),
-        createNotebookCell("cell-c", "c", null, null, hashes.c),
-        createNotebookCell("cell-d", "d", null, null, hashes.d),
-        createNotebookCell("cell-e", "e", null, null, hashes.e),
-        createNotebookCell("cell-f", "f", null, null, hashes.f),
+        createNotebookCell("cell-a", {
+          code: "a",
+          name: null,
+          config: null,
+          code_hash: hashes.a,
+        }),
+        createNotebookCell("cell-b", {
+          code: "b",
+          name: null,
+          config: null,
+          code_hash: hashes.b,
+        }),
+        createNotebookCell("cell-c", {
+          code: "c",
+          name: null,
+          config: null,
+          code_hash: hashes.c,
+        }),
+        createNotebookCell("cell-d", {
+          code: "d",
+          name: null,
+          config: null,
+          code_hash: hashes.d,
+        }),
+        createNotebookCell("cell-e", {
+          code: "e",
+          name: null,
+          config: null,
+          code_hash: hashes.e,
+        }),
+        createNotebookCell("cell-f", {
+          code: "f",
+          name: null,
+          config: null,
+          code_hash: hashes.f,
+        }),
       ];
       // Create session cells with matching code_hashes
       const sessionCells = [
@@ -787,11 +834,36 @@ describe("notebookStateFromSession", () => {
 
       // Notebook has cells with code 'a', 'c', 'z', 'e', 'g'
       const notebookCells = [
-        createNotebookCell("cell-a", "a", null, null, hashes.a),
-        createNotebookCell("cell-c", "c", null, null, hashes.c),
-        createNotebookCell("cell-z", "z", null, null, hashes.z),
-        createNotebookCell("cell-e", "e", null, null, hashes.e),
-        createNotebookCell("cell-g", "g", null, null, hashes.g),
+        createNotebookCell("cell-a", {
+          code: "a",
+          name: null,
+          config: null,
+          code_hash: hashes.a,
+        }),
+        createNotebookCell("cell-c", {
+          code: "c",
+          name: null,
+          config: null,
+          code_hash: hashes.c,
+        }),
+        createNotebookCell("cell-z", {
+          code: "z",
+          name: null,
+          config: null,
+          code_hash: hashes.z,
+        }),
+        createNotebookCell("cell-e", {
+          code: "e",
+          name: null,
+          config: null,
+          code_hash: hashes.e,
+        }),
+        createNotebookCell("cell-g", {
+          code: "g",
+          name: null,
+          config: null,
+          code_hash: hashes.g,
+        }),
       ];
 
       const session = createSession(sessionCells);
@@ -908,15 +980,24 @@ describe("notebookStateFromSession", () => {
 
       // Notebook has cells: cell-1 (1 / 0, no hash), cell-2 (mo.md("Hello"), hash=moMd), cell-3 (slider, hash=slider)
       const notebookCells = [
-        createNotebookCell("cell-1", "1 / 0", null, null, null), // no hash
-        createNotebookCell("cell-2", 'mo.md("Hello")', null, null, hashes.moMd),
-        createNotebookCell(
-          "cell-3",
-          "x = mo.ui.slider(0, 10)",
-          null,
-          null,
-          hashes.slider,
-        ),
+        createNotebookCell("cell-1", {
+          code: "1 / 0",
+          name: null,
+          config: null,
+          code_hash: null,
+        }), // no hash
+        createNotebookCell("cell-2", {
+          code: 'mo.md("Hello")',
+          name: null,
+          config: null,
+          code_hash: hashes.moMd,
+        }),
+        createNotebookCell("cell-3", {
+          code: "x = mo.ui.slider(0, 10)",
+          name: null,
+          config: null,
+          code_hash: hashes.slider,
+        }),
       ];
 
       const session = createSession(sessionCells);

package/src/core/cells/cell.ts

@@ -7,7 +7,12 @@ import { parseOutline } from "../dom/outline";
 import type { CellMessage, OutputMessage } from "../kernel/messages";
 import type { RuntimeState } from "../network/types";
 import { collapseConsoleOutputs } from "./collapseConsoleOutputs";
-import type { CellRuntimeState } from "./types";
+import type { CellRuntimeState, ConsoleOutputMessage } from "./types";
+
+// Ids increase with position, so the last output holds the maximum.
+function nextConsoleOutputId(outputs: ConsoleOutputMessage[]): number {
+  return (outputs.at(-1)?.id ?? 0) + 1;
+}
 
 export function transitionCell(
   cell: CellRuntimeState,
@@ -133,6 +138,7 @@ export function transitionCell(
           mimetype: output.mimetype,
           data: output.data,
           timestamp: output.timestamp,
+          id: output.id,
           response: output.response ?? "",
         };
       }
@@ -146,8 +152,13 @@ export function transitionCell(
     // messageConsole is an output that needs to be appended to the
     // existing console outputs.
     consoleOutputs = Array.isArray(messageConsole)
-      ? collapseConsoleOutputs(messageConsole)
-      : collapseConsoleOutputs([...consoleOutputs, messageConsole]);
+      ? collapseConsoleOutputs(
+          messageConsole.map((output, i) => ({ ...output, id: i + 1 })),
+        )
+      : collapseConsoleOutputs([
+          ...consoleOutputs,
+          { ...messageConsole, id: nextConsoleOutputId(consoleOutputs) },
+        ]);
   }
   nextCell.consoleOutputs = consoleOutputs;
   // Derive outline from output

package/src/core/cells/cells.ts

@@ -1114,6 +1114,7 @@ const {
           mimetype: stdinOutput.mimetype,
           data: stdinOutput.data,
           timestamp: stdinOutput.timestamp,
+          id: stdinOutput.id,
           // An empty response resolves the prompt without retaining the secret.
           response: stdinOutput.mimetype === "text/password" ? "" : response,
         };
@@ -1761,7 +1762,8 @@ export const cellErrorsAtom = atom((get) => {
 });
 
 export const notebookOutline = atom((get) => {
-  const { cellIds, cellRuntime } = get(notebookAtom);
+  const cellIds = get(cellIdsAtom);
+  const cellRuntime = get(cellsRuntimeAtom);
   const outlines = cellIds.inOrderIds.map(
     (cellId) => cellRuntime[cellId].outline,
   );

package/src/core/cells/pending-delete-service.ts

@@ -134,12 +134,8 @@ export function usePendingDeleteService() {
       submit({ cellIds, deleteCell, deleteManyCells, store });
     },
     clear,
-    get idle() {
-      return entries.size === 0;
-    },
-    get shouldConfirmDelete() {
-      return entries.size > 1;
-    },
+    idle: entries.size === 0,
+    shouldConfirmDelete: entries.size > 1,
   };
 }
 

package/src/core/cells/session.ts

@@ -56,7 +56,7 @@ function mergeSessionAndNotebookCells(
     return {
       cellIds,
       sessionCellData: new Map(
-        cellIds.map((id, idx) => [id, null] as [CellId, SessionCell | null]),
+        cellIds.map((id) => [id, null] as [CellId, SessionCell | null]),
       ),
       notebookCellData: new Map(
         cellIds.map(

package/src/core/cells/types.ts

@@ -95,7 +95,7 @@ export interface CellRuntimeState {
   /** TOC outline */
   outline: Outline | null;
   /** messages encoding the cell's console outputs. */
-  consoleOutputs: WithResponse<OutputMessage>[];
+  consoleOutputs: ConsoleOutputMessage[];
   /** current status of the cell */
   status: RuntimeState;
   /** whether the cell has stale inputs*/
@@ -130,3 +130,12 @@ export type WithResponse<T> = T & {
    */
   response?: string;
 };
+
+/**
+ * A console output as held by the frontend. The id is assigned when the
+ * output arrives and never changes, so it can identify the output while
+ * neighboring outputs collapse, truncate, or receive a stdin response.
+ */
+export type ConsoleOutputMessage = WithResponse<OutputMessage> & {
+  id?: number;
+};