@marimo-team/islands 0.25.3-dev3 → 0.25.3-dev5

package/src/core/attachments/state.ts

@@ -0,0 +1,21 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { components } from "@marimo-team/marimo-api";
+import { atom } from "jotai";
+import { isConnectedAtom } from "@/core/network/connection";
+
+export type Attachment = components["schemas"]["Attachment"];
+
+export const attachmentsAtom = atom<Attachment[]>([]);
+export const agentAttachmentsAtom = atom((get) => {
+  if (!get(isConnectedAtom)) {
+    return [];
+  }
+  return get(attachmentsAtom).filter(
+    (attachment) => attachment.kind === "agent",
+  );
+});
+
+export function attachmentLabel(attachment: Attachment): string {
+  return attachment.name || "Agent";
+}

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
     /////////////////

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

@@ -0,0 +1,89 @@
+/* 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 } from "../error-report";
+
+const CELL_ID = cellId("failed-cell");
+
+describe("buildErrorReport", () => {
+  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",
+        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", 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", 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",
+        message: "first\nsecond",
+        traceback:
+          "Traceback\nValueError: first\n\nTraceback\nValueError: second",
+      },
+    });
+  });
+});

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

@@ -183,6 +183,40 @@ describe("notebookStateFromSession", () => {
       });
     });
 
+    it("restores matching code from the session", () => {
+      const code = "raise ValueError('cached failure')";
+      const session = createSession([
+        createSessionCell(
+          "cell-1",
+          [
+            {
+              type: "error",
+              ename: "ValueError",
+              evalue: "cached failure",
+              traceback: ["Traceback\n", "ValueError: cached failure"],
+              code,
+            },
+          ],
+          [
+            {
+              type: "stream",
+              name: "stderr",
+              text: "<pre>ValueError: cached failure</pre>",
+              mimetype: "application/vnd.marimo+traceback",
+              code,
+            },
+          ],
+        ),
+      ]);
+      const state = notebookStateFromSession(session, null);
+      invariant(state, "state is null");
+      expect(state.cellRuntime[CELL_1].output).toMatchObject({
+        code,
+        data: [{ type: "unknown", msg: "cached failure" }],
+      });
+      expect(state.cellRuntime[CELL_1].consoleOutputs[0].code).toBe(code);
+    });
+
     it("handles data output in session cell", () => {
       const dataOutput = {
         type: "data" as const,

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

@@ -0,0 +1,55 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describeError } from "@/core/errors/error-entries";
+import type { MarimoError } from "@/core/kernel/messages";
+import { sanitizeHtml } from "@/plugins/core/sanitize-html";
+import { parseHtmlContent } from "@/utils/dom";
+import type { CellId } from "./ids";
+
+export interface CellOutputHandoff<Output> {
+  type: "cell-output";
+  cell_id: CellId;
+  code?: string;
+  output: Output;
+}
+
+export interface ErrorHandoffOutput {
+  type: "error";
+  message: string;
+  traceback?: string;
+}
+
+export function buildErrorReport(
+  cellId: CellId,
+  evidence: { code?: string } & (
+    | { errors: MarimoError[] }
+    | { traceback: string }
+  ),
+): CellOutputHandoff<ErrorHandoffOutput> {
+  let message: string;
+  let traceback: string;
+  if ("errors" in evidence) {
+    message = evidence.errors.map(describeError).join("\n");
+    traceback = evidence.errors
+      .flatMap((error) =>
+        "traceback" in error && error.traceback
+          ? [parseHtmlContent(sanitizeHtml(error.traceback))]
+          : [],
+      )
+      .join("\n\n");
+  } else {
+    traceback = parseHtmlContent(sanitizeHtml(evidence.traceback));
+    message = traceback.split("\n").findLast((line) => line.length > 0) ?? "";
+  }
+
+  return {
+    type: "cell-output",
+    cell_id: cellId,
+    ...(evidence.code === undefined ? {} : { code: evidence.code }),
+    output: {
+      type: "error",
+      message,
+      ...(traceback ? { traceback } : {}),
+    },
+  };
+}

package/src/core/cells/session.ts

@@ -223,6 +223,9 @@ function createCellRuntimeFromSession(
         timestamp: DEFAULT_TIMESTAMP,
       };
     }
+    if (runtimeState.output && primaryOutput.code !== undefined) {
+      runtimeState.output.code = primaryOutput.code;
+    }
   }
 
   const consoleOutputs = sessionCell.console || [];
@@ -238,6 +241,9 @@ function createCellRuntimeFromSession(
           data: consoleOutput.data,
           mimetype: consoleOutput.mimetype,
           timestamp: DEFAULT_TIMESTAMP,
+          ...(consoleOutput.code === undefined
+            ? {}
+            : { code: consoleOutput.code }),
         };
       }
       // Handle StreamOutput (type: "stream")
@@ -246,6 +252,9 @@ function createCellRuntimeFromSession(
         data: consoleOutput.text,
         mimetype: consoleOutput.mimetype ?? "text/plain",
         timestamp: DEFAULT_TIMESTAMP,
+        ...(consoleOutput.code === undefined
+          ? {}
+          : { code: consoleOutput.code }),
       };
     }),
   };

package/src/core/islands/__tests__/bootstrap.test.ts

@@ -3,6 +3,8 @@
 import { createStore } from "jotai";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { RuntimeState } from "@/core/kernel/RuntimeState";
+import { attachmentsAtom } from "@/core/attachments/state";
+import { Logger } from "@/utils/Logger";
 import { initializeIslands } from "../bootstrap";
 import type { IslandsPyodideBridge } from "../bridge";
 import { islandsHydratedAtom, islandsPendingInitialRunsAtom } from "../state";
@@ -48,6 +50,30 @@ describe("initializeIslands", () => {
     expect(store.get(islandsHydratedAtom)).toBe(false);
     store.set(islandsPendingInitialRunsAtom, new Set([1, 2]));
 
+    const errors = vi.spyOn(Logger, "error");
+    consumeMessage?.({
+      sessionGeneration: 1,
+      message: JSON.stringify({
+        op: "attachments",
+        data: {
+          op: "attachments",
+          attachments: [
+            {
+              id: "a1",
+              kind: "agent",
+              name: "Pi",
+              since: "2026-10-14T00:00:00Z",
+              notebook_id: "nb-test",
+              identity: "pi-thread",
+            },
+          ],
+        },
+      }) as IslandsKernelMessage["message"],
+    });
+    expect(errors).not.toHaveBeenCalled();
+    expect(store.get(attachmentsAtom)).toEqual([]);
+    expect(store.get(islandsPendingInitialRunsAtom)).toEqual(new Set([1, 2]));
+
     consumeMessage?.(completedRun(1));
     expect(store.get(islandsHydratedAtom)).toBe(false);
 

package/src/core/islands/bootstrap.ts

@@ -209,6 +209,7 @@ function handleMessage(
       case "cache-info":
       case "kernel-startup-error":
       case "notebook-document-transaction":
+      case "attachments":
         return;
 
       case "completed-run":

package/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx

@@ -43,6 +43,11 @@ vi.mock("@/core/runtime/config", async () => {
 import { MockNotebook } from "@/__mocks__/notebook";
 import { cellId } from "@/__tests__/branded";
 import { alertAtom, getPackageAlert } from "@/core/alerts/state";
+import {
+  type Attachment,
+  attachmentsAtom,
+  agentAttachmentsAtom,
+} from "@/core/attachments/state";
 import { notebookAtom } from "@/core/cells/cells";
 import { AppConfigSchema } from "@/core/config/config-schema";
 import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
@@ -184,6 +189,46 @@ describe("useMarimoKernelConnection.reconnect()", () => {
 });
 
 describe("useMarimoKernelConnection messages", () => {
+  it("replaces attachment snapshots, including the last detach", () => {
+    const store = createStore();
+    vi.mocked(useConnectionTransport).mockReturnValue(
+      makeTransport(WebSocket.OPEN),
+    );
+    vi.mocked(useRuntimeManager).mockReturnValue(
+      makeRuntimeManager() as unknown as ReturnType<typeof useRuntimeManager>,
+    );
+    renderConnectionHook(store);
+    const options = vi.mocked(useConnectionTransport).mock.calls.at(-1)![0];
+    const agent: Attachment = {
+      id: "a1",
+      kind: "agent",
+      name: "Pi",
+      since: "2026-10-14T00:00:00Z",
+      notebook_id: "nb-test",
+      identity: "pi-thread",
+    };
+    const client: Attachment = {
+      id: "c1",
+      kind: "client",
+      name: null,
+      since: "2026-10-14T00:00:01Z",
+      notebook_id: "nb-test",
+    };
+    for (const attachments of [[agent, client], [client], []]) {
+      act(() =>
+        options.onMessage(
+          new MessageEvent("message", {
+            data: JSON.stringify({
+              op: "attachments",
+              data: { op: "attachments", attachments },
+            }),
+          }),
+        ),
+      );
+      expect(store.get(attachmentsAtom)).toEqual(attachments);
+    }
+  });
+
   it("records completion of the initial run", () => {
     const store = createStore();
     vi.mocked(useConnectionTransport).mockClear();
@@ -211,6 +256,101 @@ describe("useMarimoKernelConnection messages", () => {
   });
 });
 
+describe("attachment snapshots across browser connections", () => {
+  const agent: Attachment = {
+    id: "a1",
+    kind: "agent",
+    name: "Pi",
+    since: "2026-10-14T00:00:00Z",
+    notebook_id: "nb-test",
+    identity: "pi-thread",
+  };
+
+  function connectedSession() {
+    const store = createStore();
+    store.set(connectionAtom, { state: ConnectionState.OPEN });
+    store.set(attachmentsAtom, [agent]);
+    const transport = makeTransport(WebSocket.OPEN);
+    vi.mocked(useConnectionTransport).mockReturnValue(transport);
+    vi.mocked(useRuntimeManager).mockReturnValue(
+      makeRuntimeManager() as unknown as ReturnType<typeof useRuntimeManager>,
+    );
+    renderConnectionHook(store);
+    const options = vi.mocked(useConnectionTransport).mock.calls.at(-1)![0];
+    const receive = (data: NotificationPayload["data"]) =>
+      act(() => {
+        options.onMessage(
+          new MessageEvent("message", {
+            data: JSON.stringify({ op: data.op, data }),
+          }),
+        );
+      });
+    return { store, transport, options, receive };
+  }
+
+  it.each([
+    "MARIMO_NO_FILE_KEY",
+    "MARIMO_NO_SESSION_ID",
+    "MARIMO_NO_SESSION",
+    "MARIMO_SHUTDOWN",
+    "MARIMO_KERNEL_STARTUP_ERROR",
+    "MARIMO_UNAUTHORIZED",
+    "MARIMO_KIOSK_NOT_ALLOWED",
+    "MARIMO_TRANSPORT_EXHAUSTED",
+  ])("clears cached attachments on %s", (reason) => {
+    const { store, transport, options } = connectedSession();
+    act(() => options.onClose(new CloseEvent("close", { reason })));
+    expect(store.get(attachmentsAtom)).toEqual([]);
+    expect(store.get(agentAttachmentsAtom)).toEqual([]);
+    expect(store.get(connectionAtom).state).toBe(ConnectionState.CLOSED);
+    expect(transport.reconnect).not.toHaveBeenCalled();
+  });
+
+  it("clears the snapshot on transport error", () => {
+    const { store, options } = connectedSession();
+    act(() => options.onError(new Event("error")));
+    expect(store.get(attachmentsAtom)).toEqual([]);
+    expect(store.get(agentAttachmentsAtom)).toEqual([]);
+  });
+
+  it("waits for a fresh snapshot after a transient reconnect", async () => {
+    const { store, transport, options, receive } = connectedSession();
+    act(() => options.onClose(new CloseEvent("close")));
+    expect(store.get(attachmentsAtom)).toEqual([]);
+    expect(store.get(connectionAtom).state).toBe(ConnectionState.CONNECTING);
+    expect(transport.reconnect).toHaveBeenCalledOnce();
+
+    await act(async () => options.onOpen(new Event("open")));
+    receive({ op: "reconnected" });
+    expect(store.get(connectionAtom).state).toBe(ConnectionState.OPEN);
+    expect(store.get(agentAttachmentsAtom)).toEqual([]);
+
+    const refreshed = { ...agent, id: "a2", name: "Codex" };
+    receive({ op: "attachments", attachments: [refreshed] });
+    expect(store.get(agentAttachmentsAtom)).toEqual([refreshed]);
+    receive({ op: "attachments", attachments: [] });
+    expect(store.get(agentAttachmentsAtom)).toEqual([]);
+  });
+
+  it("keeps a fresh snapshot hidden until the session is ready", async () => {
+    const { store, options, receive } = connectedSession();
+    act(() => options.onClose(new CloseEvent("close")));
+    await act(async () => options.onOpen(new Event("open")));
+    receive({ op: "attachments", attachments: [agent] });
+    expect(store.get(attachmentsAtom)).toEqual([agent]);
+    expect(store.get(agentAttachmentsAtom)).toEqual([]);
+    receive({ op: "reconnected" });
+    expect(store.get(agentAttachmentsAtom)).toEqual([agent]);
+  });
+
+  it("invalidates an old snapshot when a new transport opens", async () => {
+    const { store, options } = connectedSession();
+    await act(async () => options.onOpen(new Event("open")));
+    expect(store.get(attachmentsAtom)).toEqual([]);
+    expect(store.get(agentAttachmentsAtom)).toEqual([]);
+  });
+});
+
 it.each(["kernel-ready", "reconnected"])(
   "waits for %s before marking the session connected",
   async (op) => {
@@ -261,6 +401,59 @@ it.each(["kernel-ready", "reconnected"])(
   },
 );
 
+it.each([true, false])(
+  "keeps attachments only when kernel-ready resumes the session: %s",
+  (resumed) => {
+    const store = createStore();
+    const attachments: Attachment[] = [
+      {
+        id: "a1",
+        kind: "agent",
+        name: "Pi",
+        since: "2026-10-14T00:00:00Z",
+        notebook_id: "nb-test",
+        identity: "pi-thread",
+      },
+    ];
+    store.set(attachmentsAtom, attachments);
+    vi.mocked(useConnectionTransport).mockReturnValue(
+      makeTransport(WebSocket.OPEN),
+    );
+    vi.mocked(useRuntimeManager).mockReturnValue(
+      makeRuntimeManager() as unknown as ReturnType<typeof useRuntimeManager>,
+    );
+    renderConnectionHook(store);
+    const options = vi.mocked(useConnectionTransport).mock.calls.at(-1)![0];
+    act(() =>
+      options.onMessage(
+        new MessageEvent("message", {
+          data: JSON.stringify({
+            op: "kernel-ready",
+            data: {
+              op: "kernel-ready",
+              cell_ids: [],
+              codes: [],
+              names: [],
+              configs: [],
+              layout: null,
+              resumed,
+              ui_values: {},
+              last_executed_code: {},
+              last_execution_time: {},
+              app_config: { width: "normal" },
+              kiosk: false,
+              capabilities: { terminal: false },
+              auto_instantiated: true,
+              consumer_capabilities: { edit: true, interact: true },
+            },
+          }),
+        }),
+      ),
+    );
+    expect(store.get(attachmentsAtom)).toEqual(resumed ? attachments : []);
+  },
+);
+
 describe("connection notice", () => {
   beforeEach(() => vi.useFakeTimers());
   afterEach(() => vi.useRealTimers());

package/src/core/websocket/useMarimoKernelConnection.tsx

@@ -5,6 +5,7 @@ import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import { useRef } from "react";
 import { useErrorBoundary } from "react-error-boundary";
 import { toast } from "@/components/ui/use-toast";
+import { attachmentsAtom } from "@/core/attachments/state";
 import { getNotebook, useCellActions } from "@/core/cells/cells";
 import { applyTransactionChanges } from "@/core/cells/document-changes";
 import { AUTOCOMPLETER } from "@/core/codemirror/completion/Autocompleter";
@@ -236,6 +237,7 @@ export function useMarimoKernelConnection(opts: {
   } = useAlertActions();
   const setKioskMode = useSetAtom(kioskModeAtom);
   const setStableSessionId = useSetAtom(stableSessionIdAtom);
+  const setAttachments = useSetAtom(attachmentsAtom);
   const setCapabilities = useSetAtom(capabilitiesAtom);
   const runtimeManager = useRuntimeManager();
   const transportType = useAtomValue(connectionTransportTypeAtom);
@@ -252,6 +254,9 @@ export function useMarimoKernelConnection(opts: {
       case "reload":
         reloadSafe();
         return;
+      case "attachments":
+        setAttachments(msg.data.attachments);
+        return;
       case "startup-progress": {
         const { phase } = msg.data;
         updateStartupProgress(msg.data);
@@ -283,6 +288,7 @@ export function useMarimoKernelConnection(opts: {
           existingCells,
         });
         if (!msg.data.resumed) {
+          setAttachments([]);
           // A freshly started kernel may expose a different environment
           // (e.g. new env vars); re-run discovery instead of reusing stale
           // suggestions from the previous kernel instance.
@@ -561,6 +567,7 @@ export function useMarimoKernelConnection(opts: {
      */
     onOpen: async () => {
       updateStartupProgress(null);
+      setAttachments([]);
       // If we are open, we can reset our reconnecting flag.
       shouldTryReconnecting.current = true;
     },
@@ -603,6 +610,7 @@ export function useMarimoKernelConnection(opts: {
      */
     onClose: (e) => {
       Logger.warn("WebSocket closed", e.code, e.reason);
+      setAttachments([]);
       const decision = classifyCloseEvent(e);
       setConnection((previous) => {
         const status = decision.status;
@@ -641,6 +649,7 @@ export function useMarimoKernelConnection(opts: {
      */
     onError: (e) => {
       Logger.warn("WebSocket error", e);
+      setAttachments([]);
       setConnection({
         state: ConnectionState.CLOSED,
         code: WebSocketClosedReason.KERNEL_DISCONNECTED,