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
Define custom notebook events in the host protocol (#11215)
Trevor Manz09e13898d48a
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.pyindex 82c63454ae..440319e812 100644--- a/marimo/_core/protocol.py+++ b/marimo/_core/protocol.py@@ -113,6 +113,41 @@ class CellInput(Struct, frozen=True):) = "_"+class Custom(Struct, frozen=True):+ data: Annotated[+ Any,+ Meta(+ description="Any JSON value, including null. The producer defines its schema and consumers of the type validate it."+ ),+ ]+ type: Annotated[+ str,+ Meta(+ description="A namespaced event type under a namespace the producer controls, such as `marimo.pair.agent-message`. Clients ignore types they do not recognize while retaining the stream cursor.",+ min_length=1,+ ),+ ]+++class CustomMessage(Struct, frozen=True):+ custom: Custom+ time: Annotated[+ datetime,+ Meta(+ description="When the host emitted this event. Preserved on replay."+ ),+ ]+ request_id: (+ Annotated[+ str,+ Meta(+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did, and on snapshots unless that request's work is still in progress."+ ),+ ]+ | UnsetType+ ) = UNSET++class DecisionOption(Struct, frozen=True):id: Annotated[str, Meta(description="Identifies this answer.")]label: Annotated[str, Meta(description="Text to show a person.")]@@ -251,9 +286,10 @@ ObjectType: TypeAlias = Annotated["execution","console","display",+ "custom",],Meta(- description="The kinds a stream carries, and the values `types` accepts. The\ncatalog stream carries host, project, notebook, runtime, and\nattachment. A notebook's stream carries notebook, document, cell,\nruntime, attachment, run, execution, console, and display.\n"+ description="The kinds a stream carries, and the values `types` accepts. The\ncatalog stream carries host, project, notebook, runtime, and\nattachment. A notebook's stream carries notebook, document, cell,\nruntime, attachment, run, execution, console, display, and custom.\nCustom events describe occurrences rather than object state.\n"),]diff --git a/protocols/host/fixtures/README.md b/protocols/host/fixtures/README.mdindex 774fe9eb72..78bf82cf83 100644--- a/protocols/host/fixtures/README.md+++ b/protocols/host/fixtures/README.md@@ -31,6 +31,13 @@ and a runtime stop. Both attachments remain connected after the runtime ends.## Standalone objects+`custom-events.sse` shows a `types=custom` notebook stream: an empty snapshot+ending at `ready`, then a live custom event. `custom-events-replay.sse` resumes+from that `ready` cursor, replaying the same event before the next `ready`.+Its type and payload are illustrative, not a standardized agent-message schema.+If the cursor expires instead, the host sends `reset` and an empty snapshot;+the custom event cannot be recovered from that snapshot.+`execution-restored.json` represents an earlier evaluation of `c3` restoredfrom storage. Its source is `x = 21`, but its original run and runtime areunknown. It illustrates a separate restoration scenario, outside the sessiondiff --git a/protocols/host/fixtures/custom-events-replay.sse b/protocols/host/fixtures/custom-events-replay.ssenew file mode 100644index 0000000000..7d5b635471--- /dev/null+++ b/protocols/host/fixtures/custom-events-replay.sse@@ -0,0 +1,8 @@+id: 101+event: custom+data: {"custom":{"type":"marimo.pair.agent-message","data":{"text":"Looking into it","tags":["progress"],"details":null}},"request_id":"req-agent-1","time":"2026-10-13T20:00:00Z"}++id: 101+event: ready+data: {}+diff --git a/protocols/host/fixtures/custom-events.sse b/protocols/host/fixtures/custom-events.ssenew file mode 100644index 0000000000..a47da34894--- /dev/null+++ b/protocols/host/fixtures/custom-events.sse@@ -0,0 +1,8 @@+id: 100+event: ready+data: {}++id: 101+event: custom+data: {"custom":{"type":"marimo.pair.agent-message","data":{"text":"Looking into it","tags":["progress"],"details":null}},"request_id":"req-agent-1","time":"2026-10-13T20:00:00Z"}+diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yamlindex b12a55c3eb..a9c85b2132 100644--- a/protocols/host/openapi.yaml+++ b/protocols/host/openapi.yaml@@ -201,6 +201,13 @@ paths:independent of replay history. Removed objects are absent fromsnapshots; a resumable stream carries their removal events.+ The stream may also carry `custom` events: namespaced JSON payloads+ that describe occurrences rather than object state. These have+ cursors and timestamps and participate in replay, but never appear+ in snapshots. A reset cannot recover custom events whose history+ has expired. `types=custom` selects them. They do not belong to a+ run and are excluded by `run_id`.+The opening phase is one consistent cut of the notebook, takenunder the lock that changes to the document take, so reading to`ready` and closing is a snapshot, and `types=cell,document` is a@@ -229,7 +236,7 @@ paths:CellMessage, RuntimeMessage, AttachmentMessage,RunMessage, ExecutionMessage, ConsoleMessage, orDisplayMessage for an event named- after that kind; a RemovedMessage+ after that kind; a CustomMessage for `custom`; a RemovedMessagefor an event ending in `.removed`; and an empty objectfor `ready` and `reset`.type: object@@ -796,8 +803,23 @@ components:The kinds a stream carries, and the values `types` accepts. Thecatalog stream carries host, project, notebook, runtime, andattachment. A notebook's stream carries notebook, document, cell,- runtime, attachment, run, execution, console, and display.- enum: [host, project, notebook, document, cell, runtime, attachment, run, execution, console, display]+ runtime, attachment, run, execution, console, display, and custom.+ Custom events describe occurrences rather than object state.+ enum: [host, project, notebook, document, cell, runtime, attachment, run, execution, console, display, custom]+ Custom:+ type: object+ description: |+ A notebook occurrence with a producer-defined payload. It is replayed+ while event history is retained, but is never included in snapshots+ and does not belong to a run. The notebook is identified by the stream.+ required: [type, data]+ properties:+ type:+ type: string+ minLength: 1+ description: A namespaced event type under a namespace the producer controls, such as `marimo.pair.agent-message`. Clients ignore types they do not recognize while retaining the stream cursor.+ data:+ description: Any JSON value, including null. The producer defines its schema and consumers of the type validate it.Host:type: objectdescription: |@@ -1337,6 +1359,17 @@ components:format: date-timedescription: When the host made this change. Present on live and replayed events; omitted on snapshots.host: { $ref: '#/components/schemas/Host' }+ CustomMessage:+ type: object+ description: The data of a `custom` event. This envelope is standardized; the custom type and payload are defined by their producer.+ required: [custom, time]+ properties:+ custom: { $ref: '#/components/schemas/Custom' }+ request_id: *request_id+ time:+ type: string+ format: date-time+ description: When the host emitted this event. Preserved on replay.ProjectMessage:type: objectdescription: The data of a `project` event. The project as it now is.diff --git a/protocols/host/spec.md b/protocols/host/spec.mdindex 2281e50c35..a3ee6196bb 100644--- a/protocols/host/spec.md+++ b/protocols/host/spec.md@@ -193,6 +193,28 @@ This version carries event streams over server-sent events (SSE). Othertransports, such as WebSocket, could carry the same events while preservingtheir ordering, snapshot, and replay guarantees.+### Custom events++A **custom event** describes an occurrence in a notebook without creating or+updating an object. Hosts MAY send custom events on the notebook stream using+the `custom` event kind. The protocol defines their envelope; the producer+defines the meaning and JSON payload of each namespaced `type`, such as+`marimo.pair.agent-message`. Producers MUST use a namespace they control.+Clients MUST ignore custom types they do not recognize while retaining the+stream cursor. Consumers of a type are responsible for validating its payload.++The stream identifies the notebook. Custom events MUST carry a timestamp.+When a request causes a custom event, the envelope MUST carry that request's+key in `request_id`; otherwise, the key is omitted. They participate in the+stream's ordering and cursor-based replay, with their original ids and timestamps.+They MUST NOT appear in snapshots. Once their replay history expires, a+reset cannot recover them. Features that need recoverable state MUST+represent that state separately rather than relying on custom events alone.++`types=custom` selects custom events, regardless of their namespaced type.+Custom events do not belong to a run and are excluded when `run_id` is set.+They do not appear on the catalog stream.+## Editing and running notebooks### Capabilitiesdiff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.pyindex 769d927853..d3c07e8461 100644--- a/tests/_core/test_protocol.py+++ b/tests/_core/test_protocol.py@@ -171,6 +171,54 @@ def test_stream_models(path: Path) -> None:assert not snapshot, f"{path.name}: incomplete snapshot"+def test_custom_event_replay_preserves_envelope_and_cursor() -> None:+ live = stream_events(FIXTURES / "custom-events.sse")+ replay = stream_events(FIXTURES / "custom-events-replay.sse")+ assert [event["event"] for event in live] == ["ready", "custom"]+ assert [event["event"] for event in replay] == ["custom", "ready"]+ assert replay[0] == live[1]+ assert replay[1]["id"] == live[1]["id"]+++ "data",+ [+ None,+ True,+ False,+ 0,+ 1,+ 1.0,+ 1.5,+ "hello",+ [1, None],+ {"nested": [False]},+ ],+)+def test_custom_payload_preserves_any_json_value(data: Any) -> None:+ wire = {+ "custom": {+ "type": "example.progress",+ "data": data,+ },+ "time": "2026-10-13T20:00:00Z",+ }+ value = msgspec.json.decode(json.dumps(wire), type=protocol.CustomMessage)+ assert canonical_json(+ json.loads(msgspec.json.encode(value))+ ) == canonical_json(wire)+++def test_custom_payload_is_required_even_when_null_is_allowed() -> None:+ with pytest.raises(+ msgspec.ValidationError, match="missing required field `data`"+ ):+ msgspec.json.decode(+ '{"type":"example.progress"}',+ type=protocol.Custom,+ )++def test_catalog_capabilities_and_runtime_stop() -> None:catalogs = []for name in ("events.sse", "events-reset.sse"):