@marimo-team/islands 0.25.3-dev222 → 0.25.3-dev224

package/src/components/editor/actions/__tests__/pair-with-agent-modal.test.tsx

@@ -102,11 +102,14 @@ describe("PairWithAgentModal", () => {
       expect(
         panel.textContent?.includes("Agent connections require OpenCode 2.x"),
       ).toBe(tab === "OpenCode");
-      expect(panel).toHaveTextContent(
-        tab === "Other Agents"
-          ? "1. Copy this prompt"
-          : "1. Run in your terminal",
-      );
+      expect(
+        within(panel).getByText(
+          tab === "Other Agents"
+            ? "Copy this prompt into your agent"
+            : "Run in your terminal",
+          { exact: true },
+        ),
+      ).toBeInTheDocument();
       fireEvent.click(
         within(panel).getByRole("button", {
           name: tab === "Other Agents" ? "Copy prompt" : "Copy command",
@@ -364,6 +367,7 @@ describe("PairWithAgentModal", () => {
     });
 
     const panel = screen.getByRole("tabpanel");
+    expect(panel).toHaveTextContent("1. Run in your terminal");
     expect(panel).toHaveTextContent("2. Paste when prompted for a token");
     expect(panel).not.toHaveTextContent("secret-token");
     fireEvent.click(

package/src/components/editor/actions/__tests__/pair-with-agent.test.tsx

@@ -60,18 +60,18 @@ describe("PairWithAgent", () => {
     ).toBeVisible();
     expect(
       screen.getByRole("button", {
-        name: "Pair your agent",
+        name: "Set up pairing",
       }),
     ).toBeVisible();
   });
 
-  it("opens the pairing dialog from the banner description", () => {
+  it("opens the pairing dialog from the banner button", () => {
     stubTokenFetch();
     render(<PairWithAgentBanner />, { wrapper });
 
     fireEvent.click(
       screen.getByRole("button", {
-        name: "Pair your agent",
+        name: "Set up pairing",
       }),
     );
 

package/src/components/editor/actions/pair-with-agent-modal.tsx

@@ -118,7 +118,7 @@ export const PairWithAgentModal: React.FC<{
       <DialogHeader>
         <DialogTitle>Pair an agent</DialogTitle>
         <DialogDescription>
-          Use an AI coding agent to pair-program on this notebook.{" "}
+          Use an AI coding agent to pair program on this notebook.{" "}
           <a
             href="https://links.marimo.app/marimo-pair"
             target="_blank"
@@ -159,7 +159,7 @@ export const PairWithAgentModal: React.FC<{
               className="mt-4 flex flex-col gap-4"
             >
               <Step
-                index={1}
+                index={hasToken ? 1 : undefined}
                 title="Run in your terminal"
                 hint={
                   hostEnabled && tab === "opencode"
@@ -191,7 +191,6 @@ export const PairWithAgentModal: React.FC<{
 
           <TabsContent value="prompt" className="mt-4 flex flex-col gap-4">
             <Step
-              index={1}
               title="Copy this prompt into your agent"
               hint={
                 hasToken
@@ -224,7 +223,7 @@ export const PairWithAgentModal: React.FC<{
 };
 
 const Step: React.FC<{
-  index: number;
+  index?: number;
   title: string;
   hint?: string;
   children: React.ReactNode;
@@ -232,7 +231,8 @@ const Step: React.FC<{
   <div className="flex flex-col gap-2">
     <div className="flex items-baseline gap-2">
       <span className="text-sm font-medium">
-        {index}. {title}
+        {index !== undefined && `${index}. `}
+        {title}
       </span>
       {hint && <span className="text-xs text-muted-foreground">{hint}</span>}
     </div>

package/src/components/editor/actions/pair-with-agent.tsx

@@ -1,6 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import { BotIcon } from "lucide-react";
+import { ArrowUpRightIcon, BotIcon } from "lucide-react";
 import React from "react";
 import { AiProviderIcon } from "@/components/ai/ai-provider-icon";
 import { useImperativeModal } from "@/components/modal/ImperativeModal";
@@ -72,7 +72,7 @@ export const PairWithAgentBanner: React.FC<{
   return (
     <div
       className={cn(
-        "rounded-lg border border-(--blue-6) bg-(--blue-2)/50 p-3",
+        "rounded-lg border border-border bg-muted/30 p-3",
         className,
       )}
     >
@@ -103,18 +103,21 @@ export const PairWithAgentBanner: React.FC<{
         </fieldset>
       </div>
       <div className="mt-1 text-xs leading-relaxed">
-        <p className="inline">
+        <p>
           Pair your coding agent with this notebook to edit and run cells,
           inspect variables, and more, straight from your agent's CLI or user
           interface.
         </p>
-        <button
+        <Button
           type="button"
+          variant="outline"
+          size="xs"
           onClick={openPairWithAgentModal}
-          className="text-link hover:underline ml-1"
+          className="mt-3 gap-1"
         >
-          Pair your agent
-        </button>
+          Set up pairing
+          <ArrowUpRightIcon className="size-3.5" aria-hidden={true} />
+        </Button>
       </div>
     </div>
   );

package/src/core/notebook/replica/__tests__/executions.test.ts

@@ -0,0 +1,201 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import * as Protocol from "@marimo-team/client/protocol";
+import { executions, itemsInOrder } from "../resources/executions";
+import { createNotebookReducer } from "@marimo-team/client";
+import { fixtureEvents } from "./fixtures";
+
+const reducer = createNotebookReducer({ executions });
+const snapshot = fixtureEvents("notebook-events.sse");
+const runCells = fixtureEvents("run-cells.sse");
+const inputs = fixtureEvents("inputs.sse");
+const time = "2026-10-01T09:30:00Z";
+
+function replay(
+  events: readonly Protocol.EventOutput[],
+  from = reducer.initial,
+) {
+  return events.reduce(reducer.reduce, from);
+}
+
+const resource = (state: ReturnType<typeof replay>) =>
+  state.resources.executions;
+
+/** Build one event as the stream would deliver it. */
+const event = (message: unknown) => Protocol.Event.parse(message);
+
+const removed = (kind: string, id: string, cursor: string) =>
+  event({ event: `${kind}.removed`, id: cursor, data: { id, time } });
+
+/** How the host retires a cell execution: its items first, then itself. */
+const retire = (executionId: string, variableId: string) => [
+  removed("variable", variableId, "111"),
+  removed("execution", executionId, "112"),
+];
+
+const ids = (holder: Parameters<typeof itemsInOrder>[0]) =>
+  itemsInOrder(holder).map((item) => item.id);
+
+describe("executions resource", () => {
+  it("keeps scratch work from the snapshot and completes it after ready", () => {
+    const ready = snapshot.findIndex((item) => item.event === "ready");
+    const opening = resource(replay(snapshot.slice(0, ready + 1)));
+    const scratch = opening.executions.get("e7");
+    expect(scratch?.record.status).toBe("running");
+    expect(itemsInOrder(scratch!).map((item) => item.kind)).toEqual([
+      "console",
+    ]);
+    expect(opening.runs.get("run-scratch")?.status).toBe("running");
+    expect(opening.latest.size).toBe(0);
+
+    const done = resource(replay(snapshot));
+    expect(done.executions.get("e7")?.record.status).toBe("completed");
+    expect(done.runs.get("run-scratch")?.outcome).toBe("succeeded");
+    const released = reducer.reduce(
+      replay(snapshot),
+      removed("run", "run-scratch", "98"),
+    );
+    expect(resource(released).runs.has("run-scratch")).toBe(false);
+  });
+
+  it("indexes a cell's execution while it is on the stream", () => {
+    const start = replay(snapshot);
+    const running = resource(replay(runCells.slice(0, 5), start));
+    expect(running.latest.get("c3")).toBe("e12");
+    expect(running.executions.get("e12")?.record.status).toBe("running");
+    expect(running.latest.get("k7f2")).toBe("e13");
+    expect(running.runs.get("run-cells")?.status).toBe("running");
+
+    const done = replay(runCells, start);
+    const e12 = resource(done).executions.get("e12");
+    expect(e12?.record.status).toBe("completed");
+    expect([...e12!.variables.values()].map((v) => v.name)).toEqual(["x"]);
+    expect(resource(done).executions.get("e13")?.record.depends_on).toEqual({
+      x: { execution: "e12", update: 0 },
+    });
+    expect(resource(done).runs.get("run-cells")?.outcome).toBe("succeeded");
+
+    const retired = replay(retire("e12", "e12-x"), done);
+    expect(resource(retired).executions.has("e12")).toBe(false);
+    expect(resource(retired).latest.has("c3")).toBe(false);
+    const queued = reducer.reduce(
+      retired,
+      event({
+        event: "execution",
+        id: "113",
+        data: {
+          execution: {
+            ...e12!.record,
+            id: "e14",
+            run_id: "run-again",
+            status: "queued",
+            outcome: null,
+            started_at: null,
+            completed_at: null,
+          },
+        },
+      }),
+    );
+    expect(resource(queued).latest.get("c3")).toBe("e14");
+    expect([...resource(queued).executions.keys()]).toEqual([
+      "e7",
+      "e13",
+      "e14",
+    ]);
+  });
+
+  it("applies item and variable removals to the stream's copy", () => {
+    const done = replay(runCells, replay(snapshot));
+    const late = {
+      id: "o9",
+      execution_id: "e12",
+      seq: 0,
+      name: "stdout",
+      text: "late\n",
+    };
+    const shown = {
+      id: "d1",
+      execution_id: "e12",
+      seq: 1,
+      mimetype: "text/plain",
+      data: "figure",
+    };
+    const added = replay(
+      [
+        event({ event: "console", id: "111", data: { console: late } }),
+        event({ event: "display", id: "112", data: { display: shown } }),
+      ],
+      done,
+    );
+    expect(ids(resource(added).executions.get("e12")!)).toEqual(["o9", "d1"]);
+
+    const cleared = replay(
+      [
+        removed("display", "d1", "113"),
+        removed("console", "o9", "114"),
+        removed("variable", "e12-x", "115"),
+      ],
+      added,
+    );
+    const e12 = resource(cleared).executions.get("e12")!;
+    expect(ids(e12)).toEqual([]);
+    expect(e12.variables.size).toBe(0);
+    expect(resource(cleared).latest.get("c3")).toBe("e12");
+  });
+
+  it("orders items by seq, replaces them by id, and drops orphans", () => {
+    const start = replay(snapshot);
+    const prompted = resource(replay(inputs.slice(0, -1), start));
+    const execution = prompted.executions.get("e-input");
+    expect(
+      itemsInOrder(execution!).map((item) => [
+        item.kind,
+        item.id,
+        item.kind === "input" ? item.status : item.seq,
+      ]),
+    ).toEqual([
+      ["console", "o-input-0", 0],
+      ["input", "i1", "answered"],
+      ["console", "o-input-2", 2],
+      ["input", "i2", "cancelled"],
+    ]);
+    expect(prompted.latest.size).toBe(0);
+    const gone = resource(replay(inputs, start));
+    expect(gone.executions.has("e-input")).toBe(false);
+    expect(gone.runs.get("run-input")?.outcome).toBe("interrupted");
+
+    const orphan = reducer.reduce(
+      start,
+      event({
+        event: "console",
+        id: "400",
+        data: {
+          console: {
+            id: "o-orphan",
+            execution_id: "nope",
+            seq: 0,
+            name: "stdout",
+            text: "",
+          },
+        },
+      }),
+    );
+    expect(orphan.resources).toBe(start.resources);
+  });
+
+  it("ignores removals delivered again", () => {
+    const retired = replay(
+      retire("e12", "e12-x"),
+      replay(runCells, replay(snapshot)),
+    );
+    const again = replay(retire("e12", "e12-x"), retired);
+    expect(again.resources).toBe(retired.resources);
+  });
+
+  it("clears on reset", () => {
+    const done = replay(runCells, replay(snapshot));
+    const reset = reducer.reduce(done, { event: "reset", data: {} });
+    expect(resource(reset)).toBe(executions.initial);
+  });
+});

package/src/core/notebook/replica/__tests__/replica.test.ts

@@ -231,6 +231,8 @@ describe("NotebookReplica lifetime", () => {
       "k7f2",
     ]);
     expect(store.get(client.runtimeAtom)?.id).toBe("r1");
+    expect(store.get(client.executionsAtom).runs.has("run-scratch")).toBe(true);
+    expect(store.get(client.resultsAtom).size).toBe(3);
     attempt.drop();
     await backoff();
     expect(store.get(client.documentAtom)?.revision.order).toEqual([
@@ -239,8 +241,12 @@ describe("NotebookReplica lifetime", () => {
       "k7f2",
     ]);
     expect(store.get(client.runtimeAtom)).toBeNull();
+    expect(store.get(client.executionsAtom).runs.has("run-scratch")).toBe(true);
+    expect(store.get(client.resultsAtom).size).toBe(3);
     current.abort();
     expect(store.get(client.documentAtom)).toBeNull();
+    expect(store.get(client.executionsAtom).runs.size).toBe(0);
+    expect(store.get(client.resultsAtom).size).toBe(0);
   });
 
   it.each([

package/src/core/notebook/replica/__tests__/results.test.ts

@@ -0,0 +1,193 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import * as Protocol from "@marimo-team/client/protocol";
+import { results } from "../resources/results";
+import { createNotebookReducer } from "@marimo-team/client";
+import { fixtureEvents } from "./fixtures";
+
+const reducer = createNotebookReducer({ results });
+const snapshot = fixtureEvents("notebook-events.sse");
+const runCells = fixtureEvents("run-cells.sse");
+const time = "2026-10-01T09:30:00Z";
+
+function replay(
+  events: readonly Protocol.EventOutput[],
+  from = reducer.initial,
+) {
+  return events.reduce(reducer.reduce, from);
+}
+
+const resource = (state: ReturnType<typeof replay>) => state.resources.results;
+
+/** Build one event as the stream would deliver it. */
+const event = (message: unknown) => Protocol.Event.parse(message);
+
+const removed = (kind: string, id: string, cursor: string) =>
+  event({ event: `${kind}.removed`, id: cursor, data: { id, time } });
+
+/** How the host retires a cell execution: its items first, then itself. */
+const retire = (executionId: string, variableId: string) => [
+  removed("variable", variableId, "111"),
+  removed("execution", executionId, "112"),
+];
+
+const restored = {
+  id: "e-restored",
+  run_id: null,
+  runtime_id: null,
+  caused_by: null,
+  cell_id: "c3",
+  code: null,
+  code_hash: "0f71456db2ea83f4",
+  depends_on: {},
+  status: "completed",
+  outcome: { kind: "value", display: null },
+  started_at: "2026-09-30T09:20:01Z",
+  completed_at: "2026-09-30T09:20:02Z",
+};
+
+describe("results resource", () => {
+  it("has an entry per document cell, filled by a restored result", () => {
+    const ready = snapshot.findIndex((item) => item.event === "ready");
+    const opening = resource(replay(snapshot.slice(0, ready + 1)));
+    expect([...opening]).toEqual([
+      ["c1", null],
+      ["c3", null],
+      ["k7f2", null],
+    ]);
+
+    const opened = resource(
+      replay([
+        ...snapshot.slice(0, ready),
+        event({ event: "execution", id: "94", data: { execution: restored } }),
+        ...snapshot.slice(ready),
+      ]),
+    );
+    expect(opened.get("c3")?.id).toBe("e-restored");
+    expect(opened.get("c3")?.run_id).toBeNull();
+  });
+
+  it("records a cell's result when its execution completes", () => {
+    const start = replay(snapshot);
+    const running = resource(replay(runCells.slice(0, 5), start));
+    expect(running.get("c3")).toBeNull();
+    expect(running.get("k7f2")).toBeNull();
+
+    const done = resource(replay(runCells, start));
+    expect(done.get("c3")?.id).toBe("e12");
+    expect(done.get("c3")?.status).toBe("completed");
+    expect(done.get("k7f2")?.depends_on).toEqual({
+      x: { execution: "e12", update: 0 },
+    });
+    expect(done.get("c1")).toBeNull();
+  });
+
+  it("keeps a result while the host replaces it", () => {
+    const done = replay(runCells, replay(snapshot));
+    const result = resource(done).get("c3")!;
+    const retired = replay(retire("e12", "e12-x"), done);
+    expect(resource(retired).get("c3")).toBe(result);
+
+    const again = {
+      ...result,
+      id: "e14",
+      run_id: "run-again",
+      status: "queued",
+      outcome: null,
+      started_at: null,
+      completed_at: null,
+    };
+    const queued = reducer.reduce(
+      retired,
+      event({ event: "execution", id: "113", data: { execution: again } }),
+    );
+    expect(resource(queued).get("c3")).toBe(result);
+
+    const completed = reducer.reduce(
+      queued,
+      event({
+        event: "execution",
+        id: "114",
+        data: {
+          execution: {
+            ...again,
+            status: "completed",
+            outcome: { kind: "value", display: null },
+            started_at: time,
+            completed_at: time,
+          },
+        },
+      }),
+    );
+    expect(resource(completed).get("c3")?.id).toBe("e14");
+  });
+
+  it("replaces a result with an execution interrupted before it started", () => {
+    const done = replay(runCells, replay(snapshot));
+    const result = resource(done).get("c3")!;
+    const interrupted = {
+      ...result,
+      id: "e14",
+      run_id: "run-again",
+      status: "completed",
+      outcome: { kind: "interrupted" },
+      started_at: null,
+      completed_at: time,
+    };
+    const cancelled = replay(
+      [
+        ...retire("e12", "e12-x"),
+        event({
+          event: "execution",
+          id: "113",
+          data: {
+            execution: {
+              ...interrupted,
+              status: "queued",
+              outcome: null,
+              completed_at: null,
+            },
+          },
+        }),
+        event({
+          event: "execution",
+          id: "114",
+          data: { execution: interrupted },
+        }),
+      ],
+      done,
+    );
+    expect(resource(cancelled).get("c3")?.outcome).toEqual({
+      kind: "interrupted",
+    });
+  });
+
+  it("drops a cell deleted while its execution runs", () => {
+    const start = replay(runCells.slice(0, 5), replay(snapshot));
+    const deleted = reducer.reduce(start, removed("cell", "c3", "105"));
+    expect(resource(deleted).has("c3")).toBe(false);
+
+    const finished = replay(runCells.slice(5), deleted);
+    expect(resource(finished).has("c3")).toBe(false);
+    expect(resource(finished).get("k7f2")?.id).toBe("e13");
+  });
+
+  it("ignores cells it has not seen and clears on reset", () => {
+    const start = replay(snapshot);
+    const unknown = reducer.reduce(
+      start,
+      event({
+        event: "execution",
+        id: "98",
+        data: { execution: { ...restored, id: "e-zz", cell_id: "zz" } },
+      }),
+    );
+    expect(unknown.resources).toBe(start.resources);
+    const reset = reducer.reduce(replay(runCells, start), {
+      event: "reset",
+      data: {},
+    });
+    expect(resource(reset)).toBe(results.initial);
+  });
+});

package/src/core/notebook/replica/index.ts

@@ -11,3 +11,10 @@ export {
 } from "./connection";
 export { createNotebookReplica, type NotebookReplica } from "./replica";
 export type { Document } from "./resources/document";
+export {
+  type Execution,
+  type Executions,
+  type Item,
+  itemsInOrder,
+} from "./resources/executions";
+export type { Results } from "./resources/results";

package/src/core/notebook/replica/replica.ts

@@ -24,15 +24,26 @@ import {
 } from "./connection";
 import { attachments } from "./resources/attachments";
 import { type Document, document } from "./resources/document";
+import { type Executions, executions } from "./resources/executions";
+import { type Results, results } from "./resources/results";
 import { runtime } from "./resources/runtime";
 
-/** The kinds the editor reads, with marimo's own notifications. */
+/**
+ * The kinds the editor reads, with marimo's own notifications.
+ *
+ * Console and display items stay out until the editor reads outputs from
+ * the replica. The native notifications still carry them.
+ */
 const TYPES = [
   "notebook",
   "cell",
   "document",
   "attachment",
   "runtime",
+  "run",
+  "execution",
+  "input",
+  "variable",
   "marimo",
 ] as const;
 
@@ -66,6 +77,17 @@ export interface NotebookReplica {
   readonly attachmentsAtom: Atom<readonly Attachment[]>;
   /** The notebook's runtime, null while it has none or the stream is not ready. */
   readonly runtimeAtom: Atom<Runtime | null>;
+  /**
+   * Runs and executions as the stream reports them.
+   *
+   * Visible as events arrive, including during a snapshot, so a consumer
+   * joins with `documentAtom`, which is null until the snapshot is ready.
+   * Kept across a temporary disconnection, like the document, and cleared
+   * on reset or removal.
+   */
+  readonly executionsAtom: Atom<Executions>;
+  /** Each document cell's last completed execution record, kept while it runs again. */
+  readonly resultsAtom: Atom<Results>;
   /**
    * Follow a backend, replacing any current connection.
    *
@@ -124,7 +146,13 @@ export function createNotebookReplica(
     state: ConnectionState.NOT_STARTED,
   });
   // One atom holds the whole stream, which resource atoms derive from.
-  const reducer = createNotebookReducer({ document, attachments, runtime });
+  const reducer = createNotebookReducer({
+    document,
+    attachments,
+    runtime,
+    executions,
+    results,
+  });
   const streamAtom = atom(reducer.initial);
   // A resumed stream is live, but presence waits for this connection's ready.
   const readyAtom = atom(false);
@@ -146,6 +174,8 @@ export function createNotebookReplica(
   const runtimeAtom = atom((get) =>
     get(presentAtom) ? get(streamAtom).resources.runtime : null,
   );
+  const executionsAtom = atom((get) => get(streamAtom).resources.executions);
+  const resultsAtom = atom((get) => get(streamAtom).resources.results);
   const backendAtom = atom<NotebookBackend | null>(null);
   /** The connection this replica follows. Connecting again ends it. */
   let current: { end(): void; reconnect(): Promise<void> } | undefined;
@@ -168,6 +198,8 @@ export function createNotebookReplica(
     backendAtom,
     attachmentsAtom,
     runtimeAtom,
+    executionsAtom,
+    resultsAtom,
     connect,
     reconnect: async () => current?.reconnect(),
   };