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.

Define custom notebook events in the host protocol (#11215)

Trevor Manz09e13898d48a
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.py
index 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.md
index 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` restored
from storage. Its source is `x = 21`, but its original run and runtime are
unknown. It illustrates a separate restoration scenario, outside the session
diff --git a/protocols/host/fixtures/custom-events-replay.sse b/protocols/host/fixtures/custom-events-replay.sse
new file mode 100644
index 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.sse
new file mode 100644
index 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.yaml
index 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 from
snapshots; 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, taken
under 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, or
DisplayMessage for an event named
- after that kind; a RemovedMessage
+ after that kind; a CustomMessage for `custom`; a RemovedMessage
for an event ending in `.removed`; and an empty object
for `ready` and `reset`.
type: object
@@ -796,8 +803,23 @@ components:
The kinds a stream carries, and the values `types` accepts. The
catalog stream carries host, project, notebook, runtime, and
attachment. 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: object
description: |
@@ -1337,6 +1359,17 @@ components:
format: date-time
description: 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: object
description: The data of a `project` event. The project as it now is.
diff --git a/protocols/host/spec.md b/protocols/host/spec.md
index 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). Other
transports, such as WebSocket, could carry the same events while preserving
their 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
### Capabilities
diff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.py
index 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"):