Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Add `NotebookEvents` to `@marimo-team/client` (#11391)

Trevor Manzdd4d66d63a2a
diff --git a/packages/client/README.md b/packages/client/README.md
index 13cc91e9a5..1cc9f38dec 100644
--- a/packages/client/README.md
+++ b/packages/client/README.md
@@ -7,6 +7,13 @@ for one notebook, addressed by the notebook's URL. Request bodies are
validated before they are sent, and the host's answer comes back as data or a
problem.
+`NotebookEvents` follows a notebook's stream. The stream starts with a
+snapshot that ends in `ready` and then delivers changes. When a connection
+drops, the stream resumes from the last event it received. When it cannot,
+it delivers `reset` and a fresh snapshot follows. Given a URL, it follows the
+stream over server-sent events, as the protocol defines. Given a
+`NotebookTransport`, it follows whatever connection the transport opens.
+
```ts
import { NotebookClient } from "@marimo-team/client";
@@ -21,11 +28,17 @@ const result = await notebook.edit([
if (!result.ok) {
console.error(result.problem.type);
}
+
+for await (const event of notebook.events({ types: ["cell", "document"] })) {
+ if (event.event === "reset") {
+ // Discard what you built. A fresh snapshot follows.
+ }
+}
```
## Entry points
-- `@marimo-team/client` exports `NotebookClient`.
+- `@marimo-team/client` exports `NotebookClient` and `NotebookEvents`.
- `@marimo-team/client/protocol` has the protocol's types and zod 4 schemas,
generated from `protocols/host/openapi.yaml`. Use the schemas to validate
protocol data yourself, for example in a host or a conformance test.
diff --git a/packages/client/src/__tests__/notebook-client.test.ts b/packages/client/src/__tests__/notebook-client.test.ts
index 6d652f3d57..8768d816de 100644
--- a/packages/client/src/__tests__/notebook-client.test.ts
+++ b/packages/client/src/__tests__/notebook-client.test.ts
@@ -5,7 +5,6 @@ import NodeUrl from "node:url";
import { afterEach, describe, expect, expectTypeOf, it, vi } from "vitest";
import { z } from "zod";
import { NotebookClient } from "../notebook/client.ts";
-import type { OperationId } from "../operations.ts";
import type { OperationsBelow } from "../request.ts";
import type * as Protocol from "../protocol.ts";
@@ -78,10 +77,12 @@ describe("NotebookClient", () => {
);
await notebook.delete();
await notebook.interrupt("r/1");
- expect(fetch.mock.calls.map(([url]) => String(url))).toEqual([
- "http://localhost/api/marimo/v1/notebooks/n1?session_id=s1",
- "http://localhost/api/marimo/v1/notebooks/n1/runtime/runs/r%2F1?session_id=s1",
- ]);
+ expect(fetch.mock.calls.map(([url]) => String(url))).toMatchInlineSnapshot(`
+ [
+ "http://localhost/api/marimo/v1/notebooks/n1?session_id=s1",
+ "http://localhost/api/marimo/v1/notebooks/n1/runtime/runs/r%2F1?session_id=s1",
+ ]
+ `);
});
it("accepts problems and reads their media type without regard to case", async () => {
@@ -186,7 +187,8 @@ describe("NotebookClient", () => {
});
it("has a method for each request below a notebook", () => {
- const methods = {
+ // A new operation below a notebook fails this until it has a method.
+ expectTypeOf({
"notebook.update": "update",
"notebook.delete": "delete",
"notebook.open": "open",
@@ -197,13 +199,6 @@ describe("NotebookClient", () => {
"runtime.restart": "restart",
"runtime.run": "run",
"runtime.interrupt": "interrupt",
- } as const satisfies Record<NotebookOperationId, keyof NotebookClient>;
- expectTypeOf<Exclude<keyof NotebookClient, "url">>().toEqualTypeOf<
- (typeof methods)[NotebookOperationId]
- >();
- // Streams and host-level operations come with NotebookEvents and Client.
- expectTypeOf<Exclude<OperationId, NotebookOperationId>>().toEqualTypeOf<
- "events" | "notebook.create" | "notebook.events"
- >();
+ } as const).toExtend<Record<NotebookOperationId, keyof NotebookClient>>();
});
});
diff --git a/packages/client/src/__tests__/notebook-events.test.ts b/packages/client/src/__tests__/notebook-events.test.ts
new file mode 100644
index 0000000000..0c639e7108
--- /dev/null
+++ b/packages/client/src/__tests__/notebook-events.test.ts
@@ -0,0 +1,502 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import NodeFs from "node:fs";
+import NodeUrl from "node:url";
+import { afterEach, describe, expect, expectTypeOf, it, vi } from "vitest";
+import { NotebookClient } from "../notebook/client.ts";
+import { NotebookEvents } from "../notebook/events.ts";
+import type { NotebookEvent } from "../notebook/stream.ts";
+import { type NotebookTransport, StreamStopped } from "../transport/frame.ts";
+import { ServerSentEventStream } from "../transport/sse.ts";
+
+const fixtures = new NodeUrl.URL(
+ "../../../../protocols/host/fixtures/",
+ import.meta.url,
+);
+const snapshot = NodeFs.readFileSync(
+ new NodeUrl.URL("notebook-events.sse", fixtures),
+ "utf8",
+);
+/** The fixture's frames up to and including `ready`. */
+const throughReady = snapshot.slice(0, snapshot.indexOf("id: 96\n"));
+
+const encoder = new TextEncoder();
+
+/** A response body the test writes to. */
+function body() {
+ let controller!: ReadableStreamDefaultController<Uint8Array>;
+ const stream = new ReadableStream<Uint8Array>({
+ start(c) {
+ controller = c;
+ },
+ });
+ return {
+ response: new Response(stream, {
+ headers: { "Content-Type": "text/event-stream" },
+ }),
+ push: (text: string) => controller.enqueue(encoder.encode(text)),
+ end: () => controller.close(),
+ };
+}
+
+/** A fetch that answers each connection with the next response. */
+function answering(...responses: Response[]) {
+ const fetch = vi.fn(
+ async (_input: RequestInfo | URL, _init?: RequestInit) => {
+ const response = responses.shift();
+ if (response === undefined) {
+ return new Promise<Response>(() => undefined);
+ }
+ return response;
+ },
+ );
+ const sent = (index: number) => new Request(...fetch.mock.calls[index]);
+ return { fetch, sent };
+}
+
+function collect<K extends string>(events: NotebookEvents<K>) {
+ const received: NotebookEvent<K>[] = [];
+ events.subscribe((event) => received.push(event));
+ return received;
+}
+
+const url = "http://127.0.0.1:2718/api/marimo/v1/notebooks/n1/events";
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+});
+
+/** Parse text chunks as a host would send them. */
+async function parse(chunks: string[]) {
+ const reader = new ReadableStream<string>({
+ start(controller) {
+ chunks.forEach((chunk) => controller.enqueue(chunk));
+ controller.close();
+ },
+ })
+ .pipeThrough(new ServerSentEventStream())
+ .getReader();
+ const frames = [];
+ for (let read = await reader.read(); !read.done; read = await reader.read()) {
+ frames.push(read.value);
+ }
+ return frames;
+}
+
+describe("ServerSentEventStream", () => {
+ it("parses names, ids, multiline data, and comments across chunks", async () => {
+ expect(
+ await parse([
+ ': ping\r\nevent: cell\ndata: {"a":',
+ "\ndata: 1}\nid: 7\n\n",
+ "data: plain text\n\n",
+ ]),
+ ).toMatchInlineSnapshot(`
+ [
+ {
+ "data": {
+ "a": 1,
+ },
+ "event": "cell",
+ "id": "7",
+ },
+ {
+ "data": "plain text",
+ "event": "message",
+ },
+ ]
+ `);
+ });
+
+ it("reads a CRLF split across chunks as one line break", async () => {
+ expect(await parse(["event: cell\r", '\ndata: {"a":1}\r\n\r\n']))
+ .toMatchInlineSnapshot(`
+ [
+ {
+ "data": {
+ "a": 1,
+ },
+ "event": "cell",
+ },
+ ]
+ `);
+ });
+});
+
+/** A fetch that never answers until it is aborted. */
+function unanswered() {
+ return vi.fn(
+ (_input: RequestInfo | URL, init?: RequestInit) =>
+ new Promise<Response>((_, reject) => {
+ init?.signal?.addEventListener("abort", () =>
+ reject(new DOMException("Aborted", "AbortError")),
+ );
+ }),
+ );
+}
+
+describe("NotebookEvents", () => {
+ it("follows one run", async () => {
+ const { fetch, sent } = answering();
+ const events = new NotebookEvents(url, { runId: "r1", fetch });
+ await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(1));
+ expect(sent(0).url).toBe(`${url}?run_id=r1`);
+ events.close();
+ });
+
+ it("retries statuses that ask the client to try again", async () => {
+ vi.useFakeTimers();
+ const stream = body();
+ const { fetch } = answering(
+ new Response(null, { status: 429 }),
+ stream.response,
+ );
+ const events = new NotebookEvents(url, { fetch });
+ await vi.advanceTimersByTimeAsync(2000);
+ stream.push(throughReady);
+ await vi.waitFor(() => expect(events.cursor).toBe("95"));
+ events.close();
+ });
+
+ it("stops when the host answers with something other than events", async () => {
+ const events = new NotebookEvents(url, {
+ fetch: answering(
+ new Response("<html>", { headers: { "Content-Type": "text/html" } }),
+ ).fetch,
+ });
+ await expect(events.closed).rejects.toThrow("not answer with an event");
+ });
+
+ it("retries a host that accepts the request but never answers", async () => {
+ vi.useFakeTimers();
+ const fetch = unanswered();
+ const events = new NotebookEvents(url, { fetch });
+ await vi.advanceTimersByTimeAsync(45_000 + 2000);
+ expect(fetch).toHaveBeenCalledTimes(2);
+ events.close();
+ });
+
+ it("delivers a snapshot through ready and records the cursor", async () => {
+ const stream = body();
+ const { fetch, sent } = answering(stream.response);
+ const events = new NotebookEvents(url, {
+ token: "secret",
+ types: ["cell", "document"],
+ fetch,
+ });
+ const received = collect(events);
+ stream.push(throughReady);
+
+ await vi.waitFor(() => expect(events.cursor).toBe("95"));
+ expect(received.map((event) => event.event)).toMatchInlineSnapshot(`
+ [
+ "cell",
+ "cell",
+ "cell",
+ "document",
+ "ready",
+ ]
+ `);
+ expect(events.status).toBe("connected");
+ const request = sent(0);
+ expect(request.url).toBe(`${url}?types=cell%2Cdocument`);
+ expect(request.headers.get("Authorization")).toBe("Bearer secret");
+ expect(request.headers.get("Last-Event-ID")).toBeNull();
+ events.close();
+ await expect(events.closed).resolves.toBeUndefined();
+ expect(events.status).toBe("closed");
+ });
+
+ it("narrows events to the requested kinds", () => {
+ const events = new NotebookEvents(url, {
+ types: ["cell", "marimo"],
+ fetch: answering().fetch,
+ });
+ events.close();
+ expectTypeOf<NotebookEvent<"cell" | "marimo">["event"]>().toEqualTypeOf<
+ "cell" | "cell.removed" | "ready" | "reset" | "marimo"
+ >();
+ events.subscribe((event) => {
+ if (event.event === "cell") {
+ expectTypeOf(event.data.cell.id).toBeString();
+ } else if (event.event === "marimo") {
+ expectTypeOf(event.data).toBeUnknown();
+ }
+ });
+ });
+
+ it("resumes from its cursor after the connection drops", async () => {
+ vi.useFakeTimers();
+ const first = body();
+ const second = body();
+ const { fetch, sent } = answering(first.response, second.response);
+ const statuses: string[] = [];
+ const events = new NotebookEvents(url, {
+ fetch,
+ onStatus: (status) => statuses.push(status),
+ });
+ first.push(snapshot);
+ await vi.waitFor(() => expect(events.cursor).toBe("97"));
+ first.end();
+ await vi.advanceTimersByTimeAsync(2000);
+ await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(2));
+ expect(sent(1).headers.get("Last-Event-ID")).toBe("97");
+ expect(statuses).toMatchInlineSnapshot(`
+ [
+ "connected",
+ "connecting",
+ "connected",
+ ]
+ `);
+ events.close();
+ });
+
+ it("delivers reset before replacing an interrupted snapshot", async () => {
+ vi.useFakeTimers();
+ const first = body();
+ const second = body();
+ const { fetch, sent } = answering(first.response, second.response);
+ const events = new NotebookEvents(url, { types: ["cell"], fetch });
+ const received = collect(events);
+ first.push(throughReady.slice(0, throughReady.indexOf("event: document")));
+ await vi.waitFor(() => expect(received).toHaveLength(3));
+ first.end();
+ await vi.advanceTimersByTimeAsync(2000);
+ second.push(throughReady);
+ await vi.waitFor(() => expect(events.cursor).toBe("95"));
+ expect(sent(1).headers.get("Last-Event-ID")).toBeNull();
+ expect(received.map((event) => event.event)).toMatchInlineSnapshot(`
+ [
+ "cell",
+ "cell",
+ "cell",
+ "reset",
+ "cell",
+ "cell",
+ "cell",
+ "ready",
+ ]
+ `);
+ events.close();
+ });
+
+ it("clears the cursor on reset and keeps it across unknown kinds", async () => {
+ const stream = body();
+ const events = new NotebookEvents(url, {
+ types: ["marimo"],
+ fetch: answering(stream.response).fetch,
+ });
+ const received = collect(events);
+ stream.push(throughReady);
+ stream.push("id: 98\nevent: future\ndata: {}\n\n");
+ stream.push('id: 99\nevent: marimo\ndata: {"marimo":{"op":"x"}}\n\n');
+ await vi.waitFor(() => expect(events.cursor).toBe("99"));
+ stream.push("event: reset\ndata: {}\n\n");
+ await vi.waitFor(() => expect(events.cursor).toBeNull());
+ expect(received).toMatchInlineSnapshot(`
+ [
+ {
+ "data": {},
+ "event": "ready",
+ "id": "95",
+ },
+ {
+ "data": {
+ "marimo": {
+ "op": "x",
+ },
+ },
+ "event": "marimo",
+ "id": "99",
+ },
+ {
+ "data": {},
+ "event": "reset",
+ },
+ ]
+ `);
+ events.close();
+ });
+
+ it("stays connected through pings longer than the silence limit", async () => {
+ vi.useFakeTimers();
+ const stream = body();
+ const { fetch } = answering(stream.response);
+ const events = new NotebookEvents(url, { fetch });
+ stream.push(throughReady);
+ await vi.waitFor(() => expect(events.status).toBe("connected"));
+ for (let i = 0; i < 6; i++) {
+ await vi.advanceTimersByTimeAsync(15_000);
+ stream.push(": ping\n\n");
+ }
+ expect(fetch).toHaveBeenCalledTimes(1);
+ await vi.advanceTimersByTimeAsync(46_000);
+ expect(events.status).toBe("connecting");
+ events.close();
+ });
+
+ it("stops with the problem when the host refuses the stream", async () => {
+ const problem = {
+ type: "tag:marimo.io,2026:host/not-found",
+ title: "Not found",
+ status: 404,
+ };
+ const events = new NotebookEvents(url, {
+ fetch: answering(
+ new Response(JSON.stringify(problem), {
+ status: 404,
+ headers: { "Content-Type": "application/problem+json" },
+ }),
+ ).fetch,
+ });
+ const error = await events.closed.catch((error: unknown) => error);
+ expect(error).toBeInstanceOf(StreamStopped);
+ expect((error as StreamStopped).cause).toEqual(problem);
+ expect(events.status).toBe("closed");
+ });
+
+ it.each([
+ 'event: cell\ndata: {"cell":{"id":"c1"}}\n\n',
+ "event: reset\ndata: 5\n\n",
+ ])("stops on an invalid protocol event: %j", async (frame) => {
+ const stream = body();
+ const events = new NotebookEvents(url, {
+ fetch: answering(stream.response).fetch,
+ });
+ stream.push(frame);
+ await expect(events.closed).rejects.toThrow(/invalid (cell|reset) event/);
+ });
+
+ it("delivers nothing after it closes", async () => {
+ const stream = body();
+ const events = new NotebookEvents(url, {
+ fetch: answering(stream.response).fetch,
+ });
+ const received = collect(events);
+ events.close();
+ stream.push(throughReady);
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ expect(received).toEqual([]);
+ });
+
+ it("iterates until the caller leaves the loop", async () => {
+ const stream = body();
+ const events = new NotebookEvents(url, {
+ types: ["cell"],
+ fetch: answering(stream.response).fetch,
+ });
+ stream.push(throughReady);
+ const names: string[] = [];
+ for await (const event of events) {
+ names.push(event.event);
+ if (event.event === "ready") {
+ break;
+ }
+ }
+ expect(names).toMatchInlineSnapshot(`
+ [
+ "cell",
+ "cell",
+ "cell",
+ "ready",
+ ]
+ `);
+ expect(events.status).toBe("closed");
+ await expect(events.closed).resolves.toBeUndefined();
+ });
+
+ it("follows a stream through a custom transport", async () => {
+ vi.useFakeTimers();
+ const attempts: (string | null)[] = [];
+ const transport: NotebookTransport = async ({ cursor }, handlers) => {
+ attempts.push(cursor);
+ handlers.open();
+ if (attempts.length === 1) {
+ handlers.message({ event: "ready", id: "41", data: {} });
+ return;
+ }
+ handlers.message({ event: "marimo", id: "42", data: { marimo: {} } });
+ throw new StreamStopped("Shutting down", { cause: "MARIMO_SHUTDOWN" });
+ };
+ const events = new NotebookEvents(transport, { types: ["marimo"] });
+ const received = collect(events);
+ await vi.advanceTimersByTimeAsync(2000);
+ const error = await events.closed.catch((error: unknown) => error);
+ expect(attempts).toMatchInlineSnapshot(`
+ [
+ null,
+ "41",
+ ]
+ `);
+ expect(received.map((event) => event.event)).toMatchInlineSnapshot(`
+ [
+ "ready",
+ "marimo",
+ ]
+ `);
+ expect((error as StreamStopped).cause).toBe("MARIMO_SHUTDOWN");
+ });
+
+ it("stays closed when a transport opens after the stream closed", async () => {
+ let open: (() => void) | undefined;
+ const transport: NotebookTransport = (_attempt, handlers) => {
+ open = handlers.open;
+ return new Promise(() => undefined);
+ };
+ const events = new NotebookEvents(transport);
+ await vi.waitFor(() => expect(open).toBeDefined());
+ events.close();
+ open?.();
+ expect(events.status).toBe("closed");
+ });
+
+ it("wakes each pending read when events arrive", async () => {
+ let message: ((message: unknown) => void) | undefined;
+ const transport: NotebookTransport = (_attempt, handlers) => {
+ message = handlers.message;
+ return new Promise(() => undefined);
+ };
+ const events = new NotebookEvents(transport, { types: ["marimo"] });
+ const iterator = events[Symbol.asyncIterator]();
+ const first = iterator.next();
+ const second = iterator.next();
+ await vi.waitFor(() => expect(message).toBeDefined());
+ message?.({ event: "marimo", id: "1", data: {} });
+ message?.({ event: "marimo", id: "2", data: {} });
+ expect((await first).value).toMatchObject({ id: "1" });
+ expect((await second).value).toMatchObject({ id: "2" });
+ await iterator.return?.();
+ expect(events.status).toBe("closed");
+ });
+
+ it("stops a custom transport that delivers an invalid message", async () => {
+ let signal: AbortSignal | undefined;
+ const transport: NotebookTransport = (attempt, handlers) =>
+ new Promise(() => {
+ signal = attempt.signal;
+ // A transport reports messages from its own listeners.
+ queueMicrotask(() => handlers.message(null));
+ });
+ const events = new NotebookEvents(transport);
+ await expect(events.closed).rejects.toThrow("not an event");
+ expect(signal?.aborted).toBe(true);
+ });
+});
+
+describe("NotebookClient.events", () => {
+ it("follows the stream below the notebook's URL with the client's connection", async () => {
+ const { fetch, sent } = answering();
+ const notebook = new NotebookClient(
+ "http://localhost/api/marimo/v1/notebooks/n1?session_id=s1",
+ { token: "secret", fetch },
+ );
+ const events = notebook.events({ types: ["cell"] });
+ await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(1));
+ expect(sent(0).url).toBe(
+ "http://localhost/api/marimo/v1/notebooks/n1/events?session_id=s1&types=cell",
+ );
+ expect(sent(0).headers.get("Authorization")).toBe("Bearer secret");
+ events.close();
+ });
+});
diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
index 5ad5f0acb7..ea6eb5aeb8 100644
--- a/packages/client/src/index.ts
+++ b/packages/client/src/index.ts
@@ -1,4 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
export { NotebookClient, type NotebookClientInit } from "./notebook/client.ts";
+export { NotebookEvents, type NotebookEventsInit } from "./notebook/events.ts";
+export type { NotebookEvent } from "./notebook/stream.ts";
export type { Result } from "./request.ts";
+export { type NotebookTransport, StreamStopped } from "./transport/frame.ts";
diff --git a/packages/client/src/notebook/client.ts b/packages/client/src/notebook/client.ts
index 163729b3fb..22e2915f9a 100644
--- a/packages/client/src/notebook/client.ts
+++ b/packages/client/src/notebook/client.ts
@@ -1,7 +1,9 @@
/* Copyright 2026 Marimo. All rights reserved. */
import type * as Protocol from "../protocol.ts";
+import type { Kind } from "../reducer.ts";
import {
+ below,
type Connection,
type MutationOptions,
type OperationsBelow,
@@ -9,6 +11,7 @@ import {
type Result,
type Target,
} from "../request.ts";
+import { NotebookEvents, type NotebookEventsInit } from "./events.ts";
/** How a `NotebookClient` reaches and authenticates with its host. */
export type NotebookClientInit = Connection;
@@ -54,6 +57,21 @@ export class NotebookClient {
return new URL(this.#url);
}
+ /**
+ * Follow the notebook's stream.
+ *
+ * The stream is served below the notebook's URL over server-sent events,
+ * and shares this client's connection.
+ */
+ public events<const K extends string = Kind>(
+ options: Omit<NotebookEventsInit<K>, keyof Connection> = {},
+ ): NotebookEvents<K> {
+ return new NotebookEvents<K>(below(this.#url, "/events"), {
+ ...this.#target.connection,
+ ...options,
+ });
+ }
+
/** Rename or move the notebook. */
public update(
changes: Protocol.UpdateNotebookRequest,
diff --git a/packages/client/src/notebook/events.ts b/packages/client/src/notebook/events.ts
new file mode 100644
index 0000000000..52f103de43
--- /dev/null
+++ b/packages/client/src/notebook/events.ts
@@ -0,0 +1,281 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as Protocol from "../protocol.ts";
+import type { Kind } from "../reducer.ts";
+import type { Connection } from "../request.ts";
+import { type NotebookTransport, StreamStopped } from "../transport/frame.ts";
+import { sse } from "../transport/sse.ts";
+import {
+ type NotebookEvent,
+ NotebookStream,
+ type NotebookStreamInit,
+ report,
+} from "./stream.ts";
+
+/** Attempts in a row without an event before the stream gives up. */
+const ATTEMPTS = 10;
+
+/** The delay before reconnecting, which grows with each attempt in a row. */
+function delay(attempt: number): number {
+ return Math.min(1000 * 1.3 ** attempt, 10_000);
+}
+
+/** Whether a stream is receiving events. */
+type Status = "connecting" | "connected" | "closed";
+
+/** How a `NotebookEvents` reaches its host and what it follows. */
+export interface NotebookEventsInit<K extends string = Kind>
+ extends Connection, NotebookStreamInit<K> {
+ /**
+ * Follow one run instead of the whole notebook.
+ *
+ * Applies to a stream at a URL. A transport filters its own requests.
+ */
+ readonly runId?: Protocol.RunId;
+ /** Aborting closes the stream. */
+ readonly signal?: AbortSignal;
+ /**
+ * Called when `status` changes.
+ *
+ * Reconnecting shows as `connecting` after `connected`.
+ */
+ readonly onStatus?: (status: Status) => void;
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+ return new Promise((resolve) => {
+ const timer = setTimeout(done, ms);
+ signal.addEventListener("abort", done, { once: true });
+ function done() {
+ clearTimeout(timer);
+ signal.removeEventListener("abort", done);
+ resolve();
+ }
+ });
+}
+
+/**
+ * A notebook stream, followed across reconnects.
+ *
+ * Given a URL, it follows the stream there over server-sent events. Given a
+ * `NotebookTransport`, it follows whatever connection the transport opens.
+ *
+ * - It starts with a snapshot that ends in `ready`, then delivers changes.
+ * - After a dropped connection it resumes from its cursor, backing off between
+ * attempts. It stops after ten attempts in a row without a message.
+ * - When it cannot resume, it delivers `reset` and a fresh snapshot follows.
+ * The caller discards what it built on `reset`.
+ */
+export class NotebookEvents<
+ const K extends string = Kind,
+> implements AsyncIterable<NotebookEvent<K>> {
+ /**
+ * Settles when the stream closes.
+ *
+ * Resolves after `close()` or an abort. Rejects with `StreamStopped` when
+ * the host refuses the stream, sends an invalid event, or cannot be reached.
+ */
+ public readonly closed: Promise<void>;
+ readonly #stream: NotebookStream<K>;
+ #status: Status = "connecting";
+ readonly #controller = new AbortController();
+ readonly #onStatus: ((status: Status) => void) | undefined;
+ #settle: { resolve(): void; reject(error: unknown): void } | undefined;
+ #release: (() => void) | undefined;
+
+ public constructor(
+ source: string | URL | NotebookTransport,
+ init: NotebookEventsInit<K> = {},
+ ) {
+ let transport: NotebookTransport;
+ if (typeof source === "function") {
+ transport = source;
+ } else {
+ const url = new URL(source);
+ if (init.types !== undefined) {
+ url.searchParams.set("types", init.types.join(","));
+ }
+ if (init.runId !== undefined) {
+ url.searchParams.set("run_id", init.runId);
+ }
+ transport = sse(url, init);
+ }
+ this.#stream = new NotebookStream<K>({
+ types: init.types,
+ cursor: init.cursor,
+ });
+ this.#onStatus = init.onStatus;
+ this.closed = new Promise((resolve, reject) => {
+ this.#settle = { resolve, reject };
+ });
+ // A caller that never awaits `closed` should not see an unhandled rejection.
+ this.closed.catch(() => undefined);
+ if (init.signal?.aborted) {
+ this.close();
+ return;
+ }
+ const signal = init.signal;
+ if (signal !== undefined) {
+ const abort = () => this.close();
+ signal.addEventListener("abort", abort, { once: true });
+ this.#release = () => signal.removeEventListener("abort", abort);
+ }
+ void this.#run(transport);
+ }
+
+ /** Whether the stream is receiving events. */
+ public get status(): Status {
+ return this.#status;
+ }
+
+ /**
+ * The id of the last event the stream received.
+ *
+ * Null during a snapshot and after `reset`.
+ */
+ public get cursor(): string | null {
+ return this.#stream.cursor;
+ }
+
+ /**
+ * Call `listener` with each event, in order.
+ *
+ * Returns a function that stops calling it. A listener that throws does not
+ * interrupt the stream.
+ */
+ public subscribe(listener: (event: NotebookEvent<K>) => void): () => void {
+ return this.#stream.subscribe(listener);
+ }
+
+ /** Stop following the stream. */
+ public close(): void {
+ this.#finish()?.resolve();
+ }
+
+ /**
+ * Iterate over events until the stream closes.
+ *
+ * Leaving the loop early closes the stream.
+ */
+ public [Symbol.asyncIterator](): AsyncIterator<NotebookEvent<K>> {
+ const queue: NotebookEvent<K>[] = [];
+ const waiting: (() => void)[] = [];
+ const wake = () => waiting.splice(0).forEach((resolve) => resolve());
+ let ended: { error?: unknown } | undefined;
+ const unsubscribe = this.subscribe((event) => {
+ queue.push(event);
+ wake();
+ });
+ this.closed.then(
+ () => {
+ ended = {};
+ wake();
+ },
+ (error: unknown) => {
+ ended = { error };
+ wake();
+ },
+ );
+ const done = () => {
+ unsubscribe();
+ this.close();
+ return { done: true as const, value: undefined };
+ };
+ return {
+ next: async () => {
+ for (;;) {
+ const event = queue.shift();
+ if (event !== undefined) {
+ return { done: false, value: event };
+ }
+ if (ended !== undefined) {
+ if (ended.error !== undefined) {
+ unsubscribe();
+ throw ended.error;
+ }
+ return done();
+ }
+ // Wait for the next event or for the stream to close.
+ await new Promise<void>((resolve) => waiting.push(resolve));
+ }
+ },
+ return: async () => done(),
+ };
+ }
+
+ async #run(transport: NotebookTransport) {
+ // Start after the constructor returns, so listeners added right after it
+ // receive the first events.
+ await Promise.resolve();
+ const { signal } = this.#controller;
+ let attempt = 0;
+ while (!signal.aborted) {
+ try {
+ const cursor = this.#stream.resume();
+ await transport(
+ { cursor, signal },
+ {
+ open: () => {
+ if (this.#settle !== undefined) {
+ this.#setStatus("connected");
+ }
+ },
+ message: (message) => {
+ if (this.#settle === undefined) {
+ return;
+ }
+ attempt = 0;
+ try {
+ this.#stream.receive(message);
+ } catch (error) {
+ // The transport may call this from its own event listener,
+ // so stop here instead of relying on it to pass the error on.
+ this.#finish()?.reject(error);
+ }
+ },
+ },
+ );
+ } catch (error) {
+ this.#finish()?.reject(error);
+ return;
+ }
+ if (signal.aborted) {
+ return;
+ }
+ this.#setStatus("connecting");
+ attempt += 1;
+ if (attempt > ATTEMPTS) {
+ this.#finish()?.reject(
+ new StreamStopped("The host could not be reached"),
+ );
+ return;
+ }
+ await sleep(delay(attempt), signal);
+ }
+ }
+
+ #setStatus(status: Status) {
+ if (this.#status === status) {
+ return;
+ }
+ this.#status = status;
+ try {
+ this.#onStatus?.(status);
+ } catch (error) {
+ report(error);
+ }
+ }
+
+ /** Close the stream once and return how to settle `closed`. */
+ #finish() {
+ const settle = this.#settle;
+ if (settle === undefined) {
+ return undefined;
+ }
+ this.#settle = undefined;
+ this.#release?.();
+ this.#controller.abort();
+ this.#setStatus("closed");
+ return settle;
+ }
+}
diff --git a/packages/client/src/notebook/stream.ts b/packages/client/src/notebook/stream.ts
new file mode 100644
index 0000000000..15860d508e
--- /dev/null
+++ b/packages/client/src/notebook/stream.ts
@@ -0,0 +1,172 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import * as Protocol from "../protocol.ts";
+import type { Kind } from "../reducer.ts";
+import { type Frame, isFrame, StreamStopped } from "../transport/frame.ts";
+
+/** An event the host sends for a kind outside the protocol, such as `marimo`. */
+type ExtensionEvent<Name extends string> = Name extends unknown
+ ? { readonly event: Name; readonly data: unknown; readonly id?: string }
+ : never;
+
+/**
+ * An event a notebook stream delivers for the requested kinds.
+ *
+ * Each kind brings its record and removal events. `ready` and `reset` arrive
+ * for every stream. A kind the protocol does not define arrives with its data
+ * unvalidated.
+ */
+export type NotebookEvent<K extends string = Kind> =
+ | Extract<
+ Protocol.EventOutput,
+ { event: K | `${K}.removed` | "ready" | "reset" }
+ >
+ | ExtensionEvent<Exclude<K, Protocol.ObjectTypeOutput>>;
+
+/** What a `NotebookStream` delivers and where it starts. */
+export interface NotebookStreamInit<K extends string = Kind> {
+ /**
+ * The kinds to deliver.
+ *
+ * Omit it to deliver every kind the protocol defines. Name a kind the
+ * protocol does not define, such as `marimo`, to deliver it as well.
+ */
+ readonly types?: readonly K[];
+ /**
+ * Resume after this event id instead of starting with a snapshot.
+ *
+ * The caller holds the state it built through that id.
+ */
+ readonly cursor?: string;
+}
+
+/** The events the protocol defines, by name. */
+const PROTOCOL_EVENTS = new Set<string>(
+ Protocol.Event.options.flatMap((schema) => schema.shape.event.options),
+);
+
+/** Rethrow a listener's error without interrupting the stream. */
+export function report(error: unknown): void {
+ queueMicrotask(() => {
+ throw error;
+ });
+}
+
+/**
+ * The protocol's rules for following a notebook stream, without a connection.
+ *
+ * A connection calls `resume()` when it starts, to learn the cursor to send,
+ * and `receive()` with each message. The stream validates events, tracks the
+ * cursor, and delivers the requested kinds in order.
+ *
+ * - A stream starts with a snapshot that ends in `ready`, then delivers
+ * changes.
+ * - `reset` means the caller discards what it built. A fresh snapshot follows.
+ * The stream delivers `reset` itself when a snapshot was cut short, because
+ * a new snapshot replaces the incomplete one.
+ * - Kinds that were not requested keep their place in the stream without
+ * being delivered.
+ */
+export class NotebookStream<const K extends string = Kind> {
+ #cursor: string | null;
+ /** Whether events since the last reset have no cursor to resume from. */
+ #rebuilding = false;
+ readonly #wanted: ReadonlySet<string> | null;
+ readonly #listeners = new Set<(event: NotebookEvent<K>) => void>();
+
+ public constructor(init: NotebookStreamInit<K> = {}) {
+ this.#cursor = init.cursor ?? null;
+ this.#wanted =
+ init.types === undefined
+ ? null
+ : new Set([
+ "ready",
+ "reset",
+ ...init.types.flatMap((kind) => [kind, `${kind}.removed`]),
+ ]);
+ }
+
+ /**
+ * The id of the last event the stream received.
+ *
+ * Null during a snapshot and after `reset`.
+ */
+ public get cursor(): string | null {
+ return this.#cursor;
+ }
+
+ /**
+ * Call `listener` with each event, in order.
+ *
+ * Returns a function that stops calling it. A listener that throws does not
+ * interrupt the stream.
+ */
+ public subscribe(listener: (event: NotebookEvent<K>) => void): () => void {
+ this.#listeners.add(listener);
+ return () => this.#listeners.delete(listener);
+ }
+
+ /**
+ * Prepare for a new connection and return the cursor to send.
+ *
+ * Delivers `reset` first when the last snapshot was cut short.
+ */
+ public resume(): string | null {
+ if (this.#cursor === null && this.#rebuilding) {
+ this.#accept({ event: "reset", data: {} });
+ }
+ return this.#cursor;
+ }
+
+ /**
+ * Accept one message from the connection.
+ *
+ * Throws `StreamStopped` when the message is not an event or an event the
+ * protocol defines is invalid. The caller stops following the stream then.
+ */
+ public receive(message: unknown): void {
+ if (!isFrame(message)) {
+ throw new StreamStopped("The host sent a message that is not an event");
+ }
+ this.#accept(message);
+ }
+
+ #accept(frame: Frame) {
+ let event: NotebookEvent<string>;
+ if (PROTOCOL_EVENTS.has(frame.event)) {
+ const parsed = Protocol.Event.safeParse(frame);
+ if (!parsed.success) {
+ throw new StreamStopped(
+ `The host sent an invalid ${frame.event} event`,
+ { cause: parsed.error },
+ );
+ }
+ event = parsed.data;
+ } else {
+ event = frame as ExtensionEvent<string>;
+ }
+ if (frame.id !== undefined) {
+ this.#cursor = frame.id;
+ }
+ if (event.event === "reset") {
+ this.#cursor = null;
+ this.#rebuilding = false;
+ } else if (this.#cursor === null) {
+ this.#rebuilding = true;
+ }
+ const wanted =
+ this.#wanted === null
+ ? PROTOCOL_EVENTS.has(event.event)
+ : this.#wanted.has(event.event);
+ if (!wanted) {
+ return;
+ }
+ for (const listener of this.#listeners) {
+ try {
+ listener(event as NotebookEvent<K>);
+ } catch (error) {
+ report(error);
+ }
+ }
+ }
+}
diff --git a/packages/client/src/request.ts b/packages/client/src/request.ts
index 14b35a8eaf..9ae6d9ff1e 100644
--- a/packages/client/src/request.ts
+++ b/packages/client/src/request.ts
@@ -130,10 +130,21 @@ function idempotencyKey(): string {
}
/** Whether a `Content-Type` names `type`, ignoring case and parameters. */
-function isType(contentType: string | null, type: string): boolean {
+export function isType(contentType: string | null, type: string): boolean {
return contentType?.split(";", 1)[0].trim().toLowerCase() === type;
}
+/**
+ * A URL below `url`, keeping its query string.
+ *
+ * `suffix` is empty or starts with a slash, as the protocol's paths do.
+ */
+export function below(url: URL, suffix: string): URL {
+ const target = new URL(url);
+ target.pathname = url.pathname.replace(/\/$/, "") + suffix;
+ return target;
+}
+
/** The URL an operation's path resolves to below the target. */
function resolve<Prefix extends string>(
target: Target<Prefix>,
@@ -156,9 +167,7 @@ function resolve<Prefix extends string>(
}
return encodeURIComponent(value);
});
- const url = new URL(target.url);
- url.pathname = target.url.pathname.replace(/\/$/, "") + suffix;
- return url;
+ return below(target.url, suffix);
}
/**
diff --git a/packages/client/src/transport/frame.ts b/packages/client/src/transport/frame.ts
new file mode 100644
index 0000000000..2e8ee8c230
--- /dev/null
+++ b/packages/client/src/transport/frame.ts
@@ -0,0 +1,67 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** One event of a host stream, before validation. */
+export interface Frame {
+ readonly event: string;
+ readonly data: unknown;
+ readonly id?: string;
+}
+
+/** Whether a decoded message has the shape of a stream event. */
+export function isFrame(value: unknown): value is Frame {
+ if (typeof value !== "object" || value === null) {
+ return false;
+ }
+ const { event, id } = value as Record<string, unknown>;
+ return (
+ typeof event === "string" &&
+ event !== "" &&
+ (id === undefined || typeof id === "string")
+ );
+}
+
+/**
+ * A stream stopped and will not reconnect.
+ *
+ * `cause` says why when there is more to say.
+ *
+ * - The host refused the stream. `cause` is the `Problem` it answered with.
+ * - The host sent an invalid event. `cause` is the validation error.
+ * - The host could not be reached after repeated attempts. `cause` is
+ * undefined.
+ * - A custom transport decided to stop. `cause` is whatever it passed.
+ */
+export class StreamStopped extends Error {
+ public override readonly name = "StreamStopped";
+}
+
+/** Where one connection of a notebook stream starts. */
+export interface Attempt {
+ /** Where to resume, or null to start with a snapshot. */
+ readonly cursor: string | null;
+ /** Aborted when the stream closes. The transport closes its connection. */
+ readonly signal: AbortSignal;
+}
+
+/** What a transport reports while its connection is open. */
+export interface Handlers {
+ /** The connection is established. */
+ open(): void;
+ /** One decoded message, not yet validated. */
+ message(message: unknown): void;
+}
+
+/**
+ * Open one connection to a notebook stream and report it until it ends.
+ *
+ * `NotebookEvents` calls it again for each attempt. It resolves when the
+ * connection ended and another attempt makes sense. It rejects when the
+ * stream should stop, preferably with a `StreamStopped` that says why, and
+ * `closed` rejects with the same error. It sends the cursor however its host
+ * expects, and leaves reconnecting, validation, and the cursor's value to
+ * `NotebookEvents`.
+ */
+export type NotebookTransport = (
+ attempt: Attempt,
+ handlers: Handlers,
+) => Promise<void>;
diff --git a/packages/client/src/transport/sse.ts b/packages/client/src/transport/sse.ts
new file mode 100644
index 0000000000..35ec6ce9e5
--- /dev/null
+++ b/packages/client/src/transport/sse.ts
@@ -0,0 +1,163 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import * as Protocol from "../protocol.ts";
+import { type Connection, isType } from "../request.ts";
+import { type Frame, type NotebookTransport, StreamStopped } from "./frame.ts";
+
+/** Hosts send a comment every fifteen seconds while nothing else happens. */
+const SILENCE_MS = 45_000;
+
+/** Parse server-sent events from decoded text. */
+export class ServerSentEventStream extends TransformStream<string, Frame> {
+ public constructor() {
+ let buffer = "";
+ let event = "";
+ let data: string[] = [];
+ let id: string | undefined;
+ const dispatch = (controller: TransformStreamDefaultController<Frame>) => {
+ if (data.length > 0) {
+ const text = data.join("\n");
+ let value: unknown = text;
+ try {
+ value = JSON.parse(text);
+ } catch {
+ // Unknown events need not carry JSON.
+ }
+ // Unlike `EventSource`, an id does not carry over to later events.
+ // Snapshot events have no id, and they have no position to resume from.
+ controller.enqueue({
+ event: event || "message",
+ data: value,
+ ...(id === undefined ? {} : { id }),
+ });
+ }
+ event = "";
+ data = [];
+ id = undefined;
+ };
+ super({
+ transform(chunk, controller) {
+ buffer += chunk;
+ // A carriage return at the end may be half of a CRLF in the next chunk.
+ const held = buffer.endsWith("\r") ? "\r" : "";
+ const lines = buffer
+ .slice(0, buffer.length - held.length)
+ .split(/\r\n|\r|\n/);
+ buffer = (lines.pop() ?? "") + held;
+ for (const line of lines) {
+ if (line === "") {
+ dispatch(controller);
+ continue;
+ }
+ if (line.startsWith(":")) {
+ continue;
+ }
+ const colon = line.indexOf(":");
+ const field = colon === -1 ? line : line.slice(0, colon);
+ let value = colon === -1 ? "" : line.slice(colon + 1);
+ if (value.startsWith(" ")) {
+ value = value.slice(1);
+ }
+ if (field === "event") {
+ event = value;
+ } else if (field === "data") {
+ data.push(value);
+ } else if (field === "id" && !value.includes("\0")) {
+ id = value;
+ }
+ }
+ },
+ });
+ }
+}
+
+/** Statuses a host answers when it may accept the stream later. */
+const RETRY_STATUSES = new Set([408, 429]);
+
+/**
+ * Follow a stream over server-sent events, as the protocol defines.
+ *
+ * The cursor travels in `Last-Event-ID`. A refusal stops the stream with its
+ * `Problem`, except for statuses that ask the client to try again. Other
+ * failures and 45 seconds of silence are retried.
+ */
+export function sse(url: URL, connection: Connection): NotebookTransport {
+ return async ({ cursor, signal }, { open, message }) => {
+ const headers = new Headers(connection.headers);
+ headers.set("Accept", "text/event-stream");
+ if (connection.token !== undefined) {
+ headers.set("Authorization", `Bearer ${connection.token}`);
+ }
+ if (cursor !== null) {
+ headers.set("Last-Event-ID", cursor);
+ }
+ const controller = new AbortController();
+ const abort = () => controller.abort();
+ signal.addEventListener("abort", abort, { once: true });
+ let silence: ReturnType<typeof setTimeout> | undefined;
+ const listen = () => {
+ clearTimeout(silence);
+ silence = setTimeout(abort, SILENCE_MS);
+ };
+ try {
+ const fetch = connection.fetch ?? globalThis.fetch;
+ // A host that accepts the request but never answers counts as silence.
+ listen();
+ const response = await fetch(url, {
+ headers,
+ signal: controller.signal,
+ });
+ const { status } = response;
+ if (status >= 400 && status < 500 && !RETRY_STATUSES.has(status)) {
+ const problem = Protocol.Problem.safeParse(
+ await response.json().catch(() => undefined),
+ );
+ throw new StreamStopped(`The host refused the stream (${status})`, {
+ cause: problem.success ? problem.data : undefined,
+ });
+ }
+ if (!response.ok || response.body === null) {
+ await response.body?.cancel();
+ return;
+ }
+ if (!isType(response.headers.get("Content-Type"), "text/event-stream")) {
+ await response.body.cancel();
+ throw new StreamStopped("The host did not answer with an event stream");
+ }
+ open();
+ // Any bytes count as activity, including the host's ping comments.
+ const heard = new TransformStream<
+ Uint8Array<ArrayBuffer>,
+ Uint8Array<ArrayBuffer>
+ >({
+ transform(chunk, stream) {
+ listen();
+ stream.enqueue(chunk);
+ },
+ });
+ const reader = response.body
+ .pipeThrough(heard)
+ .pipeThrough(new TextDecoderStream())
+ .pipeThrough(new ServerSentEventStream())
+ .getReader();
+ controller.signal.addEventListener("abort", () => void reader.cancel(), {
+ once: true,
+ });
+ // Reading by hand works where streams are not async iterable.
+ for (;;) {
+ const { done, value } = await reader.read();
+ if (done) {
+ return;
+ }
+ message(value);
+ }
+ } catch (error) {
+ if (error instanceof StreamStopped) {
+ throw error;
+ }
+ } finally {
+ clearTimeout(silence);
+ signal.removeEventListener("abort", abort);
+ }
+ };
+}