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
Use generated event types throughout the host stream (#11332)
Trevor Manz557461ffc234
diff --git a/marimo/_core/executions.py b/marimo/_core/executions.pyindex 8c28c5ac38..0a9a785cd1 100644--- a/marimo/_core/executions.py+++ b/marimo/_core/executions.py@@ -5,7 +5,7 @@ from __future__ import annotationsfrom copy import deepcopyfrom dataclasses import dataclass, field-from typing import TYPE_CHECKING, Literal+from typing import TYPE_CHECKINGfrom msgspec.structs import replace@@ -56,7 +56,7 @@ class _Result:class Removed:"""A current record that a transition removed."""- kind: Literal["execution", "console", "display", "variable"]+ record_type: type[protocol.Execution | protocol.Console | protocol.Display]id: strrun_id: protocol.RunId | None@@ -497,13 +497,13 @@ class Executions:run_id = result.execution.run_idchanges: list[Removed] = [Removed(- "console" if isinstance(item, protocol.Console) else "display",+ type(item),item.id,run_id,)for item in result.outputs.values()]- changes.append(Removed("execution", execution_id, run_id))+ changes.append(Removed(protocol.Execution, execution_id, run_id))self._forget_result(execution_id)return changesdiff --git a/marimo/_core/host.py b/marimo/_core/host.pyindex 9441ed9ab6..910c4cc029 100644--- a/marimo/_core/host.py+++ b/marimo/_core/host.py@@ -11,16 +11,24 @@ from dataclasses import dataclassfrom time import monotonicfrom typing import TYPE_CHECKING-from marimo._core import protocol+from marimo._core import protocol, protocol_eventsfrom marimo._core.errors import NotFoundfrom marimo._core.notebook import Notebookfrom marimo._core.run_log import RetentionPolicy, RunLog-from marimo._core.stream import Event, Listener, Sink, Stream, message+from marimo._core.stream import (+ Listener,+ RoutedEvent,+ Sink,+ Stream,+ snapshot_event,+)if TYPE_CHECKING:from collections.abc import Collection, Iterator, Sequencefrom contextlib import AbstractContextManager+ from marimo._core.protocol_events import Body+NotebookInitializer = Callable[[protocol.Notebook, Sink], Notebook | Awaitable[Notebook]@@ -50,7 +58,7 @@ class _NotebookSink(Sink):def deferred(self) -> AbstractContextManager[None]:return self._stream.deferred()- def _append(self, event: Event) -> Event:+ def _append(self, event: RoutedEvent) -> RoutedEvent:if not self.active:return eventwith self._stream.deferred():@@ -77,10 +85,13 @@ class _NotebookRecords(Mapping[str, protocol.Notebook]):return len(self._records)-def _identity(event: Event) -> tuple[str, str]:- assert event.kind is not None- body = getattr(event.data, event.kind)- return event.name, getattr(body, "id", None) or body.notebook_id+def _identity(event: RoutedEvent) -> tuple[type[Body], str]:+ assert isinstance(event.event, protocol_events.RecordEvent)+ body = protocol_events.body(event.event)+ assert not isinstance(body, (protocol.Host, protocol.Custom))+ if isinstance(body, (protocol.Document, protocol.Analysis)):+ return type(body), body.notebook_id+ return type(body), body.idclass Host:@@ -179,7 +190,7 @@ class Host:if entry.sink is not None:entry.sink.active = Falseself._stream.remove(- "notebook",+ protocol.Notebook,record.id,notebook_id=record.id,request_id=request_id,@@ -236,13 +247,11 @@ class Host:# The initial state joins the stream the way later changes do,# so the run history sees every run from its first event.with self._stream.deferred():- for event in notebook._snapshot():- assert event.kind is not None- body = getattr(event.data, event.kind)+ for body, run_id in notebook._records():sink.publish(body,notebook_id=notebook.id,- run_id=event.run_id,+ run_id=run_id,)if self._entries.get(notebook_id) is not entry:raise NotFound(f"no notebook {notebook_id}")@@ -259,25 +268,21 @@ class Host:def _snapshot(self, notebook_id: protocol.NotebookId | None = None- ) -> list[Event]:+ ) -> list[RoutedEvent]:"""Return catalog or notebook state with retained run history."""if notebook_id is not None:records = [self._records[notebook_id]]- events: list[Event] = []+ events: list[RoutedEvent] = []else:records = list(self._records.values())- events = [Event("host", message(self._host))]- events.extend(- Event("project", message(p)) for p in self._projects.values()- )+ events = [snapshot_event(self._host)]+ events.extend(snapshot_event(p) for p in self._projects.values())for record in records:- events.append(- Event("notebook", message(record), notebook_id=record.id)- )+ events.append(snapshot_event(record, notebook_id=record.id))entry = self._entries[record.id]if entry.notebook is None:continue- seen: set[tuple[str, str]] = set()+ seen: set[tuple[type[Body], str]] = set()for event in [*entry.notebook._snapshot(),*entry.log.snapshot(),@@ -295,7 +300,7 @@ class Host:notebook_id: str | None = None,types: Collection[str] | None = None,run_id: str | None = None,- ) -> list[Event]:+ ) -> list[RoutedEvent]:"""Return a snapshot or replay followed by `ready`.A cursor requests the events after it. An unavailable cursor returns@@ -306,13 +311,18 @@ class Host:if notebook_id not in self._records:raise NotFound(f"no notebook {notebook_id}")scope = self._records[notebook_id].id- ready = Event("ready", id=self._stream.last_id)+ ready = RoutedEvent(+ protocol.ReadyEvent(data={}, id=str(self._stream.last_id))+ )if cursor is None:events = self._snapshot(scope)else:missed = self._stream.since(cursor)if missed is None:- events = [Event("reset"), *self._snapshot(scope)]+ events = [+ RoutedEvent(protocol.ResetEvent(data={})),+ *self._snapshot(scope),+ ]else:events = [e for e in missed if e.visible_in(notebook_id)]return [e for e in [*events, ready] if e.wanted(types, run_id)]@@ -334,7 +344,7 @@ class Host:) -> Callable[[], None]:"""Subscribe to matching events and return an unsubscribe function."""- def filtered(event: Event) -> None:+ def filtered(event: RoutedEvent) -> None:if event.visible_in(notebook_id) and event.wanted(types, run_id):listener(event)diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.pyindex 8d03364da4..6615010edd 100644--- a/marimo/_core/notebook.py+++ b/marimo/_core/notebook.py@@ -16,10 +16,10 @@ from marimo._core.document import Stalefrom marimo._core.errors import Conflict, EditConflict, NoRuntime, NotFoundfrom marimo._core.executions import Executions, Released, Removedfrom marimo._core.ids import mint-from marimo._core.stream import Event, Kind, kind_of, message, utcnow+from marimo._core.stream import RoutedEvent, snapshot_event, utcnowif TYPE_CHECKING:- from collections.abc import Callable, Mapping, Sequence+ from collections.abc import Callable, Iterator, Mapping, Sequencefrom marimo._core.analysis import Analyzerfrom marimo._core.document import (@@ -28,7 +28,8 @@ if TYPE_CHECKING:DocumentCell,)from marimo._core.executions import Change- from marimo._core.stream import Body, Sink+ from marimo._core.protocol_events import Body, RemovableBody, SnapshotBody+ from marimo._core.stream import SinkLOGGER = logging.getLogger(__name__)@@ -275,7 +276,7 @@ class Notebook:self._apply(self.executions.remove_cell(protocol.CellId(cell_id)))- self._remove("cell", cell_id, request_id)+ self._remove(protocol.Cell, cell_id, request_id)record = self._refresh()if record is not None:self._publish(record, request_id)@@ -421,7 +422,7 @@ class Notebook:assert self._runtime is not Noneself._apply(self.executions.interrupt())runtime, self._runtime = self._runtime, None- self._remove("runtime", runtime.id, self._runtime_request)+ self._remove(protocol.Runtime, runtime.id, self._runtime_request)self._runtime_request = None# ---- runs ----------------------------------------------------------@@ -492,7 +493,7 @@ class Notebook:"""Remove an attachment if it exists."""attachment = self._attachments.pop(attachment_id, None)if attachment is not None:- self._remove("attachment", attachment.id, None)+ self._remove(protocol.Attachment, attachment.id, None)# ---- backend updates -----------------------------------------------@@ -583,35 +584,31 @@ class Notebook:# ---- stream --------------------------------------------------------- def _snapshot(self) -> list[Event]:- """Return current state as events in dependency order."""- bodies: list[Body] = [- *(self._cell_record(cell) for cell in self.document),- self._document_record,- ]+ def _records(self) -> Iterator[tuple[SnapshotBody, protocol.RunId | None]]:+ """Current records in dependency order, borrowed until publication."""+ for cell in self.document:+ yield self._cell_record(cell), None+ yield self._document_record, Noneif self._analysis is not None:- bodies.append(self._analysis)+ yield self._analysis, Noneif self._runtime is not None:- bodies.append(self._runtime)- bodies.extend(self._attachments.values())- events = [- Event(kind_of(body), message(body), notebook_id=self.id)- for body in bodies- ]- executions = self.executions- for record in executions._records():- run_id = executions.run_id_of(record)- events.append(- Event(- kind_of(record),- message(- record, request_id=executions.snapshot_request(run_id)- ),- notebook_id=self.id,- run_id=run_id,- )+ yield self._runtime, None+ for attachment in self._attachments.values():+ yield attachment, None+ for record in self.executions._records():+ yield record, self.executions.run_id_of(record)++ def _snapshot(self) -> list[RoutedEvent]:+ """Return current state as events in dependency order."""+ return [+ snapshot_event(+ record,+ request_id=self.executions.snapshot_request(run_id),+ notebook_id=self.id,+ run_id=run_id,)- return events+ for record, run_id in self._records()+ ]def _dispose(self, *, request_id: str | None = None) -> None:"""Close the notebook and remove its state, children first.@@ -627,7 +624,7 @@ class Notebook:self.detach(attachment_id)if self._runtime is not None:runtime, self._runtime = self._runtime, None- self._remove("runtime", runtime.id, request_id)+ self._remove(protocol.Runtime, runtime.id, request_id)def _publish(self, body: Body, request_id: str | None) -> None:self.sink.publish(@@ -638,12 +635,12 @@ class Notebook:def _remove(self,- kind: Kind,+ record_type: type[RemovableBody],object_id: str,request_id: str | None,) -> None:self.sink.remove(- kind,+ record_type,object_id,notebook_id=self.id,request_id=request_id,@@ -662,7 +659,7 @@ class Notebook:request_id = executions.request_id(run_id)if isinstance(change, Removed):self.sink.remove(- change.kind,+ change.record_type,change.id,notebook_id=self.id,run_id=run_id,diff --git a/marimo/_core/protocol_events.py b/marimo/_core/protocol_events.pynew file mode 100644index 0000000000..0b4f5e55ff--- /dev/null+++ b/marimo/_core/protocol_events.py@@ -0,0 +1,612 @@+# Copyright 2026 Marimo. All rights reserved.+# AUTO-GENERATED FILE — DO NOT EDIT.+# Generated from protocols/host/openapi.yaml.+# Regenerate with `make host-protocol-codegen`.+"""Typed envelope adapters. Payload ownership stays with the caller."""++from __future__ import annotations++from typing import TYPE_CHECKING, TypeAlias, overload++from msgspec import UNSET, UnsetType++from marimo._core import protocol++if TYPE_CHECKING:+ from datetime import datetime++Body: TypeAlias = (+ protocol.Analysis+ | protocol.Attachment+ | protocol.Cell+ | protocol.Console+ | protocol.Custom+ | protocol.Display+ | protocol.Document+ | protocol.Execution+ | protocol.Host+ | protocol.Notebook+ | protocol.Project+ | protocol.Run+ | protocol.Runtime+ | protocol.Variable+)+SnapshotBody: TypeAlias = (+ protocol.Analysis+ | protocol.Attachment+ | protocol.Cell+ | protocol.Console+ | protocol.Display+ | protocol.Document+ | protocol.Execution+ | protocol.Host+ | protocol.Notebook+ | protocol.Project+ | protocol.Run+ | protocol.Runtime+ | protocol.Variable+)+RecordEvent: TypeAlias = (+ protocol.AnalysisEvent+ | protocol.AttachmentEvent+ | protocol.CellEvent+ | protocol.ConsoleEvent+ | protocol.CustomEvent+ | protocol.DisplayEvent+ | protocol.DocumentEvent+ | protocol.ExecutionEvent+ | protocol.HostEvent+ | protocol.NotebookEvent+ | protocol.ProjectEvent+ | protocol.RunEvent+ | protocol.RuntimeEvent+ | protocol.VariableEvent+)+RemovableBody: TypeAlias = (+ protocol.Attachment+ | protocol.Cell+ | protocol.Console+ | protocol.Display+ | protocol.Execution+ | protocol.Notebook+ | protocol.Project+ | protocol.Run+ | protocol.Runtime+ | protocol.Variable+)+RemovalEvent: TypeAlias = (+ protocol.AttachmentRemovedEvent+ | protocol.CellRemovedEvent+ | protocol.ConsoleRemovedEvent+ | protocol.DisplayRemovedEvent+ | protocol.ExecutionRemovedEvent+ | protocol.NotebookRemovedEvent+ | protocol.ProjectRemovedEvent+ | protocol.RunRemovedEvent+ | protocol.RuntimeRemovedEvent+ | protocol.VariableRemovedEvent+)+++@overload+def record(+ value: protocol.Analysis,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.AnalysisEvent: ...+++@overload+def record(+ value: protocol.Attachment,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.AttachmentEvent: ...+++@overload+def record(+ value: protocol.Cell,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.CellEvent: ...+++@overload+def record(+ value: protocol.Console,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.ConsoleEvent: ...+++@overload+def record(+ value: protocol.Custom,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime,+) -> protocol.CustomEvent: ...+++@overload+def record(+ value: protocol.Display,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.DisplayEvent: ...+++@overload+def record(+ value: protocol.Document,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.DocumentEvent: ...+++@overload+def record(+ value: protocol.Execution,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.ExecutionEvent: ...+++@overload+def record(+ value: protocol.Host,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.HostEvent: ...+++@overload+def record(+ value: protocol.Notebook,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.NotebookEvent: ...+++@overload+def record(+ value: protocol.Project,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.ProjectEvent: ...+++@overload+def record(+ value: protocol.Run,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.RunEvent: ...+++@overload+def record(+ value: protocol.Runtime,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.RuntimeEvent: ...+++@overload+def record(+ value: protocol.Variable,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.VariableEvent: ...+++def record(+ value: Body,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> RecordEvent:+ """Wrap a record without copying it; occurrences require a timestamp."""+ match value:+ case protocol.Analysis():+ return protocol.AnalysisEvent(+ protocol.AnalysisMessage(+ analysis=value, request_id=request_id, time=time+ )+ )++ case protocol.Attachment():+ return protocol.AttachmentEvent(+ protocol.AttachmentMessage(+ attachment=value, request_id=request_id, time=time+ )+ )++ case protocol.Cell():+ return protocol.CellEvent(+ protocol.CellMessage(+ cell=value, request_id=request_id, time=time+ )+ )++ case protocol.Console():+ return protocol.ConsoleEvent(+ protocol.ConsoleMessage(+ console=value, request_id=request_id, time=time+ )+ )++ case protocol.Custom():+ if isinstance(time, UnsetType):+ raise ValueError("CustomEvent requires an emission time")++ return protocol.CustomEvent(+ protocol.CustomMessage(+ custom=value, request_id=request_id, time=time+ )+ )++ case protocol.Display():+ return protocol.DisplayEvent(+ protocol.DisplayMessage(+ display=value, request_id=request_id, time=time+ )+ )++ case protocol.Document():+ return protocol.DocumentEvent(+ protocol.DocumentMessage(+ document=value, request_id=request_id, time=time+ )+ )++ case protocol.Execution():+ return protocol.ExecutionEvent(+ protocol.ExecutionMessage(+ execution=value, request_id=request_id, time=time+ )+ )++ case protocol.Host():+ return protocol.HostEvent(+ protocol.HostMessage(+ host=value, request_id=request_id, time=time+ )+ )++ case protocol.Notebook():+ return protocol.NotebookEvent(+ protocol.NotebookMessage(+ notebook=value, request_id=request_id, time=time+ )+ )++ case protocol.Project():+ return protocol.ProjectEvent(+ protocol.ProjectMessage(+ project=value, request_id=request_id, time=time+ )+ )++ case protocol.Run():+ return protocol.RunEvent(+ protocol.RunMessage(+ run=value, request_id=request_id, time=time+ )+ )++ case protocol.Runtime():+ return protocol.RuntimeEvent(+ protocol.RuntimeMessage(+ runtime=value, request_id=request_id, time=time+ )+ )++ case protocol.Variable():+ return protocol.VariableEvent(+ protocol.VariableMessage(+ variable=value, request_id=request_id, time=time+ )+ )++ raise TypeError(f"Unsupported record type: {type(value)}")+++@overload+def body(event: protocol.AnalysisEvent) -> protocol.Analysis: ...+++@overload+def body(event: protocol.AttachmentEvent) -> protocol.Attachment: ...+++@overload+def body(event: protocol.CellEvent) -> protocol.Cell: ...+++@overload+def body(event: protocol.ConsoleEvent) -> protocol.Console: ...+++@overload+def body(event: protocol.CustomEvent) -> protocol.Custom: ...+++@overload+def body(event: protocol.DisplayEvent) -> protocol.Display: ...+++@overload+def body(event: protocol.DocumentEvent) -> protocol.Document: ...+++@overload+def body(event: protocol.ExecutionEvent) -> protocol.Execution: ...+++@overload+def body(event: protocol.HostEvent) -> protocol.Host: ...+++@overload+def body(event: protocol.NotebookEvent) -> protocol.Notebook: ...+++@overload+def body(event: protocol.ProjectEvent) -> protocol.Project: ...+++@overload+def body(event: protocol.RunEvent) -> protocol.Run: ...+++@overload+def body(event: protocol.RuntimeEvent) -> protocol.Runtime: ...+++@overload+def body(event: protocol.VariableEvent) -> protocol.Variable: ...+++def body(event: RecordEvent) -> Body:+ """Read a record payload without copying it."""+ match event:+ case protocol.AnalysisEvent(data=data):+ return data.analysis++ case protocol.AttachmentEvent(data=data):+ return data.attachment++ case protocol.CellEvent(data=data):+ return data.cell++ case protocol.ConsoleEvent(data=data):+ return data.console++ case protocol.CustomEvent(data=data):+ return data.custom++ case protocol.DisplayEvent(data=data):+ return data.display++ case protocol.DocumentEvent(data=data):+ return data.document++ case protocol.ExecutionEvent(data=data):+ return data.execution++ case protocol.HostEvent(data=data):+ return data.host++ case protocol.NotebookEvent(data=data):+ return data.notebook++ case protocol.ProjectEvent(data=data):+ return data.project++ case protocol.RunEvent(data=data):+ return data.run++ case protocol.RuntimeEvent(data=data):+ return data.runtime++ case protocol.VariableEvent(data=data):+ return data.variable++ raise TypeError(f"Not a record event: {type(event)}")+++@overload+def removed(+ record_type: type[protocol.Attachment],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.AttachmentRemovedEvent: ...+++@overload+def removed(+ record_type: type[protocol.Cell],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.CellRemovedEvent: ...+++@overload+def removed(+ record_type: type[protocol.Console],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.ConsoleRemovedEvent: ...+++@overload+def removed(+ record_type: type[protocol.Display],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.DisplayRemovedEvent: ...+++@overload+def removed(+ record_type: type[protocol.Execution],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.ExecutionRemovedEvent: ...+++@overload+def removed(+ record_type: type[protocol.Notebook],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.NotebookRemovedEvent: ...+++@overload+def removed(+ record_type: type[protocol.Project],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.ProjectRemovedEvent: ...+++@overload+def removed(+ record_type: type[protocol.Run],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.RunRemovedEvent: ...+++@overload+def removed(+ record_type: type[protocol.Runtime],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.RuntimeRemovedEvent: ...+++@overload+def removed(+ record_type: type[protocol.Variable],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.VariableRemovedEvent: ...+++def removed(+ record_type: type[RemovableBody],+ object_id: str,+ *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> RemovalEvent:+ """Construct the removal envelope for a supported record type."""++ if record_type is protocol.Attachment:+ return protocol.AttachmentRemovedEvent(+ protocol.RemovedMessage(+ id=object_id, request_id=request_id, time=time+ )+ )++ if record_type is protocol.Cell:+ return protocol.CellRemovedEvent(+ protocol.RemovedMessage(+ id=object_id, request_id=request_id, time=time+ )+ )++ if record_type is protocol.Console:+ return protocol.ConsoleRemovedEvent(+ protocol.RemovedMessage(+ id=object_id, request_id=request_id, time=time+ )+ )++ if record_type is protocol.Display:+ return protocol.DisplayRemovedEvent(+ protocol.RemovedMessage(+ id=object_id, request_id=request_id, time=time+ )+ )++ if record_type is protocol.Execution:+ return protocol.ExecutionRemovedEvent(+ protocol.RemovedMessage(+ id=object_id, request_id=request_id, time=time+ )+ )++ if record_type is protocol.Notebook:+ return protocol.NotebookRemovedEvent(+ protocol.RemovedMessage(+ id=object_id, request_id=request_id, time=time+ )+ )++ if record_type is protocol.Project:+ return protocol.ProjectRemovedEvent(+ protocol.RemovedMessage(+ id=object_id, request_id=request_id, time=time+ )+ )++ if record_type is protocol.Run:+ return protocol.RunRemovedEvent(+ protocol.RemovedMessage(+ id=object_id, request_id=request_id, time=time+ )+ )++ if record_type is protocol.Runtime:+ return protocol.RuntimeRemovedEvent(+ protocol.RemovedMessage(+ id=object_id, request_id=request_id, time=time+ )+ )++ if record_type is protocol.Variable:+ return protocol.VariableRemovedEvent(+ protocol.RemovedMessage(+ id=object_id, request_id=request_id, time=time+ )+ )++ raise TypeError(f"No removal event for {record_type}")diff --git a/marimo/_core/run_log.py b/marimo/_core/run_log.pyindex cabf5baf7a..3edbe2b667 100644--- a/marimo/_core/run_log.py+++ b/marimo/_core/run_log.py@@ -7,8 +7,8 @@ from dataclasses import dataclass, fieldfrom math import isfinitefrom typing import TYPE_CHECKING-from marimo._core import protocol-from marimo._core.stream import Event, Kind, message, removal+from marimo._core import protocol, protocol_events+from marimo._core.stream import RoutedEvent, removal, snapshot_eventif TYPE_CHECKING:from collections.abc import Callable@@ -29,15 +29,15 @@ class RetentionPolicy:class _Scratch:"""A scratch execution's latest event and its outputs."""- execution: Event- outputs: dict[str, Event] = field(default_factory=dict)+ execution: RoutedEvent+ outputs: dict[str, RoutedEvent] = field(default_factory=dict)@dataclassclass _Run:"""A run's latest event and what still keeps it visible."""- event: Event+ event: RoutedEventrequest_id: str | Nonelive: set[str] = field(default_factory=set)scratch: dict[str, _Scratch] = field(default_factory=dict)@@ -60,10 +60,10 @@ class RunLog:self._clock = clockself._runs: dict[str, _Run] = {}- def observe(self, event: Event) -> list[Event]:+ def observe(self, event: RoutedEvent) -> list[RoutedEvent]:"""Record an event and return removals to publish after it."""- match event:- case Event(+ match event.event:+ case protocol.RunEvent(data=protocol.RunMessage(run=run, request_id=request_id)):entry = self._runs.get(run.id)@@ -76,7 +76,9 @@ class RunLog:if run.status == "completed" and entry.completed_at is None:entry.completed_at = self._clock()return self._close(run.id)- case Event(data=protocol.ExecutionMessage(execution=execution)):+ case protocol.ExecutionEvent(+ data=protocol.ExecutionMessage(execution=execution)+ ):if (entry := self._entry(event)) is not None:entry.had_executions = Trueentry.live.add(execution.id)@@ -86,12 +88,16 @@ class RunLog:entry.scratch[execution.id] = _Scratch(event)else:scratch.execution = event- case Event(data=protocol.ConsoleMessage(console=item)):+ case protocol.ConsoleEvent(+ data=protocol.ConsoleMessage(console=item)+ ):self._record_output(event, item)- case Event(data=protocol.DisplayMessage(display=item)):+ case protocol.DisplayEvent(+ data=protocol.DisplayMessage(display=item)+ ):self._record_output(event, item)- case Event(- kind="execution", data=protocol.RemovedMessage(id=execution_id)+ case protocol.ExecutionRemovedEvent(+ data=protocol.RemovedMessage(id=execution_id)):if (entry := self._entry(event)) is not None:entry.live.discard(execution_id)@@ -105,10 +111,10 @@ class RunLog:entry = self._runs.get(run_id)if entry is None:return None- assert isinstance(entry.event.data, protocol.RunMessage)- return entry.event.data.run+ assert isinstance(entry.event.event, protocol.RunEvent)+ return entry.event.event.data.run- def snapshot(self) -> list[Event]:+ def snapshot(self) -> list[RoutedEvent]:"""Return the runs and scratch the log holds, parents first."""events = [self._snapshot_event(e.event, e) for e in self._runs.values()@@ -122,10 +128,10 @@ class RunLog:)return events- def expire(self, policy: RetentionPolicy) -> list[Event]:+ def expire(self, policy: RetentionPolicy) -> list[RoutedEvent]:"""Return removals for scratch whose retention has ended."""now = self._clock()- events: list[Event] = []+ events: list[RoutedEvent] = []for run_id, entry in list(self._runs.items()):if ((entry.scratch or not entry.had_executions)@@ -135,9 +141,9 @@ class RunLog:events.extend(self._release(run_id))return events- def clear(self) -> list[Event]:+ def clear(self) -> list[RoutedEvent]:"""Remove all retained history."""- events: list[Event] = []+ events: list[RoutedEvent] = []for run_id, entry in list(self._runs.items()):entry.live.clear()if entry.completed_at is None:@@ -145,11 +151,11 @@ class RunLog:events.extend(self._release(run_id))return events- def _entry(self, event: Event) -> _Run | None:+ def _entry(self, event: RoutedEvent) -> _Run | None:return None if event.run_id is None else self._runs.get(event.run_id)def _record_output(- self, event: Event, item: protocol.Console | protocol.Display+ self, event: RoutedEvent, item: protocol.Console | protocol.Display) -> None:entry = self._entry(event)if entry is None:@@ -158,21 +164,28 @@ class RunLog:if scratch is not None:scratch.outputs[item.id] = event- def _release(self, run_id: str) -> list[Event]:+ def _release(self, run_id: str) -> list[RoutedEvent]:"""Remove a run's scratch, then the run if nothing else holds it."""entry = self._runs[run_id]- events: list[Event] = []+ events: list[RoutedEvent] = []for execution_id, scratch in entry.scratch.items():for output in scratch.outputs.values():- assert output.kind is not None- item = getattr(output.data, output.kind)- events.append(self._removal(entry, output.kind, item.id))- events.append(self._removal(entry, "execution", execution_id))+ assert isinstance(+ output.event,+ (protocol.ConsoleEvent, protocol.DisplayEvent),+ )+ body = protocol_events.body(output.event)+ events.append(self._removal(entry, type(body), body.id))+ events.append(+ self._removal(entry, protocol.Execution, execution_id)+ )entry.live.discard(execution_id)entry.scratch.clear()return [*events, *self._close(run_id, retain_empty=False)]- def _close(self, run_id: str, *, retain_empty: bool = True) -> list[Event]:+ def _close(+ self, run_id: str, *, retain_empty: bool = True+ ) -> list[RoutedEvent]:entry = self._runs[run_id]if (entry.completed_at is None@@ -181,29 +194,30 @@ class RunLog:):return []del self._runs[run_id]- return [self._removal(entry, "run", run_id)]-- def _removal(self, entry: _Run, kind: Kind, object_id: str) -> Event:+ return [self._removal(entry, protocol.Run, run_id)]++ def _removal(+ self,+ entry: _Run,+ record_type: type[protocol_events.RemovableBody],+ object_id: str,+ ) -> RoutedEvent:return removal(- kind,+ record_type,object_id,notebook_id=entry.event.notebook_id,request_id=entry.request_id,run_id=entry.event.run_id,)- def _snapshot_event(self, event: Event, entry: _Run) -> Event:- assert event.kind is not None- body = getattr(event.data, event.kind)- return Event(- event.name,- message(- body,- request_id=(- None- if entry.completed_at is not None- else entry.request_id- ),+ def _snapshot_event(self, event: RoutedEvent, entry: _Run) -> RoutedEvent:+ assert isinstance(event.event, protocol_events.RecordEvent)+ body = protocol_events.body(event.event)+ assert isinstance(body, protocol_events.SnapshotBody)+ return snapshot_event(+ body,+ request_id=(+ None if entry.completed_at is not None else entry.request_id),notebook_id=event.notebook_id,run_id=event.run_id,diff --git a/marimo/_core/stream.py b/marimo/_core/stream.pyindex eb21e0cf9b..706c23cf8b 100644--- a/marimo/_core/stream.py+++ b/marimo/_core/stream.py@@ -13,94 +13,32 @@ from collections import dequefrom collections.abc import Callable, Collection, Iteratorfrom contextlib import AbstractContextManager, contextmanagerfrom copy import deepcopy-from dataclasses import dataclass+from dataclasses import dataclass, replacefrom datetime import datetime, timezone-from typing import Literal, TypeAlias, get_argsimport msgspecfrom msgspec import UNSET-from marimo._core import protocol+from marimo._core import protocol, protocol_eventsLOGGER = logging.getLogger(__name__)-Body: TypeAlias = (- protocol.Host- | protocol.Project- | protocol.Notebook- | protocol.Document- | protocol.Analysis- | protocol.Cell- | protocol.Runtime- | protocol.Attachment- | protocol.Run- | protocol.Execution- | protocol.Console- | protocol.Display- | protocol.Variable- | protocol.Custom-)-"""Every object a stream carries. The wrapper map and the notebook kinds-derive from it; the catalog kinds are a chosen subset."""---Kind: TypeAlias = Literal[- "host",- "project",- "notebook",- "document",- "analysis",- "cell",- "runtime",- "attachment",- "run",- "execution",- "console",- "display",- "variable",- "custom",-]-"""The kinds of object a stream carries, one per `Body` type."""--_KIND_BY_NAME: dict[str, Kind] = {kind: kind for kind in get_args(Kind)}-assert set(_KIND_BY_NAME) == {- body_type.__name__.lower() for body_type in get_args(Body)-}---def kind_of(body: Body) -> Kind:- """Return the object's event kind, used by the `types` filter."""- return _KIND_BY_NAME[type(body).__name__.lower()]---_WRAPPERS: dict[Kind, type[msgspec.Struct]] = {- _KIND_BY_NAME[body_type.__name__.lower()]: getattr(- protocol, f"{body_type.__name__}Message"- )- for body_type in get_args(Body)-}--CATALOG_KINDS: frozenset[Kind] = frozenset(- {"host", "project", "notebook", "runtime", "attachment"}-)-# Host and project describe the whole host, so they never belong to one-# notebook's stream. Every other kind does.-NOTEBOOK_KINDS = frozenset(_WRAPPERS) - {"host", "project"}--def message(- body: Body,+def snapshot_event(+ body: protocol_events.SnapshotBody,*,+ notebook_id: protocol.NotebookId | None = None,+ run_id: protocol.RunId | None = None,request_id: str | None = None,- time: datetime | None = None,-) -> msgspec.Struct:- """Wrap an object in its protocol message."""- kind = kind_of(body)- fields: dict[str, Body] = {kind: deepcopy(body)}- return _WRAPPERS[kind](- **fields,- request_id=UNSET if request_id is None else request_id,- time=UNSET if time is None else time,+) -> RoutedEvent:+ """Copy current state into an event without an emission time or cursor."""+ return RoutedEvent(+ protocol_events.record(+ deepcopy(body),+ request_id=UNSET if request_id is None else request_id,+ ),+ notebook_id=notebook_id,+ run_id=run_id,)@@ -109,66 +47,100 @@ def utcnow() -> datetime:def removal(- kind: Kind,+ record_type: type[protocol_events.RemovableBody],object_id: str,*,notebook_id: protocol.NotebookId | None = None,request_id: str | None = None,run_id: protocol.RunId | None = None,-) -> Event:+) -> RoutedEvent:"""Return an event announcing an object's removal."""- data = protocol.RemovedMessage(- id=object_id,- request_id=UNSET if request_id is None else request_id,- time=utcnow(),- )- return Event(- f"{kind}.removed", data, notebook_id=notebook_id, run_id=run_id+ return RoutedEvent(+ protocol_events.removed(+ record_type,+ object_id,+ request_id=UNSET if request_id is None else request_id,+ time=utcnow(),+ ),+ notebook_id=notebook_id,+ run_id=run_id,)-@dataclass(frozen=True)-class Event:- """An event with an optional replay cursor and notebook scope.+class ExtensionEvent(msgspec.Struct, frozen=True, tag_field="event"):+ """Base envelope for host extensions outside the public protocol.- Snapshot events have no `id`. Control events have no `data`.+ Subclasses declare their event tag and payload type."""- name: str- data: msgspec.Struct | None = None- id: int | None = None+ data: msgspec.Struct+ id: str | msgspec.UnsetType = UNSET+++def event_name(event: protocol.Event | ExtensionEvent) -> str:+ """Read the wire tag for transport framing and client type filters."""+ tag = event.__struct_config__.tag+ assert isinstance(tag, str)+ return tag+++@dataclass(frozen=True)+class RoutedEvent:+ """A typed wire event with internal notebook and run routing."""++ event: protocol.Event | ExtensionEventnotebook_id: protocol.NotebookId | None = Nonerun_id: protocol.RunId | None = None@property- def kind(self) -> Kind | None:- """The object kind without the `.removed` suffix.-- `ready` and `reset` carry no object and have no kind.- """- return _KIND_BY_NAME.get(self.name.partition(".")[0])+ def id(self) -> int | None:+ """The stream's integer cursor, absent on snapshots and resets."""+ return None if self.event.id is UNSET else int(self.event.id)def visible_in(self, notebook_id: str | None) -> bool:"""Whether the event belongs in the catalog or notebook stream."""+ if isinstance(self.event, (protocol.ReadyEvent, protocol.ResetEvent)):+ return Falseif notebook_id is None:- return self.kind in CATALOG_KINDS- return self.notebook_id == notebook_id and (- self.kind in NOTEBOOK_KINDS- or (self.kind is None and self.name not in ("ready", "reset"))+ return isinstance(+ self.event,+ (+ protocol.HostEvent,+ protocol.ProjectEvent,+ protocol.ProjectRemovedEvent,+ protocol.NotebookEvent,+ protocol.NotebookRemovedEvent,+ protocol.RuntimeEvent,+ protocol.RuntimeRemovedEvent,+ protocol.AttachmentEvent,+ protocol.AttachmentRemovedEvent,+ ),+ )+ return self.notebook_id == notebook_id and not isinstance(+ self.event,+ (+ protocol.HostEvent,+ protocol.ProjectEvent,+ protocol.ProjectRemovedEvent,+ ),)def wanted(self, types: Collection[str] | None, run_id: str | None = None) -> bool:"""Apply kind and run filters, always including `ready` and `reset`."""- if self.name in ("ready", "reset"):+ if isinstance(self.event, (protocol.ReadyEvent, protocol.ResetEvent)):return True- return (types is None or (self.kind or self.name) in types) and (- run_id is None or self.run_id == run_id- )+ if types is not None:+ kind = event_name(self.event)+ if isinstance(self.event, protocol_events.RemovalEvent):+ kind = kind.removesuffix(".removed")+ if kind not in types:+ return False+ return run_id is None or self.run_id == run_id-Listener = Callable[[Event], None]+Listener = Callable[[RoutedEvent], None]class Sink(ABC):@@ -178,37 +150,44 @@ class Sink(ABC):each event before the stream records it."""- def append(self, event: Event) -> Event:+ def append(self, event: RoutedEvent) -> RoutedEvent:"""Record an event without requiring a public protocol type."""return self._append(deepcopy(event))def publish(self,- body: Body,+ body: protocol_events.Body,*,notebook_id: protocol.NotebookId | None = None,request_id: str | None = None,run_id: protocol.RunId | None = None,- ) -> Event:+ ) -> RoutedEvent:"""Publish a new or updated object."""- data = message(body, request_id=request_id, time=utcnow())return self._append(- Event(kind_of(body), data, notebook_id=notebook_id, run_id=run_id)+ RoutedEvent(+ protocol_events.record(+ deepcopy(body),+ request_id=UNSET if request_id is None else request_id,+ time=utcnow(),+ ),+ notebook_id=notebook_id,+ run_id=run_id,+ ))def remove(self,- kind: Kind,+ record_type: type[protocol_events.RemovableBody],object_id: str,*,notebook_id: protocol.NotebookId | None = None,request_id: str | None = None,run_id: protocol.RunId | None = None,- ) -> Event:+ ) -> RoutedEvent:"""Publish an object's removal."""return self._append(removal(- kind,+ record_type,object_id,notebook_id=notebook_id,request_id=request_id,@@ -221,7 +200,7 @@ class Sink(ABC):"""Deliver events published in the block once it ends."""@abstractmethod- def _append(self, event: Event) -> Event:+ def _append(self, event: RoutedEvent) -> RoutedEvent:"""Record an owned event and return an isolated copy as recorded.The event must already be isolated from the caller. Forward it to@@ -238,16 +217,18 @@ class Stream(Sink):def __init__(self, *, history: int = 1000) -> None:self._last_id = 0- self._history: deque[Event] = deque(maxlen=history)+ self._history: deque[RoutedEvent] = deque(maxlen=history)self._listeners: list[Listener] = []- self._pending: deque[tuple[Event, tuple[Listener, ...]]] = deque()+ self._pending: deque[tuple[RoutedEvent, tuple[Listener, ...]]] = (+ deque()+ )self._dispatching = False@propertydef last_id(self) -> int:return self._last_id- def since(self, cursor: int) -> list[Event] | None:+ def since(self, cursor: int) -> list[RoutedEvent] | None:"""Return events after `cursor`, or `None` for a stale or future cursor."""if cursor == self._last_id:return []@@ -292,14 +273,11 @@ class Stream(Sink):self._dispatching = Falseself._drain()- def _append(self, event: Event) -> Event:+ def _append(self, event: RoutedEvent) -> RoutedEvent:self._last_id += 1- stamped = Event(- event.name,- event.data,- self._last_id,- event.notebook_id,- event.run_id,+ stamped = replace(+ event,+ event=msgspec.structs.replace(event.event, id=str(self._last_id)),)self._history.append(stamped)self._pending.append((stamped, tuple(self._listeners)))diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.pyindex 43f2606721..7ecdeef58e 100644--- a/marimo/_server/host/api.py+++ b/marimo/_server/host/api.py@@ -30,6 +30,7 @@ from marimo._core.errors import (NoRuntime,NotFound,)+from marimo._core.stream import event_namefrom marimo._server.api.auth import TOKEN_QUERY_PARAM, validate_authfrom marimo._server.api.deps import AppState, AppStateBasefrom marimo._server.api.endpoints.ws.ws_connection_validator import (@@ -52,7 +53,7 @@ if TYPE_CHECKING:from starlette.requests import HTTPConnection, Requestfrom marimo._core.notebook import Notebook- from marimo._core.stream import Event+ from marimo._core.stream import RoutedEventfrom marimo._server.host.bridge import SessionBridgefrom marimo._server.host.context import HostContext@@ -254,10 +255,10 @@ def _mutation(operation: str) -> Callable[[_Endpoint], _Endpoint]:lifecycle_accepted: Callable[[Response], None] | None = Noneif operation == "runtime.run" and request.method == "POST":# The receipt outlives results without retaining their payloads.- def updated(event: Event) -> None:- if isinstance(event.data, protocol.RunMessage):- run = event.data.run- if event.data.request_id == key:+ def updated(event: RoutedEvent) -> None:+ if isinstance(event.event, protocol.RunEvent):+ run = event.event.data.run+ if event.event.data.request_id == key:mutation.run = runif (run.status == "completed"@@ -319,13 +320,13 @@ def _watch_lifecycle() -> tuple[Callable[[Response], None], Callable[[], None]]:runtime_id: protocol.RuntimeId | None = Noneprevious_id: protocol.RuntimeId | None = None- early: list[Event] = []+ early: list[RoutedEvent] = []def settle() -> None:context.settle(mutation)unsubscribe()- def updated(event: Event) -> None:+ def updated(event: RoutedEvent) -> None:nonlocal previous_idif mutation.expires_at is not None:return@@ -333,13 +334,13 @@ def _watch_lifecycle(# A backend can finish synchronously, before the response exists.early.append(event)return- if event.name == "notebook.removed":+ if isinstance(event.event, protocol.NotebookRemovedEvent):settle()- elif isinstance(event.data, protocol.RuntimeMessage):- runtime = event.data.runtime+ elif isinstance(event.event, protocol.RuntimeEvent):+ runtime = event.event.data.runtimeif (operation == "runtime.restart"- and event.data.request_id == request_id+ and event.event.data.request_id == request_idand runtime.status == "terminating"and runtime.id != runtime_id):@@ -350,12 +351,10 @@ def _watch_lifecycle(and runtime.status in ("running", "failed")):settle()- elif event.name == "runtime.removed" and isinstance(- event.data, protocol.RemovedMessage- ):- if event.data.id == runtime_id or (- event.data.id == previous_id- and event.data.request_id != request_id+ elif isinstance(event.event, protocol.RuntimeRemovedEvent):+ if event.event.data.id == runtime_id or (+ event.event.data.id == previous_id+ and event.event.data.request_id != request_id):# A later stop can cancel a restart before its replacement starts.settle()@@ -672,12 +671,14 @@ def _initial_events(notebook_id: protocol.NotebookId | None,run_id: str | None = None,include_session: bool = False,-) -> list[Event]:+) -> list[RoutedEvent]:"""Capture a snapshot or replay, with `ready` marking its end."""events = bridge.host.events(cursor, notebook_id=notebook_id, types=types, run_id=run_id)- needs_snapshot = cursor is None or events[0].name == "reset"+ needs_snapshot = cursor is None or isinstance(+ events[0].event, protocol.ResetEvent+ )if include_session and notebook_id is not None and needs_snapshot:ready = events.pop()events.extend(@@ -691,13 +692,13 @@ def _initial_events(class _EventSubscription:def __init__(- self, initial: list[Event], queue: asyncio.Queue[Event]+ self, initial: list[RoutedEvent], queue: asyncio.Queue[RoutedEvent]) -> None:self.initial = initialself._queue = queueself._ready_id = initial[-1].id or 0- async def next(self) -> Event:+ async def next(self) -> RoutedEvent:"""Wait for a live event not already covered by the initial state."""while True:event = await self._queue.get()@@ -715,7 +716,7 @@ def _subscribe_events(run_id: str | None = None,include_session: bool = False,) -> Iterator[_EventSubscription]:- queue: asyncio.Queue[Event] = asyncio.Queue()+ queue: asyncio.Queue[RoutedEvent] = asyncio.Queue()# Subscribe and capture state in one event-loop turn to avoid lost updates.unsubscribe = bridge.host.subscribe(queue.put_nowait,@@ -775,13 +776,13 @@ def _stream()-def _frame(event: Event) -> bytes:+def _frame(event: RoutedEvent) -> bytes:"""Encode an event as an SSE frame."""lines = []if event.id is not None:lines.append(f"id: {event.id}")- lines.append(f"event: {event.name}")- data = b"{}" if event.data is None else msgspec.json.encode(event.data)+ lines.append(f"event: {event_name(event.event)}")+ data = msgspec.json.encode(event.event.data)lines.append(f"data: {data.decode()}")return ("\n".join(lines) + "\n\n").encode()diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.pyindex 94880074d6..8a4c5f5c8b 100644--- a/marimo/_server/host/bridge.py+++ b/marimo/_server/host/bridge.py@@ -38,7 +38,7 @@ if TYPE_CHECKING:from marimo._config.manager import MarimoConfigManagerfrom marimo._core.backend import Message- from marimo._core.stream import Event, Sink+ from marimo._core.stream import RoutedEvent, Sinkfrom marimo._messaging.notebook import NotebookCellfrom marimo._server.session_manager import SessionManagerfrom marimo._session.notebook import AppFileManager@@ -383,7 +383,7 @@ class SessionBridge(SessionEventListener):def session_snapshot(self, notebook_id: protocol.NotebookId- ) -> list[Event]:+ ) -> list[RoutedEvent]:"""Return retained marimo events for one client without publishing them."""session = self._session_of(notebook_id)if session is None:@@ -658,8 +658,11 @@ class SessionBridge(SessionEventListener):self._backends[notebook_id] = backendreturn backend- def _forget_backend(self, event: Event) -> None:- if event.name == "notebook.removed" and event.notebook_id is not None:+ def _forget_backend(self, event: RoutedEvent) -> None:+ if (+ isinstance(event.event, protocol.NotebookRemovedEvent)+ and event.notebook_id is not None+ ):self._backends.pop(event.notebook_id, None)self._file_texts.pop(event.notebook_id, None)self._rebaselining.pop(event.notebook_id, None)diff --git a/marimo/_server/host/events.py b/marimo/_server/host/events.pyindex 07246a34cc..d7b9b10ed4 100644--- a/marimo/_server/host/events.py+++ b/marimo/_server/host/events.py@@ -6,7 +6,7 @@ from __future__ import annotationsimport msgspecfrom marimo._core import protocol-from marimo._core.stream import Event+from marimo._core.stream import ExtensionEvent, RoutedEventfrom marimo._messaging.notification import NotificationMessage@@ -19,25 +19,24 @@ class MarimoMessage(msgspec.Struct, frozen=True):marimo: NotificationMessage+class MarimoEvent(ExtensionEvent, frozen=True, tag="marimo"):+ """A typed envelope for internal marimo notifications."""++ data: MarimoMessage++def notification_event(notebook_id: protocol.NotebookId, notification: NotificationMessage-) -> Event:+) -> RoutedEvent:"""Wrap a notification with its notebook and optional run scope."""run_id = getattr(notification, "run_id", None)- return Event(- "marimo",- MarimoMessage(notification),+ return RoutedEvent(+ MarimoEvent(MarimoMessage(notification)),notebook_id=notebook_id,run_id=protocol.RunId(run_id) if run_id is not None else None,)-def serialize_event(event: Event) -> str:+def serialize_event(event: RoutedEvent) -> str:"""Encode one host event as a WebSocket frame."""- frame: dict[str, object] = {- "event": event.name,- "data": {} if event.data is None else event.data,- }- if event.id is not None:- frame["id"] = str(event.id)- return msgspec.json.encode(frame).decode()+ return msgspec.json.encode(event.event).decode()diff --git a/marimo/_server/host/websocket.py b/marimo/_server/host/websocket.pyindex 64609865ff..268a9a01bf 100644--- a/marimo/_server/host/websocket.py+++ b/marimo/_server/host/websocket.py@@ -18,7 +18,7 @@ from marimo._server.api.endpoints.ws.ws_message_loop import (from marimo._server.api.endpoints.ws.ws_session_connector import ConnectionTypefrom marimo._server.codes import WebSocketCloseReason, WebSocketCodesfrom marimo._server.host.events import (- MarimoMessage,+ MarimoEvent,notification_event,serialize_event,)@@ -29,7 +29,7 @@ if TYPE_CHECKING:from starlette.websockets import WebSocketfrom marimo._core.notebook import Notebook- from marimo._core.stream import Event+ from marimo._core.stream import RoutedEventfrom marimo._messaging.types import KernelMessagefrom marimo._server.api.endpoints.ws.ws_connection_validator import (ConnectionParams,@@ -75,7 +75,7 @@ class EditorEventSocket(SessionHandler):self.types = typesself.cursor = cursorself._ready_id = 0- self._events: asyncio.Queue[Event | _Close] = asyncio.Queue()+ self._events: asyncio.Queue[RoutedEvent | _Close] = asyncio.Queue()self._connection_type = (ConnectionType.RTC_EXISTINGif params.rtc_enabled and not params.kiosk@@ -89,10 +89,10 @@ class EditorEventSocket(SessionHandler):if event.wanted(self.types):self._events.put_nowait(event)- def _on_host_event(self, event: Event) -> None:+ def _on_host_event(self, event: RoutedEvent) -> None:# The session delivers marimo notifications with recipient filtering,# including edits that must not echo to the client that sent them.- if event.name != "marimo" and (+ if not isinstance(event.event, MarimoEvent) and (event.id is None or event.id > self._ready_id):self._events.put_nowait(event)@@ -112,7 +112,7 @@ class EditorEventSocket(SessionHandler):for event in initial:# Session notifications must retain their recipient filtering,# including on reconnect; only protocol records use replay.- if event.name != "marimo":+ if not isinstance(event.event, MarimoEvent):self._events.put_nowait(event)await self.websocket.accept()async with self._connection_lifetime(self.websocket) as startup:@@ -167,14 +167,14 @@ class EditorEventSocket(SessionHandler):):await self.websocket.close(event.code, event.reason)return- if isinstance(event.data, MarimoMessage):+ if isinstance(event.event, MarimoEvent):viewer = self.params.kioskif self._session is not None:viewer = self._is_viewer(self._session, self._connection_type)if should_filter_operation(- event.data.marimo.name, is_kiosk=viewer+ event.event.data.marimo.name, is_kiosk=viewer):continueawait self.websocket.send_text(serialize_event(event))diff --git a/protocols/host/README.md b/protocols/host/README.mdindex 831ba13148..8f2ce43e93 100644--- a/protocols/host/README.md+++ b/protocols/host/README.md@@ -9,7 +9,8 @@ notebooks and runtimes.- [Conformance tests](conformance/README.md)The OpenAPI schema is the source of truth for the Python types in-`marimo/_core/protocol.py` and the frontend schemas and types in+`marimo/_core/protocol.py`, the typed event adapters in+`marimo/_core/protocol_events.py`, and the frontend schemas and types in`frontend/src/core/host/protocol.ts`. The frontend generator also adds thenative `marimo` event with an `unknown` payload.diff --git a/protocols/host/generate.py b/protocols/host/generate.pyindex 6332c61fd7..a1619613c6 100644--- a/protocols/host/generate.py+++ b/protocols/host/generate.py@@ -2,6 +2,7 @@# requires-python = ">=3.11"# dependencies = [# "datamodel-code-generator==0.72.0",+# "jinja2==3.1.6",# "ruff==0.16.4",# "msgspec[yaml]==0.22.0"# ]@@ -76,6 +77,82 @@ def tuple_arrays(source: bytes) -> bytes:return source+def event_adapters(document: dict[str, Any]) -> str:+ """Derive typed event adapters from the discriminator and schema refs."""+ from jinja2 import Environment, FileSystemLoader, StrictUndefined++ schemas = document["components"]["schemas"]+ mapping = schemas["Event"]["discriminator"]["mapping"]++ def reference(value: dict[str, Any]) -> str:+ ref = value["$ref"]+ prefix = "#/components/schemas/"+ if not ref.startswith(prefix):+ raise ValueError(f"Expected a local schema reference: {ref}")+ return ref.removeprefix(prefix)++ records = {}+ removals = []+ for tag, ref in sorted(mapping.items()):+ name = reference({"$ref": ref})+ data = schemas[name]["properties"]["data"]+ if "$ref" not in data:+ continue # Control events have no record payload.+ message = reference(data)+ if tag.endswith(".removed"):+ removals.append((tag.removesuffix(".removed"), name, message))+ continue+ schema = schemas[message]+ fields = {+ field: reference(value)+ for field, value in schema["properties"].items()+ if "$ref" in value+ and schemas[reference(value)].get("type") == "object"+ and field in schema.get("required", [])+ }+ if len(fields) != 1:+ raise ValueError(f"{message} must contain one required record")+ field, body = next(iter(fields.items()))+ if set(schema["properties"]) != {field, "request_id", "time"}:+ raise ValueError(f"Unsupported event metadata in {message}")+ records[tag] = {+ "event": name,+ "message": message,+ "body": body,+ "field": field,+ "requires_time": "time" in schema.get("required", []),+ }++ removed = []+ for tag, name, message in removals:+ if tag not in records:+ raise ValueError(f"{name} has no corresponding record event")+ removed.append({**records[tag], "event": name, "message": message})++ env = Environment(+ loader=FileSystemLoader(Path(__file__).parent / "templates"),+ undefined=StrictUndefined,+ keep_trailing_newline=True,+ )+ return env.get_template("events.py.jinja2").render(+ records=list(records.values()), removals=removed+ )+++def format_generated(output_path: Path) -> None:+ subprocess.run(+ [+ "ruff",+ "format",+ "--isolated",+ "--line-length",+ "79",+ str(output_path),+ ],+ check=True,+ )++def generate_models(document: dict[str, Any], output_path: Path) -> None:from datamodel_code_generator import (DataModelType,@@ -124,17 +201,7 @@ def generate_models(document: dict[str, Any], output_path: Path) -> None:output_path.write_bytes(tuple_arrays(output_path.read_bytes()))- subprocess.run(- [- "ruff",- "format",- "--isolated",- "--line-length",- "79",- str(output_path),- ],- check=True,- )+ format_generated(output_path)def main() -> None:@@ -144,20 +211,25 @@ def main() -> None:parser.add_argument("--check", action="store_true")args = parser.parse_args()root = Path(__file__).resolve().parent- destination = root.parents[1] / "marimo" / "_core" / "protocol.py"+ destination = root.parents[1] / "marimo" / "_core"document = sorted_keys(msgspec.yaml.decode((root / "openapi.yaml").read_bytes()))with tempfile.TemporaryDirectory() as directory:output = Path(directory) / "protocol.py"generate_models(document, output)- content = output.read_bytes()- if not destination.exists() or destination.read_bytes() != content:- if args.check:- raise SystemExit(- "Host models are stale; run make host-protocol-codegen"- )- destination.write_bytes(content)+ adapters = Path(directory) / "protocol_events.py"+ adapters.write_text(event_adapters(document), encoding="utf-8")+ format_generated(adapters)+ for generated in (output, adapters):+ target = destination / generated.name+ content = generated.read_bytes()+ if not target.exists() or target.read_bytes() != content:+ if args.check:+ raise SystemExit(+ "Host bindings are stale; run make host-protocol-codegen"+ )+ target.write_bytes(content)print("Host protocol models are current.")diff --git a/protocols/host/generate.py.lock b/protocols/host/generate.py.lockindex bb4d3b5eda..88efab3624 100644--- a/protocols/host/generate.py.lock+++ b/protocols/host/generate.py.lock@@ -17,6 +17,7 @@ marimo-lens = false[manifest]requirements = [{ name = "datamodel-code-generator", specifier = "==0.72.0" },+ { name = "jinja2", specifier = "==3.1.6" },{ name = "msgspec", extras = ["yaml"], specifier = "==0.22.0" },{ name = "ruff", specifier = "==0.16.4" },]diff --git a/protocols/host/templates/events.py.jinja2 b/protocols/host/templates/events.py.jinja2new file mode 100644index 0000000000..8e30625c0d--- /dev/null+++ b/protocols/host/templates/events.py.jinja2@@ -0,0 +1,87 @@+# Copyright 2026 Marimo. All rights reserved.+# AUTO-GENERATED FILE — DO NOT EDIT.+# Generated from protocols/host/openapi.yaml.+# Regenerate with `make host-protocol-codegen`.+"""Typed envelope adapters. Payload ownership stays with the caller."""++from __future__ import annotations++from typing import TYPE_CHECKING, TypeAlias, overload++from msgspec import UNSET, UnsetType++from marimo._core import protocol++if TYPE_CHECKING:+ from datetime import datetime++Body: TypeAlias = {% for r in records %}protocol.{{ r.body }}{{ " | " if not loop.last }}{% endfor %}+SnapshotBody: TypeAlias = {% for r in records if not r.requires_time %}protocol.{{ r.body }}{{ " | " if not loop.last }}{% endfor %}+RecordEvent: TypeAlias = {% for r in records %}protocol.{{ r.event }}{{ " | " if not loop.last }}{% endfor %}+RemovableBody: TypeAlias = {% for r in removals %}protocol.{{ r.body }}{{ " | " if not loop.last }}{% endfor %}+RemovalEvent: TypeAlias = {% for r in removals %}protocol.{{ r.event }}{{ " | " if not loop.last }}{% endfor %}++{% for r in records %}+@overload+def record(+ value: protocol.{{ r.body }}, *,+ request_id: str | UnsetType = UNSET,+ time: datetime{{ "" if r.requires_time else " | UnsetType = UNSET" }},+) -> protocol.{{ r.event }}: ...+{% endfor %}++def record(+ value: Body, *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> RecordEvent:+ """Wrap a record without copying it; occurrences require a timestamp."""+ match value:+{% for r in records %}+ case protocol.{{ r.body }}():+{% if r.requires_time %}+ if isinstance(time, UnsetType):+ raise ValueError("{{ r.event }} requires an emission time")+{% endif %}+ return protocol.{{ r.event }}(+ protocol.{{ r.message }}({{ r.field }}=value, request_id=request_id, time=time)+ )+{% endfor %}+ raise TypeError(f"Unsupported record type: {type(value)}")++{% for r in records %}+@overload+def body(event: protocol.{{ r.event }}) -> protocol.{{ r.body }}: ...+{% endfor %}++def body(event: RecordEvent) -> Body:+ """Read a record payload without copying it."""+ match event:+{% for r in records %}+ case protocol.{{ r.event }}(data=data):+ return data.{{ r.field }}+{% endfor %}+ raise TypeError(f"Not a record event: {type(event)}")++{% for r in removals %}+@overload+def removed(+ record_type: type[protocol.{{ r.body }}], object_id: str, *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> protocol.{{ r.event }}: ...+{% endfor %}++def removed(+ record_type: type[RemovableBody], object_id: str, *,+ request_id: str | UnsetType = UNSET,+ time: datetime | UnsetType = UNSET,+) -> RemovalEvent:+ """Construct the removal envelope for a supported record type."""+{% for r in removals %}+ if record_type is protocol.{{ r.body }}:+ return protocol.{{ r.event }}(+ protocol.{{ r.message }}(id=object_id, request_id=request_id, time=time)+ )+{% endfor %}+ raise TypeError(f"No removal event for {record_type}")diff --git a/pyproject.toml b/pyproject.tomlindex 0c48430564..741186acf8 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -171,6 +171,8 @@ test = ["inline-snapshot~=0.29.0","hypothesis~=6.102.1","dirty-equals~=0.9.0",+ # For protocol code generation tests+ "jinja2>=3.1.6",# No cp315 wheels as of 2026-10 for matplotlib 3.10 and zstandard; drop the# python_version markers when published. numpy is listed on its own because# tests used to get it only through matplotlib.diff --git a/tests/_core/conftest.py b/tests/_core/conftest.pyindex 4c66737dc3..4e96a8fb58 100644--- a/tests/_core/conftest.py+++ b/tests/_core/conftest.py@@ -7,13 +7,13 @@ import asyncioimport pytest-from marimo._core import backend as be, protocol+from marimo._core import backend as be, protocol, protocol_eventsfrom marimo._core.document import Document, code_hashfrom marimo._core.executions import CellExecution, Executionsfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebookfrom marimo._core.run_log import RetentionPolicy-from marimo._core.stream import Event, Sink+from marimo._core.stream import RoutedEvent, Sink, event_nameOPERATIONS = ["notebook.create", "runtime.start", "runtime.run"]@@ -155,19 +155,19 @@ async def notebook(host: Host, backend: ScriptedBackend) -> Notebook:@pytest.fixture-def log(host: Host) -> list[Event]:+def log(host: Host) -> list[RoutedEvent]:"""Collect events published during the test."""- events: list[Event] = []+ events: list[RoutedEvent] = []host.subscribe(events.append, notebook_id="n1")return events-def names(events: list[Event]) -> list[str]:- return [e.name for e in events]+def names(events: list[RoutedEvent]) -> list[str]:+ return [event_name(e.event) for e in events]-def request_ids(events: list[Event]) -> list[object]:- return [getattr(e.data, "request_id", None) for e in events]+def request_ids(events: list[RoutedEvent]) -> list[object]:+ return [getattr(e.event.data, "request_id", None) for e in events]class Clock:@@ -221,17 +221,36 @@ def finish(notebook: Notebook, execution: protocol.ExecutionId) -> None:notebook.observe(be.Status(execution, "completed"))-def fold(events: list[Event], initial: dict | None = None) -> dict:+def fold(events: list[RoutedEvent], initial: dict | None = None) -> dict:state = dict(initial or {})- for event in events:- if event.name == "reset":+ for routed in events:+ event = routed.event+ if isinstance(event, protocol.ResetEvent):state.clear()- elif event.kind in {"run", "execution", "console", "display"}:- if event.name.endswith(".removed"):- state.pop((event.kind, event.data.id), None)- else:- body = getattr(event.data, event.kind)- state[event.kind, body.id] = body+ elif isinstance(+ event,+ (+ protocol.RunEvent,+ protocol.ExecutionEvent,+ protocol.ConsoleEvent,+ protocol.DisplayEvent,+ ),+ ):+ body = protocol_events.body(event)+ state[event_name(event), body.id] = body+ elif isinstance(+ event,+ (+ protocol.RunRemovedEvent,+ protocol.ExecutionRemovedEvent,+ protocol.ConsoleRemovedEvent,+ protocol.DisplayRemovedEvent,+ ),+ ):+ state.pop(+ (event_name(event).removesuffix(".removed"), event.data.id),+ None,+ )return statediff --git a/tests/_core/test_executions.py b/tests/_core/test_executions.pyindex baae72ac79..b61e2a2b80 100644--- a/tests/_core/test_executions.py+++ b/tests/_core/test_executions.py@@ -16,7 +16,7 @@ from marimo._core.executions import (Released,Removed,)-from marimo._core.stream import kind_of, utcnow+from marimo._core.stream import utcnowfrom tests._core.conftest import retained_executionNOTEBOOK = protocol.NotebookId("n1")@@ -81,9 +81,11 @@ def describe(changes: list[Change]) -> list[str]:if isinstance(change, Released):out.append(f"released {change.run_id}")elif isinstance(change, Removed):- out.append(f"{change.kind}.removed {change.id}")+ out.append(+ f"{change.record_type.__name__.lower()}.removed {change.id}"+ )else:- out.append(f"{kind_of(change)} {change.id}")+ out.append(f"{type(change).__name__.lower()} {change.id}")return outdiff --git a/tests/_core/test_host.py b/tests/_core/test_host.pyindex ab99ae03ba..a4ded7bb12 100644--- a/tests/_core/test_host.py+++ b/tests/_core/test_host.py@@ -13,7 +13,7 @@ from msgspec.structs import replacefrom marimo._core import backend as be, protocolfrom marimo._core.errors import NotFoundfrom marimo._core.host import Host-from marimo._core.stream import Event, Sink+from marimo._core.stream import RoutedEvent, Sink, event_namefrom tests._core.conftest import (Clock,ScriptedBackend,@@ -42,11 +42,11 @@ def test_a_subscriber_can_remove_a_notebook_after_its_children(if trigger == "run":notebook.start()notebook.observe(be.Running(runtime_id_of(notebook)))- events: list[Event] = []+ events: list[RoutedEvent] = []- def remove(event: Event) -> None:+ def remove(event: RoutedEvent) -> None:events.append(event)- if event.name == trigger:+ if event_name(event.event) == trigger:host.remove_notebook(notebook.id)host.subscribe(remove, notebook_id=notebook.id)@@ -87,8 +87,8 @@ def test_replacing_a_cell_result_updates_history_before_delivery(notebook.observe(be.Done(run.id, "succeeded"))snapshots = []- def read_snapshot(event: Event) -> None:- if event.name == "console.removed":+ def read_snapshot(event: RoutedEvent) -> None:+ if isinstance(event.event, protocol.ConsoleRemovedEvent):snapshots.append(set(fold(host.events(notebook_id=notebook.id))))host.subscribe(read_snapshot, notebook_id=notebook.id)@@ -125,7 +125,9 @@ async def test_catalog_snapshot_and_replay_exclude_runs(host: Host) -> None:]assert all(e.id is None for e in events[:-1])assert events[-1].id == cursor + 2- assert all(getattr(e.data, "time", None) is UNSET for e in events[:-1])+ assert all(+ getattr(e.event.data, "time", None) is UNSET for e in events[:-1]+ )assert names(host.events(cursor)) == ["attachment", "ready"]@@ -202,9 +204,9 @@ async def test_types_filter_keeps_ready_and_reset(host: Host) -> None:async def test_subscribe_filters_the_live_stream(host: Host) -> None:host.update_project(project())notebook = await add_notebook(host, record(), ScriptedBackend())- catalog: list[Event] = []- mine: list[Event] = []- runtimes: list[Event] = []+ catalog: list[RoutedEvent] = []+ mine: list[RoutedEvent] = []+ runtimes: list[RoutedEvent] = []host.subscribe(catalog.append)host.subscribe(mine.append, notebook_id="n1")unsubscribe = host.subscribe(runtimes.append, types={"runtime"})@@ -229,7 +231,7 @@ async def test_removing_a_notebook_removes_what_it_owns_first(notebook.observe(be.Running(runtime_id_of(notebook)))notebook.attach()run = notebook.run("1", request_id="r1")- log: list[Event] = []+ log: list[RoutedEvent] = []host.subscribe(log.append, notebook_id="n1")host.remove_notebook("n1", request_id="req-del")@@ -241,7 +243,7 @@ async def test_removing_a_notebook_removes_what_it_owns_first("run.removed","notebook.removed",]- assert getattr(log[-1].data, "request_id", None) == "req-del"+ assert getattr(log[-1].event.data, "request_id", None) == "req-del"assert "n1" not in host.notebookswith pytest.raises(NotFound):(await host.notebook(notebook.id))@@ -257,7 +259,7 @@ async def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:run = notebook.run("1", request_id="run")runtime = notebook.runtimebackend.calls.clear()- log: list[Event] = []+ log: list[RoutedEvent] = []host.subscribe(log.append, notebook_id="n1")host.update_notebook(record())@@ -271,15 +273,15 @@ async def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:assert backend.calls == []assert host.events(notebook_id="n1", types={"run"})[0- ].data == protocol.RunMessage(run=run, request_id="run")- assert host.events(notebook_id="n1")[0].data == protocol.NotebookMessage(- notebook=moved- )- assert host.events(types={"notebook"})[0].data == protocol.NotebookMessage(- notebook=moved- )+ ].event.data == protocol.RunMessage(run=run, request_id="run")+ assert host.events(notebook_id="n1")[+ 0+ ].event.data == protocol.NotebookMessage(notebook=moved)+ assert host.events(types={"notebook"})[+ 0+ ].event.data == protocol.NotebookMessage(notebook=moved)assert names(log) == ["notebook"]- assert getattr(log[0].data, "request_id", None) == "req-mv"+ assert getattr(log[0].event.data, "request_id", None) == "req-mv"with pytest.raises(NotFound):host.update_notebook(record("n9"))with pytest.raises(ValueError, match="project"):@@ -293,7 +295,7 @@ def test_removed_notebook_handles_cannot_be_reused(host: Host,notebook: Notebook,backend: ScriptedBackend,- log: list[Event],+ log: list[RoutedEvent],) -> None:runtime, _ = notebook.start()notebook.observe(be.Running(runtime.id))@@ -350,9 +352,9 @@ async def test_catalog_updates_do_not_share_mutable_records(replay = host.events(0, types={"project"})projects = [- e.data.project+ e.event.data.projectfor e in replay- if isinstance(e.data, protocol.ProjectMessage)+ if isinstance(e.event, protocol.ProjectEvent)]assert projects == [project(),@@ -523,7 +525,7 @@ async def test_expiration_converges_for_live_replay_and_snapshot("console","display",}- live: list[Event] = []+ live: list[RoutedEvent] = []host.subscribe(live.append, notebook_id=notebook.id, run_id=run.id)clock.now = 9host.expire()@@ -536,11 +538,11 @@ async def test_expiration_converges_for_live_replay_and_snapshot("execution.removed","run.removed",]- assert all(event.data.request_id == "request" for event in live)+ assert all(event.event.data.request_id == "request" for event in live)replay = host.events(snapshot[-1].id, notebook_id=notebook.id, run_id=run.id)- assert (replay[0].name == "reset") == (history == 2)+ assert (isinstance(replay[0].event, protocol.ResetEvent)) == (history == 2)assert (fold(live, initial)== fold(replay, initial)@@ -593,7 +595,7 @@ async def test_run_survives_until_its_last_cell_execution_is_replaced() -> (finish(notebook, first)finish(notebook, second)notebook.observe(be.Done(original.id, "succeeded"))- live: list[Event] = []+ live: list[RoutedEvent] = []host.subscribe(live.append, notebook_id=notebook.id, run_id=original.id)replacement = notebook.run("code", request_id="replacement")@@ -732,7 +734,7 @@ async def test_completed_scratch_runs_belong_to_the_host() -> None:))assert ("execution", execution) in fold(notebook._snapshot())- live: list[Event] = []+ live: list[RoutedEvent] = []host.subscribe(live.append, notebook_id=notebook.id)finish(notebook, execution)notebook.observe(be.Done(run.id, "succeeded"))diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.pyindex 8fdf53f026..686a13e2f2 100644--- a/tests/_core/test_notebook.py+++ b/tests/_core/test_notebook.py@@ -12,7 +12,7 @@ from inline_snapshot import snapshotfrom msgspec import UNSETfrom msgspec.structs import replace-from marimo._core import backend as be, protocol+from marimo._core import backend as be, protocol, protocol_eventsfrom marimo._core.document import Document, DocumentCellfrom marimo._core.errors import Conflict, NoRuntime, NotFoundfrom marimo._core.executions import CellExecution, Executions@@ -44,7 +44,7 @@ from marimo._core.protocol import (RuntimeMessage,ValueOutcome,)-from marimo._core.stream import Event, Stream+from marimo._core.stream import RoutedEvent, Stream, event_namefrom tests._core.conftest import (Clock,ScriptedBackend,@@ -66,8 +66,16 @@ def published() -> tuple[protocol.Document, list[protocol.Cell]]:"""The document and cell records the notebook publishes."""events = notebook._snapshot()- (document,) = [e.data.document for e in events if e.kind == "document"] # type: ignore[union-attr]- cells = [e.data.cell for e in events if e.kind == "cell"] # type: ignore[union-attr]+ (document,) = [+ e.event.data.document+ for e in events+ if isinstance(e.event, protocol.DocumentEvent)+ ]+ cells = [+ e.event.data.cell+ for e in events+ if isinstance(e.event, protocol.CellEvent)+ ]return document, cells@@ -110,14 +118,17 @@ class TestStart:host.events(0, notebook_id=notebook.id),):assert [- event.data.runtime+ event.event.data.runtimefor event in events- if isinstance(event.data, RuntimeMessage)+ if isinstance(event.event.data, RuntimeMessage)] == [runtime]assert backend.calls == [("start", runtime.id)]def test_starts_a_runtime_and_asks_the_backend(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:runtime, created = notebook.start(request_id="req-1")@@ -128,7 +139,10 @@ class TestStart:assert request_ids(log) == ["req-1"]def test_returns_an_existing_runtime_without_starting(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:first, _ = notebook.start()again, created = notebook.start()@@ -139,7 +153,7 @@ class TestStart:assert names(log) == ["runtime"]def test_request_follows_the_runtime_until_it_settles(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:notebook.start(request_id="req-1")notebook.observe(@@ -158,7 +172,7 @@ class TestStart:assert notebook.runtime.message is Nonedef test_a_kernel_that_never_comes_up_fails(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:notebook.start(request_id="req-1")notebook.observe(@@ -173,7 +187,10 @@ class TestStart:class TestStop:def test_stop_cancels_a_pending_restart(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:runtime = running(notebook, backend)notebook.restart(request_id="restart")@@ -192,7 +209,10 @@ class TestStop:notebook.stop()def test_terminates_then_removes_once_the_kernel_is_gone(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:running(notebook, backend)log.clear()@@ -211,7 +231,7 @@ class TestStop:host: Host,notebook: Notebook,backend: ScriptedBackend,- log: list[Event],+ log: list[RoutedEvent],) -> None:running(notebook, backend)run = scratch(notebook)@@ -227,7 +247,7 @@ class TestStop:"run","runtime.removed",]- interrupted = log[1].data+ interrupted = log[1].event.dataassert isinstance(interrupted, ExecutionMessage)assert interrupted.execution.status == "completed"assert isinstance(interrupted.execution.outcome, InterruptedOutcome)@@ -241,7 +261,10 @@ class TestStop:]def test_a_failed_runtime_is_removed_at_once(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:notebook.start()notebook.observe(be.Exited(runtime_id_of(notebook), "boom"))@@ -260,7 +283,7 @@ class TestStop:host: Host,notebook: Notebook,backend: ScriptedBackend,- log: list[Event],+ log: list[RoutedEvent],) -> None:running(notebook, backend)run = scratch(notebook)@@ -297,7 +320,10 @@ class TestRestart:notebook.restart()def test_replaces_the_runtime_and_keeps_old_results(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:before = running(notebook, backend)run = scratch(notebook)@@ -336,7 +362,7 @@ class TestRestart:"runtime","runtime",]- execution = log[1].data+ execution = log[1].event.dataassert isinstance(execution, ExecutionMessage)assert execution.execution.runtime_id == before.idassert request_ids(log)[0] == "req-restart"@@ -362,7 +388,10 @@ class TestRestart:class TestAdoption:def test_a_kernel_someone_else_started_is_published(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:adopted = notebook.adopt(lambda _: None)notebook.observe(@@ -381,7 +410,10 @@ class TestAdoption:assert request_ids(log) == [UNSET, UNSET, UNSET]def test_reports_about_other_kernels_change_nothing(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:stranger = RuntimeId("rt-stranger")notebook.observe(be.Running(stranger, marimo_version="0.25.0"))@@ -436,7 +468,7 @@ class TestAdoption:host: Host,notebook: Notebook,backend: ScriptedBackend,- log: list[Event],+ log: list[RoutedEvent],) -> None:running(notebook, backend)run = scratch(notebook)@@ -449,9 +481,9 @@ class TestAdoption:assert notebook.runtime.message == "killed"assert names(log) == ["execution", "run", "runtime"][run] = [- event.data.run+ event.event.data.runfor event in host.events(notebook_id=notebook.id)- if isinstance(event.data, RunMessage)+ if isinstance(event.event.data, RunMessage)]assert run.status == "completed"@@ -482,7 +514,7 @@ class TestRun:notebook.observe(be.Status(ExecutionId("e1"), "completed"))notebook.observe(be.Done(run.id, "succeeded"))cursor = host.events()[-1].id- live: list[Event] = []+ live: list[RoutedEvent] = []unsubscribe = host.subscribe(live.append, notebook_id=notebook.id, run_id=run.id)@@ -517,7 +549,7 @@ class TestRun:host: Host,notebook: Notebook,backend: ScriptedBackend,- log: list[Event],+ log: list[RoutedEvent],) -> None:running(notebook, backend)log.clear()@@ -558,17 +590,17 @@ class TestRun:runs = [data.runfor event in log- if isinstance(data := event.data, RunMessage)+ if isinstance(data := event.event.data, RunMessage)]executions = [data.executionfor event in log- if isinstance(data := event.data, ExecutionMessage)+ if isinstance(data := event.event.data, ExecutionMessage)]consoles = [data.consolefor event in log- if isinstance(data := event.data, ConsoleMessage)+ if isinstance(data := event.event.data, ConsoleMessage)]assert [run.status for run in runs] == ["queued",@@ -583,9 +615,16 @@ class TestRun:("completed", value("working<pre>9</pre>")),]retained = [- event.data+ event.event.datafor event in host.events(notebook_id=notebook.id)- if event.kind in {"run", "execution", "console"}+ if isinstance(+ event.event,+ (+ protocol.RunEvent,+ protocol.ExecutionEvent,+ protocol.ConsoleEvent,+ ),+ )]assert retained == [RunMessage(run=runs[-1]),@@ -649,7 +688,10 @@ class TestRun:]def test_one_run_at_a_time(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:running(notebook, backend)first = notebook.run("1", request_id="first")@@ -657,9 +699,9 @@ class TestRun:notebook.run("2", request_id="second")notebook.observe(be.Done(first.id, "succeeded"))final = next(- event.data+ event.event.datafor event in reversed(log)- if isinstance(event.data, RunMessage)+ if isinstance(event.event.data, RunMessage))assert isinstance(final, RunMessage)assert final.run.status == "completed"@@ -675,16 +717,19 @@ class TestRun:notebook.observe(be.Produced(console("o1", "e1", "0\n")))notebook.observe(be.Produced(console("o1", "e1", "0\n1\n")))items = [- event.data.console+ event.event.data.consolefor event in host.events(notebook_id=notebook.id)- if isinstance(event.data, ConsoleMessage)+ if isinstance(event.event.data, ConsoleMessage)]assert len(items) == 1assert isinstance(items[0], Console)assert items[0].text == "0\n1\n"def test_messages_about_unknown_runs_are_ignored(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:running(notebook, backend)log.clear()@@ -702,7 +747,10 @@ class TestRun:class TestRunCompletion:def test_later_work_gets_its_own_run(- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]+ self,+ notebook: Notebook,+ backend: ScriptedBackend,+ log: list[RoutedEvent],) -> None:running(notebook, backend)original = scratch(notebook)@@ -715,9 +763,9 @@ class TestRunCompletion:assert request_ids(log) == [UNSET, UNSET]assert all(event.run_id == "later" for event in log)final = next(- event.data+ event.event.datafor event in reversed(log)- if isinstance(event.data, RunMessage)+ if isinstance(event.event.data, RunMessage))assert isinstance(final, RunMessage)assert final.run.caused_by == "e1"@@ -728,7 +776,7 @@ class TestRunCompletion:self,notebook: Notebook,backend: ScriptedBackend,- log: list[Event],+ log: list[RoutedEvent],outcome: RunOutcome,) -> None:running(notebook, backend)@@ -736,9 +784,9 @@ class TestRunCompletion:assert run.outcome is Nonenotebook.observe(be.Done(run.id, outcome))final = next(- event.data+ event.event.datafor event in reversed(log)- if isinstance(event.data, RunMessage)+ if isinstance(event.event.data, RunMessage))assert isinstance(final, RunMessage)assert final.run.status == "completed"@@ -751,7 +799,7 @@ class TestRunCompletion:self,notebook: Notebook,backend: ScriptedBackend,- log: list[Event],+ log: list[RoutedEvent],outcome: RunOutcome,) -> None:running(notebook, backend)@@ -802,9 +850,9 @@ class TestRunCompletion:notebook.observe(be.Done(run.id, "succeeded"))notebook.observe(be.Done(run.id, outcome))final = next(- event.data+ event.event.datafor event in reversed(log)- if isinstance(event.data, RunMessage)+ if isinstance(event.event.data, RunMessage))assert isinstance(final, RunMessage)assert final.run.outcome == outcome@@ -863,7 +911,7 @@ class TestCellResults:self,notebook: Notebook,backend: ScriptedBackend,- log: list[Event],+ log: list[RoutedEvent],same_run: bool,) -> None:running(notebook, backend)@@ -915,9 +963,9 @@ class TestCellResults:"execution",]visible = [- event.data.execution.id+ event.event.data.execution.idfor event in notebook._snapshot()- if isinstance(event.data, ExecutionMessage)+ if isinstance(event.event.data, ExecutionMessage)]assert visible == [new]notebook.observe(be.Concluded(new, ValueOutcome(None)))@@ -959,7 +1007,7 @@ class TestCellResults:class TestAttachments:def test_api_clients_attach_and_detach(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:att = notebook.attach()notebook.detach(att.id)@@ -970,7 +1018,7 @@ class TestAttachments:assert names(log) == ["attachment", "attachment.removed"]def test_one_identity_attaches_separately(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:first = notebook.attach(identity="k1", kind="agent", name="Codex")second = notebook.attach(identity="k1", kind="agent", name="Codex")@@ -981,7 +1029,7 @@ class TestAttachments:assert _attachment_ids(notebook) == {first.id, second.id}def test_detach_leaves_other_attachments_with_the_identity(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:first = notebook.attach(identity="k1")second = notebook.attach(identity="k1")@@ -993,39 +1041,39 @@ class TestAttachments:assert _attachment_ids(notebook) == {second.id}def test_attach_without_an_identity_omits_it_on_the_wire(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:att = notebook.attach()assert att.identity is UNSET- wire = msgspec.json.decode(msgspec.json.encode(log[0].data))+ wire = msgspec.json.decode(msgspec.json.encode(log[0].event.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]+ self, notebook: Notebook, log: list[RoutedEvent]) -> 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+ published = log[0].event.dataassert isinstance(published, CustomMessage)assert published.custom == customassert published.request_id == "req-1"assert published.time is not UNSETdef test_emit_rejects_data_that_is_not_json(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> 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]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:with pytest.raises(ValueError):notebook.emit("", 1)@@ -1041,9 +1089,9 @@ class TestEmit:def _attachment_ids(notebook: Notebook) -> set[str]:return {- event.data.attachment.id+ event.event.data.attachment.idfor event in notebook._snapshot()- if isinstance(event.data, AttachmentMessage)+ if isinstance(event.event.data, AttachmentMessage)}@@ -1085,15 +1133,17 @@ async def test_outputs_follow_their_execution_through_updates_and_removal(notebook.observe(be.Done(run.id, "succeeded"))initial = host.events(notebook_id=notebook.id)assert [- getattr(event.data, event.kind)+ protocol_events.body(event.event)for event in initial- if event.kind in {"console", "display"}+ if isinstance(+ event.event, (protocol.ConsoleEvent, protocol.DisplayEvent)+ )] == [first_console, first_display, second_console, second_display]- live: list[Event] = []+ live: list[RoutedEvent] = []snapshots: list[dict] = []- def updated(event: Event) -> None:+ def updated(event: RoutedEvent) -> None:live.append(event)snapshots.append(fold(notebook._snapshot()))@@ -1112,9 +1162,9 @@ async def test_outputs_follow_their_execution_through_updates_and_removal(host.remove_notebook(notebook.id)assert [- (event.name, event.data.id)+ (event_name(event.event), event.event.data.id)for event in live- if event.name.endswith(".removed")+ if isinstance(event.event, protocol_events.RemovalEvent)] == [("console.removed", first_console.id),("display.removed", first_display.id),@@ -1135,7 +1185,7 @@ async def test_outputs_follow_their_execution_through_updates_and_removal(assert all(("execution", first) not in statefor event, state in zip(live, snapshots, strict=True)- if event.name.endswith(".removed")+ if isinstance(event.event, protocol_events.RemovalEvent))@@ -1158,7 +1208,7 @@ async def test_initial_results_are_published_and_replaced_by_live_execution(saved_etag=document.etag,),)- live: list[Event] = []+ live: list[RoutedEvent] = []host.subscribe(live.append, notebook_id=record().id)notebook = await host.notebook(record().id)assert notebook.runtime is None@@ -1271,9 +1321,11 @@ def test_restoration_preserves_revisions_and_outputs(assert notebook.executions.current(CellId("c1")) == retainedassert backend.calls == []outputs = [- e for e in notebook._snapshot() if e.kind in ("console", "display")+ protocol_events.body(e.event)+ for e in notebook._snapshot()+ if isinstance(e.event, (protocol.ConsoleEvent, protocol.DisplayEvent))]- assert [getattr(e.data, e.kind).seq for e in outputs] == [0, 1, 2]+ assert [output.seq for output in outputs] == [0, 1, 2]# Restoration copies the supplied records.document_record.app_config["width"] = "medium"assert published(notebook) == published(original)@@ -1301,7 +1353,7 @@ async def test_edits_preserve_results_and_deletion_removes_them() -> None:assert (next(iter(notebook.document)).code_hash != retained.execution.code_hash)- live: list[Event] = []+ live: list[RoutedEvent] = []host.subscribe(live.append, notebook_id=notebook.id)notebook.replace([], {})assert list(notebook.document) == []@@ -1369,7 +1421,7 @@ async def test_source_edits_keep_live_results_until_the_cell_is_deleted() -> (notebook.replace([DocumentCell("c1", "43")], {})assert notebook.executions._records() == retained- live: list[Event] = []+ live: list[RoutedEvent] = []host.subscribe(live.append, notebook_id=notebook.id)notebook.replace([], {})assert list(notebook.document) == []diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.pyindex 5ce83dc880..405963e9f4 100644--- a/tests/_core/test_notebook_document.py+++ b/tests/_core/test_notebook_document.py@@ -24,7 +24,7 @@ from marimo._core.errors import EditConflict, Invalidfrom marimo._core.executions import Executionsfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebook-from marimo._core.stream import Event, Stream+from marimo._core.stream import RoutedEvent, Streamfrom tests._core.conftest import (ScriptedAnalyzer,ScriptedBackend,@@ -104,8 +104,16 @@ def records() -> tuple[protocol.Document, list[protocol.Cell]]:"""The document and cell records the notebook publishes."""events = notebook._snapshot()- (document,) = [e.data.document for e in events if e.kind == "document"] # type: ignore[union-attr]- cells = [e.data.cell for e in events if e.kind == "cell"] # type: ignore[union-attr]+ (document,) = [+ e.event.data.document+ for e in events+ if isinstance(e.event, protocol.DocumentEvent)+ ]+ cells = [+ e.event.data.cell+ for e in events+ if isinstance(e.event, protocol.CellEvent)+ ]return document, cells@@ -503,17 +511,17 @@ class TestNotebook:self,host: Host,notebook: Notebook,- log: list[Event],+ log: list[RoutedEvent],method: str,remove: bool,) -> None:notebook.replace([cell("c1", "0")], {})log.clear()- def change_again(event: Event) -> None:+ def change_again(event: RoutedEvent) -> None:if (- isinstance(event.data, protocol.CellMessage)- and event.data.request_id == "first"+ isinstance(event.event, protocol.CellEvent)+ and event.event.data.request_id == "first"):change = delete("c1", "*") if remove else put("c1", "2", "*")notebook.edit([change], request_id="second")@@ -527,11 +535,11 @@ class TestNotebook:)first_cell, first_document = log[:2]- assert isinstance(first_cell.data, protocol.CellMessage)- assert isinstance(first_document.data, protocol.DocumentMessage)- published = first_cell.data.cell+ assert isinstance(first_cell.event, protocol.CellEvent)+ assert isinstance(first_document.event, protocol.DocumentEvent)+ published = first_cell.event.data.cellassert response == protocol.EditResponse(- document=first_document.data.document,+ document=first_document.event.data.document,cells={"c1": protocol.CellVersion(etag=published.etag,@@ -545,7 +553,7 @@ class TestNotebook:)async def test_initialization_publishes_cells_then_the_document(- self, host: Host, log: list[Event]+ self, host: Host, log: list[RoutedEvent]) -> None:host.update_project(project())host.add_notebook(@@ -577,7 +585,7 @@ class TestNotebook:assert "cell" not in names(host.events())def test_replace_publishes_what_changed(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:notebook.replace(fixture_cells(), {})log.clear()@@ -592,11 +600,11 @@ class TestNotebook:)assert names(log) == ["cell", "cell.removed", "document"]- assert all(e.data.request_id == "edit-1" for e in log) # type: ignore[union-attr]- assert log[1].data.id == "k7f2" # type: ignore[union-attr]+ assert all(e.event.data.request_id == "edit-1" for e in log) # type: ignore[union-attr]+ assert log[1].event.data.id == "k7f2" # type: ignore[union-attr]def test_replace_can_record_the_saved_revision(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:notebook.replace(fixture_cells(), {})log.clear()@@ -612,10 +620,10 @@ class TestNotebook:"cell.removed","document",]- assert log[-1].data.document == response.document # type: ignore[union-attr]+ assert log[-1].event.data.document == response.document # type: ignore[union-attr]def test_mark_saved_records_the_revision_that_was_written(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:notebook.replace(fixture_cells(), {})written = notebook.document.etag@@ -628,13 +636,13 @@ class TestNotebook:assert document.etag != writtenassert names(log) == ["document"]assert request_ids(log) == ["save-1"]- assert log[0].data.document == document # type: ignore[union-attr]+ assert log[0].event.data.document == document # type: ignore[union-attr]# Marking the same revision again publishes nothing.assert notebook.mark_saved(written) == documentassert names(log) == ["document"]def test_edit_publishes_as_one_unit_with_the_request_key(- self, notebook: Notebook, log: list[Event]+ self, notebook: Notebook, log: list[RoutedEvent]) -> None:notebook.replace(fixture_cells(), {})log.clear()@@ -651,7 +659,7 @@ class TestNotebook:assert names(log) == ["cell", "cell.removed", "document"]assert request_ids(log) == ["edit-1"] * 3- assert response.document == log[-1].data.document # type: ignore[union-attr]+ assert response.document == log[-1].event.data.document # type: ignore[union-attr]assert set(response.cells) == {"c2", "k7f2"}@@ -667,7 +675,7 @@ def cell_analyses(class TestAnalysis:async def test_the_initial_revision_is_analyzed_and_published_after_the_document(- self, host: Host, log: list[Event]+ self, host: Host, log: list[RoutedEvent]) -> None:host.update_project(project())analyzer = ScriptedAnalyzer()@@ -705,7 +713,7 @@ class TestAnalysis:]async def test_edits_during_analysis_are_analyzed_once_afterwards(- self, host: Host, log: list[Event]+ self, host: Host, log: list[RoutedEvent]) -> None:host.update_project(project())analyzer = ScriptedAnalyzer()@@ -745,7 +753,7 @@ class TestAnalysis:assert notebook.analysis.document_etag == latest.etagasync def test_an_edit_is_analyzed_under_its_request_key(- self, host: Host, log: list[Event]+ self, host: Host, log: list[RoutedEvent]) -> None:host.update_project(project())analyzer = ScriptedAnalyzer()@@ -809,7 +817,7 @@ class TestAnalysis:@pytest.mark.parametrize("edit_while_running", [False, True])async def test_a_failed_analysis_leaves_the_notebook_ready_for_the_next(- self, host: Host, log: list[Event], edit_while_running: bool+ self, host: Host, log: list[RoutedEvent], edit_while_running: bool) -> None:host.update_project(project())analyzer = ScriptedAnalyzer()@@ -839,7 +847,7 @@ class TestAnalysis:assert names(log) == ["analysis"]async def test_removal_discards_a_result_even_if_cancellation_is_suppressed(- self, host: Host, log: list[Event]+ self, host: Host, log: list[RoutedEvent]) -> None:started, cancelled = asyncio.Event(), asyncio.Event()result = asyncio.get_running_loop().create_future()diff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.pyindex 6dc3a8d6cd..fa6cc22ab0 100644--- a/tests/_core/test_protocol.py+++ b/tests/_core/test_protocol.py@@ -12,7 +12,7 @@ from typing import Anyimport msgspecimport pytest-from marimo._core import protocol+from marimo._core import protocol, protocol_eventsFIXTURES = (Path(__file__).resolve().parents[2] / "protocols" / "host" / "fixtures"@@ -171,6 +171,38 @@ def test_stream_models(path: Path) -> None:assert not snapshot, f"{path.name}: incomplete snapshot"+ "path", sorted(FIXTURES.glob("*.sse")), ids=lambda path: path.name+)+def test_produced_events_match_wire_fixtures(path: Path) -> None:+ for frame in stream_events(path):+ expected = {**frame, "data": json.loads(frame["data"])}+ wire = msgspec.json.decode(json.dumps(expected), type=protocol.Event)+ if isinstance(wire, (protocol.ReadyEvent, protocol.ResetEvent)):+ continue+ if isinstance(wire, protocol_events.RemovalEvent):+ record_type = getattr(+ protocol, frame["event"].removesuffix(".removed").title()+ )+ produced = protocol_events.removed(+ record_type,+ wire.data.id,+ request_id=wire.data.request_id,+ time=wire.data.time,+ )+ else:+ value = protocol_events.body(wire)+ produced = protocol_events.record(+ value, request_id=wire.data.request_id, time=wire.data.time+ )+ assert protocol_events.body(produced) is value+ # The stream assigns cursors independently of constructing envelopes.+ encoded = msgspec.json.encode(+ msgspec.structs.replace(produced, id=wire.id)+ )+ assert json.loads(encoded) == expected++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")diff --git a/tests/_core/test_stream.py b/tests/_core/test_stream.pyindex 23a42efbd5..e3c0c05962 100644--- a/tests/_core/test_stream.py+++ b/tests/_core/test_stream.py@@ -8,17 +8,16 @@ from typing import get_argsimport msgspecimport pytest-from marimo._core import backend as be, protocol+from marimo._core import backend as be, protocol, protocol_eventsfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebookfrom marimo._core.stream import (- CATALOG_KINDS,- NOTEBOOK_KINDS,- Body,- Event,+ ExtensionEvent,+ RoutedEvent,Stream,- kind_of,- message,+ event_name,+ removal,+ utcnow,)from tests._core.conftest import ScriptedBackend, names, project@@ -28,29 +27,29 @@ def test_subscriber_failure_does_not_prevent_startup(notebook: Notebook,backend: ScriptedBackend,) -> None:- def fail(_event: Event) -> None:+ def fail(_event: RoutedEvent) -> None:raise RuntimeError("subscriber failed")host.subscribe(fail)- delivered: list[Event] = []+ delivered: list[RoutedEvent] = []host.subscribe(delivered.append)runtime, created = notebook.start()assert createdassert backend.calls == [("start", runtime.id)]- assert [e.name for e in delivered] == ["runtime"]+ assert [event_name(e.event) for e in delivered] == ["runtime"]def test_nested_publications_follow_the_current_event() -> None:stream = Stream()- def publish_another(event: Event) -> None:+ def publish_another(event: RoutedEvent) -> None:if event.id == 1:stream.publish(project("p2"))stream.subscribe(publish_another)- delivered: list[Event] = []+ delivered: list[RoutedEvent] = []stream.subscribe(delivered.append)stream.publish(project())@@ -62,40 +61,40 @@ def test_nested_publications_follow_the_current_event() -> None:def test_readers_cannot_change_other_readers_or_replay() -> None:stream = Stream()- def mutate(event: Event) -> None:- assert isinstance(event.data, protocol.ProjectMessage)+ def mutate(event: RoutedEvent) -> None:+ assert isinstance(event.event, protocol.ProjectEvent)with pytest.raises(AttributeError):- event.data.project.name = "subscriber mutation"+ event.event.data.project.name = "subscriber mutation"with pytest.raises(AttributeError):- event.data.project.operations.clear()+ event.event.data.project.operations.clear()stream.subscribe(mutate)- delivered: list[Event] = []+ delivered: list[RoutedEvent] = []stream.subscribe(delivered.append)original = project()published = stream.publish(original)with pytest.raises(AttributeError):original.name = "caller mutation"- assert isinstance(published.data, protocol.ProjectMessage)- assert published.data.project == project()+ assert isinstance(published.event, protocol.ProjectEvent)+ assert published.event.data.project == project()with pytest.raises(AttributeError):- published.data.project.name = "return value mutation"- assert isinstance(delivered[0].data, protocol.ProjectMessage)- assert delivered[0].data.project == project()+ published.event.data.project.name = "return value mutation"+ assert isinstance(delivered[0].event, protocol.ProjectEvent)+ assert delivered[0].event.data.project == project()with pytest.raises(AttributeError):- delivered[0].data.project.name = "listener mutation"+ delivered[0].event.data.project.name = "listener mutation"replay = stream.since(0)assert replay is not None- assert isinstance(replay[0].data, protocol.ProjectMessage)- assert replay[0].data.project == project()+ assert isinstance(replay[0].event, protocol.ProjectEvent)+ assert replay[0].event.data.project == project()with pytest.raises(AttributeError):- replay[0].data.project.name = "replay mutation"+ replay[0].event.data.project.name = "replay mutation"reread = stream.since(0)assert reread is not None- assert isinstance(reread[0].data, protocol.ProjectMessage)- assert reread[0].data.project == project()+ assert isinstance(reread[0].event, protocol.ProjectEvent)+ assert reread[0].event.data.project == project()@pytest.mark.parametrize("external", [False, True])@@ -107,28 +106,31 @@ def test_mutable_payloads_are_isolated_from_callers_and_listeners(sink = notebook.sink if via_notebook else streamcursor = stream.last_idpayload = protocol.Custom(type="example", data={"values": [1]})- delivered: list[Event] = []+ delivered: list[RoutedEvent] = []- def mutate(event: Event) -> None:- assert isinstance(event.data, protocol.CustomMessage)- event.data.custom.data["values"].append(2)+ def mutate(event: RoutedEvent) -> None:+ assert isinstance(event.event, protocol.CustomEvent)+ event.event.data.custom.data["values"].append(2)stream.subscribe(mutate)stream.subscribe(delivered.append)if external:- event = Event(- "custom",- protocol.CustomMessage(custom=payload, time=msgspec.UNSET),+ event = RoutedEvent(+ protocol.CustomEvent(+ protocol.CustomMessage(custom=payload, time=utcnow())+ ),)published = sink.append(event)else:published = sink.publish(payload)payload.data["values"].append(3)- assert isinstance(published.data, protocol.CustomMessage)- published.data.custom.data["values"].append(4)+ assert isinstance(published.event, protocol.CustomEvent)+ published.event.data.custom.data["values"].append(4)replay = stream.since(cursor)assert replay is not None- assert [event.data.custom.data for event in [*delivered, *replay]] == [+ assert [+ event.event.data.custom.data for event in [*delivered, *replay]+ ] == [{"values": [1]},{"values": [1]},]@@ -136,7 +138,7 @@ def test_mutable_payloads_are_isolated_from_callers_and_listeners(def test_deferred_events_join_history_before_delivery() -> None:stream = Stream()- delivered: list[Event] = []+ delivered: list[RoutedEvent] = []stream.subscribe(delivered.append)with stream.deferred():@@ -150,8 +152,8 @@ def test_deferred_events_join_history_before_delivery() -> None:def test_subscribers_act_after_the_command_reaches_the_backend(host: Host, notebook: Notebook, backend: ScriptedBackend) -> None:- def stop_on_starting(event: Event) -> None:- if event.name == "runtime":+ def stop_on_starting(event: RoutedEvent) -> None:+ if isinstance(event.event, protocol.RuntimeEvent):notebook.stop()host.subscribe(stop_on_starting, types={"runtime"})@@ -172,8 +174,8 @@ def test_subscribers_cannot_interrupt_a_restart(backend.calls.clear()started: list[tuple[protocol.Runtime, bool]] = []- def start_on_removal(event: Event) -> None:- if event.name == "runtime.removed":+ def start_on_removal(event: RoutedEvent) -> None:+ if isinstance(event.event, protocol.RuntimeRemovedEvent):started.append(notebook.start())host.subscribe(start_on_removal, types={"runtime"})@@ -193,8 +195,8 @@ def test_subscribers_cannot_start_a_runtime_during_adoption(started: list[tuple[protocol.Runtime, bool]] = []attached: list[protocol.RuntimeId] = []- def start_on_removal(event: Event) -> None:- if event.name == "runtime.removed":+ def start_on_removal(event: RoutedEvent) -> None:+ if isinstance(event.event, protocol.RuntimeRemovedEvent):started.append(notebook.start())host.subscribe(start_on_removal, types={"runtime"})@@ -213,9 +215,8 @@ def test_custom_events_are_on_the_notebook_stream_only() -> None:cursor = host.events(notebook_id=notebook.id)[-1].idassert cursor is not None- custom = notebook.emit("marimo.test", {"hello": 1})+ notebook.emit("marimo.test", {"hello": 1})- assert kind_of(custom) == "custom"assert names(host.events(cursor, notebook_id=notebook.id)) == ["custom","ready",@@ -232,18 +233,56 @@ def test_custom_events_are_on_the_notebook_stream_only(assert names(replayed) == ["custom"]-def test_every_body_has_a_kind_a_stream_and_a_message() -> None:- kinds = {body_type.__name__.lower() for body_type in get_args(Body)}- assert kinds == CATALOG_KINDS | NOTEBOOK_KINDS- assert CATALOG_KINDS - NOTEBOOK_KINDS == {"host", "project"}- for body_type in get_args(Body):+def test_every_body_has_a_kind_a_stream_and_a_typed_event() -> None:+ for body_type in get_args(protocol_events.Body):kind = body_type.__name__.lower()- wrapper = type(message(_blank(body_type)))+ event = Stream().publish(+ _blank(body_type),+ notebook_id=protocol.NotebookId("n1"),+ )+ assert type(event.event).__name__ == f"{body_type.__name__}Event"+ assert event_name(event.event) == kind+ wrapper = type(event.event.data)assert wrapper.__name__ == f"{body_type.__name__}Message"assert kind in {field.name for field in msgspec.structs.fields(wrapper)}- assert kind_of(_blank(body_type)) == kind+ assert event.wanted({kind})+ assert not event.wanted({"unknown"})+ assert protocol_events.body(event.event) == _blank(body_type)+ assert event.visible_in(None) == (+ kind in {"host", "project", "notebook", "runtime", "attachment"}+ )+ assert event.visible_in("n1") == (kind not in {"host", "project"})+ assert not event.visible_in("n2")+++ "record_type", get_args(protocol_events.RemovableBody)+)+def test_removals_preserve_scope_and_type_filters(+ record_type: type[protocol_events.RemovableBody],+) -> None:+ kind = record_type.__name__.lower()+ event = removal(record_type, "item", notebook_id=protocol.NotebookId("n1"))+ assert event.visible_in(None) == (+ kind in {"project", "notebook", "runtime", "attachment"}+ )+ assert event.visible_in("n1") == (kind != "project")+ assert not event.visible_in("n2")+ assert event.wanted({kind})+ assert not event.wanted({"host"})+++def test_extension_type_filters_preserve_the_full_wire_name() -> None:+ class Extension(ExtensionEvent, tag="extension.removed"):+ pass++ event = RoutedEvent(Extension(protocol.RemovedMessage(id="item")))+ assert [+ event.wanted(types)+ for types in (None, {"extension.removed"}, {"extension"})+ ] == [True, True, False]def _blank(body_type: type[msgspec.Struct]) -> msgspec.Struct:diff --git a/tests/_lint/test_host_protocol_codegen.py b/tests/_lint/test_host_protocol_codegen.pyindex 873b5f4898..ad56a89f77 100644--- a/tests/_lint/test_host_protocol_codegen.py+++ b/tests/_lint/test_host_protocol_codegen.py@@ -2,10 +2,15 @@from __future__ import annotations+from datetime import datetime+from pathlib import Path+import msgspec+import msgspec.yamlimport pytest-from protocols.host.generate import tuple_arrays+from marimo._core import protocol+from protocols.host.generate import event_adapters, tuple_arrays@pytest.mark.parametrize(@@ -44,3 +49,56 @@ class Example(Struct, frozen=True):assert value.xs == ("a",)assert value.value == "after"assert value.rows == ((1, 2),)+++def test_event_adapters_follow_schema_references(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Record access does not depend on names matching the wire tag."""+ document = msgspec.yaml.decode(+ Path("protocols/host/openapi.yaml").read_bytes()+ )+ schemas = document["components"]["schemas"]+ message = schemas.pop("ProjectMessage")+ message["properties"]["workspace"] = message["properties"].pop("project")+ message["required"] = ["workspace"]+ schemas["WorkspaceUpdate"] = message+ event = schemas.pop("ProjectEvent")+ event["properties"]["data"]["$ref"] = (+ "#/components/schemas/WorkspaceUpdate"+ )+ schemas["WorkspaceChanged"] = event+ schemas["Event"]["discriminator"]["mapping"]["project"] = (+ "#/components/schemas/WorkspaceChanged"+ )+ update_type = msgspec.defstruct(+ "WorkspaceUpdate",+ [+ ("workspace", protocol.Project),+ ("request_id", str | msgspec.UnsetType, msgspec.UNSET),+ ("time", datetime | msgspec.UnsetType, msgspec.UNSET),+ ],+ )+ event_type = msgspec.defstruct("WorkspaceChanged", [("data", update_type)])+ monkeypatch.setattr(+ protocol, "WorkspaceUpdate", update_type, raising=False+ )+ monkeypatch.setattr(+ protocol, "WorkspaceChanged", event_type, raising=False+ )+ namespace = {}+ exec(compile(event_adapters(document), "<adapters>", "exec"), namespace)+ project = protocol.Project(+ id=protocol.ProjectId("p1"),+ name="project",+ root="/tmp",+ message=None,+ operations=(),+ status="ready",+ )+ wrapped = namespace["record"](project)+ assert wrapped == event_type(update_type(project))+ assert namespace["body"](wrapped) is project+ assert namespace["removed"](protocol.Project, project.id) == (+ protocol.ProjectRemovedEvent(protocol.RemovedMessage(id="p1"))+ )diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.pyindex 3bfcc69073..384d292819 100644--- a/tests/_server/host/test_host_api.py+++ b/tests/_server/host/test_host_api.py@@ -21,12 +21,12 @@ from marimo._core.host import Hostfrom marimo._core.notebook import Notebookfrom marimo._core.protocol import ProjectMessagefrom marimo._core.run_log import RetentionPolicy-from marimo._core.stream import Event+from marimo._core.stream import RoutedEvent, event_namefrom marimo._messaging.notification import CompletedRunNotificationfrom marimo._server.host import HOST_API_PATH, api as api_modulefrom marimo._server.host.bridge import SessionBridgefrom marimo._server.host.context import HostContext-from marimo._server.host.events import MarimoMessage+from marimo._server.host.events import MarimoEvent, MarimoMessagefrom marimo._server.host.index import WorkspaceIndexfrom marimo._server.main import create_starlette_appfrom marimo._server.models.home import MarimoFile@@ -553,7 +553,10 @@ async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:disconnect()await asyncio.wait_for(task, 5)- assert [e.name for e in harness.host.events(notebook_id=notebook.id)] == [+ assert [+ event_name(e.event)+ for e in harness.host.events(notebook_id=notebook.id)+ ] == ["notebook","cell","document",@@ -622,7 +625,9 @@ async def test_a_reconnect_with_one_identity_attaches_fresh(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()]+ assert "attachment" not in [+ event_name(e.event) for e in harness.host.events()+ ]second, second_task, disconnect_second = request(harness.app,@@ -1143,7 +1148,10 @@ async def test_request_receipts_expire_independently_of_results(assert replayed.json()["status"] == "completed"assert replayed.json()["outcome"] == "succeeded"assert any(- event.kind == "execution"+ isinstance(+ event.event,+ (protocol.ExecutionEvent, protocol.ExecutionRemovedEvent),+ )for event in harness.host.events(notebook_id=nid)) == (cell_id is not None)conflicting = await finished(@@ -1381,9 +1389,9 @@ async def test_operations_the_host_does_not_offer_are_501(notebook = await harness.host.notebook(harness.notebook_id)host = Host(operations=[])[project] = [- e.data.project+ e.event.data.projectfor e in harness.host.events()- if isinstance(e.data, ProjectMessage)+ if isinstance(e.event.data, ProjectMessage)]host.update_project(project)host.add_notebook(harness.host.notebooks[notebook.id], make_notebook)@@ -1959,7 +1967,7 @@ async def test_marimo_notifications_use_their_own_sse_kind(await wait_for(response, until_ready)payload = MarimoMessage(CompletedRunNotification(run_id="r1"))published = notebook.sink.append(- Event("marimo", payload, notebook_id=notebook.id)+ RoutedEvent(MarimoEvent(payload), notebook_id=notebook.id))await wait_for(response, lambda r: "marimo" in r.names())assert [r for r in response.records if r.get("event") == "marimo"] == [@@ -1994,7 +2002,9 @@ def test_websocket_delivers_live_events(harness: Harness, query: str) -> None:)client.portal.call(analyzed, notebook)payload = MarimoMessage(CompletedRunNotification(run_id="r1"))- event = Event("marimo", payload, notebook_id=notebook.id, run_id="r1")+ event = RoutedEvent(+ MarimoEvent(payload), notebook_id=notebook.id, run_id="r1"+ )client.portal.call(notebook.sink.append, event)path = f"{HOST_API_PATH}/notebooks/{notebook.id}/events/ws{query}"with client.websocket_connect(@@ -2004,13 +2014,17 @@ def test_websocket_delivers_live_events(harness: Harness, query: str) -> None:assert all("id" not in event for event in initial[:-1])client.portal.call(notebook.sink.append,- Event("marimo", payload, notebook_id="nb_other", run_id="r1"),+ RoutedEvent(+ MarimoEvent(payload), notebook_id="nb_other", run_id="r1"+ ),)if "run_id" in query:client.portal.call(notebook.sink.append,- Event(- "marimo", payload, notebook_id=notebook.id, run_id="r2"+ RoutedEvent(+ MarimoEvent(payload),+ notebook_id=notebook.id,+ run_id="r2",),)first = client.portal.call(notebook.sink.append, event)@@ -2060,12 +2074,15 @@ def test_websocket_disconnect_detaches_the_client()client.portal.call(analyzed, notebook)removed = asyncio.Event()- events: list[Event] = []+ events: list[RoutedEvent] = []- def observe(event: Event) -> None:- if event.notebook_id == notebook.id and event.kind == "attachment":+ def observe(event: RoutedEvent) -> None:+ if event.notebook_id == notebook.id and isinstance(+ event.event,+ (protocol.AttachmentEvent, protocol.AttachmentRemovedEvent),+ ):events.append(event)- if event.name == "attachment.removed":+ if isinstance(event.event, protocol.AttachmentRemovedEvent):removed.set()unsubscribe = client.portal.call(harness.host.subscribe, observe)@@ -2083,13 +2100,15 @@ def test_websocket_disconnect_detaches_the_client(else:websocket.close()client.portal.call(asyncio.wait_for, removed.wait(), 5)- assert [event.name for event in events] == [+ assert [event_name(event.event) for event in events] == ["attachment","attachment.removed",]- assert isinstance(events[0].data, protocol.AttachmentMessage)- assert isinstance(events[1].data, protocol.RemovedMessage)- assert events[1].data.id == events[0].data.attachment.id+ assert isinstance(events[0].event, protocol.AttachmentEvent)+ assert isinstance(events[1].event, protocol.AttachmentRemovedEvent)+ assert (+ events[1].event.data.id == events[0].event.data.attachment.id+ )assert harness.backend().calls == []finally:client.portal.call(unsubscribe)@@ -2174,7 +2193,7 @@ def test_editor_authentication_is_limited_to_the_event_socket(payload = MarimoMessage(CompletedRunNotification(run_id="r1"))published = client.portal.call(notebook.sink.append,- Event("marimo", payload, notebook_id=notebook.id),+ RoutedEvent(MarimoEvent(payload), notebook_id=notebook.id),)assert websocket.receive_json() == {"id": str(published.id),@@ -2284,7 +2303,7 @@ def test_websocket_rejects_unknown_notebooks_and_routes(def test_websocket_snapshot_failure_releases_subscription(harness: Harness, monkeypatch: pytest.MonkeyPatch) -> None:- def broken(*_args: Any, **_kwargs: Any) -> list[Event]:+ def broken(*_args: Any, **_kwargs: Any) -> list[RoutedEvent]:raise RuntimeError("snapshot failed")with TestClient(with_client_address(harness.app)) as client:diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.pyindex d3936332de..68ad0e303d 100644--- a/tests/_server/host/test_host_bridge.py+++ b/tests/_server/host/test_host_bridge.py@@ -11,7 +11,7 @@ import pytestfrom marimo._core import protocolfrom marimo._core.errors import Conflict, DecisionRequired, EditConflict-from marimo._core.stream import Event+from marimo._core.stream import RoutedEventfrom marimo._messaging.notification import (CompletedRunNotification,ExecutionNotification,@@ -20,7 +20,7 @@ from marimo._messaging.notification import ()from marimo._runtime.scratch import SCRATCH_CELL_IDfrom marimo._server.host.bridge import SessionBridge-from marimo._server.host.events import MarimoMessage+from marimo._server.host.events import MarimoEvent, MarimoMessagefrom marimo._server.models.home import MarimoFilefrom marimo._server.workspace import FixedFilesWorkspacefrom tests._core.conftest import names@@ -193,10 +193,10 @@ async def test_a_subscriber_can_stop_an_adopted_session(session = FakeSession(str(tmp_path / "a.py"))manager.sessions["browser"] = session- def stop_on_starting(event: Event) -> None:+ def stop_on_starting(event: RoutedEvent) -> None:if (- isinstance(event.data, protocol.RuntimeMessage)- and event.data.runtime.status == "starting"+ isinstance(event.event, protocol.RuntimeEvent)+ and event.event.data.runtime.status == "starting"):notebook.stop()@@ -401,7 +401,7 @@ async def test_editor_transactions_reach_the_host_document(await bridge.open()record = bridge.index.notebook_for(str(tmp_path / "a.py"))assert record is not None- events: list[Event] = []+ events: list[RoutedEvent] = []bridge.host.subscribe(events.append, notebook_id=record.id)# The document comes from the session, ids included.@@ -452,7 +452,7 @@ async def test_host_edits_reach_the_session_as_one_transaction(record = bridge.index.notebook_for(str(tmp_path / "a.py"))assert record is not Nonenotebook = await bridge.host.notebook(record.id)- events: list[Event] = []+ events: list[RoutedEvent] = []bridge.host.subscribe(events.append, notebook_id=record.id)response = await bridge.edit(@@ -474,13 +474,15 @@ async def test_host_edits_reach_the_session_as_one_transaction(assert isinstance(notification, NotebookDocumentTransactionNotification)assert notification.transaction.source == "host"# The session echoes the edit without publishing the document twice.- assert names([e for e in events if e.name != "marimo"]) == [+ assert names(+ [e for e in events if not isinstance(e.event, MarimoEvent)]+ ) == ["cell","document",]- assert [e.data for e in events if e.name == "marimo"] == [- MarimoMessage(notification)- ]+ assert [+ e.event.data for e in events if isinstance(e.event, MarimoEvent)+ ] == [MarimoMessage(notification)]assert notebook.document.etag == response.document.etagassert "y = x" not in (tmp_path / "a.py").read_text()bridge.close()@@ -540,7 +542,7 @@ async def test_a_new_session_replaces_a_read_without_host_edits(assert record is not Nonenotebook = await bridge.host.notebook(record.id)document = notebook.document- events: list[Event] = []+ events: list[RoutedEvent] = []bridge.host.subscribe(events.append, notebook_id=record.id)# The file changes after the host read it, then a session opens it.@@ -703,7 +705,7 @@ async def test_save_writes_the_cells_and_keeps_the_app_config(notebook = await bridge.host.notebook(record.id)document = notebook.document(cell,) = document- events: list[Event] = []+ events: list[RoutedEvent] = []bridge.host.subscribe(events.append, notebook_id=record.id)edited = await bridge.edit(@@ -730,7 +732,7 @@ async def test_save_writes_the_cells_and_keeps_the_app_config(assert "x = 2" in textassert 'width="full"' in textassert names(events)[-1] == "document"- assert events[-1].data.request_id == "save-1" # type: ignore[union-attr]+ assert events[-1].event.data.request_id == "save-1" # type: ignore[union-attr]bridge.close()@@ -804,7 +806,7 @@ async def test_save_with_a_session_writes_through_the_editors_file_manager((cell,) = document# The editor wrote once, so its manager remembers what is on disk.session.app_file_manager.save_from_cells(list(session.document.cells))- events: list[Event] = []+ events: list[RoutedEvent] = []bridge.host.subscribe(events.append, notebook_id=record.id)edited = await bridge.edit(@@ -823,10 +825,10 @@ async def test_save_with_a_session_writes_through_the_editors_file_manager(published = [efor e in events- if e.name == "document"- and e.data.document.saved_etag == saved.document.etag # type: ignore[union-attr]+ if isinstance(e.event, protocol.DocumentEvent)+ and e.event.data.document.saved_etag == saved.document.etag # type: ignore[union-attr]]- assert [e.data.request_id for e in published] == ["save-1"] # type: ignore[union-attr]+ assert [e.event.data.request_id for e in published] == ["save-1"] # type: ignore[union-attr]bridge.close()@@ -1005,11 +1007,11 @@ async def test_session_notifications_join_the_notebook_stream_once(assert a is not Noneassert b is not None- first: list[Event] = []- second: list[Event] = []- catalog: list[Event] = []- other: list[Event] = []- filtered: list[Event] = []+ first: list[RoutedEvent] = []+ second: list[RoutedEvent] = []+ catalog: list[RoutedEvent] = []+ other: list[RoutedEvent] = []+ filtered: list[RoutedEvent] = []bridge.host.subscribe(first.append, notebook_id=a.id)bridge.host.subscribe(second.append, notebook_id=a.id)bridge.host.subscribe(catalog.append)@@ -1029,8 +1031,8 @@ async def test_session_notifications_join_the_notebook_stream_once(assert first == secondassert catalog == other == []- assert filtered == [e for e in first if e.name == "marimo"]- assert [(e.run_id, e.data) for e in filtered] == [+ assert filtered == [e for e in first if isinstance(e.event, MarimoEvent)]+ assert [(e.run_id, e.event.data) for e in filtered] == [(None, MarimoMessage(variables)),(protocol.RunId("run-1"), MarimoMessage(planned)),]diff --git a/tests/_server/host/test_host_events.py b/tests/_server/host/test_host_events.pynew file mode 100644index 0000000000..1eee7ec79b--- /dev/null+++ b/tests/_server/host/test_host_events.py@@ -0,0 +1,97 @@+# Copyright 2026 Marimo. All rights reserved.+"""Typed envelopes preserve transport framing and event routing."""++from __future__ import annotations++import json+from typing import Any++import pytest++from marimo._core import protocol+from marimo._core.stream import RoutedEvent, Stream, snapshot_event+from marimo._messaging.notification import CompletedRunNotification+from marimo._server.host.api import _frame+from marimo._server.host.events import (+ MarimoEvent,+ MarimoMessage,+ notification_event,+ serialize_event,+)+++ ("event", "expected"),+ [+ (+ snapshot_event(protocol.Host(operations=("runtime.start",))),+ {+ "event": "host",+ "data": {"host": {"operations": ["runtime.start"]}},+ },+ ),+ (+ RoutedEvent(protocol.ReadyEvent(data={}, id="42")),+ {"event": "ready", "data": {}, "id": "42"},+ ),+ (+ RoutedEvent(protocol.ResetEvent(data={})),+ {"event": "reset", "data": {}},+ ),+ (+ notification_event(+ protocol.NotebookId("n1"),+ CompletedRunNotification(run_id="r1"),+ ),+ {+ "event": "marimo",+ "data": {+ "marimo": {+ "op": "completed-run",+ "run_id": "r1",+ "outcome": "succeeded",+ "error": None,+ }+ },+ },+ ),+ ],+)+def test_transports_encode_the_same_envelope(+ event: RoutedEvent, expected: dict[str, Any]+) -> None:+ assert json.loads(serialize_event(event)) == expected+ frame = _frame(event).decode()+ assert frame.endswith("\n\n")+ fields = dict(line.split(": ", 1) for line in frame.strip().splitlines())+ assert {**fields, "data": json.loads(fields["data"])} == expected+++def test_extension_routing_and_control_filters() -> None:+ notebook_id = protocol.NotebookId("n1")+ event = notification_event(+ notebook_id, CompletedRunNotification(run_id="r1")+ )+ assert [event.visible_in(scope) for scope in (None, "n1", "n2")] == [+ False,+ True,+ False,+ ]+ assert event.wanted({"marimo"}, "r1")+ assert not event.wanted({"cell"}, "r1")+ assert not event.wanted({"marimo"}, "r2")++ stream = Stream()+ recorded = stream.append(event)+ assert recorded.event == MarimoEvent(+ data=MarimoMessage(CompletedRunNotification(run_id="r1")), id="1"+ )+ assert stream.since(0) == [recorded]++ for wire in (+ protocol.ReadyEvent(data={}, id="1"),+ protocol.ResetEvent(data={}),+ ):+ control = RoutedEvent(wire, notebook_id=notebook_id)+ assert control.wanted({"cell"}, "other-run")+ assert not control.visible_in(notebook_id)diff --git a/tests/_server/host/test_host_index.py b/tests/_server/host/test_host_index.pyindex e653ad779b..00e49274ad 100644--- a/tests/_server/host/test_host_index.py+++ b/tests/_server/host/test_host_index.py@@ -12,7 +12,7 @@ from marimo._core import backend as befrom marimo._core.errors import NotFoundfrom marimo._core.host import Hostfrom marimo._core.protocol import ProjectMessage-from marimo._core.stream import Event+from marimo._core.stream import RoutedEventfrom marimo._server.host.index import WorkspaceIndexfrom marimo._server.models.home import MarimoFilefrom marimo._server.workspace import FixedFilesWorkspace@@ -54,9 +54,9 @@ def test_refresh_publishes_the_project_and_its_notebooks("ready",][project] = [- e.data.project+ e.event.data.projectfor e in host.events()- if isinstance(e.data, ProjectMessage)+ if isinstance(e.event.data, ProjectMessage)]assert project.root == str(tmp_path)assert project.status == "indexed"@@ -69,7 +69,7 @@ def test_ids_survive_a_rescan_and_a_move(tmp_path: Path) -> None:index = WorkspaceIndex(host, workspace(tmp_path, "a.py"), make_notebook)index.refresh()(notebook,) = host.notebooks.values()- log: list[Event] = []+ log: list[RoutedEvent] = []host.subscribe(log.append)index.refresh()diff --git a/tests/_server/host/test_host_record.py b/tests/_server/host/test_host_record.pyindex bdc892a768..852079d30b 100644--- a/tests/_server/host/test_host_record.py+++ b/tests/_server/host/test_host_record.py@@ -199,7 +199,9 @@ async def test_idle_host_expires_results_and_stops_maintenance(removed = asyncio.Event()host.subscribe(lambda event: (- removed.set() if event.name == "run.removed" else None+ removed.set()+ if isinstance(event.event, protocol.RunRemovedEvent)+ else None),notebook_id=notebook.id,)