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
Add server registry and SSE execute endpoint (#8592)
Trevor Manz7f2c978b02e1
diff --git a/marimo/_mcp/code_server/main.py b/marimo/_mcp/code_server/main.pyindex 635958c8ea..c6dc1302f7 100644--- a/marimo/_mcp/code_server/main.py+++ b/marimo/_mcp/code_server/main.py@@ -8,9 +8,8 @@ in a running marimo kernel via the scratchpad.from __future__ import annotations-import asyncioimport os-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKINGfrom marimo._ai._tools.types import (CodeExecutionResult,@@ -19,11 +18,11 @@ from marimo._ai._tools.types import ()from marimo._dependencies.dependencies import DependencyManagerfrom marimo._loggers import marimo_logger-from marimo._messaging.cell_output import CellChannel-from marimo._messaging.notification import CellNotification-from marimo._messaging.serde import deserialize_kernel_message-from marimo._runtime.scratch import SCRATCH_CELL_ID-from marimo._session.events import SessionEventBus, SessionEventListener+from marimo._server.scratchpad import (+ EXECUTION_TIMEOUT,+ ScratchCellListener,+ extract_result,+)from marimo._types.ids import SessionIdLOGGER = marimo_logger()@@ -32,52 +31,6 @@ if TYPE_CHECKING:from starlette.applications import Starlettefrom starlette.types import Receive, Scope, Send- from marimo._messaging.types import KernelMessage- from marimo._session.session import Session--_EXECUTION_TIMEOUT = 30.0 # seconds---class _ScratchCellListener(SessionEventListener):- """Listens for scratch cell idle notifications and signals waiters.-- Implements SessionExtension so it can be dynamically attached to a- session via session.attach_extension / session.detach_extension.- """-- def __init__(self) -> None:- self._waiters: dict[str, asyncio.Event] = {}-- def wait_for(self, session_id: str) -> asyncio.Event:- event = asyncio.Event()- self._waiters[session_id] = event- return event-- # SessionExtension protocol- def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:- del session- event_bus.subscribe(self)-- def on_detach(self) -> None:- pass-- def on_notification_sent(- self, session: Session, notification: KernelMessage- ) -> None:- del session- msg = deserialize_kernel_message(notification)- if not isinstance(msg, CellNotification):- return- if msg.cell_id != SCRATCH_CELL_ID:- return- if msg.status != "idle":- return- # Signal any waiter for this session- for sid, event in list(self._waiters.items()):- if not event.is_set():- event.set()- del self._waiters[sid]-def setup_code_mcp_server(app: Starlette, *, allow_remote: bool = False@@ -122,10 +75,6 @@ def setup_code_mcp_server(transport_security=transport_security,)- # Per-session locks to prevent overlapping scratchpad executions- session_locks: dict[str, asyncio.Lock] = {}- listener = _ScratchCellListener()-@mcp.tool()async def list_sessions() -> ListSessionsResult:"""List active marimo sessions.@@ -176,38 +125,22 @@ def setup_code_mcp_server("Use list_sessions to find valid session IDs.",)- # Attach listener as a session extension- session.attach_extension(listener)-- lock = session_locks.setdefault(session_id, asyncio.Lock())- async with lock:- try:- # Set up event before sending command- done = listener.wait_for(session_id)-- # Send the scratchpad execution command+ listener = ScratchCellListener()+ with session.scoped(listener):+ async with session.scratchpad_lock:session.put_control_request(ExecuteScratchpadCommand(code=code),from_consumer_id=None,)+ await listener.wait(timeout=EXECUTION_TIMEOUT)- # Wait for the scratch cell to become idle- await asyncio.wait_for(done.wait(), timeout=_EXECUTION_TIMEOUT)-- # FIXME: stdout/stderr are flushed every 10ms by the buffered- # writer thread. Wait 50ms so trailing console output arrives- # before we read cell_notifications.- # See: marimo-team/marimo-lsp ExecutionRegistry.ts- await asyncio.sleep(0.05)- except asyncio.TimeoutError:+ if listener.timed_out:return CodeExecutionResult(success=False,- error=f"Execution timed out after {_EXECUTION_TIMEOUT}s",+ error=f"Execution timed out after {EXECUTION_TIMEOUT}s",)- finally:- session.detach_extension(listener)- return _extract_result(session)+ return extract_result(session)# Build the streamable HTTP appmcp_app = mcp.streamable_http_app()@@ -228,51 +161,3 @@ def setup_code_mcp_server(app.routes.insert(0, Mount("/mcp", mcp_app))app.state.code_mcp = mcp---def _extract_result(session: Any) -> CodeExecutionResult:- """Read the scratch cell's final state from the session view."""- cell_notif = session.session_view.cell_notifications.get(SCRATCH_CELL_ID)- if cell_notif is None:- return CodeExecutionResult(success=True)-- # Output- output_data = None- if cell_notif.output is not None:- data = cell_notif.output.data- if isinstance(data, str):- output_data = data- elif isinstance(data, dict):- output_data = data.get(- "text/plain", data.get("text/html", str(data))- )- # list → errors, handled below-- # Console- stdout: list[str] = []- stderr: list[str] = []- for out in (- cell_notif.console if isinstance(cell_notif.console, list) else []- ):- if out is None:- continue- if out.channel == CellChannel.STDOUT:- stdout.append(str(out.data))- elif out.channel == CellChannel.STDERR:- stderr.append(str(out.data))-- # Errors- errors: list[str] = []- if cell_notif.output is not None and isinstance(- cell_notif.output.data, list- ):- for err in cell_notif.output.data:- errors.append(str(getattr(err, "msg", None) or err))-- return CodeExecutionResult(- success=len(errors) == 0,- output=output_data,- stdout=stdout,- stderr=stderr,- errors=errors,- )diff --git a/marimo/_messaging/tracebacks.py b/marimo/_messaging/tracebacks.pyindex 0304e6b955..72f34a549d 100644--- a/marimo/_messaging/tracebacks.py+++ b/marimo/_messaging/tracebacks.py@@ -3,6 +3,7 @@ from __future__ import annotationsimport sys+from marimo._messaging.context import HTTP_REQUEST_CTXfrom marimo._messaging.types import Stderr@@ -21,10 +22,24 @@ def _highlight_traceback(traceback: str) -> str:return f'<span class="codehilite">{body}</span>'+def _accepts_html() -> bool:+ """Check if the current request context accepts HTML responses.++ Returns True when there is no request context (e.g. websocket/browser)+ or when the Accept header explicitly includes text/html.+ """+ request = HTTP_REQUEST_CTX.get(None)+ if request is None:+ return True+ return "text/html" in request.headers.get("accept", "")++def write_traceback(traceback: str) -> None:- if isinstance(sys.stderr, Stderr):+ if isinstance(sys.stderr, Stderr) and _accepts_html():+ # Strip marimo's internal executor.py frame and highlight for the UI+ trimmed = _trim_traceback(traceback)sys.stderr._write_with_mimetype(- _highlight_traceback(_trim_traceback(traceback)),+ _highlight_traceback(trimmed),mimetype="application/vnd.marimo+traceback",)else:diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.pyindex 7be8933b03..d03efacb49 100644--- a/marimo/_runtime/runtime.py+++ b/marimo/_runtime/runtime.py@@ -1711,6 +1711,10 @@ class Kernel:clear_console=True,cell_id=SCRATCH_CELL_ID,)+ CellNotificationUtils.broadcast_status(+ cell_id=SCRATCH_CELL_ID,+ status="idle",+ )returnelif not cell:returndiff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.pyindex f6443cae45..d4915b2f71 100644--- a/marimo/_server/api/endpoints/execution.py+++ b/marimo/_server/api/endpoints/execution.py@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Optionalfrom uuid import uuid4from starlette.authentication import requires-from starlette.responses import JSONResponse+from starlette.responses import JSONResponse, StreamingResponsefrom marimo import _loggersfrom marimo._messaging.notification import AlertNotification@@ -34,6 +34,8 @@ from marimo._server.uvicorn_utils import close_uvicornfrom marimo._types.ids import ConsumerIdif TYPE_CHECKING:+ from collections.abc import AsyncGenerator+from starlette.requests import RequestLOGGER = _loggers.marimo_logger()@@ -239,6 +241,60 @@ async def run_cell(return SuccessResponse()[email protected]("/execute", include_in_schema=False)+@requires("edit")+async def execute_code(+ *,+ request: Request,+) -> StreamingResponse:+ """+ requestBody:+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/ExecuteScratchpadRequest"+ responses:+ 200:+ description: Execute code in the kernel, streaming results as SSE.+ content:+ text/event-stream:+ schema:+ type: string+ """ # noqa: E501+ from marimo._runtime.commands import ExecuteScratchpadCommand+ from marimo._server.scratchpad import (+ EXECUTION_TIMEOUT,+ ScratchCellListener,+ build_done_event,+ build_timeout_event,+ )++ app_state = AppState(request)+ body = await parse_request(request, cls=ExecuteScratchpadRequest)+ session = app_state.require_current_session()++ async def sse_generator() -> AsyncGenerator[str, None]:+ listener = ScratchCellListener()+ with session.scoped(listener):+ async with session.scratchpad_lock:+ session.put_control_request(+ ExecuteScratchpadCommand(+ code=body.code,+ request=HTTPRequest.from_request(request),+ ),+ from_consumer_id=None,+ )+ async for event in listener.stream(timeout=EXECUTION_TIMEOUT):+ yield event++ if listener.timed_out:+ yield build_timeout_event(EXECUTION_TIMEOUT)+ else:+ yield build_done_event(session)++ return StreamingResponse(sse_generator(), media_type="text/event-stream")++@router.post("/scratchpad/run")@requires("edit")async def run_scratchpad(diff --git a/marimo/_server/api/endpoints/health.py b/marimo/_server/api/endpoints/health.pyindex 9bdc38cb71..09c5e14ae5 100644--- a/marimo/_server/api/endpoints/health.py+++ b/marimo/_server/api/endpoints/health.py@@ -2,7 +2,7 @@from __future__ import annotationsfrom functools import lru_cache-from typing import TYPE_CHECKING, Any, Optional+from typing import TYPE_CHECKING, Any, Optional, TypedDictfrom starlette.authentication import requiresfrom starlette.responses import JSONResponse, PlainTextResponse@@ -92,6 +92,42 @@ async def status(request: Request) -> JSONResponse:)+class SessionInfo(TypedDict):+ filename: str | None+ path: str | None++[email protected]("/api/sessions", include_in_schema=False)+@requires("edit")+async def list_sessions(request: Request) -> JSONResponse:+ """List active session IDs and their notebook paths.++ Only available when the server was started without an auth token+ (``--no-token``) and without skew protection+ (``--no-skew-protection``).+ """++ state = AppState(request)++ if state.enable_auth or state.skew_protection:+ return JSONResponse(+ {+ "error": "Session listing requires --no-token and "+ "--no-skew-protection"+ },+ status_code=403,+ )++ sessions = {+ session_id: SessionInfo(+ filename=session.app_file_manager.filename,+ path=session.app_file_manager.path,+ )+ for session_id, session in state.session_manager.sessions.items()+ }+ return JSONResponse(sessions)++@router.get("/api/version")async def version(request: Request) -> PlainTextResponse:"""diff --git a/marimo/_server/api/lifespans.py b/marimo/_server/api/lifespans.pyindex c64a268d59..cd469280bb 100644--- a/marimo/_server/api/lifespans.py+++ b/marimo/_server/api/lifespans.py@@ -207,6 +207,49 @@ async def signal_handler(app: Starlette) -> AsyncIterator[None]:yield+async def server_registry(app: Starlette) -> AsyncIterator[None]:+ """Register this server in the local registry for discovery.++ Only servers started **without** an auth token (``--no-token``)+ **and** without skew protection (``--no-skew-protection``) are+ registered. This ensures only servers that have explicitly opted+ into relaxed local access are discoverable.+ """+ from marimo._server.server_registry import (+ ServerRegistryEntry,+ ServerRegistryWriter,+ )++ state = AppState.from_app(app)++ # Guard: only register when the user has opted into relaxed local+ # access (no auth token, no skew protection).+ if state.enable_auth or state.skew_protection:+ LOGGER.debug(+ "Skipping server registry: auth=%s, skew_protection=%s",+ state.enable_auth,+ state.skew_protection,+ )+ yield+ return++ entry = ServerRegistryEntry.from_server(+ host=state.host,+ port=state.port,+ base_url=state.base_url,+ )+ writer = ServerRegistryWriter(entry)+ try:+ writer.register()+ except Exception as e:+ LOGGER.warning("Failed to register server: %s", e)++ yield++ writer.deregister()++@contextlib.asynccontextmanagerasync def etc(app: Starlette) -> AsyncIterator[None]:del appdiff --git a/marimo/_server/router.py b/marimo/_server/router.pyindex 00a938a1fa..60599ee67e 100644--- a/marimo/_server/router.py+++ b/marimo/_server/router.py@@ -38,7 +38,7 @@ class APIRouter(Router):)def post(- self, path: str+ self, path: str, include_in_schema: bool = True) -> Callable[[DecoratedCallable], DecoratedCallable]:"""Post method that returns a JSON response"""@@ -62,6 +62,7 @@ class APIRouter(Router):path=self.prefix + path,endpoint=wrapper_func,methods=["POST"],+ include_in_schema=include_in_schema,)return wrapper_func # type: ignore[return-value]diff --git a/marimo/_server/scratchpad.py b/marimo/_server/scratchpad.pynew file mode 100644index 0000000000..5dfe5400a9--- /dev/null+++ b/marimo/_server/scratchpad.py@@ -0,0 +1,286 @@+# Copyright 2026 Marimo. All rights reserved.+"""Shared utilities for scratchpad execution."""++from __future__ import annotations++import asyncio+import json+import sys+from typing import TYPE_CHECKING, Any, TypedDict++if sys.version_info < (3, 11):+ from typing_extensions import NotRequired+else:+ from typing import NotRequired++from marimo._ai._tools.types import CodeExecutionResult+from marimo._messaging.cell_output import CellChannel+from marimo._messaging.notification import CellNotification+from marimo._messaging.serde import deserialize_kernel_message+from marimo._runtime.scratch import SCRATCH_CELL_ID+from marimo._session.events import SessionEventBus, SessionEventListener++if TYPE_CHECKING:+ from collections.abc import AsyncGenerator++ from marimo._messaging.types import KernelMessage+ from marimo._session.session import Session++EXECUTION_TIMEOUT = 30.0 # seconds++# Channel name constants for SSE events+_CHANNEL_MAP = {+ CellChannel.STDOUT: "stdout",+ CellChannel.STDERR: "stderr",+}+++# -- SSE event payload types --------------------------------------------------+++class OutputData(TypedDict):+ mimetype: str+ data: str+++class ErrorData(TypedDict):+ type: str+ msg: str+ exception_type: NotRequired[str]+++class ConsoleEvent(TypedDict):+ data: str+++class DoneSuccess(TypedDict):+ success: bool+ output: NotRequired[OutputData]+++class DoneError(TypedDict):+ success: bool+ error: ErrorData+++def _format_sse(event: str, data: Any) -> str:+ """Format a single SSE event (event + JSON data)."""+ return f"event: {event}\ndata: {json.dumps(data)}\n\n"+++# -- Listeners ----------------------------------------------------------------+++class ScratchCellListener(SessionEventListener):+ """Listens for scratch cell notifications via an asyncio.Queue.++ Supports both SSE streaming (via ``stream()``) and simple blocking+ wait (via ``wait()``) so the same listener works for the HTTP+ ``/execute`` endpoint and the MCP ``execute_code`` tool.+ """++ def __init__(self) -> None:+ self._queue: asyncio.Queue[CellNotification | None] = asyncio.Queue()+ self.timed_out = False++ def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:+ del session+ self._event_bus = event_bus+ event_bus.subscribe(self)++ def on_detach(self) -> None:+ if hasattr(self, "_event_bus"):+ self._event_bus.unsubscribe(self)+ del self._event_bus++ def on_notification_sent(+ self, session: Session, notification: KernelMessage+ ) -> None:+ del session+ msg = deserialize_kernel_message(notification)+ if not isinstance(msg, CellNotification):+ return+ if msg.cell_id != SCRATCH_CELL_ID:+ return+ self._queue.put_nowait(msg)+ if msg.status == "idle":+ self._queue.put_nowait(None) # sentinel++ async def stream(+ self, timeout: float = EXECUTION_TIMEOUT+ ) -> AsyncGenerator[str, None]:+ """Yield SSE-formatted stdout/stderr events until execution completes."""+ import time++ deadline = time.monotonic() + timeout+ while True:+ remaining = deadline - time.monotonic()+ if remaining <= 0:+ self.timed_out = True+ return+ try:+ msg = await asyncio.wait_for(+ self._queue.get(), timeout=remaining+ )+ except asyncio.TimeoutError:+ self.timed_out = True+ return++ if msg is None:+ # Done sentinel — but stdout/stderr are flushed every+ # 10ms by the buffered writer thread. Wait 50ms so+ # trailing console output arrives before we finish.+ await asyncio.sleep(0.05)+ while not self._queue.empty():+ trailing = self._queue.get_nowait()+ if trailing is not None:+ for event_str in _format_console(trailing):+ yield event_str+ return++ for event_str in _format_console(msg):+ yield event_str++ async def wait(self, timeout: float = EXECUTION_TIMEOUT) -> None:+ """Block until execution completes, discarding streamed events.++ Sets ``self.timed_out`` if the deadline is exceeded.+ """+ import time++ deadline = time.monotonic() + timeout+ while True:+ remaining = deadline - time.monotonic()+ if remaining <= 0:+ self.timed_out = True+ return+ try:+ msg = await asyncio.wait_for(+ self._queue.get(), timeout=remaining+ )+ except asyncio.TimeoutError:+ self.timed_out = True+ return+ if msg is None:+ # Same flush delay as stream()+ await asyncio.sleep(0.05)+ return+++# -- Helpers ------------------------------------------------------------------+++def _format_console(msg: CellNotification) -> list[str]:+ """Extract SSE-formatted stdout/stderr events from a CellNotification."""+ if msg.console is None:+ return []+ console_list = (+ msg.console if isinstance(msg.console, list) else [msg.console]+ )+ return [+ _format_sse(channel, ConsoleEvent(data=str(out.data)))+ for out in console_list+ if out is not None+ for channel in (_CHANNEL_MAP.get(out.channel),)+ if channel is not None+ ]+++def build_done_event(session: Session) -> str:+ """Build the ``done`` SSE event from the session's scratch cell state."""+ cell_notif = session.session_view.cell_notifications.get(SCRATCH_CELL_ID)+ if cell_notif is None:+ return _format_sse("done", DoneSuccess(success=True))++ output = cell_notif.output++ # Error case+ if (+ output is not None+ and output.channel == CellChannel.MARIMO_ERROR+ and isinstance(output.data, list)+ and output.data+ ):+ err = output.data[0]+ error_data = ErrorData(+ type=type(err).__name__,+ msg=str(getattr(err, "msg", None) or err),+ )+ if hasattr(err, "exception_type"):+ error_data["exception_type"] = err.exception_type+ return _format_sse("done", DoneError(success=False, error=error_data))++ # Success case+ if output is not None:+ data = output.data+ if isinstance(data, dict):+ data = data.get("text/plain", data.get("text/html", str(data)))+ return _format_sse(+ "done",+ DoneSuccess(+ success=True,+ output=OutputData(+ mimetype=str(output.mimetype), data=str(data)+ ),+ ),+ )++ return _format_sse("done", DoneSuccess(success=True))+++def build_timeout_event(timeout: float) -> str:+ """Build a ``done`` SSE event for a timeout."""+ return _format_sse(+ "done",+ DoneError(+ success=False,+ error=ErrorData(+ type="TimeoutError",+ msg=f"Execution timed out after {timeout}s",+ ),+ ),+ )+++def extract_result(session: Session) -> CodeExecutionResult:+ """Read the scratch cell's final state from the session view."""+ cell_notif = session.session_view.cell_notifications.get(SCRATCH_CELL_ID)+ if cell_notif is None:+ return CodeExecutionResult(success=True)++ output_data = None+ if cell_notif.output is not None:+ data = cell_notif.output.data+ if isinstance(data, str):+ output_data = data+ elif isinstance(data, dict):+ output_data = data.get(+ "text/plain", data.get("text/html", str(data))+ )++ stdout: list[str] = []+ stderr: list[str] = []+ for out in (+ cell_notif.console if isinstance(cell_notif.console, list) else []+ ):+ if out is None:+ continue+ if out.channel == CellChannel.STDOUT:+ stdout.append(str(out.data))+ elif out.channel == CellChannel.STDERR:+ stderr.append(str(out.data))++ errors: list[str] = []+ if cell_notif.output is not None and isinstance(+ cell_notif.output.data, list+ ):+ for err in cell_notif.output.data:+ errors.append(str(getattr(err, "msg", None) or err))++ return CodeExecutionResult(+ success=len(errors) == 0,+ output=output_data,+ stdout=stdout,+ stderr=stderr,+ errors=errors,+ )diff --git a/marimo/_server/server_registry.py b/marimo/_server/server_registry.pynew file mode 100644index 0000000000..72c57a221b--- /dev/null+++ b/marimo/_server/server_registry.py@@ -0,0 +1,130 @@+# Copyright 2026 Marimo. All rights reserved.+"""Local discovery registry for running marimo instances.++Each marimo server writes a small JSON file to+``~/.local/state/marimo/servers/<host>_<port>.json`` at startup and+removes it on shutdown. External tools (e.g. ``list-sessions.sh``)+read these files to discover running instances — no marimo import or+HTTP endpoint is required.++SECURITY: Only instances that have opted into relaxed local access —+started **without** an auth token (``--no-token``) **and** without+skew protection (``--no-skew-protection``) — should be registered.+See the guard in ``lifespans.server_registry``.+"""++from __future__ import annotations++import atexit+import json+import os+import tempfile+from dataclasses import asdict, dataclass+from datetime import datetime, timezone+from typing import TYPE_CHECKING++if TYPE_CHECKING:+ from pathlib import Path++from marimo import _loggers+from marimo._utils.xdg import marimo_state_dir++LOGGER = _loggers.marimo_logger()++SERVERS_DIR_NAME = "servers"+++def _servers_dir() -> Path:+ return marimo_state_dir() / SERVERS_DIR_NAME+++def _entry_path(server_id: str) -> Path:+ safe_id = server_id.replace(":", "_").replace("/", "_")+ return _servers_dir() / f"{safe_id}.json"+++@dataclass(frozen=True)+class ServerRegistryEntry:+ """Minimal descriptor for a running marimo server.++ SECURITY NOTE: These files live on the local filesystem and are+ readable by any process running as the same user. Keep the fields+ to the bare minimum needed for discovery — no secrets, no auth+ tokens, no session data. If you want to add a field, ask whether+ an unauthenticated local process really needs it.+ """++ server_id: str+ pid: int+ host: str+ port: int+ base_url: str+ started_at: str+ version: str++ @staticmethod+ def from_server(+ *,+ host: str,+ port: int,+ base_url: str,+ ) -> ServerRegistryEntry:+ from marimo._version import __version__++ return ServerRegistryEntry(+ server_id=f"{host}:{port}",+ pid=os.getpid(),+ host=host,+ port=port,+ base_url=base_url,+ started_at=datetime.now(timezone.utc).isoformat(),+ version=__version__,+ )+++class ServerRegistryWriter:+ """Writes a registry entry on server start, removes on shutdown."""++ def __init__(self, entry: ServerRegistryEntry) -> None:+ self._entry = entry+ self._path = _entry_path(entry.server_id)+ self._registered = False++ def register(self) -> None:+ servers_dir = _servers_dir()+ servers_dir.mkdir(parents=True, exist_ok=True)++ data = json.dumps(asdict(self._entry), indent=2)++ # Atomic write: temp file then rename+ fd, tmp_path = tempfile.mkstemp(dir=str(servers_dir), suffix=".tmp")+ try:+ try:+ os.write(fd, data.encode("utf-8"))+ finally:+ os.close(fd)+ os.chmod(tmp_path, 0o600)+ os.replace(tmp_path, str(self._path))+ except Exception:+ try:+ os.unlink(tmp_path)+ except OSError:+ pass+ raise++ self._registered = True+ atexit.register(self.deregister)+ LOGGER.debug("Registered server: %s", self._path)++ def deregister(self) -> None:+ if not self._registered:+ return+ try:+ self._path.unlink(missing_ok=True)+ LOGGER.debug("Deregistered server: %s", self._path)+ except OSError as e:+ LOGGER.warning(+ "Failed to remove registry entry %s: %s", self._path, e+ )+ finally:+ self._registered = Falsediff --git a/marimo/_server/start.py b/marimo/_server/start.pyindex 67d3c0f8fb..1dc6723c71 100644--- a/marimo/_server/start.py+++ b/marimo/_server/start.py@@ -274,6 +274,7 @@ def start(lifespans.logging,lifespans.open_browser,lifespans.tool_manager,+ lifespans.server_registry,*LIFESPAN_REGISTRY.get_all(),]diff --git a/marimo/_session/session.py b/marimo/_session/session.pyindex 756d2dc987..3c3db1b926 100644--- a/marimo/_session/session.py+++ b/marimo/_session/session.py@@ -7,6 +7,8 @@ and websocket for bidirectional communication.from __future__ import annotations+import asyncio+import contextlibfrom typing import TYPE_CHECKING, Optionalfrom uuid import uuid4@@ -57,7 +59,7 @@ from marimo._types.ids import ConsumerIdfrom marimo._utils.repr import format_reprif TYPE_CHECKING:- from collections.abc import Mapping+ from collections.abc import Iterator, Mappingfrom marimo._server.models.models import InstantiateNotebookRequest@@ -201,6 +203,7 @@ class SessionImpl(Session):self.session_view = SessionView()self.config_manager = config_managerself.extensions = extensions+ self.scratchpad_lock = asyncio.Lock()self._kernel_manager.start_kernel()self._event_bus = SessionEventBus()@@ -239,16 +242,19 @@ class SessionImpl(Session):)continue- def attach_extension(self, extension: SessionExtension) -> None:- """Dynamically attach an extension to the session."""+ @contextlib.contextmanager+ def scoped(+ self, extension: SessionExtension+ ) -> Iterator[SessionExtension]:+ """Attach an extension for the duration of the context."""self.extensions.append(extension)extension.on_attach(self, self._event_bus)-- def detach_extension(self, extension: SessionExtension) -> None:- """Dynamically detach an extension from the session."""- extension.on_detach()- if extension in self.extensions:- self.extensions.remove(extension)+ try:+ yield extension+ finally:+ extension.on_detach()+ if extension in self.extensions:+ self.extensions.remove(extension)@propertydef consumers(self) -> Mapping[SessionConsumer, ConsumerId]:diff --git a/marimo/_session/types.py b/marimo/_session/types.pyindex 26ad5c0f2e..f4ab6a1449 100644--- a/marimo/_session/types.py+++ b/marimo/_session/types.py@@ -8,12 +8,14 @@ implementations.from __future__ import annotations+import contextlibfrom enum import Enumfrom typing import TYPE_CHECKING, Any, Optional, Protocol, Unionif TYPE_CHECKING:+ import asyncioimport threading- from collections.abc import Mapping+ from collections.abc import Iterator, Mappingfrom marimo._config.manager import MarimoConfigManagerfrom marimo._messaging.notification import NotificationMessage@@ -109,6 +111,7 @@ class Session(Protocol):config_manager: MarimoConfigManagersession_view: SessionViewttl_seconds: int+ scratchpad_lock: asyncio.Lock@propertydef consumers(self) -> Mapping[SessionConsumer, ConsumerId]:@@ -182,12 +185,11 @@ class Session(Protocol):"""Instantiate the app."""...- def attach_extension(self, extension: SessionExtension) -> None:- """Dynamically attach an extension to the session."""- ...-- def detach_extension(self, extension: SessionExtension) -> None:- """Dynamically detach an extension from the session."""+ @contextlib.contextmanager+ def scoped(+ self, extension: SessionExtension+ ) -> Iterator[SessionExtension]:+ """Attach an extension for the duration of the context."""...def close(self) -> None:diff --git a/tests/_messaging/test_tracebacks.py b/tests/_messaging/test_tracebacks.pyindex 84e88f2ea0..364e625f2e 100644--- a/tests/_messaging/test_tracebacks.py+++ b/tests/_messaging/test_tracebacks.py@@ -3,13 +3,16 @@ from __future__ import annotationsfrom unittest.mock import MagicMock, patch+from marimo._messaging.context import HTTP_REQUEST_CTXfrom marimo._messaging.tracebacks import (+ _accepts_html,_highlight_traceback,_trim_traceback,is_code_highlighting,write_traceback,)from marimo._messaging.types import Stderr+from marimo._runtime.commands import HTTPRequestclass TestTracebacks:@@ -81,6 +84,125 @@ class TestTracebacks:assert is_code_highlighting("") is Falseassert is_code_highlighting('class="not-codehilite"') is False+ def test_write_traceback_plain_text_when_accept_not_html(self) -> None:+ """When HTTP request has Accept without text/html, use plain text."""+ mock_stderr = MagicMock(spec=Stderr)+ req = HTTPRequest(+ url={},+ base_url={},+ headers={"accept": "text/event-stream"},+ query_params={},+ path_params={},+ cookies={},+ meta={},+ user=None,+ )+ token = HTTP_REQUEST_CTX.set(req)+ try:+ with patch("sys.stderr", mock_stderr):+ traceback = 'Traceback (most recent call last):\n File "<stdin>", line 1, in <module>\nValueError: bad'+ write_traceback(traceback)+ mock_stderr.write.assert_called_once()+ mock_stderr._write_with_mimetype.assert_not_called()+ finally:+ HTTP_REQUEST_CTX.reset(token)++ def test_write_traceback_html_when_accept_includes_html(self) -> None:+ """When HTTP request has Accept with text/html, use HTML formatting."""+ mock_stderr = MagicMock(spec=Stderr)+ req = HTTPRequest(+ url={},+ base_url={},+ headers={"accept": "text/html, application/json"},+ query_params={},+ path_params={},+ cookies={},+ meta={},+ user=None,+ )+ token = HTTP_REQUEST_CTX.set(req)+ try:+ with patch("sys.stderr", mock_stderr):+ traceback = 'Traceback (most recent call last):\n File "<stdin>", line 1, in <module>\nValueError: bad'+ write_traceback(traceback)+ mock_stderr._write_with_mimetype.assert_called_once()+ mock_stderr.write.assert_not_called()+ finally:+ HTTP_REQUEST_CTX.reset(token)+++class TestAcceptsHtml:+ def test_no_request_context(self) -> None:+ assert _accepts_html() is True++ def test_accept_event_stream(self) -> None:+ req = HTTPRequest(+ url={},+ base_url={},+ headers={"accept": "text/event-stream"},+ query_params={},+ path_params={},+ cookies={},+ meta={},+ user=None,+ )+ token = HTTP_REQUEST_CTX.set(req)+ try:+ assert _accepts_html() is False+ finally:+ HTTP_REQUEST_CTX.reset(token)++ def test_accept_html(self) -> None:+ req = HTTPRequest(+ url={},+ base_url={},+ headers={"accept": "text/html"},+ query_params={},+ path_params={},+ cookies={},+ meta={},+ user=None,+ )+ token = HTTP_REQUEST_CTX.set(req)+ try:+ assert _accepts_html() is True+ finally:+ HTTP_REQUEST_CTX.reset(token)++ def test_accept_wildcard(self) -> None:+ req = HTTPRequest(+ url={},+ base_url={},+ headers={"accept": "*/*"},+ query_params={},+ path_params={},+ cookies={},+ meta={},+ user=None,+ )+ token = HTTP_REQUEST_CTX.set(req)+ try:+ assert _accepts_html() is False+ finally:+ HTTP_REQUEST_CTX.reset(token)++ def test_no_accept_header(self) -> None:+ req = HTTPRequest(+ url={},+ base_url={},+ headers={},+ query_params={},+ path_params={},+ cookies={},+ meta={},+ user=None,+ )+ token = HTTP_REQUEST_CTX.set(req)+ try:+ assert _accepts_html() is False+ finally:+ HTTP_REQUEST_CTX.reset(token)+def test_trim(self) -> None:prefix = "Traceback (most recent call last):\n"head = ' File ".../marimo/_runtime/executor.py", line 139, in execute_cell\n return eval(cell.last_expr, glbls)\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^\n'diff --git a/tests/_server/test_scratchpad.py b/tests/_server/test_scratchpad.pynew file mode 100644index 0000000000..bd650e6b7f--- /dev/null+++ b/tests/_server/test_scratchpad.py@@ -0,0 +1,372 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import json+from unittest.mock import MagicMock++import pytest++from marimo._ai._tools.types import CodeExecutionResult+from marimo._messaging.cell_output import CellChannel, CellOutput+from marimo._messaging.errors import (+ MarimoExceptionRaisedError,+ MarimoSyntaxError,+)+from marimo._messaging.notification import CellNotification+from marimo._runtime.scratch import SCRATCH_CELL_ID+from marimo._server.scratchpad import (+ ScratchCellListener,+ _format_console,+ _format_sse,+ build_done_event,+ build_timeout_event,+ extract_result,+)+++def _make_session(+ notification: CellNotification | None = None,+) -> MagicMock:+ session = MagicMock()+ session.session_view.cell_notifications = {}+ if notification is not None:+ session.session_view.cell_notifications[SCRATCH_CELL_ID] = notification+ return session+++def _parse_sse(sse: str) -> tuple[str, dict[str, object]]:+ """Parse an SSE string into (event_name, json_data)."""+ event = ""+ data = ""+ for line in sse.strip().splitlines():+ if line.startswith("event: "):+ event = line[len("event: ") :]+ elif line.startswith("data: "):+ data = line[len("data: ") :]+ return event, json.loads(data)+++class TestExtractResult:+ def test_no_notification(self) -> None:+ result = extract_result(_make_session())+ assert result == CodeExecutionResult(success=True)++ def test_string_output(self) -> None:+ notif = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=CellOutput(+ channel=CellChannel.OUTPUT,+ mimetype="text/plain",+ data="hello",+ ),+ console=None,+ status="idle",+ )+ result = extract_result(_make_session(notif))+ assert result.success is True+ assert result.output == "hello"++ def test_dict_output_text_plain(self) -> None:+ notif = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=CellOutput(+ channel=CellChannel.OUTPUT,+ mimetype="text/plain",+ data={"text/plain": "value", "text/html": "<b>value</b>"},+ ),+ console=None,+ status="idle",+ )+ result = extract_result(_make_session(notif))+ assert result.output == "value"++ def test_dict_output_html_fallback(self) -> None:+ notif = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=CellOutput(+ channel=CellChannel.OUTPUT,+ mimetype="text/html",+ data={"text/html": "<b>hi</b>"},+ ),+ console=None,+ status="idle",+ )+ result = extract_result(_make_session(notif))+ assert result.output == "<b>hi</b>"++ def test_stdout_stderr(self) -> None:+ notif = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=None,+ console=[+ CellOutput(+ channel=CellChannel.STDOUT,+ mimetype="text/plain",+ data="out1",+ ),+ CellOutput(+ channel=CellChannel.STDERR,+ mimetype="text/plain",+ data="err1",+ ),+ CellOutput(+ channel=CellChannel.STDOUT,+ mimetype="text/plain",+ data="out2",+ ),+ ],+ status="idle",+ )+ result = extract_result(_make_session(notif))+ assert result.stdout == ["out1", "out2"]+ assert result.stderr == ["err1"]++ def test_errors(self) -> None:+ err_obj = MagicMock()+ err_obj.msg = "NameError: x is not defined"+ notif = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=CellOutput(+ channel=CellChannel.MARIMO_ERROR,+ mimetype="application/vnd.marimo+error",+ data=[err_obj],+ ),+ console=None,+ status="idle",+ )+ result = extract_result(_make_session(notif))+ assert result.success is False+ assert len(result.errors) == 1+ assert "NameError" in result.errors[0]++ def test_none_console_entries_skipped(self) -> None:+ notif = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=None,+ console=[+ None,+ CellOutput( # type: ignore[list-item]+ channel=CellChannel.STDOUT,+ mimetype="text/plain",+ data="ok",+ ),+ ],+ status="idle",+ )+ result = extract_result(_make_session(notif))+ assert result.stdout == ["ok"]+++class TestFormatSse:+ def test_json_payload(self) -> None:+ result = _format_sse("done", {"success": True})+ assert result == 'event: done\ndata: {"success": true}\n\n'++ def test_newlines_in_json_are_escaped(self) -> None:+ result = _format_sse("stdout", {"data": "line1\nline2\n"})+ # The JSON string escapes \n, so it's a single data: line+ assert result.count("\ndata: ") == 1+ event, payload = _parse_sse(result)+ assert event == "stdout"+ assert payload["data"] == "line1\nline2\n"+++class TestFormatConsole:+ def test_stdout(self) -> None:+ msg = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ console=CellOutput.stdout("hello world\n"),+ )+ events = _format_console(msg)+ assert len(events) == 1+ event, payload = _parse_sse(events[0])+ assert event == "stdout"+ assert payload["data"] == "hello world\n"++ def test_stderr(self) -> None:+ msg = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ console=CellOutput.stderr("warning\n"),+ )+ events = _format_console(msg)+ assert len(events) == 1+ event, payload = _parse_sse(events[0])+ assert event == "stderr"+ assert payload["data"] == "warning\n"++ def test_list_of_outputs(self) -> None:+ msg = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ console=[+ CellOutput.stdout("line1\n"),+ CellOutput.stderr("err1\n"),+ ],+ )+ events = _format_console(msg)+ assert len(events) == 2+ assert _parse_sse(events[0])[0] == "stdout"+ assert _parse_sse(events[1])[0] == "stderr"++ def test_none_console(self) -> None:+ msg = CellNotification(cell_id=SCRATCH_CELL_ID)+ assert _format_console(msg) == []++ def test_none_entries_skipped(self) -> None:+ msg = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ console=[+ None, # type: ignore[list-item]+ CellOutput.stdout("ok\n"),+ ],+ )+ events = _format_console(msg)+ assert len(events) == 1++ def test_multiline_data_stays_single_sse_line(self) -> None:+ msg = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ console=CellOutput.stdout("a\nb\nc\n"),+ )+ events = _format_console(msg)+ assert len(events) == 1+ # Should be exactly one data: line (newlines escaped in JSON)+ assert events[0].count("\ndata: ") == 1+ _, payload = _parse_sse(events[0])+ assert payload["data"] == "a\nb\nc\n"+++class TestBuildDoneEvent:+ def test_no_notification(self) -> None:+ event, data = _parse_sse(build_done_event(_make_session()))+ assert event == "done"+ assert data == {"success": True}++ def test_success_with_output(self) -> None:+ notif = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=CellOutput(+ channel=CellChannel.OUTPUT,+ mimetype="text/plain",+ data="42",+ ),+ status="idle",+ )+ _, data = _parse_sse(build_done_event(_make_session(notif)))+ assert data["success"] is True+ assert data["output"]["mimetype"] == "text/plain"+ assert data["output"]["data"] == "42"++ def test_success_with_dict_output(self) -> None:+ notif = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=CellOutput(+ channel=CellChannel.OUTPUT,+ mimetype="text/plain",+ data={"text/plain": "value", "text/html": "<b>v</b>"},+ ),+ status="idle",+ )+ _, data = _parse_sse(build_done_event(_make_session(notif)))+ assert data["success"] is True+ assert data["output"]["data"] == "value"++ def test_error_with_exception(self) -> None:+ err = MarimoExceptionRaisedError(+ msg="NameError: x is not defined",+ exception_type="NameError",+ raising_cell=None,+ )+ notif = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=CellOutput.errors([err]),+ status="idle",+ )+ _, data = _parse_sse(build_done_event(_make_session(notif)))+ assert data["success"] is False+ assert data["error"]["type"] == "MarimoExceptionRaisedError"+ assert data["error"]["exception_type"] == "NameError"+ assert "NameError" in data["error"]["msg"]++ def test_error_without_exception_type(self) -> None:+ err = MarimoSyntaxError(msg="invalid syntax", lineno=1)+ notif = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=CellOutput.errors([err]),+ status="idle",+ )+ _, data = _parse_sse(build_done_event(_make_session(notif)))+ assert data["success"] is False+ assert data["error"]["type"] == "MarimoSyntaxError"+ assert "exception_type" not in data["error"]++ def test_timeout(self) -> None:+ _, data = _parse_sse(build_timeout_event(30.0))+ assert data["success"] is False+ assert data["error"]["type"] == "TimeoutError"+ assert "30.0s" in data["error"]["msg"]+++class TestScratchCellListener:+ @pytest.mark.asyncio+ async def test_stream_basic(self) -> None:+ from marimo._messaging.serde import serialize_kernel_message++ listener = ScratchCellListener()+ event_bus = MagicMock()+ session = MagicMock()+ listener.on_attach(session, event_bus)++ running = CellNotification(cell_id=SCRATCH_CELL_ID, status="running")+ console = CellNotification(+ cell_id=SCRATCH_CELL_ID,+ console=CellOutput.stdout("hello\n"),+ )+ idle = CellNotification(cell_id=SCRATCH_CELL_ID, status="idle")++ for notif in [running, console, idle]:+ listener.on_notification_sent(+ session, serialize_kernel_message(notif)+ )++ events: list[str] = []+ async for event in listener.stream():+ events.append(event)++ # running has no console → no events; console has stdout; idle has no console+ assert len(events) == 1+ name, payload = _parse_sse(events[0])+ assert name == "stdout"+ assert payload["data"] == "hello\n"+ assert not listener.timed_out++ @pytest.mark.asyncio+ async def test_ignores_other_cells(self) -> None:+ from marimo._messaging.serde import serialize_kernel_message++ listener = ScratchCellListener()+ event_bus = MagicMock()+ session = MagicMock()+ listener.on_attach(session, event_bus)++ other_cell = CellNotification(+ cell_id="other_cell_id",+ status="running", # type: ignore[arg-type]+ )+ listener.on_notification_sent(+ session, serialize_kernel_message(other_cell)+ )+ assert listener._queue.empty()++ @pytest.mark.asyncio+ async def test_stream_timeout(self) -> None:+ listener = ScratchCellListener()+ event_bus = MagicMock()+ session = MagicMock()+ listener.on_attach(session, event_bus)++ events: list[str] = []+ async for event in listener.stream(timeout=0.1):+ events.append(event)++ assert events == []+ assert listener.timed_out is Truediff --git a/tests/_server/test_server_registry.py b/tests/_server/test_server_registry.pynew file mode 100644index 0000000000..679a259ed6--- /dev/null+++ b/tests/_server/test_server_registry.py@@ -0,0 +1,128 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import json+import os+import sys+from dataclasses import asdict+from typing import TYPE_CHECKING+from unittest.mock import patch++import pytest++from marimo._server.server_registry import (+ ServerRegistryEntry,+ ServerRegistryWriter,+)++if TYPE_CHECKING:+ from pathlib import Path+++def _make_entry(+ *,+ port: int = 2718,+ host: str = "localhost",+ pid: int | None = None,+) -> ServerRegistryEntry:+ return ServerRegistryEntry(+ server_id=f"{host}:{port}",+ pid=pid or os.getpid(),+ host=host,+ port=port,+ base_url="",+ started_at="2026-01-01T00:00:00+00:00",+ version="0.0.0",+ )+++def _patch_servers_dir(tmp_path: Path):+ return patch(+ "marimo._server.server_registry._servers_dir",+ return_value=tmp_path,+ )+++# --- Writer round-trip ---+++def test_round_trip(tmp_path: Path):+ entry = _make_entry()+ with _patch_servers_dir(tmp_path):+ writer = ServerRegistryWriter(entry)+ writer.register()++ files = list(tmp_path.glob("*.json"))+ assert len(files) == 1+ data = json.loads(files[0].read_text())+ assert data == asdict(entry)++ writer.deregister()+ assert list(tmp_path.glob("*.json")) == []+++def test_deregister_is_idempotent(tmp_path: Path):+ entry = _make_entry()+ with _patch_servers_dir(tmp_path):+ writer = ServerRegistryWriter(entry)+ writer.register()+ writer.deregister()+ writer.deregister() # should not raise+ assert list(tmp_path.glob("*.json")) == []++[email protected](sys.platform == "win32", reason="Unix file permissions")+def test_file_permissions(tmp_path: Path):+ entry = _make_entry()+ with _patch_servers_dir(tmp_path):+ writer = ServerRegistryWriter(entry)+ writer.register()++ files = list(tmp_path.glob("*.json"))+ assert len(files) == 1+ assert oct(files[0].stat().st_mode & 0o777) == "0o600"++ writer.deregister()+++def test_multiple_entries(tmp_path: Path):+ e1 = _make_entry(port=2718)+ e2 = _make_entry(port=2719)+ with _patch_servers_dir(tmp_path):+ w1 = ServerRegistryWriter(e1)+ w2 = ServerRegistryWriter(e2)+ w1.register()+ w2.register()++ files = list(tmp_path.glob("*.json"))+ assert len(files) == 2++ w1.deregister()+ w2.deregister()+++# --- from_server ---+++def test_from_server():+ entry = ServerRegistryEntry.from_server(+ host="localhost",+ port=2718,+ base_url="",+ )+ assert entry.server_id == "localhost:2718"+ assert entry.pid == os.getpid()+ assert entry.host == "localhost"+ assert entry.port == 2718+ assert entry.base_url == ""+ assert entry.version # non-empty+++def test_from_server_with_base_url():+ entry = ServerRegistryEntry.from_server(+ host="0.0.0.0",+ port=8080,+ base_url="/prefix",+ )+ assert entry.server_id == "0.0.0.0:8080"+ assert entry.base_url == "/prefix"