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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
Add `NotebookEvents` to `@marimo-team/client` (#11391)
Trevor Manzdd4d66d63a2a
diff --git a/packages/client/README.md b/packages/client/README.mdindex 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 arevalidated before they are sent, and the host's answer comes back as data or aproblem.+`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.+```tsimport { 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 validateprotocol 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ }+ };+}