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
Support app sessions on the host event stream (#11362)
Trevor Manzc2a158714c4a
diff --git a/marimo/_server/api/endpoints/assets.py b/marimo/_server/api/endpoints/assets.pyindex ce63c27b72..232985d495 100644--- a/marimo/_server/api/endpoints/assets.py+++ b/marimo/_server/api/endpoints/assets.py@@ -423,6 +423,7 @@ async def index(request: Request) -> Response:)if (context is not None+ and context.bridge.app_sessions is Noneand absolute_filepathand not app_state.remote_url):diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.pyindex bc426e85ef..b5c4299336 100644--- a/marimo/_server/host/bridge.py+++ b/marimo/_server/host/bridge.py@@ -6,6 +6,7 @@ from __future__ import annotationsimport asyncioimport copyfrom dataclasses import dataclass+from pathlib import Pathfrom typing import TYPE_CHECKING, Anyfrom marimo import _loggers@@ -26,7 +27,9 @@ from marimo._server.host.analysis import HostAnalyzerfrom marimo._server.host.backend import RequestMetadata, SessionBackendfrom marimo._server.host.events import notification_eventfrom marimo._server.host.index import WorkspaceIndex+from marimo._server.host.sessions import AppSessionNotebooksfrom marimo._session.events import SessionEventListener+from marimo._session.model import SessionModefrom marimo._session.notebook.storage import rename_no_replacefrom marimo._utils.generated_with import (contents_differ_excluding_generated_with,@@ -34,7 +37,6 @@ from marimo._utils.generated_with import (if TYPE_CHECKING:from collections.abc import Mapping, Sequence- from pathlib import Pathfrom marimo._config.manager import MarimoConfigManagerfrom marimo._core.backend import Message@@ -110,21 +112,41 @@ class SessionBridge(SessionEventListener):# TODO(MO-8005): The response to the session's latest mirror of its# app config, for the edit that caused it. Ends with the mirror.self._mirrored: dict[protocol.NotebookId, protocol.EditResponse] = {}- self.host = Host(operations=OPERATIONS)+ self.host: Host = Host(+ operations=OPERATIONS if manager.mode is SessionMode.EDIT else ()+ )self._backends: dict[protocol.NotebookId, SessionBackend] = {}- self.index = WorkspaceIndex(- self.host, manager.workspace, self._initialize_notebook+ self._index: WorkspaceIndex | None = (+ WorkspaceIndex(+ self.host, manager.workspace, self._initialize_notebook+ )+ if manager.mode is SessionMode.EDIT+ else None+ )+ self.app_sessions: AppSessionNotebooks | None = (+ AppSessionNotebooks(self.host, self._initialize_app_notebook)+ if manager.mode is SessionMode.RUN+ else None)self._unsubscribe = self.host.subscribe(self._on_host_event, types={"notebook"})+ @property+ def index(self) -> WorkspaceIndex:+ """The file catalog, when workspace indexing is enabled."""+ if self._index is None:+ raise Conflict("This host has no file catalog")+ return self._index+async def open(self) -> None:"""Index notebooks, adopt sessions, and subscribe to session events."""- self.index.refresh()+ if self.app_sessions is None:+ self.index.refresh()self._manager.event_bus.subscribe(self)- for session in list(self._manager.sessions.values()):- await self._adopt(session)+ if self.app_sessions is None:+ for session in list(self._manager.sessions.values()):+ await self.adopt(session)def close(self) -> None:self._manager.event_bus.unsubscribe(self)@@ -143,6 +165,22 @@ class SessionBridge(SessionEventListener):async with self._files_lock:await self.index.refresh_async()+ async def _initialize_app_notebook(+ self, record: protocol.Notebook, sink: Sink+ ) -> Notebook:+ assert self.app_sessions is not None+ session = self.app_sessions.session(record.id)+ cells, app_config = documents.from_session(session)+ document = Document(cells, app_config)+ return Notebook(+ record.id,+ document,+ Executions(),+ self._make_backend(record.id, sink),+ sink,+ saved_etag=document.etag,+ )+async def _initialize_notebook(self, record: protocol.Notebook, sink: Sink) -> Notebook:@@ -420,6 +458,10 @@ class SessionBridge(SessionEventListener):notebook = self.host.peek_notebook(notebook_id)if session is None or notebook is None:return+ if self.app_sessions is not None:+ cells, app_config = documents.from_session(session)+ notebook.replace(cells, app_config, saved=True)+ return# The editor owns the file now; a baseline being read for the# host is no longer wanted.self._rebaselining.pop(notebook_id, None)@@ -465,6 +507,8 @@ class SessionBridge(SessionEventListener):Its baseline for external changes is the file as the editorleft it, read off the event loop before the next save compares."""+ if self.app_sessions is not None:+ returnsession.app_file_manager.on_persisted = Noneself._rebaselining[notebook_id] = (asyncio.get_running_loop().create_task(@@ -642,6 +686,10 @@ class SessionBridge(SessionEventListener):self, notebook_id: protocol.NotebookId, sink: Sink) -> SessionBackend:def file() -> str | None:+ if self.app_sessions is not None:+ return self.app_sessions.session(+ notebook_id+ ).app_file_manager.pathpath = self.index.file_of(notebook_id)return None if path is None else str(path)@@ -680,43 +728,83 @@ class SessionBridge(SessionEventListener):self._rebaselining.pop(event.notebook_id, None)self._mirrored.pop(event.notebook_id, None)- async def _adopt(self, session: Session) -> None:+ async def adopt(self, session: Session) -> Notebook | None:+ """Expose the notebook selected by the existing session lifecycle."""+ existing = self.notebook_for_session(session)+ if existing is not None:+ return existing+ for notebook_id, candidate in self._adopting.items():+ if candidate is session:+ return await self.bind(notebook_id, session)path = session.app_file_manager.path- notebook = self.index.notebook_for(path)- if notebook is None and path is not None:- notebook = self.index.ensure(path)+ notebook: protocol.Notebook | None+ if self.app_sessions is not None:+ notebook_id = self.app_sessions.register(session)+ notebook = self.host.notebooks[notebook_id]+ else:+ notebook = self.index.notebook_for(path)+ if notebook is None:+ notebook = (+ self.index.untitled()+ if path is None+ else self.index.ensure(path)+ )if notebook is None:LOGGER.debug("Not publishing session for %s", path)- return- if self._adopting.setdefault(notebook.id, session) is not session:- return- try:- loaded = await self.host.notebook(notebook.id)- finally:- self._adopting.pop(notebook.id, None)- backend = self._backends[notebook.id]- if backend.session is not None:- return+ return Nonetry:- loaded.adopt(lambda runtime_id: backend.adopt(runtime_id, session))+ return await self.bind(notebook.id, session)except Conflict:LOGGER.debug("Not publishing a second session for %s", path)- return+ return None++ async def bind(+ self, notebook_id: protocol.NotebookId, session: Session+ ) -> Notebook:+ """Bind a registered notebook to a runtime independently of its source."""+ if self._adopting.setdefault(notebook_id, session) is not session:+ raise Conflict("The notebook already belongs to another session")+ try:+ loaded = await self.host.notebook(notebook_id)+ finally:+ self._adopting.pop(notebook_id, None)+ backend = self._backends[notebook_id]+ if backend.session is session:+ return loaded+ if backend.session is not None:+ raise Conflict("The notebook already belongs to another session")+ loaded.adopt(lambda runtime_id: backend.adopt(runtime_id, session))+ return loaded# Session eventsasync def on_session_created(self, session: Session) -> None:- await self._adopt(session)+ # App startup may finish after its browser has left. Bind only when+ # a connection claims it, so observers do not keep abandoned apps alive.+ if self.app_sessions is None:+ await self.adopt(session)++ async def on_session_closed(self, session: Session) -> None:+ if self.app_sessions is not None:+ self.app_sessions.remove(session)async def on_session_notebook_renamed(self, session: Session, old_path: str | None) -> None:notebook = self.index.notebook_for(old_path)+ if notebook is None:+ loaded = self.notebook_for_session(session)+ if loaded is not None:+ notebook = self.host.notebooks[loaded.id]path = session.app_file_manager.pathif path is None:returnif notebook is None:# Add notebooks to the catalog when first saved.- await self._adopt(session)+ await self.adopt(session)return- self.index.moved(notebook.id, path)+ if self.index.moved(notebook.id, path) is None:+ # An initially empty workspace has no project root. Keep the+ # session notebook until workspace discovery can include its file.++ self.index.rename(notebook.id, Path(path).stem)diff --git a/marimo/_server/host/index.py b/marimo/_server/host/index.pyindex a36282f687..6b8c1e6e32 100644--- a/marimo/_server/host/index.py+++ b/marimo/_server/host/index.py@@ -114,6 +114,19 @@ class WorkspaceIndex:return Nonereturn self._publish(file, modified, request_id=request_id)+ def untitled(self) -> protocol.Notebook:+ """Register an editor document before it has a file."""+ record = protocol.Notebook(+ id=mint(protocol.NotebookId, "nb"),+ project_id=self.project_id,+ path=None,+ name="Untitled",+ operations=("notebook.edit",),+ updated_at=None,+ )+ self._host.add_notebook(record, self._initialize)+ return record+def moved(self,notebook_id: protocol.NotebookId,diff --git a/marimo/_server/host/lifespan.py b/marimo/_server/host/lifespan.pyindex af16e78293..a69993020b 100644--- a/marimo/_server/host/lifespan.py+++ b/marimo/_server/host/lifespan.py@@ -25,12 +25,32 @@ if TYPE_CHECKING:LOGGER = _loggers.marimo_logger()+async def ensure_app_host(app: Starlette) -> HostContext:+ """Initialize a private app host, including for mounts without a lifespan."""+ state = AppStateBase.from_app(app)+ assert state.mode is SessionMode.RUN+ if state.host_context is not None:+ return state.host_context+ bridge = SessionBridge(state.session_manager, state.config_manager)+ # App open only subscribes to session events: it does not index files or+ # await adoption. Concurrent first connections share this context.+ await bridge.open()+ context = HostContext(bridge=bridge, token="", port=0)+ app.state.host_context = context+ return context++@contextlib.asynccontextmanagerasync def host(app: Starlette) -> AsyncIterator[None]:- """Initialize the host API and discovery record in edit mode."""+ """Serve notebook sessions; publish local discovery only in edit mode."""state = AppStateBase.from_app(app)- if state.mode is not SessionMode.EDIT:- yield+ if state.mode is SessionMode.RUN:+ context = await ensure_app_host(app)+ try:+ yield+ finally:+ context.bridge.close()+ app.state.host_context = Nonereturnserver = state.server.configdiff --git a/marimo/_server/host/middleware.py b/marimo/_server/host/middleware.pyindex 1a630aab74..9c25e294a1 100644--- a/marimo/_server/host/middleware.py+++ b/marimo/_server/host/middleware.py@@ -58,6 +58,10 @@ class HostApiMiddleware:context = getattr(request.app.state, "host_context", None)if context is None:response = problem(404, "not-found", "This server is not a host")+ elif context.bridge.app_sessions is not None:+ response = problem(+ 404, "not-found", "App sessions do not expose a host catalog"+ )elif self.editor_socket.matches(scope)[0] is Match.FULL and not _bearer_matches(diff --git a/marimo/_server/host/sessions.py b/marimo/_server/host/sessions.pynew file mode 100644index 0000000000..113d399a7e--- /dev/null+++ b/marimo/_server/host/sessions.py@@ -0,0 +1,67 @@+# Copyright 2026 Marimo. All rights reserved.+"""Private notebook identities for independently running app sessions."""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++from marimo._core import protocol+from marimo._core.errors import NotFound+from marimo._core.ids import mint++if TYPE_CHECKING:+ from marimo._core.host import Host, NotebookInitializer+ from marimo._session.session import Session+++class AppSessionNotebooks:+ """Register actual app sessions without indexing their source files."""++ def __init__(self, host: Host, initialize: NotebookInitializer) -> None:+ self._host = host+ self._initialize = initialize+ self._sessions: dict[protocol.NotebookId, Session] = {}+ self._project_id = mint(protocol.ProjectId, "proj")+ host.update_project(+ protocol.Project(+ id=self._project_id,+ name="app",+ root=None,+ status="indexed",+ message=None,+ operations=(),+ )+ )++ def register(self, session: Session) -> protocol.NotebookId:+ for notebook_id, candidate in self._sessions.items():+ if candidate is session:+ return notebook_id+ notebook_id = mint(protocol.NotebookId, "nb")+ self._sessions[notebook_id] = session+ path = session.app_file_manager.path+ self._host.add_notebook(+ protocol.Notebook(+ id=notebook_id,+ project_id=self._project_id,+ path=None,+ name=Path(path).stem if path else "app",+ updated_at=None,+ operations=(),+ ),+ self._initialize,+ )+ return notebook_id++ def session(self, notebook_id: protocol.NotebookId) -> Session:+ try:+ return self._sessions[notebook_id]+ except KeyError:+ raise NotFound(f"no notebook {notebook_id}") from None++ def remove(self, session: Session) -> None:+ for notebook_id, candidate in list(self._sessions.items()):+ if candidate is session:+ del self._sessions[notebook_id]+ self._host.remove_notebook(notebook_id)diff --git a/tests/_server/host/conftest.py b/tests/_server/host/conftest.pyindex 5efe780541..7debe8db80 100644--- a/tests/_server/host/conftest.py+++ b/tests/_server/host/conftest.py@@ -15,7 +15,7 @@ from marimo._messaging.notification import NotificationMessagefrom marimo._messaging.serde import serialize_kernel_messagefrom marimo._session.consumer import SessionConsumerfrom marimo._session.events import SessionEventBus-from marimo._session.model import ConnectionState+from marimo._session.model import ConnectionState, SessionModefrom marimo._session.types import KernelStatefrom marimo._types.ids import ConsumerId@@ -104,6 +104,8 @@ class FakeSession:class FakeManager:"""A session manager with configurable startup results and timing."""+ mode = SessionMode.EDIT+def __init__(self) -> None:self.sessions: dict[str, FakeSession] = {}self.event_bus = SessionEventBus()diff --git a/tests/_server/host/test_app_sessions.py b/tests/_server/host/test_app_sessions.pynew file mode 100644index 0000000000..05480197e5--- /dev/null+++ b/tests/_server/host/test_app_sessions.py@@ -0,0 +1,41 @@+# Copyright 2026 Marimo. All rights reserved.+"""App notebook identity and the boundary between sessions and discovery."""++from __future__ import annotations++import pytest++from marimo._server.host.bridge import SessionBridge+from marimo._server.host.context import HostContext+from marimo._server.main import create_starlette_app+from marimo._session.model import SessionMode+from tests._server.host.drive import finished+from tests._server.mocks import (+ get_mock_session_manager,+ get_starlette_server_state_init,+)+++ ("path", "method"),+ [+ ("/events", "GET"),+ ("/notebooks/unknown/edits", "POST"),+ ],+)+async def test_app_mode_never_exposes_the_catalog_or_mutations(path, method):+ manager = get_mock_session_manager(mode=SessionMode.RUN)+ app = create_starlette_app(base_url="", enable_auth=False)+ get_starlette_server_state_init(session_manager=manager).apply(app.state)+ bridge = SessionBridge(manager)+ app.state.host_context = HostContext(+ bridge=bridge, token="host-token", port=1234+ )+ await bridge.open()+ try:+ response = await finished(+ app, method, path, headers={"Authorization": "Bearer host-token"}+ )+ assert response.status == 404+ finally:+ bridge.close()diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.pyindex 63671489e2..2b63c642e4 100644--- a/tests/_server/host/test_host_api.py+++ b/tests/_server/host/test_host_api.py@@ -27,7 +27,6 @@ from marimo._server.host import HOST_API_PATH, api as api_modulefrom marimo._server.host.bridge import SessionBridgefrom marimo._server.host.context import HostContextfrom marimo._server.host.events import MarimoEvent, MarimoMessage-from marimo._server.host.index import WorkspaceIndexfrom marimo._server.main import create_starlette_appfrom marimo._server.models.home import MarimoFilefrom marimo._server.workspace import FixedFilesWorkspace, SingleFileWorkspace@@ -135,6 +134,7 @@ def harness()app = create_starlette_app(base_url="", enable_auth=True)manager = get_mock_session_manager()+ manager.workspace = workspaceget_starlette_server_state_init(session_manager=manager).apply(app.state)bridge = SessionBridge(manager)bridge.host.retention = getattr(request, "param", RetentionPolicy())@@ -147,9 +147,6 @@ def harness(return backendmonkeypatch.setattr(bridge, "_make_backend", make)- bridge.index = WorkspaceIndex(- bridge.host, workspace, bridge._initialize_notebook- )bridge.index.refresh()app.state.host_context = HostContext(bridge=bridge,diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.pyindex 83fd4329fb..5e75fff64a 100644--- a/tests/_server/host/test_host_bridge.py+++ b/tests/_server/host/test_host_bridge.py@@ -1055,7 +1055,7 @@ async def test_session_notebook_lookup_boundaries(await bridge.open()notebook = bridge.notebook_for_session(saved) # type: ignore[arg-type]assert notebook is not None- assert bridge.notebook_for_session(unsaved) is None # type: ignore[arg-type]+ assert bridge.notebook_for_session(unsaved) is not None # type: ignore[arg-type]assert bridge.notebook_for_session(outside) is None # type: ignore[arg-type]assert (bridge.notebook_for_session(FakeSession(str(tmp_path / "a.py")))