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.

Identify host attachments and emit unstable events (#11213)

Kiran Gadhave6b5b4071dcdf
diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.py
index 7aec4a4859..2523ccb15f 100644
--- a/marimo/_core/notebook.py
+++ b/marimo/_core/notebook.py
@@ -8,8 +8,9 @@ backend updates and publishes events.
from __future__ import annotations
from time import monotonic
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
+import msgspec
from msgspec.structs import replace
from marimo._core import backend as be, protocol
@@ -21,7 +22,7 @@ from marimo._core.stream import Event, kind_of, message, utcnow
if TYPE_CHECKING:
from collections.abc import Callable
- from marimo._core.stream import Stream
+ from marimo._core.stream import Body, Stream
class Notebook:
@@ -249,21 +250,43 @@ class Notebook:
# ---- attachments ---------------------------------------------------
- def attach(self) -> protocol.Attachment:
- """Record an attached host API client."""
+ def attach(
+ self,
+ *,
+ identity: str | None = None,
+ kind: str | None = None,
+ name: str | None = None,
+ ) -> protocol.Attachment:
+ """Attach a client to this notebook.
+
+ Each call creates a separate attachment. `identity` is stored as
+ data. It does not affect the attachment lifetime. An omitted `kind`
+ is `client`. An empty `name` is stored as null.
+
+ Raises:
+ msgspec.ValidationError: If a value breaks the protocol's
+ constraints on the attachment field of the same name.
+ """
self._require_open()
- attachment = protocol.Attachment(
- id=mint(protocol.AttachmentId, "att"),
- notebook_id=self.id,
- kind="client",
- name=None,
- since=utcnow(),
- )
+ fields: dict[str, Any] = {
+ "id": mint(protocol.AttachmentId, "att"),
+ "notebook_id": self.id,
+ "kind": kind or "client",
+ "name": name or None,
+ "since": utcnow(),
+ }
+ if identity is not None:
+ fields["identity"] = identity
+ attachment = msgspec.convert(fields, protocol.Attachment)
self._attachments[attachment.id] = attachment
self._publish(attachment, None)
return attachment
def detach(self, attachment_id: str) -> None:
+ """Remove the attachment and publish its removal.
+
+ Unknown IDs are ignored.
+ """
attachment = self._attachments.pop(attachment_id, None)
if attachment is not None:
self._remove("attachment", attachment.id, None)
@@ -338,6 +361,32 @@ class Notebook:
started_at=utcnow(),
)
+ def emit(
+ self,
+ type: str, # noqa: A002
+ data: Any,
+ *,
+ request_id: str | None = None,
+ ) -> protocol.Custom:
+ """Publish a custom event on the notebook stream.
+
+ A custom event is a notebook occurrence with a producer-defined
+ payload.
+
+ Raises:
+ TypeError: If `data` is not a JSON value.
+ ValueError: If `type` is empty.
+ """
+ self._require_open()
+ if not type:
+ raise ValueError("type must be a non-empty string")
+ # Fail here, in the producer, instead of inside every subscriber's
+ # stream when the event is framed.
+ msgspec.json.encode(data)
+ custom = protocol.Custom(type=type, data=data)
+ self._publish(custom, request_id)
+ return custom
+
# ---- stream --------------------------------------------------------
def _snapshot(self) -> list[Event]:
@@ -372,11 +421,7 @@ class Notebook:
runtime, self._runtime = self._runtime, None
self._remove("runtime", runtime.id, request_id)
- def _publish(
- self,
- body: protocol.Runtime | protocol.Attachment,
- request_id: str | None,
- ) -> None:
+ def _publish(self, body: Body, request_id: str | None) -> None:
self._stream.publish(
body,
notebook_id=self.id,
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.py
index 440319e812..6430914edd 100644
--- a/marimo/_core/protocol.py
+++ b/marimo/_core/protocol.py
@@ -585,14 +585,16 @@ class Attachment(Struct, frozen=True):
kind: Annotated[
str,
Meta(
- description="What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize."
+ description="What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize.",
+ pattern="^[a-z0-9-]+$",
),
]
name: (
Annotated[
str,
Meta(
- description="A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty."
+ description="A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty.",
+ max_length=256,
),
]
| None
diff --git a/marimo/_core/stream.py b/marimo/_core/stream.py
index 310a0d5ea7..059dded3a4 100644
--- a/marimo/_core/stream.py
+++ b/marimo/_core/stream.py
@@ -35,9 +35,11 @@ NOTEBOOK_KINDS = frozenset(
"execution",
"console",
"display",
+ "custom",
}
)
+
Body: TypeAlias = (
protocol.Host
| protocol.Project
@@ -48,6 +50,7 @@ Body: TypeAlias = (
| protocol.Execution
| protocol.Console
| protocol.Display
+ | protocol.Custom
)
_WRAPPERS: dict[str, type[msgspec.Struct]] = {
@@ -60,6 +63,7 @@ _WRAPPERS: dict[str, type[msgspec.Struct]] = {
"execution": protocol.ExecutionMessage,
"console": protocol.ConsoleMessage,
"display": protocol.DisplayMessage,
+ "custom": protocol.CustomMessage,
}
diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.py
index 74b84e866a..b278f6dd5b 100644
--- a/marimo/_server/host/api.py
+++ b/marimo/_server/host/api.py
@@ -45,6 +45,17 @@ _Body = TypeVar("_Body", bound=msgspec.Struct)
PROBLEM_TYPE_PREFIX = "tag:marimo.io,2026:host/"
"""Prefix for host protocol problem types."""
+ATTACHMENT_IDENTITY = "Marimo-Attachment-Identity"
+ATTACHMENT_KIND = "Marimo-Attachment-Kind"
+ATTACHMENT_NAME = "Marimo-Attachment-Name"
+
+_ATTACHMENT_HEADERS = {
+ "identity": ATTACHMENT_IDENTITY,
+ "kind": ATTACHMENT_KIND,
+ "name": ATTACHMENT_NAME,
+}
+"""Attachment fields and the request headers that supply them."""
+
PING = b": ping\n\n"
PING_SECONDS = 15.0
@@ -355,7 +366,14 @@ async def _notebook_events(request: Request) -> Response:
run_id = request.query_params.get("run_id")
if run_id == "":
return problem(400, "invalid-request", "run_id must not be empty")
- attachment = notebook.attach()
+ try:
+ attachment = notebook.attach(
+ identity=request.headers.get(ATTACHMENT_IDENTITY),
+ kind=request.headers.get(ATTACHMENT_KIND),
+ name=request.headers.get(ATTACHMENT_NAME),
+ )
+ except msgspec.ValidationError as e:
+ return problem(400, "invalid-request", _attachment_problem(e))
return _stream(
context,
cursor,
@@ -382,6 +400,15 @@ def _types(request: Request) -> set[str] | None:
return {kind for kind in asked.split(",") if kind}
+def _attachment_problem(error: msgspec.ValidationError) -> str:
+ """Name the request header behind a rejected attachment field."""
+ detail = str(error)
+ for field, header in _ATTACHMENT_HEADERS.items():
+ if detail.endswith(f"`$.{field}`"):
+ return f"{header} is invalid"
+ return "attachment headers are invalid"
+
+
def _stream(
context: HostContext,
cursor: int | None,
diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yaml
index a9c85b2132..e27cb379cb 100644
--- a/protocols/host/openapi.yaml
+++ b/protocols/host/openapi.yaml
@@ -614,9 +614,11 @@ components:
description: |
A human-readable label copied to the attachment's `name`, such as
`Notebook CLI`. Omitted or empty means the attachment's name is
- null. The value must be at most 256 bytes when encoded as UTF-8;
- longer values receive a 400 `invalid-request` response.
- schema: { type: string }
+ null. The value must be at most 256 characters; longer values
+ receive a 400 `invalid-request` response.
+ schema:
+ type: string
+ maxLength: 256
IdempotencyKey:
name: Idempotency-Key
in: header
@@ -944,9 +946,11 @@ components:
individual connection or change its lifetime.
kind:
type: string
+ pattern: '^[a-z0-9-]+$'
description: What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize.
name:
type: [string, 'null']
+ maxLength: 256
description: A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty.
since:
type: string
diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.py
index 1b38a0942e..937b38c377 100644
--- a/tests/_core/test_notebook.py
+++ b/tests/_core/test_notebook.py
@@ -3,6 +3,7 @@
from __future__ import annotations
+import msgspec
import pytest
from dirty_equals import IsDatetime
from inline_snapshot import snapshot
@@ -14,8 +15,11 @@ from marimo._core.errors import Conflict, NoRuntime, NotFound
from marimo._core.host import Host
from marimo._core.notebook import Notebook
from marimo._core.protocol import (
+ AttachmentMessage,
Console,
ConsoleMessage,
+ Custom,
+ CustomMessage,
DisplayData,
Error,
ErrorOutcome,
@@ -950,3 +954,80 @@ class TestAttachments:
assert att.kind == "client"
assert att.notebook_id == "n1"
assert names(log) == ["attachment", "attachment.removed"]
+
+ def test_one_identity_attaches_separately(
+ self, notebook: Notebook, log: list[Event]
+ ) -> None:
+ first = notebook.attach(identity="k1", kind="agent", name="Codex")
+ second = notebook.attach(identity="k1", kind="agent", name="Codex")
+
+ assert first.id != second.id
+ assert first.identity == second.identity == "k1"
+ assert names(log) == ["attachment", "attachment"]
+ assert _attachment_ids(notebook) == {first.id, second.id}
+
+ def test_detach_leaves_other_attachments_with_the_identity(
+ self, notebook: Notebook, log: list[Event]
+ ) -> None:
+ first = notebook.attach(identity="k1")
+ second = notebook.attach(identity="k1")
+ log.clear()
+
+ notebook.detach(first.id)
+
+ assert names(log) == ["attachment.removed"]
+ assert _attachment_ids(notebook) == {second.id}
+
+ def test_attach_without_an_identity_omits_it_on_the_wire(
+ self, notebook: Notebook, log: list[Event]
+ ) -> None:
+ att = notebook.attach()
+
+ assert att.identity is UNSET
+ wire = msgspec.json.decode(msgspec.json.encode(log[0].data))
+ assert "identity" not in wire["attachment"]
+
+
+class TestEmit:
+ def test_emit_publishes_a_custom_event_on_the_notebook_stream(
+ self, notebook: Notebook, log: list[Event]
+ ) -> None:
+ custom = notebook.emit("marimo.test", {"hello": 1}, request_id="req-1")
+
+ assert custom == Custom(type="marimo.test", data={"hello": 1})
+ assert names(log) == ["custom"]
+ assert log[0].notebook_id == notebook.id
+ published = log[0].data
+ assert isinstance(published, CustomMessage)
+ assert published.custom == custom
+ assert published.request_id == "req-1"
+ assert published.time is not UNSET
+
+ def test_emit_rejects_data_that_is_not_json(
+ self, notebook: Notebook, log: list[Event]
+ ) -> None:
+ with pytest.raises(TypeError):
+ notebook.emit("marimo.test", object())
+ assert "custom" not in names(log)
+
+ def test_emit_rejects_an_empty_type(
+ self, notebook: Notebook, log: list[Event]
+ ) -> None:
+ with pytest.raises(ValueError):
+ notebook.emit("", 1)
+ assert "custom" not in names(log)
+
+ def test_emit_on_a_closed_notebook_raises(
+ self, host: Host, notebook: Notebook
+ ) -> None:
+ host.remove_notebook(notebook.id)
+ with pytest.raises(NotFound):
+ notebook.emit("marimo.test", {"hello": 1})
+
+
+def _attachment_ids(notebook: Notebook) -> set[str]:
+ return {
+ event.data.attachment.id
+ for event in notebook._snapshot()
+ if isinstance(event.data, AttachmentMessage)
+ }
diff --git a/tests/_core/test_stream.py b/tests/_core/test_stream.py
index 28e4df677d..c0d15b0e97 100644
--- a/tests/_core/test_stream.py
+++ b/tests/_core/test_stream.py
@@ -8,8 +8,8 @@ import pytest
from marimo._core import backend as be, protocol
from marimo._core.host import Host
from marimo._core.notebook import Notebook
-from marimo._core.stream import Event, Stream
-from tests._core.conftest import ScriptedBackend, project
+from marimo._core.stream import Event, Stream, kind_of
+from tests._core.conftest import ScriptedBackend, names, project
def test_subscriber_failure_does_not_prevent_startup(
@@ -159,3 +159,27 @@ def test_subscribers_cannot_start_a_runtime_during_adoption(
[(replacement, False)],
[],
)
+
+
+def test_custom_events_are_on_the_notebook_stream_only(
+ host: Host, notebook: Notebook
+) -> None:
+ cursor = host.events(notebook_id=notebook.id)[-1].id
+ assert cursor is not None
+ custom = notebook.emit("marimo.test", {"hello": 1})
+
+ assert kind_of(custom) == "custom"
+ assert names(host.events(cursor, notebook_id=notebook.id)) == [
+ "custom",
+ "ready",
+ ]
+ assert "custom" not in names(host.events())
+ assert names(
+ host.events(cursor, notebook_id=notebook.id, types={"custom"})
+ ) == ["custom", "ready"]
+ assert names(
+ host.events(cursor, notebook_id=notebook.id, types={"attachment"})
+ ) == ["ready"]
+ replayed = host._stream.since(cursor)
+ assert replayed is not None
+ assert names(replayed) == ["custom"]
diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.py
index 5d6db882ca..6100ba7f89 100644
--- a/tests/_server/host/test_host_api.py
+++ b/tests/_server/host/test_host_api.py
@@ -10,6 +10,7 @@ from pathlib import Path
from typing import TYPE_CHECKING
from urllib.parse import parse_qs, urlsplit
+import msgspec
import pytest
from marimo._core import backend as be, protocol
@@ -294,6 +295,132 @@ async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:
assert missing.status == 404
+IDENTIFIED = {
+ **AUTH,
+ api_module.ATTACHMENT_IDENTITY: "k1",
+ api_module.ATTACHMENT_KIND: "agent",
+ api_module.ATTACHMENT_NAME: "Codex",
+}
+
+
+async def attachment_of(
+ harness: Harness, headers: dict[str, str]
+) -> protocol.Attachment:
+ """Open a notebook stream with `headers` and return its attachment."""
+ response, task, disconnect = request(
+ harness.app,
+ "GET",
+ f"/notebooks/{harness.notebook_id}/events",
+ headers=headers,
+ query="types=attachment",
+ )
+ await wait_for(response, until_ready)
+ assert response.names() == ["attachment", "ready"]
+ message = msgspec.convert(
+ response.records[0]["data"], protocol.AttachmentMessage
+ )
+ disconnect()
+ await asyncio.wait_for(task, 5)
+ return message.attachment
+
+
+async def test_attachment_headers_name_the_client(harness: Harness) -> None:
+ attachment = await attachment_of(harness, IDENTIFIED)
+ assert attachment.identity == "k1"
+ assert attachment.kind == "agent"
+ assert attachment.name == "Codex"
+
+
+async def test_an_empty_attachment_name_is_null(harness: Harness) -> None:
+ attachment = await attachment_of(
+ harness, {**AUTH, api_module.ATTACHMENT_NAME: ""}
+ )
+ assert attachment.name is None
+
+
+async def test_a_reconnect_with_one_identity_attaches_fresh(
+ harness: Harness,
+) -> None:
+ path = f"/notebooks/{harness.notebook_id}/events"
+ first, first_task, disconnect_first = request(
+ harness.app, "GET", path, headers=IDENTIFIED, query="types=attachment"
+ )
+ await wait_for(first, until_ready)
+ cursor = first.records[-1]["id"]
+ old = first.records[0]["data"]["attachment"]
+ disconnect_first()
+ await asyncio.wait_for(first_task, 5)
+ assert "attachment" not in [e.name for e in harness.host.events()]
+
+ second, second_task, disconnect_second = request(
+ harness.app,
+ "GET",
+ path,
+ headers={**IDENTIFIED, "Last-Event-ID": cursor},
+ query="types=attachment",
+ )
+ await wait_for(second, until_ready)
+ assert second.names() == ["attachment.removed", "attachment", "ready"]
+ assert second.records[0]["data"]["id"] == old["id"]
+ new = second.records[1]["data"]["attachment"]
+ assert new["identity"] == old["identity"] == "k1"
+ assert new["id"] != old["id"]
+
+ disconnect_second()
+ await asyncio.wait_for(second_task, 5)
+
+
+async def test_custom_events_use_their_own_sse_kind(
+ harness: Harness,
+) -> None:
+ notebook = harness.host.notebook(harness.notebook_id)
+ path = f"/notebooks/{notebook.id}/events"
+ custom, custom_task, disconnect_custom = request(
+ harness.app, "GET", path, headers=AUTH, query="types=custom"
+ )
+ attachments, attach_task, disconnect_attach = request(
+ harness.app, "GET", path, headers=AUTH, query="types=attachment"
+ )
+ await wait_for(custom, until_ready)
+ await wait_for(attachments, until_ready)
+
+ notebook.emit("marimo.test", {"hello": 1})
+ await wait_for(custom, lambda response: "custom" in response.names())
+ frame = next(r for r in custom.records if r.get("event") == "custom")
+ message = msgspec.convert(frame["data"], protocol.CustomMessage)
+ assert message.custom == protocol.Custom(
+ type="marimo.test", data={"hello": 1}
+ )
+ assert "custom" not in attachments.names()
+
+ disconnect_custom()
+ disconnect_attach()
+ await asyncio.gather(custom_task, attach_task)
+
+
+ ("header", "value"),
+ [
+ (api_module.ATTACHMENT_IDENTITY, ""),
+ (api_module.ATTACHMENT_KIND, "Agent"),
+ (api_module.ATTACHMENT_NAME, "n" * 257),
+ ],
+)
+async def test_invalid_attachment_headers_are_rejected(
+ harness: Harness, header: str, value: str
+) -> None:
+ response = await finished(
+ harness.app,
+ "GET",
+ f"/notebooks/{harness.notebook_id}/events",
+ headers={**AUTH, header: value},
+ )
+ assert response.status == 400
+ body = response.json()
+ assert body["type"].endswith("/invalid-request")
+ assert body["detail"] == f"{header} is invalid"
+
+
async def test_runtime_lifecycle_over_http(harness: Harness) -> None:
app, nid = harness.app, harness.notebook_id
path = f"/notebooks/{nid}/runtime"