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
Publish resumable host events for editor sessions (#11304)
Trevor Manz03a7f176c86e
diff --git a/marimo/_core/host.py b/marimo/_core/host.pyindex 2588cc4076..9441ed9ab6 100644--- a/marimo/_core/host.py+++ b/marimo/_core/host.py@@ -55,9 +55,9 @@ class _NotebookSink(Sink):return eventwith self._stream.deferred():removals = self._log.observe(event)- recorded = self._stream.append(event)+ recorded = self._stream._append(event)for removed in removals:- self._stream.append(removed)+ self._stream._append(removed)return recordeddiff --git a/marimo/_core/stream.py b/marimo/_core/stream.pyindex 187dd51757..eb21e0cf9b 100644--- a/marimo/_core/stream.py+++ b/marimo/_core/stream.py@@ -152,7 +152,10 @@ class Event:"""Whether the event belongs in the catalog or notebook stream."""if notebook_id is None:return self.kind in CATALOG_KINDS- return self.notebook_id == notebook_id and self.kind in NOTEBOOK_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"))+ )def wanted(self, types: Collection[str] | None, run_id: str | None = None@@ -160,7 +163,7 @@ class Event:"""Apply kind and run filters, always including `ready` and `reset`."""if self.name in ("ready", "reset"):return True- return (types is None or self.kind in types) and (+ return (types is None or (self.kind or self.name) in types) and (run_id is None or self.run_id == run_id)@@ -175,6 +178,10 @@ class Sink(ABC):each event before the stream records it."""+ def append(self, event: Event) -> Event:+ """Record an event without requiring a public protocol type."""+ return self._append(deepcopy(event))+def publish(self,body: Body,@@ -215,7 +222,11 @@ class Sink(ABC):@abstractmethoddef _append(self, event: Event) -> Event:- """Record an event and return it as recorded."""+ """Record an owned event and return an isolated copy as recorded.++ The event must already be isolated from the caller. Forward it to+ another sink's `_append` without copying it again.+ """class Stream(Sink):@@ -281,10 +292,6 @@ class Stream(Sink):self._dispatching = Falseself._drain()- def append(self, event: Event) -> Event:- """Record an emitted event with a cursor belonging to this log."""- return self._append(deepcopy(event))-def _append(self, event: Event) -> Event:self._last_id += 1stamped = Event(diff --git a/marimo/_server/api/endpoints/ws/session_handler.py b/marimo/_server/api/endpoints/ws/session_handler.pyindex 11955c5f20..70da09d458 100644--- a/marimo/_server/api/endpoints/ws/session_handler.py+++ b/marimo/_server/api/endpoints/ws/session_handler.py@@ -75,6 +75,8 @@ class SessionHandler(SessionConsumer, abc.ABC):`message_queue`."""+ _replay_notebook_on_reconnect = False+def __init__(self,*,@@ -311,7 +313,9 @@ class SessionHandler(SessionConsumer, abc.ABC):description="You have reconnected to an existing session.",))- self._write_environment_state(session)+ self._replay_previous_session(+ session, include_notebook=self._replay_notebook_on_reconnect+ )returnself._write_kernel_ready_from_session_view(session, self.params.kiosk)@@ -357,29 +361,15 @@ class SessionHandler(SessionConsumer, abc.ABC):# Replay all operationsself._replay_previous_session(session)- def _write_environment_state(self, session: Session) -> None:- # Attachment and snapshot delivery run in one event-loop turn, before- # any later live deltas. Empty states also clear a previous session.- for source in ("kernel", "server"):- self._serialize_and_notify(- EnvironmentStateNotification(- source=source,- state=session.session_view.get_environment_state(source),- )- )- if session.session_view.startup_progress is not None:- # Completed startup follows kernel-ready/reconnected on the normal- # queue, so replay cannot put a ready notebook back into startup.- self._serialize_and_notify(session.session_view.startup_progress)-- def _replay_previous_session(self, session: Session) -> None:- """Replay the previous session view."""- self._write_environment_state(session)- notifications = session.session_view.notifications- if len(notifications) == 0:- LOGGER.debug("No notifications to replay")- return- LOGGER.debug(f"Replaying {len(notifications)} notifications")+ def _replay_previous_session(+ self, session: Session, *, include_notebook: bool = True+ ) -> None:+ """Replay retained state to this client."""+ # Send after kernel-ready/reconnected and before later live deltas.+ notifications = session.session_view.snapshot_notifications(+ include_notebook=include_notebook+ )+ LOGGER.debug("Replaying %s notifications", len(notifications))for notif in notifications:LOGGER.debug("Replaying notification %s", notif)self._serialize_and_notify(notif)diff --git a/marimo/_server/api/endpoints/ws/ws_message_loop.py b/marimo/_server/api/endpoints/ws/ws_message_loop.pyindex c9a75578d9..cf27998d4a 100644--- a/marimo/_server/api/endpoints/ws/ws_message_loop.py+++ b/marimo/_server/api/endpoints/ws/ws_message_loop.py@@ -33,7 +33,7 @@ KIOSK_EXCLUDED_OPERATIONS = {}-def _should_filter_operation(op: str, *, is_kiosk: bool) -> bool:+def should_filter_operation(op: str, *, is_kiosk: bool) -> bool:"""Determine if operation should be filtered based on kiosk mode.Args:@@ -71,7 +71,7 @@ def prepare_wire_message(data: KernelMessage, *, is_kiosk: bool) -> str | None:"""op: str = deserialize_kernel_notification_name(data)- if _should_filter_operation(op, is_kiosk=is_kiosk):+ if should_filter_operation(op, is_kiosk=is_kiosk):return Nonetry:diff --git a/marimo/_server/api/router.py b/marimo/_server/api/router.pyindex fe942ec421..6dd0570bd7 100644--- a/marimo/_server/api/router.py+++ b/marimo/_server/api/router.py@@ -31,6 +31,7 @@ from marimo._server.api.endpoints.sql import router as sql_routerfrom marimo._server.api.endpoints.storage import router as storage_routerfrom marimo._server.api.endpoints.terminal import router as terminal_routerfrom marimo._server.api.endpoints.ws_endpoint import router as ws_router+from marimo._server.host.api import editor_events_routefrom marimo._server.router import APIRouterif TYPE_CHECKING:@@ -83,6 +84,8 @@ def build_routes(base_url: str = "") -> list[BaseRoute]:packages_router, prefix="/api/packages", name="packages")app_router.include_router(lsp_router, prefix="/api/lsp", name="lsp")+ # Register before the catch-all mount shared by health, ws, and assets.+ app_router.routes.append(editor_events_route(base_url))app_router.include_router(health_router, name="health")app_router.include_router(ws_router, name="ws")app_router.include_router(assets_router, name="assets")diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.pyindex dd74271b1a..43f2606721 100644--- a/marimo/_server/host/api.py+++ b/marimo/_server/host/api.py@@ -7,15 +7,18 @@ import asyncioimport hashlibimport threadingfrom collections.abc import Awaitable, Callable+from contextlib import contextmanagerfrom functools import wrapsfrom pathlib import Pathfrom typing import TYPE_CHECKING, TypeAlias, TypeVar, get_argsfrom urllib.parse import quoteimport msgspec+from anyio import create_task_groupfrom starlette.exceptions import HTTPExceptionfrom starlette.responses import Response, StreamingResponse-from starlette.routing import Route, Router+from starlette.routing import Route, Router, WebSocketRoute+from starlette.websockets import WebSocket, WebSocketDisconnectfrom marimo import _loggersfrom marimo._core import protocol@@ -27,20 +30,30 @@ from marimo._core.errors import (NoRuntime,NotFound,)-from marimo._server.api.auth import TOKEN_QUERY_PARAM-from marimo._server.api.deps import AppStateBase+from marimo._server.api.auth import TOKEN_QUERY_PARAM, validate_auth+from marimo._server.api.deps import AppState, AppStateBase+from marimo._server.api.endpoints.ws.ws_connection_validator import (+ ConnectionRejection,+ parse_connection_params,+)+from marimo._server.api.endpoints.ws_endpoint import DOC_MANAGERfrom marimo._server.api.utils import format_url_host, open_url_in_browser+from marimo._server.host import HOST_API_PATHfrom marimo._server.host.context import CachedMutation+from marimo._server.host.events import serialize_event+from marimo._server.host.websocket import EditorEventSocketfrom marimo._server.sse import SSE_HEADERSfrom marimo._server.tokens import AuthTokenif TYPE_CHECKING:- from collections.abc import AsyncIterator+ from collections.abc import AsyncIterator, Iterator- from starlette.requests import Request+ from anyio import CancelScope+ from starlette.requests import HTTPConnection, Requestfrom marimo._core.notebook import Notebookfrom marimo._core.stream import Event+ from marimo._server.host.bridge import SessionBridgefrom marimo._server.host.context import HostContextLOGGER = _loggers.marimo_logger()@@ -65,7 +78,9 @@ _ATTACHMENT_HEADERS = {PING = b": ping\n\n"PING_SECONDS = 15.0-OBJECT_TYPES = frozenset(get_args(get_args(protocol.ObjectType)[0]))+OBJECT_TYPES = frozenset(get_args(get_args(protocol.ObjectType)[0])) | {+ "marimo"+}"""Values the `types` stream filter accepts."""_TITLES = {@@ -133,6 +148,7 @@ def build_app() -> Router:Route("/notebooks/{id}", _update_notebook, methods=["PATCH"]),Route("/notebooks/{id}", _delete_notebook, methods=["DELETE"]),Route("/notebooks/{id}/events", _notebook_events, methods=["GET"]),+ WebSocketRoute("/notebooks/{id}/events/ws", _notebook_events_ws),Route("/notebooks/{id}/edits", _edit_notebook, methods=["POST"]),Route("/notebooks/{id}/save", _save_notebook, methods=["POST"]),Route("/notebooks/{id}/open", _open_notebook, methods=["POST"]),@@ -153,7 +169,7 @@ def build_app() -> Router:for route in routes:# Starlette implies HEAD for every GET route, but a HEAD here would# open a real stream and attach a client nobody can see.- if route.methods == {"GET", "HEAD"}:+ if isinstance(route, Route) and route.methods == {"GET", "HEAD"}:route.methods = {"GET"}return Router(routes=routes,@@ -164,16 +180,21 @@ def build_app() -> Router:async def _not_found(scope, receive, send) -> None: # type: ignore[no-untyped-def]+ if scope["type"] == "websocket":+ await WebSocket(scope, receive, send).close(+ code=1008, reason="No such route"+ )+ returnawait problem(404, "not-found", "No such route")(scope, receive, send)-def _context(request: Request) -> HostContext:+def _context(request: HTTPConnection) -> HostContext:context = getattr(request.app.state, "host_context", None)assert context is not None, "HostApiMiddleware admits requests only then"return context # type: ignore[no-any-return]-async def _notebook(request: Request) -> Notebook:+async def _notebook(request: HTTPConnection) -> Notebook:return await _context(request).bridge.host.notebook(request.path_params["id"])@@ -454,8 +475,160 @@ async def _notebook_events(request: Request) -> Response:)-def _cursor(request: Request) -> int | Response | None:+def editor_events_route(base_url: str = "") -> WebSocketRoute:+ """Expose the notebook event socket through editor authentication."""+ return WebSocketRoute(+ f"{base_url}{HOST_API_PATH}/notebooks/{{id}}/events/ws",+ _editor_events_ws,+ )+++async def _editor_events_ws(websocket: WebSocket) -> None:+ state = AppStateBase.from_app(websocket.app)+ if state.enable_auth and not validate_auth(websocket):+ await websocket.close(+ code=1008, reason="Editor authentication required"+ )+ return+ # TODO: Move editor lifecycle and recipient routing to host attachments so+ # event subscriptions no longer need the legacy session_id.+ if "session_id" not in websocket.query_params:+ await _notebook_events_ws(websocket)+ return++ if "run_id" in websocket.query_params:+ await websocket.close(+ code=1008,+ reason="Editor sessions do not support run_id filtering",+ )+ return++ cursor = _cursor(websocket)+ if isinstance(cursor, Response):+ await websocket.close(code=1008, reason="Invalid event cursor")+ return+ types = _types(websocket)+ if isinstance(types, Response):+ await websocket.close(code=1008, reason="Invalid event types")+ return+ app_state = AppState(websocket)+ params = parse_connection_params(app_state)+ if isinstance(params, ConnectionRejection):+ await websocket.close(params.code, params.reason)+ return+ bridge = _context(websocket).bridge+ try:+ notebook = await _notebook(websocket)+ except (NotFound, Conflict) as exc:+ await websocket.close(code=1008, reason=str(exc))+ return+ manager = app_state.session_manager+ app = manager.app_manager(params.file_key)+ record = bridge.index.notebook_for(app.path)+ existing = manager.get_session(params.session_id)+ if (+ record is None+ or record.id != notebook.id+ or (+ existing is not None and existing.app_file_manager.path != app.path+ )+ ):+ await websocket.close(+ code=1008, reason="Session notebook does not match"+ )+ return+ await EditorEventSocket(+ websocket,+ notebook=notebook,+ bridge=bridge,+ manager=manager,+ params=params,+ doc_manager=DOC_MANAGER,+ types=types,+ cursor=cursor,+ ).start()+++async def _notebook_events_ws(websocket: WebSocket) -> None:+ """Send a snapshot or replay, then live notebook events."""+ cursor = _cursor(websocket)+ if isinstance(cursor, Response):+ await websocket.close(code=1008, reason="Invalid event cursor")+ return+ types = _types(websocket)+ if isinstance(types, Response):+ await websocket.close(code=1008, reason="Invalid event types")+ return+ run_id = websocket.query_params.get("run_id")+ if run_id == "":+ await websocket.close(code=1008, reason="run_id must not be empty")+ return+ try:+ notebook = await _notebook(websocket)+ attachment = notebook.attach(+ identity=websocket.headers.get(ATTACHMENT_IDENTITY),+ kind=websocket.headers.get(ATTACHMENT_KIND),+ name=websocket.headers.get(ATTACHMENT_NAME),+ )+ except (NotFound, Conflict) as exc:+ await websocket.close(code=1008, reason=str(exc))+ return+ except msgspec.ValidationError as exc:+ await websocket.close(code=1008, reason=_attachment_problem(exc))+ return++ bridge = _context(websocket).bridge++ async def send_events(+ subscription: _EventSubscription, cancel_scope: CancelScope+ ) -> None:+ try:+ for event in subscription.initial:+ await websocket.send_text(serialize_event(event))+ while True:+ event = await subscription.next()+ await websocket.send_text(serialize_event(event))+ except WebSocketDisconnect:+ cancel_scope.cancel()++ message = None+ try:+ with _subscribe_events(+ bridge,+ cursor,+ types,+ notebook_id=notebook.id,+ run_id=run_id,+ include_session=True,+ ) as subscription:+ await websocket.accept()+ async with create_task_group() as tasks:+ tasks.start_soon(send_events, subscription, tasks.cancel_scope)+ try:+ message = await websocket.receive()+ finally:+ tasks.cancel_scope.cancel()+ if (+ message is not None+ and message["type"] != "websocket.disconnect"+ ):+ await websocket.close(+ code=1003, reason="This socket only sends events"+ )+ except WebSocketDisconnect:+ pass+ finally:+ notebook.detach(attachment.id)+++def _cursor(request: HTTPConnection) -> int | Response | None:raw = request.headers.get("Last-Event-ID")+ if request.scope["type"] == "websocket":+ query = request.query_params.get("cursor")+ if query is not None:+ if raw is not None and raw != query:+ return problem(400, "invalid-request", "Conflicting cursors")+ raw = queryif raw is None:return None# Header text is latin-1, where superscripts count as digits.@@ -467,7 +640,7 @@ def _cursor(request: Request) -> int | Response | None:return problem(400, "invalid-request", "Last-Event-ID is too long")-def _types(request: Request) -> set[str] | Response | None:+def _types(request: HTTPConnection) -> set[str] | Response | None:asked = request.query_params.get("types")if not asked:return None@@ -491,45 +664,109 @@ def _attachment_problem(error: msgspec.ValidationError) -> str:return "attachment headers are invalid"+def _initial_events(+ bridge: SessionBridge,+ cursor: int | None,+ types: set[str] | None,+ *,+ notebook_id: protocol.NotebookId | None,+ run_id: str | None = None,+ include_session: bool = False,+) -> list[Event]:+ """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"+ if include_session and notebook_id is not None and needs_snapshot:+ ready = events.pop()+ events.extend(+ event+ for event in bridge.session_snapshot(notebook_id)+ if event.wanted(types, run_id)+ )+ events.append(ready)+ return events+++class _EventSubscription:+ def __init__(+ self, initial: list[Event], queue: asyncio.Queue[Event]+ ) -> None:+ self.initial = initial+ self._queue = queue+ self._ready_id = initial[-1].id or 0++ async def next(self) -> Event:+ """Wait for a live event not already covered by the initial state."""+ while True:+ event = await self._queue.get()+ if event.id is None or event.id > self._ready_id:+ return event+++@contextmanager+def _subscribe_events(+ bridge: SessionBridge,+ cursor: int | None,+ types: set[str] | None,+ *,+ notebook_id: protocol.NotebookId | None,+ run_id: str | None = None,+ include_session: bool = False,+) -> Iterator[_EventSubscription]:+ queue: asyncio.Queue[Event] = asyncio.Queue()+ # Subscribe and capture state in one event-loop turn to avoid lost updates.+ unsubscribe = bridge.host.subscribe(+ queue.put_nowait,+ notebook_id=notebook_id,+ types=types,+ run_id=run_id,+ )+ try:+ initial = _initial_events(+ bridge,+ cursor,+ types,+ notebook_id=notebook_id,+ run_id=run_id,+ include_session=include_session,+ )+ yield _EventSubscription(initial, queue)+ finally:+ unsubscribe()++def _stream(context: HostContext,cursor: int | None,types: set[str] | None,*,- notebook_id: str | None,+ notebook_id: protocol.NotebookId | None,run_id: str | None = None,on_close: Callable[[], None] | None = None,) -> Response:- host = context.bridge.host-async def body() -> AsyncIterator[bytes]:- queue: asyncio.Queue[Event] = asyncio.Queue()- # Subscribe before reading initial events to avoid losing updates.- # Queued events at or before the ready cursor are skipped.- unsubscribe = host.subscribe(- queue.put_nowait,- notebook_id=notebook_id,- types=types,- run_id=run_id,- )try:- initial = host.events(- cursor, notebook_id=notebook_id, types=types, run_id=run_id- )- for event in initial:- yield _frame(event)- ready_id = initial[-1].id or 0- while True:- try:- event = await asyncio.wait_for(queue.get(), PING_SECONDS)- except asyncio.TimeoutError:- yield PING- continue- if event.id is not None and event.id <= ready_id:- continue- yield _frame(event)+ with _subscribe_events(+ context.bridge,+ cursor,+ types,+ notebook_id=notebook_id,+ run_id=run_id,+ ) as subscription:+ for event in subscription.initial:+ yield _frame(event)+ while True:+ try:+ event = await asyncio.wait_for(+ subscription.next(), PING_SECONDS+ )+ except asyncio.TimeoutError:+ yield PING+ continue+ yield _frame(event)finally:- unsubscribe()if on_close is not None:on_close()diff --git a/marimo/_server/host/backend.py b/marimo/_server/host/backend.pyindex 0169389c59..9e125806ba 100644--- a/marimo/_server/host/backend.py+++ b/marimo/_server/host/backend.py@@ -21,6 +21,7 @@ from marimo._messaging.notification import (from marimo._messaging.serde import deserialize_kernel_messagefrom marimo._runtime.commands import ExecuteScratchpadCommandfrom marimo._runtime.scratch import SCRATCH_CELL_ID+from marimo._server.host.events import notification_eventfrom marimo._server.host.translate import RunTranslatorfrom marimo._server.scratchpad import snapshot_for_scratchpadfrom marimo._session.consumer import SessionConsumer@@ -31,6 +32,8 @@ from marimo._types.ids import ConsumerId, SessionIdfrom marimo._version import __version__if TYPE_CHECKING:+ from marimo._core.stream import Sink+ from marimo._messaging.notification import NotificationMessagefrom marimo._messaging.types import KernelMessagefrom marimo._server.session_manager import SessionManagerfrom marimo._session.events import SessionEventBus@@ -77,6 +80,7 @@ class SessionBackend(SessionConsumer):file: Callable[[], str | None],manager: SessionManager,observe: Observe,+ sink: Sink,document_changed: Callable[[], None] | None = None,session_attached: Callable[[], None] | None = None,session_detached: Callable[[Session], None] | None = None,@@ -86,6 +90,7 @@ class SessionBackend(SessionConsumer):"""Resolve the notebook's current path after file moves."""self._manager = managerself._observe = observe+ self._sink = sinkself._document_changed = document_changed"""Called after the session's document changes, from any writer."""self._session_attached = session_attached@@ -292,6 +297,11 @@ class SessionBackend(SessionConsumer):def notify(self, notification: KernelMessage) -> None:message = deserialize_kernel_message(notification)+ with self._sink.deferred():+ self._sink.append(notification_event(self._notebook_id, message))+ self._handle_notification(message)++ def _handle_notification(self, message: NotificationMessage) -> None:if isinstance(message, NotebookDocumentTransactionNotification):if self._document_changed is not None and self.session is not None:self._document_changed()diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.pyindex 3c98b9726b..94880074d6 100644--- a/marimo/_server/host/bridge.py+++ b/marimo/_server/host/bridge.py@@ -24,6 +24,7 @@ from marimo._runtime.commands import RenameNotebookCommandfrom marimo._server.host import OPERATIONS, document as documentsfrom marimo._server.host.analysis import HostAnalyzerfrom marimo._server.host.backend import SessionBackend+from marimo._server.host.events import notification_eventfrom marimo._server.host.index import WorkspaceIndexfrom marimo._session.events import SessionEventListenerfrom marimo._session.notebook.storage import rename_no_replace@@ -163,7 +164,7 @@ class SessionBridge(SessionEventListener):saved_etag = document.etag if session is None else Noneif session is not None and loaded is not None:saved_etag = Document(loaded.cells, loaded.app_config).etag- backend = self._make_backend(record.id)+ backend = self._make_backend(record.id, sink)return Notebook(record.id,document,@@ -380,6 +381,18 @@ class SessionBridge(SessionEventListener):cells=response.cells, document=mirrored.document)+ def session_snapshot(+ self, notebook_id: protocol.NotebookId+ ) -> list[Event]:+ """Return retained marimo events for one client without publishing them."""+ session = self._session_of(notebook_id)+ if session is None:+ return []+ return [+ notification_event(notebook_id, notification)+ for notification in session.session_view.snapshot_notifications()+ ]+def _session_of(self, notebook_id: protocol.NotebookId) -> Session | None:backend = self._backends.get(notebook_id)return None if backend is None else backend.session@@ -615,7 +628,7 @@ class SessionBridge(SessionEventListener):self.index.moved(notebook_id, str(target), request_id=request_id)def _make_backend(- self, notebook_id: protocol.NotebookId+ self, notebook_id: protocol.NotebookId, sink: Sink) -> SessionBackend:def file() -> str | None:path = self.index.file_of(notebook_id)@@ -635,6 +648,7 @@ class SessionBridge(SessionEventListener):file,self._manager,observe,+ sink,document_changed=lambda: self._mirror(notebook_id),session_attached=lambda: self._attach_document(notebook_id),session_detached=lambda session: self._detach_document(diff --git a/marimo/_server/host/events.py b/marimo/_server/host/events.pynew file mode 100644index 0000000000..07246a34cc--- /dev/null+++ b/marimo/_server/host/events.py@@ -0,0 +1,43 @@+# Copyright 2026 Marimo. All rights reserved.+"""Internal marimo events for the host stream."""++from __future__ import annotations++import msgspec++from marimo._core import protocol+from marimo._core.stream import Event+from marimo._messaging.notification import NotificationMessage+++class MarimoMessage(msgspec.Struct, frozen=True):+ """A marimo notification carried by the host event stream.++ This type is internal to marimo and may change between releases.+ """++ marimo: NotificationMessage+++def notification_event(+ notebook_id: protocol.NotebookId, notification: NotificationMessage+) -> Event:+ """Wrap a notification with its notebook and optional run scope."""+ run_id = getattr(notification, "run_id", None)+ return Event(+ "marimo",+ 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:+ """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()diff --git a/marimo/_server/host/middleware.py b/marimo/_server/host/middleware.pyindex c057d463cb..1a630aab74 100644--- a/marimo/_server/host/middleware.py+++ b/marimo/_server/host/middleware.py@@ -1,8 +1,9 @@# Copyright 2026 Marimo. All rights reserved."""Local access and bearer-token authentication for the host API.-Requests must come from loopback and address a loopback name on the-server's port. The bearer token comes from the host discovery record.+Host bearer requests must come from loopback and address a loopback name+on the server's port. The bearer token comes from the host discovery record.+The notebook event socket also accepts the editor's authentication."""from __future__ import annotations@@ -13,12 +14,13 @@ from ipaddress import IPv6Address, ip_addressfrom typing import TYPE_CHECKINGfrom starlette.exceptions import HTTPException-from starlette.requests import Request+from starlette.requests import HTTPConnectionfrom starlette.routing import Match, Route+from starlette.websockets import WebSocketfrom marimo import _loggersfrom marimo._server.host import HOST_API_PATH-from marimo._server.host.api import build_app, problem+from marimo._server.host.api import build_app, editor_events_route, problemif TYPE_CHECKING:from collections.abc import Sequence@@ -39,19 +41,31 @@ class HostApiMiddleware:self.app = appself.prefix = base_url + HOST_API_PATHself.host_app = build_app()+ self.editor_socket = editor_events_route(base_url)async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:- if scope["type"] != "http" or not self._is_host_path(scope["path"]):+ if scope["type"] not in (+ "http",+ "websocket",+ ) or not self._is_host_path(scope["path"]):await self.app(scope, receive, send)return- request = Request(scope)+ request = HTTPConnection(scope)client = scope.get("client")context = getattr(request.app.state, "host_context", None)if context is None:response = problem(404, "not-found", "This server is not a host")+ elif self.editor_socket.matches(scope)[+ 0+ ] is Match.FULL and not _bearer_matches(+ request.headers.get("Authorization"), context.token+ ):+ # Let the editor middleware load the cookie before authenticating.+ await self.app(scope, receive, send)+ returnelif client is None or not _is_loopback(client[0]):response = problem(403, "forbidden", "The host API answers only this machine"@@ -74,7 +88,11 @@ class HostApiMiddleware:async def guarded(message: Message) -> None:nonlocal started- if message["type"] == "http.response.start":+ if message["type"] in (+ "http.response.start",+ "websocket.accept",+ "websocket.close",+ ):started = Trueawait send(message)@@ -86,21 +104,33 @@ class HostApiMiddleware:# The bare router has no exception middleware, so a known# path with an unsupported method surfaces here as a 405.response = _router_problem(exc, scope, self.host_app.routes)- await response(scope, receive, send)+ await _respond(response, scope, receive, send)except Exception:if started:# The server logs the failure once it ends the stream.raiseLOGGER.exception("The host API failed on %s", scope["path"])response = problem(500, "internal", "The host failed")- await response(scope, receive, send)+ await _respond(response, scope, receive, send)return- await response(scope, receive, send)+ await _respond(response, scope, receive, send)def _is_host_path(self, path: str) -> bool:return path == self.prefix or path.startswith(self.prefix + "/")+async def _respond(+ response: Response, scope: Scope, receive: Receive, send: Send+) -> None:+ if scope["type"] == "websocket":+ await WebSocket(scope, receive, send).close(+ code=1008,+ reason=f"Host API request rejected ({response.status_code})",+ )+ else:+ await response(scope, receive, send)++def _router_problem(exc: HTTPException, scope: Scope, routes: Sequence[BaseRoute]) -> Response:diff --git a/marimo/_server/host/websocket.py b/marimo/_server/host/websocket.pynew file mode 100644index 0000000000..64609865ff--- /dev/null+++ b/marimo/_server/host/websocket.py@@ -0,0 +1,196 @@+# Copyright 2026 Marimo. All rights reserved.+"""Editor sessions carried by the host event socket."""++from __future__ import annotations++import asyncio+from dataclasses import dataclass+from typing import TYPE_CHECKING++from starlette.websockets import WebSocketDisconnect, WebSocketState++from marimo._messaging.notification import KernelStartupErrorNotification+from marimo._messaging.serde import deserialize_kernel_message+from marimo._server.api.endpoints.ws.session_handler import SessionHandler+from marimo._server.api.endpoints.ws.ws_message_loop import (+ should_filter_operation,+)+from marimo._server.api.endpoints.ws.ws_session_connector import ConnectionType+from marimo._server.codes import WebSocketCloseReason, WebSocketCodes+from marimo._server.host.events import (+ MarimoMessage,+ notification_event,+ serialize_event,+)+from marimo._session.managers.ipc import KernelStartupError+from marimo._utils.asyncio_utils import cancel_and_wait++if TYPE_CHECKING:+ from starlette.websockets import WebSocket++ from marimo._core.notebook import Notebook+ from marimo._core.stream import Event+ from marimo._messaging.types import KernelMessage+ from marimo._server.api.endpoints.ws.ws_connection_validator import (+ ConnectionParams,+ )+ from marimo._server.host.bridge import SessionBridge+ from marimo._server.rtc.doc import LoroDocManager+ from marimo._server.session_manager import SessionManager+++@dataclass(frozen=True)+class _Close:+ code: int+ reason: str+++class EditorEventSocket(SessionHandler):+ """Merge host events with the session's private notification delivery."""++ # Shared-log replay omits native notifications to preserve recipients.+ _replay_notebook_on_reconnect = True++ def __init__(+ self,+ websocket: WebSocket,+ *,+ notebook: Notebook,+ bridge: SessionBridge,+ manager: SessionManager,+ params: ConnectionParams,+ doc_manager: LoroDocManager,+ types: set[str] | None,+ cursor: int | None,+ ) -> None:+ super().__init__(+ manager=manager,+ params=params,+ mode=manager.mode,+ doc_manager=doc_manager,+ )+ self.websocket = websocket+ self.notebook = notebook+ self.bridge = bridge+ self.types = types+ self.cursor = cursor+ self._ready_id = 0+ self._events: asyncio.Queue[Event | _Close] = asyncio.Queue()+ self._connection_type = (+ ConnectionType.RTC_EXISTING+ if params.rtc_enabled and not params.kiosk+ else ConnectionType.NEW+ )++ def notify(self, notification: KernelMessage) -> None:+ event = notification_event(+ self.notebook.id, deserialize_kernel_message(notification)+ )+ if event.wanted(self.types):+ self._events.put_nowait(event)++ def _on_host_event(self, event: Event) -> 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 (+ event.id is None or event.id > self._ready_id+ ):+ self._events.put_nowait(event)++ async def start(self) -> None:+ attachment = self.notebook.attach(identity=self.params.session_id)+ unsubscribe = self.bridge.host.subscribe(+ self._on_host_event,+ notebook_id=self.notebook.id,+ types=self.types,+ )+ try:+ initial = self.bridge.host.events(+ self.cursor, notebook_id=self.notebook.id, types=self.types+ )+ self._ready_id = initial[-1].id or 0+ for event in initial:+ # Session notifications must retain their recipient filtering,+ # including on reconnect; only protocol records use replay.+ if event.name != "marimo":+ self._events.put_nowait(event)+ await self.websocket.accept()+ async with self._connection_lifetime(self.websocket) as startup:+ sending = asyncio.create_task(self._send_events())++ async def connect_and_listen() -> None:+ try:+ _, self._connection_type = await startup+ except asyncio.CancelledError:+ return+ except KernelStartupError as exc:+ self._serialize_and_notify(+ KernelStartupErrorNotification(error=str(exc))+ )+ self._request_close(+ WebSocketCodes.UNEXPECTED_ERROR,+ WebSocketCloseReason.KERNEL_STARTUP_ERROR,+ )+ await sending+ return+ except WebSocketDisconnect as exc:+ self._request_close(exc.code, exc.reason or "")+ await sending+ return+ self._check_status_update()+ await self._wait_for_disconnect()++ listening = asyncio.create_task(connect_and_listen())+ try:+ done, _ = await asyncio.wait(+ (sending, listening),+ return_when=asyncio.FIRST_COMPLETED,+ )+ for task in done:+ task.result()+ except WebSocketDisconnect:+ pass+ finally:+ await cancel_and_wait(listening)+ await cancel_and_wait(sending)+ finally:+ unsubscribe()+ self.notebook.detach(attachment.id)++ async def _send_events(self) -> None:+ while True:+ event = await self._events.get()+ if isinstance(event, _Close):+ if (+ self.websocket.client_state+ is not WebSocketState.DISCONNECTED+ ):+ await self.websocket.close(event.code, event.reason)+ return+ if isinstance(event.data, MarimoMessage):+ viewer = self.params.kiosk+ if 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+ ):+ continue+ await self.websocket.send_text(serialize_event(event))++ async def _wait_for_disconnect(self) -> None:+ while True:+ message = await self.websocket.receive()+ if message["type"] == "websocket.disconnect":+ return++ def _request_close(self, code: int, reason: str) -> None:+ self._events.put_nowait(_Close(code, reason))++ def _is_transport_connected(self) -> bool:+ return self.websocket.application_state is WebSocketState.CONNECTED++ def _cancel_message_loop(self) -> None:+ # on_detach queues a close behind pending notifications.+ passdiff --git a/marimo/_session/state/session_view.py b/marimo/_session/state/session_view.pyindex f525d8b654..f8e8198306 100644--- a/marimo/_session/state/session_view.py+++ b/marimo/_session/state/session_view.py@@ -18,6 +18,7 @@ from marimo._messaging.notification import (DataSourceConnectionsNotification,EnvironmentOperationNotification,EnvironmentState,+ EnvironmentStateNotification,EsmSpec,InterruptedNotification,ModelClose,@@ -599,8 +600,25 @@ class SessionView:self.last_execution_time[cell_id] = time_elapsed- @property- def notifications(self) -> list[NotificationMessage]:+ def snapshot_notifications(+ self, *, include_notebook: bool = True+ ) -> list[NotificationMessage]:+ """Copy retained notifications for a connecting client.++ An existing client can omit notebook state and refresh only its+ environment and startup status. The caller supplies kernel-ready.+ """+ notifications: list[NotificationMessage] = [+ EnvironmentStateNotification(source=source, state=state)+ for source, state in self._environment_states.items()+ ]+ if self.startup_progress is not None:+ notifications.append(self.startup_progress)+ if include_notebook:+ notifications.extend(self._notebook_notifications())+ return copy.deepcopy(notifications)++ def _notebook_notifications(self) -> list[NotificationMessage]:all_notifications: list[NotificationMessage] = []if self.variable_notifications.variables:all_notifications.append(self.variable_notifications)diff --git a/tests/_core/test_stream.py b/tests/_core/test_stream.pyindex 316ecfbb48..23a42efbd5 100644--- a/tests/_core/test_stream.py+++ b/tests/_core/test_stream.py@@ -99,10 +99,13 @@ def test_readers_cannot_change_other_readers_or_replay() -> None:@pytest.mark.parametrize("external", [False, True])[email protected]("via_notebook", [False, True])def test_mutable_payloads_are_isolated_from_callers_and_listeners(- external: bool,+ host: Host, notebook: Notebook, external: bool, via_notebook: bool) -> None:- stream = Stream()+ stream = host._stream if via_notebook else Stream()+ sink = notebook.sink if via_notebook else stream+ cursor = stream.last_idpayload = protocol.Custom(type="example", data={"values": [1]})delivered: list[Event] = []@@ -117,13 +120,13 @@ def test_mutable_payloads_are_isolated_from_callers_and_listeners("custom",protocol.CustomMessage(custom=payload, time=msgspec.UNSET),)- published = stream.append(event)+ published = sink.append(event)else:- published = stream.publish(payload)+ published = sink.publish(payload)payload.data["values"].append(3)assert isinstance(published.data, protocol.CustomMessage)published.data.custom.data["values"].append(4)- replay = stream.since(0)+ replay = stream.since(cursor)assert replay is not Noneassert [event.data.custom.data for event in [*delivered, *replay]] == [{"values": [1]},diff --git a/tests/_export/test_exporter.py b/tests/_export/test_exporter.pyindex 62b2a69e19..731f967a4b 100644--- a/tests/_export/test_exporter.py+++ b/tests/_export/test_exporter.py@@ -269,7 +269,7 @@ async def test_run_notebook_with_stop() -> None:assert did_error is Falsecell_notifications = [op- for op in session_view.notifications+ for op in session_view.snapshot_notifications()if isinstance(op, CellNotification)]snapshot(@@ -354,7 +354,7 @@ async def test_run_notebook_with_stack_trace() -> None:assert did_error is Truecell_notifications = [op- for op in session_view.notifications+ for op in session_view.snapshot_notifications()if isinstance(op, CellNotification)]@@ -401,7 +401,7 @@ async def test_run_notebook_with_console_output(cell_notifications = [op- for op in session_view.notifications+ for op in session_view.snapshot_notifications()if isinstance(op, CellNotification)]snapshot(@@ -632,7 +632,7 @@ def test_export_as_html_omits_getpass_response()assert secret not in html- assert secret not in encode_json_str(session_view.notifications)+ assert secret not in encode_json_str(session_view.snapshot_notifications())assert parse_mount_config(html)["session"]["cells"][0]["console"] == [{"type": "stream",diff --git a/tests/_server/api/endpoints/test_kiosk.py b/tests/_server/api/endpoints/test_kiosk.pyindex 4c978ba9ab..650216c8bd 100644--- a/tests/_server/api/endpoints/test_kiosk.py+++ b/tests/_server/api/endpoints/test_kiosk.py@@ -204,8 +204,6 @@ def test_third_viewer_survives_takeover(client: TestClient) -> None:def test_capabilities_changed_is_not_recorded(client: TestClient) -> None:- from marimo._messaging.serde import deserialize_kernel_message-with client.websocket_connect("/ws?session_id=a", headers=_HEADERS) as ta:assert_kernel_ready_response(ta.receive_json())with client.websocket_connect(@@ -221,8 +219,7 @@ def test_capabilities_changed_is_not_recorded(client: TestClient) -> None:sm = client.app.state.session_managersession = next(iter(sm.sessions.values()))recorded = [- deserialize_kernel_message(n).name- for n in session.session_view.notifications+ n.name for n in session.session_view.snapshot_notifications()]assert "consumer-capabilities" not in recordeddiff --git a/tests/_server/host/drive.py b/tests/_server/host/drive.pyindex c22b247a40..64a9e13aa6 100644--- a/tests/_server/host/drive.py+++ b/tests/_server/host/drive.py@@ -16,6 +16,8 @@ if TYPE_CHECKING:from collections.abc import Callable, MutableMappingfrom starlette.applications import Starlette+ from starlette.testclient import WebSocketTestSession+ from starlette.types import ASGIApp, Receive, Scope, SendPORT = 1234"""Server port used to validate the request's Host header."""@@ -24,6 +26,31 @@ AUTHORITY = f"127.0.0.1:{PORT}"LOOPBACK = ("127.0.0.1", 50000)+def with_client_address(+ app: ASGIApp, address: tuple[str, int] = LOOPBACK+) -> ASGIApp:+ """Set the peer address without requiring Starlette's newer `client` option."""++ async def wrapped(scope: Scope, receive: Receive, send: Send) -> None:+ if scope["type"] in ("http", "websocket"):+ scope = {**scope, "client": address}+ await app(scope, receive, send)++ return wrapped+++def socket_snapshot(websocket: WebSocketTestSession) -> list[dict[str, Any]]:+ """Read the opening snapshot or replay, including its ready boundary."""+ events = []+ while True:+ event = websocket.receive_json()+ events.append(event)+ if event["event"] == "ready":+ assert event["data"] == {}+ assert isinstance(event["id"], str)+ return events++class Response:def __init__(self) -> None:self.status = 0diff --git a/tests/_server/host/test_editor_websocket.py b/tests/_server/host/test_editor_websocket.pynew file mode 100644index 0000000000..6f2859f4de--- /dev/null+++ b/tests/_server/host/test_editor_websocket.py@@ -0,0 +1,418 @@+# Copyright 2026 Marimo. All rights reserved.+"""The editor's session lifecycle on the host event stream."""++from __future__ import annotations++import asyncio+from typing import TYPE_CHECKING, Any++import msgspec+import pytest+from starlette.websockets import WebSocketDisconnect++from marimo._messaging.cell_output import CellChannel, CellOutput+from marimo._messaging.notification import (+ AlertNotification,+ CellNotification,+ StartupProgressNotification,+)+from marimo._messaging.serde import serialize_kernel_message+from marimo._server.host import HOST_API_PATH+from marimo._server.host.bridge import SessionBridge+from marimo._server.host.context import HostContext+from marimo._session.managers.ipc import KernelStartupError+from marimo._types.ids import ConsumerId, SessionId+from tests._server.api.endpoints.ws_helpers import headers+from tests._server.host.drive import socket_snapshot+from tests._server.mocks import get_session_manager++if TYPE_CHECKING:+ from collections.abc import Iterator+ from pathlib import Path++ from starlette.testclient import TestClient, WebSocketTestSession+++def editor_host(client: TestClient) -> Iterator[SessionBridge]:+ bridge = SessionBridge(get_session_manager(client))+ client.app.state.host_context = HostContext( # type: ignore[union-attr]+ bridge=bridge, token="host-token", port=1234+ )+ with client:+ assert client.portal is not None+ client.portal.call(bridge.open)+ try:+ yield bridge+ finally:+ client.portal.call(bridge.close)+++def socket_url(bridge: SessionBridge, session_id: str = "s1") -> str:+ (notebook_id,) = bridge.host.notebooks+ return f"{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?session_id={session_id}&access_token=fake-token"+++def receive_notification(+ websocket: WebSocketTestSession, op: str+) -> dict[str, Any]:+ while True:+ event = websocket.receive_json()+ assert "op" not in event+ if event["event"] == "marimo" and event["data"]["marimo"]["op"] == op:+ return event["data"]["marimo"]++[email protected]("types", [None, "marimo", "marimo,run"])+def test_editor_starts_and_runs_through_the_host_socket(+ client: TestClient, editor_host: SessionBridge, types: str | None+) -> None:+ url = socket_url(editor_host)+ if types is not None:+ url += f"&types={types}"+ with client.websocket_connect(url) as websocket:+ messages = []+ while True:+ event = websocket.receive_json()+ messages.append(event)+ if (+ event["event"] == "marimo"+ and event["data"]["marimo"]["op"] == "kernel-ready"+ ):+ ready = event["data"]["marimo"]+ break+ assert ready["resumed"] is False+ assert ready["consumer_capabilities"]["edit"] is True+ boundary = next(+ i for i, event in enumerate(messages) if event["event"] == "ready"+ )+ assert all("id" not in event for event in messages[:boundary])+ assert messages[boundary]["data"] == {}+ if types is None:+ names = [event["event"] for event in messages[:boundary]]+ assert names[0] == "notebook"+ assert names.index("cell") < names.index("document")+ cell_id = ready["cell_ids"][0]+ response = client.post(+ "/api/kernel/run",+ headers=headers("s1"),+ json={"cellIds": [cell_id], "codes": ["print('host socket')"]},+ )+ assert response.status_code == 200, response.text+ while True:+ event = websocket.receive_json()+ messages.append(event)+ if (+ event["event"] == "marimo"+ and event["data"]["marimo"]["op"] == "completed-run"+ ):+ break+ received_types = {event["event"] for event in messages}+ if types is None:+ assert "run" in received_types+ else:+ assert received_types == {*types.split(","), "ready"}+ consoles = [+ event["data"]["marimo"]["console"]+ for event in messages+ if event["event"] == "marimo"+ and event["data"]["marimo"]["op"] == "cell-op"+ and event["data"]["marimo"]["console"]+ ]+ assert sum("host socket" in str(output) for output in consoles) == 1+++def test_reconnect_keeps_state_and_refresh_replays_it(+ client: TestClient, editor_host: SessionBridge+) -> None:+ url = f"{socket_url(editor_host)}&types=marimo"+ with client.websocket_connect(url) as websocket:+ ready = receive_notification(websocket, "kernel-ready")+ cell_id = ready["cell_ids"][0]+ response = client.post(+ "/api/kernel/run",+ headers=headers("s1"),+ json={"cellIds": [cell_id], "codes": ["print('retained output')"]},+ )+ assert response.status_code == 200, response.text+ receive_notification(websocket, "completed-run")+ with client.websocket_connect(url) as websocket:+ socket_snapshot(websocket)+ while True:+ event = websocket.receive_json()+ assert event["event"] == "marimo"+ notification = event["data"]["marimo"]+ assert notification["op"] not in ("kernel-ready", "cell-op")+ if notification["op"] == "reconnected":+ break+ assert (+ receive_notification(websocket, "alert")["title"] == "Reconnected"+ )+ cell = receive_notification(websocket, "cell-op")+ assert cell["cell_id"] == cell_id+ assert "retained output" in str(cell["console"])+ with client.websocket_connect(+ f"{socket_url(editor_host, 's2')}&types=marimo"+ ) as websocket:+ ready = receive_notification(websocket, "kernel-ready")+ assert ready["resumed"] is True+ assert ready["kiosk"] is False+ cell = receive_notification(websocket, "cell-op")+ assert cell["cell_id"] == cell_id+ assert "retained output" in str(cell["console"])++[email protected]("replay", ["snapshot", "cursor", "reset"])+def test_reconnect_recovers_offline_notifications(+ client: TestClient, editor_host: SessionBridge, replay: str+) -> None:+ url = f"{socket_url(editor_host)}&types=marimo"+ with client.websocket_connect(url) as socket:+ cursor = socket_snapshot(socket)[-1]["id"]+ ready = receive_notification(socket, "kernel-ready")+ session = get_session_manager(client).get_session(SessionId("s1"))+ assert session is not None+ assert client.portal is not None+ update = CellNotification(+ cell_id=ready["cell_ids"][0],+ status="idle",+ output=CellOutput(+ channel=CellChannel.OUTPUT,+ mimetype="text/plain",+ data="offline output",+ timestamp=1.0,+ ),+ console=[+ CellOutput(+ channel=CellChannel.STDOUT,+ mimetype="text/plain",+ data="offline console",+ timestamp=1.0,+ )+ ],+ timestamp=1.0,+ )+ client.portal.call(session.notify, update, None)+ client.portal.call(+ session.notify,+ AlertNotification(title="excluded", description=""),+ ConsumerId("s1"),+ )+ if replay == "cursor":+ url += f"&cursor={cursor}"+ elif replay == "reset":+ url += "&cursor=999999999"+ with client.websocket_connect(url) as socket:+ opening = socket_snapshot(socket)+ assert [event["event"] for event in opening] == (+ ["reset", "ready"] if replay == "reset" else ["ready"]+ )+ receive_notification(socket, "reconnected")+ client.portal.call(+ session.notify,+ AlertNotification(title="marker", description=""),+ None,+ )+ notifications = []+ while True:+ event = socket.receive_json()+ notification = event["data"]["marimo"]+ if (+ notification["op"] == "alert"+ and notification["title"] == "marker"+ ):+ break+ notifications.append(notification)+ assert [n for n in notifications if n["op"] == "cell-op"] == [+ msgspec.json.decode(serialize_kernel_message(update))+ ]+ assert not any(n["op"] == "kernel-ready" for n in notifications)+ assert not any(+ n["op"] == "alert" and n["title"] == "excluded"+ for n in notifications+ )++[email protected]("run_id", ["", "wanted"])+def test_run_filter_is_rejected_before_starting_an_editor_session(+ client: TestClient, editor_host: SessionBridge, run_id: str+) -> None:+ with pytest.raises(WebSocketDisconnect) as exc:+ with client.websocket_connect(+ f"{socket_url(editor_host)}&run_id={run_id}"+ ):+ pytest.fail("Editor run filter was accepted")+ assert (exc.value.code, exc.value.reason) == (+ 1008,+ "Editor sessions do not support run_id filtering",+ )+ assert not get_session_manager(client).sessions+++def test_second_tab_gets_private_startup_and_excluded_messages_do_not_echo(+ client: TestClient, editor_host: SessionBridge+) -> None:+ with client.websocket_connect(socket_url(editor_host)) as first:+ receive_notification(first, "kernel-ready")+ with client.websocket_connect(socket_url(editor_host, "s2")) as second:+ ready = receive_notification(second, "kernel-ready")+ assert ready["kiosk"] is True+ assert ready["consumer_capabilities"]["edit"] is False+ session = get_session_manager(client).get_session(SessionId("s1"))+ assert session is not None+ first.portal.call(+ session.notify,+ AlertNotification(title="other client", description=""),+ ConsumerId("s1"),+ )+ first.portal.call(+ session.notify,+ AlertNotification(title="marker", description=""),+ None,+ )+ while True:+ event = first.receive_json()+ if event["event"] != "marimo":+ continue+ notification = event["data"]["marimo"]+ assert notification["op"] != "kernel-ready"+ if notification["op"] == "alert":+ assert notification["title"] == "marker"+ break+ assert (+ receive_notification(second, "alert")["title"]+ == "other client"+ )+ assert receive_notification(second, "alert")["title"] == "marker"+++def test_session_cannot_bind_to_another_notebook(+ client: TestClient, editor_host: SessionBridge, tmp_path: Path+) -> None:+ other = tmp_path / "other.py"+ other.write_text("import marimo\napp = marimo.App()\n")+ with pytest.raises(WebSocketDisconnect) as exc:+ with client.websocket_connect(+ f"{socket_url(editor_host)}&file={other}"+ ):+ pytest.fail("Mismatched notebook was accepted")+ assert exc.value.code == 1008+ assert not get_session_manager(client).sessions+++def test_startup_failure_is_sent_before_the_close(+ client: TestClient,+ editor_host: SessionBridge,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ async def fail(**kwargs: Any) -> None:+ del kwargs+ raise KernelStartupError("kernel could not start")++ monkeypatch.setattr(get_session_manager(client), "create_session", fail)+ with client.websocket_connect(socket_url(editor_host)) as websocket:+ assert (+ receive_notification(websocket, "kernel-startup-error")["error"]+ == "kernel could not start"+ )+ with pytest.raises(WebSocketDisconnect) as exc:+ websocket.receive_json()+ assert (exc.value.code, exc.value.reason) == (+ 1011,+ "MARIMO_KERNEL_STARTUP_ERROR",+ )+++def test_disconnect_during_startup_cancels_the_connection(+ client: TestClient,+ editor_host: SessionBridge,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ cancelled = asyncio.Event()++ async def wait_for_startup(**kwargs: Any) -> None:+ kwargs["session_consumer"].notify(+ serialize_kernel_message(+ StartupProgressNotification(+ phase="starting-kernel",+ logs="Starting",+ log_mode="replace",+ )+ )+ )+ try:+ await asyncio.Event().wait()+ finally:+ cancelled.set()++ monkeypatch.setattr(+ get_session_manager(client), "create_session", wait_for_startup+ )+ with client.websocket_connect(socket_url(editor_host)) as websocket:+ assert (+ receive_notification(websocket, "startup-progress")["logs"]+ == "Starting"+ )+ assert client.portal is not None+ client.portal.call(asyncio.wait_for, cancelled.wait(), 5)+ assert not get_session_manager(client).sessions+++def test_invalid_event_types_are_rejected_before_starting_a_session(+ client: TestClient, editor_host: SessionBridge+) -> None:+ with pytest.raises(WebSocketDisconnect) as exc:+ with client.websocket_connect(+ f"{socket_url(editor_host)}&types=unknown"+ ):+ pytest.fail("Invalid event types were accepted")+ assert (exc.value.code, exc.value.reason) == (1008, "Invalid event types")+ assert not get_session_manager(client).sessions+++def test_editor_resumes_host_events_without_replaying_private_notifications(+ client: TestClient, editor_host: SessionBridge+) -> None:+ url = f"{socket_url(editor_host)}&types=marimo,custom"+ with client.websocket_connect(url) as socket:+ cursor = socket_snapshot(socket)[-1]["id"]+ receive_notification(socket, "kernel-ready")+ session = get_session_manager(client).get_session(SessionId("s1"))+ assert session is not None+ socket.portal.call(+ session.notify,+ AlertNotification(title="excluded", description=""),+ ConsumerId("s1"),+ )+ socket.portal.call(+ session.notify,+ AlertNotification(title="marker", description=""),+ None,+ )+ assert receive_notification(socket, "alert")["title"] == "marker"+ assert client.portal is not None+ (notebook_id,) = editor_host.host.notebooks+ notebook = client.portal.call(editor_host.host.notebook, notebook_id)+ client.portal.call(notebook.emit, "test.missed", {"text": "replayed"})+ with client.websocket_connect(f"{url}&cursor={cursor}") as socket:+ opening = socket_snapshot(socket)+ assert [event["event"] for event in opening] == ["custom", "ready"]+ assert opening[0]["data"]["custom"] == {+ "type": "test.missed",+ "data": {"text": "replayed"},+ }+ receive_notification(socket, "reconnected")+ assert receive_notification(socket, "alert")["title"] == "Reconnected"++[email protected]("cursor", ["bad", "-1", ""])+def test_invalid_cursor_is_rejected_before_starting_a_session(+ client: TestClient, editor_host: SessionBridge, cursor: str+) -> None:+ with pytest.raises(WebSocketDisconnect) as exc:+ with client.websocket_connect(+ f"{socket_url(editor_host)}&cursor={cursor}"+ ):+ pytest.fail("Invalid cursor was accepted")+ assert (exc.value.code, exc.value.reason) == (1008, "Invalid event cursor")+ assert not get_session_manager(client).sessionsdiff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.pyindex dd438a7399..3bfcc69073 100644--- a/tests/_server/host/test_host_api.py+++ b/tests/_server/host/test_host_api.py@@ -13,15 +13,20 @@ from urllib.parse import parse_qs, urlsplitimport msgspecimport pytestfrom starlette.routing import Route+from starlette.testclient import TestClient+from starlette.websockets import WebSocketDisconnectfrom marimo._core import backend as be, protocolfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebookfrom marimo._core.protocol import ProjectMessagefrom marimo._core.run_log import RetentionPolicy-from marimo._server.host import api as api_module+from marimo._core.stream import Event+from marimo._messaging.notification import CompletedRunNotification+from 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 MarimoMessagefrom marimo._server.host.index import WorkspaceIndexfrom marimo._server.main import create_starlette_appfrom marimo._server.models.home import MarimoFile@@ -29,12 +34,16 @@ from marimo._server.workspace import FixedFilesWorkspace, SingleFileWorkspacefrom marimo._session.notebook import AppFileManagerfrom tests._core.conftest import ScriptedBackend, make_notebook, runtime_id_offrom tests._server.host.drive import (+ AUTHORITY,+ LOOPBACK,PORT,Response,finished,request,+ socket_snapshot,until_ready,wait_for,+ with_client_address,)from tests._server.mocks import (get_mock_session_manager,@@ -46,6 +55,8 @@ if TYPE_CHECKING:from starlette.applications import Starlette+ from marimo._core.stream import Sink+TOKEN = "record-token"AUTH = {"Authorization": f"Bearer {TOKEN}"}pytestmark = pytest.mark.usefixtures("enable_host")@@ -129,7 +140,8 @@ def harness(bridge.host.retention = getattr(request, "param", RetentionPolicy())harness = Harness(app, bridge, tmp_path)- def make(notebook_id: str) -> ScriptedBackend:+ def make(notebook_id: str, sink: Sink) -> ScriptedBackend:+ del sinkbackend = ScriptedBackend()harness.backends[notebook_id] = backendreturn backend@@ -199,7 +211,8 @@ async def test_a_wrong_method_on_a_known_route_is_a_405_problem(def _declared_routes() -> dict[str, set[str]]:methods: dict[str, set[str]] = {}for route in api_module.build_app().routes:- assert isinstance(route, Route)+ if not isinstance(route, Route):+ continuepath = route.path.replace("{id}", "nb-x").replace("{run_id}", "run-x")methods.setdefault(path, set()).update(route.methods or set())return methods@@ -384,6 +397,7 @@ async def test_a_failure_inside_a_stream_does_not_restart_the_response(raise RuntimeError("frame failed")monkeypatch.setattr(api_module, "_frame", broken)+ listeners = len(harness.host._stream._listeners)response, task, _ = request(harness.app, "GET", "/events", headers=AUTH)# Older Starlette raises the body's error inside an ExceptionGroup.with pytest.raises(Exception) as caught:@@ -391,6 +405,39 @@ async def test_a_failure_inside_a_stream_does_not_restart_the_response(assert "frame failed" in repr(caught.value)assert response.status == 200assert response.body == b""+ assert len(harness.host._stream._listeners) == listeners+++async def test_sse_heartbeats_do_not_end_the_subscription(+ harness: Harness, monkeypatch: pytest.MonkeyPatch+) -> None:+ monkeypatch.setattr(api_module, "PING_SECONDS", 0.01)+ notebook = await harness.host.notebook(harness.notebook_id)+ response, task, disconnect = request(+ harness.app,+ "GET",+ f"/notebooks/{notebook.id}/events",+ headers=AUTH,+ query="types=custom",+ )+ try:+ await wait_for(+ response,+ lambda r: (+ sum(record.get("comment") == "ping" for record in r.records)+ >= 2+ ),+ )+ notebook.emit("test.after-heartbeat", {"value": 42})+ await wait_for(response, lambda r: "custom" in r.names())+ assert [+ record["data"]["custom"]+ for record in response.records+ if record.get("event") == "custom"+ ] == [{"type": "test.after-heartbeat", "data": {"value": 42}}]+ finally:+ disconnect()+ await asyncio.wait_for(task, 5)async def test_the_catalog_stream_sends_a_snapshot_then_changes(@@ -1894,3 +1941,364 @@ async def test_a_file_changed_outside_marimo_needs_a_decision()assert edited.status == 200, edited.bodyassert (await save(f"save-{n}", b"{}")).status == 200++[email protected]("query", ["", "types=marimo"])+async def test_marimo_notifications_use_their_own_sse_kind(+ harness: Harness, query: str+) -> None:+ notebook = await harness.host.notebook(harness.notebook_id)+ response, task, disconnect = request(+ harness.app,+ "GET",+ f"/notebooks/{notebook.id}/events",+ headers=AUTH,+ query=query,+ )+ try:+ await wait_for(response, until_ready)+ payload = MarimoMessage(CompletedRunNotification(run_id="r1"))+ published = notebook.sink.append(+ Event("marimo", 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"] == [+ {+ "id": str(published.id),+ "event": "marimo",+ "data": {+ "marimo": {+ "op": "completed-run",+ "run_id": "r1",+ "outcome": "succeeded",+ "error": None,+ }+ },+ }+ ]+ finally:+ disconnect()+ await asyncio.wait_for(task, 5)+++ "query", ["", "?types=marimo", "?types=marimo&run_id=r1"]+)+def test_websocket_delivers_live_events(harness: Harness, query: str) -> None:+ with TestClient(+ with_client_address(harness.app), base_url=f"http://{AUTHORITY}"+ ) as client:+ assert client.portal is not None+ notebook = client.portal.call(+ harness.host.notebook, harness.notebook_id+ )+ client.portal.call(analyzed, notebook)+ payload = MarimoMessage(CompletedRunNotification(run_id="r1"))+ event = Event("marimo", 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(+ f"ws://{AUTHORITY}{path}", headers=dict(AUTH)+ ) as websocket:+ initial = socket_snapshot(websocket)+ 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"),+ )+ if "run_id" in query:+ client.portal.call(+ notebook.sink.append,+ Event(+ "marimo", payload, notebook_id=notebook.id, run_id="r2"+ ),+ )+ first = client.portal.call(notebook.sink.append, event)+ client.portal.call(+ notebook.emit, "test.message", {"text": "hello"}+ )+ second = client.portal.call(notebook.sink.append, event)+ expected = {+ "event": "marimo",+ "data": {+ "marimo": {+ "op": "completed-run",+ "run_id": "r1",+ "outcome": "succeeded",+ "error": None,+ }+ },+ }+ assert websocket.receive_json() == {+ "id": str(first.id),+ **expected,+ }+ if not query:+ custom = websocket.receive_json()+ assert custom["event"] == "custom"+ assert custom["data"]["custom"] == {+ "type": "test.message",+ "data": {"text": "hello"},+ }+ assert websocket.receive_json() == {+ "id": str(second.id),+ **expected,+ }++[email protected]("send_message", [False, True])+def test_websocket_disconnect_detaches_the_client(+ harness: Harness,+ send_message: bool,+) -> None:+ with TestClient(+ with_client_address(harness.app), base_url=f"http://{AUTHORITY}"+ ) as client:+ assert client.portal is not None+ notebook = client.portal.call(+ harness.host.notebook, harness.notebook_id+ )+ client.portal.call(analyzed, notebook)+ removed = asyncio.Event()+ events: list[Event] = []++ def observe(event: Event) -> None:+ if event.notebook_id == notebook.id and event.kind == "attachment":+ events.append(event)+ if event.name == "attachment.removed":+ removed.set()++ unsubscribe = client.portal.call(harness.host.subscribe, observe)+ try:+ path = f"{HOST_API_PATH}/notebooks/{notebook.id}/events/ws"+ with client.websocket_connect(+ f"ws://{AUTHORITY}{path}", headers=dict(AUTH)+ ) as websocket:+ socket_snapshot(websocket)+ if send_message:+ websocket.send_json({"command": "run"})+ with pytest.raises(WebSocketDisconnect) as exc:+ websocket.receive_json()+ assert exc.value.code == 1003+ else:+ websocket.close()+ client.portal.call(asyncio.wait_for, removed.wait(), 5)+ assert [event.name 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 harness.backend().calls == []+ finally:+ client.portal.call(unsubscribe)+++ ("headers", "address", "authority"),+ [+ ({}, LOOPBACK, AUTHORITY),+ ({"Authorization": "Bearer wrong"}, LOOPBACK, AUTHORITY),+ (AUTH, ("192.0.2.1", 50000), AUTHORITY),+ (AUTH, LOOPBACK, "example.com:1234"),+ ],+)+def test_websocket_rejects_invalid_authentication(+ harness: Harness,+ headers: dict[str, str],+ address: tuple[str, int],+ authority: str,+) -> None:+ client = TestClient(+ with_client_address(harness.app, address),+ base_url=f"http://{authority}",+ )+ path = f"{HOST_API_PATH}/notebooks/{harness.notebook_id}/events/ws"+ with pytest.raises(WebSocketDisconnect) as exc:+ with client.websocket_connect(+ f"ws://{authority}{path}", headers=dict(headers)+ ):+ pytest.fail("Unauthenticated socket was accepted")+ assert exc.value.code == 1008+ assert harness.backends == {}++[email protected]("base_url", ["", "/app"])[email protected]("credential", ["cookie", "query"])+ ("authority", "address", "rejected_status"),+ [+ (AUTHORITY, LOOPBACK, 401),+ ("notebooks.example:1234", ("192.0.2.1", 50000), 403),+ ],+)+def test_editor_authentication_is_limited_to_the_event_socket(+ harness: Harness,+ base_url: str,+ credential: str,+ authority: str,+ address: tuple[str, int],+ rejected_status: int,+) -> None:+ app = create_starlette_app(base_url=base_url, enable_auth=True)+ manager = harness.app.state.session_manager+ get_starlette_server_state_init(+ session_manager=manager, base_url=base_url+ ).apply(app.state)+ app.state.host_context = harness.app.state.host_context+ with TestClient(+ with_client_address(app, address), base_url=f"http://{authority}"+ ) as client:+ query = ""+ if credential == "cookie":+ response = client.post(+ f"{base_url}/auth/login",+ data={"password": str(manager.auth_token)},+ follow_redirects=False,+ )+ assert response.status_code == 302+ assert client.cookies+ else:+ query = f"?access_token={manager.auth_token}"+ assert client.portal is not None+ notebook = client.portal.call(+ harness.host.notebook, harness.notebook_id+ )+ path = f"{base_url}{HOST_API_PATH}/notebooks/{notebook.id}"+ separator = "&" if query else "?"+ with client.websocket_connect(+ f"ws://{authority}{path}/events/ws{query}{separator}types=marimo"+ ) as websocket:+ socket_snapshot(websocket)+ payload = MarimoMessage(CompletedRunNotification(run_id="r1"))+ published = client.portal.call(+ notebook.sink.append,+ Event("marimo", payload, notebook_id=notebook.id),+ )+ assert websocket.receive_json() == {+ "id": str(published.id),+ "event": "marimo",+ "data": {+ "marimo": {+ "op": "completed-run",+ "run_id": "r1",+ "outcome": "succeeded",+ "error": None,+ }+ },+ }+ assert harness.backend().calls == []+ for endpoint in (path, f"{path}/events"):+ assert (+ client.get(f"{endpoint}{query}").status_code == rejected_status+ )+ with pytest.raises(WebSocketDisconnect) as exc:+ with client.websocket_connect(+ f"ws://{authority}{base_url}{HOST_API_PATH}/events/ws{query}"+ ):+ pytest.fail("Editor credentials authorized another socket")+ assert exc.value.code == 1008++[email protected]("token", ["wrong", TOKEN])+def test_event_socket_query_requires_the_editor_token(+ harness: Harness, token: str+) -> None:+ client = TestClient(with_client_address(harness.app))+ path = f"{HOST_API_PATH}/notebooks/{harness.notebook_id}/events/ws"+ with pytest.raises(WebSocketDisconnect) as exc:+ with client.websocket_connect(+ f"ws://{AUTHORITY}{path}?access_token={token}"+ ):+ pytest.fail("Invalid editor token was accepted")+ assert exc.value.code == 1008+ assert harness.backends == {}+++def test_event_socket_respects_disabled_editor_authentication(+ harness: Harness,+) -> None:+ app = create_starlette_app(base_url="", enable_auth=False)+ get_starlette_server_state_init(+ session_manager=harness.app.state.session_manager+ ).apply(app.state)+ app.state.enable_auth = False+ app.state.host_context = harness.app.state.host_context+ with TestClient(+ with_client_address(app), base_url=f"http://{AUTHORITY}"+ ) as client:+ path = f"{HOST_API_PATH}/notebooks/{harness.notebook_id}"+ with client.websocket_connect(f"ws://{AUTHORITY}{path}/events/ws"):+ pass+ assert client.get(path).status_code == 401+ assert harness.backend().calls == []+++ ("query", "headers", "reason"),+ [+ ("?types=bogus", AUTH, "Invalid event types"),+ ("?run_id=", AUTH, "run_id must not be empty"),+ ("?cursor=bad", AUTH, "Invalid event cursor"),+ ("?cursor=", AUTH, "Invalid event cursor"),+ ("", {**AUTH, "Last-Event-ID": "-1"}, "Invalid event cursor"),+ ("?cursor=1", {**AUTH, "Last-Event-ID": "2"}, "Invalid event cursor"),+ (+ "",+ {**AUTH, "Marimo-Attachment-Identity": ""},+ "Marimo-Attachment-Identity is invalid",+ ),+ ],+)+def test_websocket_rejects_invalid_subscriptions(+ harness: Harness, query: str, headers: dict[str, str], reason: str+) -> None:+ client = TestClient(+ with_client_address(harness.app), base_url=f"http://{AUTHORITY}"+ )+ path = f"{HOST_API_PATH}/notebooks/{harness.notebook_id}/events/ws{query}"+ with pytest.raises(WebSocketDisconnect) as exc:+ with client.websocket_connect(+ f"ws://{AUTHORITY}{path}", headers=dict(headers)+ ):+ pytest.fail("Invalid subscription was accepted")+ assert (exc.value.code, exc.value.reason) == (1008, reason)++[email protected]("path", ["/notebooks/missing/events/ws", "/missing"])+def test_websocket_rejects_unknown_notebooks_and_routes(+ harness: Harness, path: str+) -> None:+ client = TestClient(+ with_client_address(harness.app), base_url=f"http://{AUTHORITY}"+ )+ with pytest.raises(WebSocketDisconnect) as exc:+ with client.websocket_connect(+ f"ws://{AUTHORITY}{HOST_API_PATH}{path}", headers=dict(AUTH)+ ):+ pytest.fail("Unknown resource was accepted")+ assert exc.value.code == 1008+++def test_websocket_snapshot_failure_releases_subscription(+ harness: Harness, monkeypatch: pytest.MonkeyPatch+) -> None:+ def broken(*_args: Any, **_kwargs: Any) -> list[Event]:+ raise RuntimeError("snapshot failed")++ with TestClient(with_client_address(harness.app)) as client:+ assert client.portal is not None+ notebook = client.portal.call(+ harness.host.notebook, harness.notebook_id+ )+ client.portal.call(analyzed, notebook)+ listeners = len(harness.host._stream._listeners)+ monkeypatch.setattr(harness.host, "events", broken)+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook.id}/events/ws"+ with pytest.raises(WebSocketDisconnect) as caught:+ with client.websocket_connect(url, headers=dict(AUTH)):+ pytest.fail("Snapshot failure accepted a connection")+ assert caught.value.code == 1008+ assert notebook._attachments == {}+ assert len(harness.host._stream._listeners) == listenersdiff --git a/tests/_server/host/test_host_backend.py b/tests/_server/host/test_host_backend.pyindex 42ff53a81b..7df12cc98f 100644--- a/tests/_server/host/test_host_backend.py+++ b/tests/_server/host/test_host_backend.py@@ -8,6 +8,7 @@ import asyncioimport pytestfrom marimo._core import backend as be, protocol+from marimo._core.stream import Streamfrom marimo._messaging.notification import (CellNotification,CompletedRunNotification,@@ -34,6 +35,7 @@ def backend(manager: FakeManager, observed: Observed) -> SessionBackend:lambda: "/ws/forecasts.py",manager, # type: ignore[arg-type]observed,+ Stream(),)@@ -88,6 +90,7 @@ async def test_a_notebook_without_a_file_cannot_start(lambda: None,manager, # type: ignore[arg-type]observed,+ Stream(),).start(RT1)await observed.wait_for(be.Exited)assert observed.messages == [diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.pyindex ab8868743e..d3936332de 100644--- a/tests/_server/host/test_host_bridge.py+++ b/tests/_server/host/test_host_bridge.py@@ -16,9 +16,11 @@ from marimo._messaging.notification import (CompletedRunNotification,ExecutionNotification,StartupProgressNotification,+ VariablesNotification,)from marimo._runtime.scratch import SCRATCH_CELL_IDfrom marimo._server.host.bridge import SessionBridge+from marimo._server.host.events import MarimoMessagefrom marimo._server.models.home import MarimoFilefrom marimo._server.workspace import FixedFilesWorkspacefrom tests._core.conftest import names@@ -450,7 +452,6 @@ 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)- document = notebook.documentevents: list[Event] = []bridge.host.subscribe(events.append, notebook_id=record.id)@@ -472,8 +473,14 @@ async def test_host_edits_reach_the_session_as_one_transaction((notification,) = session.notificationsassert isinstance(notification, NotebookDocumentTransactionNotification)assert notification.transaction.source == "host"- # The backend saw its own edit come back and mirrored nothing new.- assert names(events) == ["cell", "document"]+ # The session echoes the edit without publishing the document twice.+ assert names([e for e in events if e.name != "marimo"]) == [+ "cell",+ "document",+ ]+ assert [e.data for e in events if e.name == "marimo"] == [+ MarimoMessage(notification)+ ]assert notebook.document.etag == response.document.etagassert "y = x" not in (tmp_path / "a.py").read_text()bridge.close()@@ -983,3 +990,48 @@ async def test_reloading_refuses_to_drop_an_edit_made_while_reading(assert conflict.value.document == edited.documentassert notebook.document.cell(cell.id).code == "x = 3" # type: ignore[union-attr]bridge.close()+++async def test_session_notifications_join_the_notebook_stream_once(+ manager: FakeManager, tmp_path: Path+) -> None:+ prepare(manager, tmp_path, "a.py", "b.py")+ session = FakeSession(str(tmp_path / "a.py"))+ manager.sessions["browser"] = session+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ await bridge.open()+ a = bridge.index.notebook_for(str(tmp_path / "a.py"))+ b = bridge.index.notebook_for(str(tmp_path / "b.py"))+ assert a is not None+ assert b is not None++ first: list[Event] = []+ second: list[Event] = []+ catalog: list[Event] = []+ other: list[Event] = []+ filtered: list[Event] = []+ bridge.host.subscribe(first.append, notebook_id=a.id)+ bridge.host.subscribe(second.append, notebook_id=a.id)+ bridge.host.subscribe(catalog.append)+ bridge.host.subscribe(other.append, notebook_id=b.id)+ bridge.host.subscribe(filtered.append, notebook_id=a.id, types={"marimo"})++ variables = VariablesNotification(variables=[])+ planned = ExecutionNotification(+ run_id="run-1",+ execution_id="execution-1",+ cell_id="cell-1",+ phase="planned",+ code="x = 1",+ )+ session.broadcast(variables)+ session.broadcast(planned)++ assert first == second+ assert catalog == other == []+ assert filtered == [e for e in first if e.name == "marimo"]+ assert [(e.run_id, e.data) for e in filtered] == [+ (None, MarimoMessage(variables)),+ (protocol.RunId("run-1"), MarimoMessage(planned)),+ ]+ bridge.close()diff --git a/tests/_server/host/test_host_websocket.py b/tests/_server/host/test_host_websocket.pynew file mode 100644index 0000000000..1d04e2fd57--- /dev/null+++ b/tests/_server/host/test_host_websocket.py@@ -0,0 +1,322 @@+# Copyright 2026 Marimo. All rights reserved.+"""Retained session state on the host WebSocket."""++from __future__ import annotations++from typing import TYPE_CHECKING++import msgspec+import pytest+from starlette.applications import Starlette+from starlette.middleware import Middleware+from starlette.testclient import TestClient++from marimo._messaging.cell_output import CellChannel, CellOutput+from marimo._messaging.notification import (+ CellNotification,+ CompletedRunNotification,+)+from marimo._server.host import HOST_API_PATH+from marimo._server.host.bridge import SessionBridge+from marimo._server.host.context import HostContext+from marimo._server.host.middleware import HostApiMiddleware+from marimo._server.models.home import MarimoFile+from marimo._server.workspace import FixedFilesWorkspace+from marimo._session.notebook import AppFileManager+from marimo._session.state.session_view import SessionView+from tests._server.host.conftest import FakeManager, FakeSession+from tests._server.host.drive import (+ AUTHORITY,+ PORT,+ socket_snapshot,+ with_client_address,+)++if TYPE_CHECKING:+ from pathlib import Path++ from starlette.types import Message, Receive, Scope, Send++AUTH = {"Authorization": "Bearer snapshot-test"}+++def session_host(+ manager: FakeManager, tmp_path: Path+) -> tuple[Starlette, SessionBridge, FakeSession]:+ path = tmp_path / "notebook.py"+ path.write_text(+ "import marimo\napp = marimo.App()\n"+ "@app.cell\ndef _():\n x = 1\n return (x,)\n"+ )+ manager.workspace = FixedFilesWorkspace(+ [MarimoFile(name=path.name, path=str(path))], directory=str(tmp_path)+ )+ session = FakeSession(str(path))+ session.document = AppFileManager(str(path)).app.cell_manager.document+ session.session_view = SessionView()+ session.session_view.add_notification(+ CellNotification(+ cell_id=session.document.cell_ids[0],+ output=CellOutput(+ channel=CellChannel.OUTPUT,+ mimetype="text/plain",+ data="retained output",+ timestamp=1.0,+ ),+ status="idle",+ run_id="r1",+ timestamp=1.0,+ )+ )+ manager.sessions["existing"] = session+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ app = Starlette(middleware=[Middleware(HostApiMiddleware)])+ app.state.host_context = HostContext(+ bridge=bridge, token="snapshot-test", port=PORT+ )+ return app, bridge, session+++def test_snapshot_is_private_and_precedes_updates_during_accept(+ session_host: tuple[Starlette, SessionBridge, FakeSession],+) -> None:+ app, bridge, session = session_host+ connections = 0++ async def app_with_update(+ scope: Scope, receive: Receive, send: Send+ ) -> None:+ async def send_with_update(message: Message) -> None:+ nonlocal connections+ if message["type"] == "websocket.accept":+ connections += 1+ if connections == 2:+ session.notify(CompletedRunNotification(run_id="live"))+ await send(message)++ await app(scope, receive, send_with_update)++ with TestClient(with_client_address(app_with_update)) as client:+ assert client.portal is not None+ client.portal.call(bridge.open)+ try:+ (notebook_id,) = bridge.host.notebooks+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?types=marimo"+ with client.websocket_connect(url, headers=dict(AUTH)) as first:+ opening = socket_snapshot(first)+ initial = opening[:-1]+ assert initial == [+ {+ "event": "marimo",+ "data": {+ "marimo": {+ "op": "environment-state",+ "source": source,+ "state": {+ "restart_required": False,+ "operations": [],+ },+ }+ },+ }+ for source in ("kernel", "server")+ ] + [+ {+ "event": "marimo",+ "data": {+ "marimo": {+ "op": "cell-op",+ "cell_id": session.document.cell_ids[0],+ "output": {+ "channel": "output",+ "mimetype": "text/plain",+ "data": "retained output",+ "timestamp": 1.0,+ },+ "console": None,+ "status": "idle",+ "stale_inputs": None,+ "run_id": "r1",+ "execution_id": None,+ "timestamp": 1.0,+ }+ },+ }+ ]+ with client.websocket_connect(+ url, headers=dict(AUTH)+ ) as second:+ assert socket_snapshot(second)[:-1] == initial+ live = second.receive_json()+ assert first.receive_json() == live+ assert live == {+ "id": live["id"],+ "event": "marimo",+ "data": {+ "marimo": {+ "op": "completed-run",+ "run_id": "live",+ "outcome": "succeeded",+ "error": None,+ }+ },+ }+ finally:+ client.portal.call(bridge.close)+++ ("query", "has_snapshot"),+ [+ ("types=marimo&run_id=r1", True),+ ("types=marimo&run_id=other", False),+ ("types=custom", False),+ ],+)+def test_snapshot_obeys_type_and_run_filters(+ session_host: tuple[Starlette, SessionBridge, FakeSession],+ query: str,+ has_snapshot: bool,+) -> None:+ app, bridge, session = session_host+ with TestClient(with_client_address(app)) as client:+ assert client.portal is not None+ client.portal.call(bridge.open)+ try:+ (notebook_id,) = bridge.host.notebooks+ notebook = client.portal.call(bridge.host.notebook, notebook_id)+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?{query}"+ with client.websocket_connect(+ url, headers=dict(AUTH)+ ) as websocket:+ opening = socket_snapshot(websocket)+ assert len(opening) == (2 if has_snapshot else 1)+ if has_snapshot:+ snapshot = opening[0]+ assert "id" not in snapshot+ assert snapshot["event"] == "marimo"+ assert snapshot["data"]["marimo"]["run_id"] == "r1"+ assert (+ snapshot["data"]["marimo"]["output"]["data"]+ == "retained output"+ )+ if query == "types=custom":+ client.portal.call(notebook.emit, "test.marker", {})+ assert websocket.receive_json()["event"] == "custom"+ else:+ run_id = "r1" if has_snapshot else "other"+ client.portal.call(+ session.notify, CompletedRunNotification(run_id=run_id)+ )+ assert websocket.receive_json()["data"]["marimo"] == {+ "op": "completed-run",+ "run_id": run_id,+ "outcome": "succeeded",+ "error": None,+ }+ finally:+ client.portal.call(bridge.close)+++def test_opening_delivers_protocol_and_session_state_before_ready(+ session_host: tuple[Starlette, SessionBridge, FakeSession],+) -> None:+ app, bridge, session = session_host+ with TestClient(with_client_address(app)) as client:+ assert client.portal is not None+ client.portal.call(bridge.open)+ try:+ (notebook_id,) = bridge.host.notebooks+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook_id}/events/ws"+ with client.websocket_connect(url, headers=dict(AUTH)) as socket:+ opening = socket_snapshot(socket)+ names = [event["event"] for event in opening]+ assert names[0] == "notebook"+ assert names.index("cell") < names.index("document")+ assert names.index("document") < names.index("marimo")+ assert "attachment" in names+ assert all("id" not in event for event in opening[:-1])+ cell = next(+ e["data"]["cell"] for e in opening if e["event"] == "cell"+ )+ document = next(+ e["data"]["document"]+ for e in opening+ if e["event"] == "document"+ )+ assert cell["id"] == session.document.cell_ids[0]+ assert document["order"] == [cell["id"]]+ finally:+ client.portal.call(bridge.close)++[email protected]("use_header", [False, True])+def test_reconnect_replays_original_events_then_continues_live(+ session_host: tuple[Starlette, SessionBridge, FakeSession],+ use_header: bool,+) -> None:+ app, bridge, session = session_host+ with TestClient(with_client_address(app)) as client:+ assert client.portal is not None+ client.portal.call(bridge.open)+ try:+ (notebook_id,) = bridge.host.notebooks+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?types=marimo"+ with client.websocket_connect(url, headers=dict(AUTH)) as socket:+ cursor = socket_snapshot(socket)[-1]["id"]+ client.portal.call(+ session.notify, CompletedRunNotification(run_id="missed")+ )+ missed = socket.receive_json()+ headers = dict(AUTH)+ if use_header:+ headers["Last-Event-ID"] = cursor+ else:+ url += f"&cursor={cursor}"+ with client.websocket_connect(url, headers=headers) as socket:+ replay = socket_snapshot(socket)+ assert replay[:-1] == [missed]+ client.portal.call(+ session.notify, CompletedRunNotification(run_id="live")+ )+ live = socket.receive_json()+ assert live["data"]["marimo"]["run_id"] == "live"+ assert int(live["id"]) > int(replay[-1]["id"])+ finally:+ client.portal.call(bridge.close)+++def test_expired_cursor_resets_to_current_state(+ session_host: tuple[Starlette, SessionBridge, FakeSession],+) -> None:+ app, bridge, _ = session_host+ with TestClient(with_client_address(app)) as client:+ assert client.portal is not None+ client.portal.call(bridge.open)+ try:+ (notebook_id,) = bridge.host.notebooks+ notebook = client.portal.call(bridge.host.notebook, notebook_id)+ url = f"ws://{AUTHORITY}{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?types=cell,document,marimo,custom"+ with client.websocket_connect(url, headers=dict(AUTH)) as socket:+ initial = socket_snapshot(socket)+ cursor = initial[-1]["id"]+ # Expire the default 1000-event replay history.+ for index in range(1001):+ client.portal.call(+ notebook.emit, "test.expire", {"index": index}+ )+ with client.websocket_connect(+ f"{url}&cursor={cursor}", headers=dict(AUTH)+ ) as socket:+ reset = socket_snapshot(socket)+ assert reset[0] == {"event": "reset", "data": {}}+ assert reset[1:-1] == initial[:-1]+ assert int(reset[-1]["id"]) > int(cursor)+ event = client.portal.call(notebook.emit, "test.live", {})+ live = socket.receive_json()+ assert live["event"] == "custom"+ assert live["data"]["custom"] == msgspec.to_builtins(event)+ assert int(live["id"]) > int(reset[-1]["id"])+ finally:+ client.portal.call(bridge.close)diff --git a/tests/_session/state/test_session_external_storage.py b/tests/_session/state/test_session_external_storage.pyindex b2aed2bcc3..08588a8d4c 100644--- a/tests/_session/state/test_session_external_storage.py+++ b/tests/_session/state/test_session_external_storage.py@@ -130,7 +130,8 @@ def test_add_storage_namespaces(session_view: SessionView) -> None:# Check namespaces appear in notificationsassert (- session_view.external_storage_namespaces in session_view.notifications+ session_view.external_storage_namespaces+ in session_view.snapshot_notifications())@@ -212,7 +213,7 @@ def test_storage_namespaces_empty_not_in_notifications(assert session_view.external_storage_namespaces.namespaces == []storage_ops = [op- for op in session_view.notifications+ for op in session_view.snapshot_notifications()if isinstance(op, StorageNamespacesNotification)]assert len(storage_ops) == 0@@ -238,7 +239,7 @@ def test_storage_namespaces_in_notifications()storage_ops = [op- for op in session_view.notifications+ for op in session_view.snapshot_notifications()if isinstance(op, StorageNamespacesNotification)]assert storage_ops == snapshot(diff --git a/tests/_session/state/test_session_view.py b/tests/_session/state/test_session_view.pyindex d2e9b2b39c..33927364b8 100644--- a/tests/_session/state/test_session_view.py+++ b/tests/_session/state/test_session_view.py@@ -27,6 +27,7 @@ from marimo._messaging.notification import (EnvironmentOperationNotification,EnvironmentOperationStatus,EnvironmentState,+ EnvironmentStateNotification,EsmSpec,ModelClose,ModelCustom,@@ -44,6 +45,7 @@ from marimo._messaging.notification import (SQLTableListPreviewNotification,SQLTablePreviewNotification,StartupLogsNotification,+ StartupProgressNotification,VariableDeclarationNotification,VariablesNotification,VariableValue,@@ -1011,7 +1013,9 @@ def test_add_data_source_connections(session_view: SessionView) -> None:assert INTERNAL_DUCKDB_ENGINE in names# Check connectors in operations- assert session_view.data_connectors in session_view.notifications+ assert (+ session_view.data_connectors in session_view.snapshot_notifications()+ )# Filter out connections from variablessession_view.add_raw_notification(@@ -1830,7 +1834,7 @@ def test_session_view_startup_logs_operations_exclude_done(session_view.add_notification(start_log)# Should include in operations while in progress- operations = session_view.notifications+ operations = session_view.snapshot_notifications()startup_ops = [op for op in operations if isinstance(op, StartupLogsNotification)]@@ -1842,7 +1846,7 @@ def test_session_view_startup_logs_operations_exclude_done(session_view.add_notification(done_log)# Should not include done startup logs in operations- operations = session_view.notifications+ operations = session_view.snapshot_notifications()startup_ops = [op for op in operations if isinstance(op, StartupLogsNotification)]@@ -2428,3 +2432,60 @@ def test_preparation_remains_available_after_package_changes(logs={},),]++[email protected]("include_notebook", [False, True])+def test_snapshot_notifications_preserve_replay_order(+ session_view: SessionView, include_notebook: bool+) -> None:+ progress = StartupProgressNotification(+ phase="starting-kernel", logs="Ready\n", log_mode="replace"+ )+ model = ModelLifecycleNotification(+ model_id=WidgetModelId("model"),+ message=ModelOpen(state={"value": 1}, buffer_paths=[], buffers=[]),+ )+ cell = CellNotification(+ cell_id=cell_id,+ output=CellOutput(+ channel=CellChannel.OUTPUT,+ mimetype="text/plain",+ data="old output",+ ),+ status="idle",+ )+ # The output can arrive before its widget model exists.+ for notification in (cell, model, progress):+ session_view.add_notification(notification)++ notifications = session_view.snapshot_notifications(+ include_notebook=include_notebook+ )+ assert notifications == [+ EnvironmentStateNotification(+ source="kernel",+ state=EnvironmentState(restart_required=False, operations=[]),+ ),+ EnvironmentStateNotification(+ source="server",+ state=EnvironmentState(restart_required=False, operations=[]),+ ),+ progress,+ *([model, cell] if include_notebook else []),+ ]+ captured = msgspec.json.encode(notifications)+ session_view.update_cell_outputs({cell_id: ("text/plain", "new output")})+ session_view.add_notification(+ StartupProgressNotification(+ phase="starting-kernel", logs="More logs\n", log_mode="append"+ )+ )+ assert msgspec.json.encode(notifications) == captured+ assert (+ msgspec.json.encode(+ session_view.snapshot_notifications(+ include_notebook=include_notebook+ )+ )+ != captured+ )diff --git a/tests/conftest.py b/tests/conftest.pyindex 459e5bf560..6deb957e14 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -471,7 +471,7 @@ def session_view() -> Generator[SessionView, None, None]:yield sv# Test all operations can be serialized/deserialized- for operation in sv.notifications:+ for operation in sv.snapshot_notifications():assert_serialize_roundtrip(operation)