Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

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.py
index 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 None
and absolute_filepath
and not app_state.remote_url
):
diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.py
index bc426e85ef..b5c4299336 100644
--- a/marimo/_server/host/bridge.py
+++ b/marimo/_server/host/bridge.py
@@ -6,6 +6,7 @@ from __future__ import annotations
import asyncio
import copy
from dataclasses import dataclass
+from pathlib import Path
from typing import TYPE_CHECKING, Any
from marimo import _loggers
@@ -26,7 +27,9 @@ from marimo._server.host.analysis import HostAnalyzer
from marimo._server.host.backend import RequestMetadata, SessionBackend
from marimo._server.host.events import notification_event
from marimo._server.host.index import WorkspaceIndex
+from marimo._server.host.sessions import AppSessionNotebooks
from marimo._session.events import SessionEventListener
+from marimo._session.model import SessionMode
from marimo._session.notebook.storage import rename_no_replace
from 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 Path
from marimo._config.manager import MarimoConfigManager
from 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 editor
left it, read off the event loop before the next save compares.
"""
+ if self.app_sessions is not None:
+ return
session.app_file_manager.on_persisted = None
self._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.path
path = 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 None
try:
- 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 events
async 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.path
if path is None:
return
if 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.py
index a36282f687..6b8c1e6e32 100644
--- a/marimo/_server/host/index.py
+++ b/marimo/_server/host/index.py
@@ -114,6 +114,19 @@ class WorkspaceIndex:
return None
return 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.py
index 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.asynccontextmanager
async 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 = None
return
server = state.server.config
diff --git a/marimo/_server/host/middleware.py b/marimo/_server/host/middleware.py
index 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.py
new file mode 100644
index 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.py
index 5efe780541..7debe8db80 100644
--- a/tests/_server/host/conftest.py
+++ b/tests/_server/host/conftest.py
@@ -15,7 +15,7 @@ from marimo._messaging.notification import NotificationMessage
from marimo._messaging.serde import serialize_kernel_message
from marimo._session.consumer import SessionConsumer
from marimo._session.events import SessionEventBus
-from marimo._session.model import ConnectionState
+from marimo._session.model import ConnectionState, SessionMode
from marimo._session.types import KernelState
from 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.py
new file mode 100644
index 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.py
index 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_module
from marimo._server.host.bridge import SessionBridge
from marimo._server.host.context import HostContext
from marimo._server.host.events import MarimoEvent, MarimoMessage
-from marimo._server.host.index import WorkspaceIndex
from marimo._server.main import create_starlette_app
from marimo._server.models.home import MarimoFile
from 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 = workspace
get_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 backend
monkeypatch.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.py
index 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")))