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.

Serve the host protocol from `marimo edit` (#11180)

Trevor Manz060703cd4f53
diff --git a/frontend/src/core/islands/bootstrap.ts b/frontend/src/core/islands/bootstrap.ts
index 0292cd0682..0267d9c9f5 100644
--- a/frontend/src/core/islands/bootstrap.ts
+++ b/frontend/src/core/islands/bootstrap.ts
@@ -283,6 +283,7 @@ function handleMessage(
return;
case "consumer-capabilities":
+ case "execution":
return;
default:
logNever(msg);
diff --git a/frontend/src/core/websocket/useMarimoKernelConnection.tsx b/frontend/src/core/websocket/useMarimoKernelConnection.tsx
index 601a9e0f58..67e11422a5 100644
--- a/frontend/src/core/websocket/useMarimoKernelConnection.tsx
+++ b/frontend/src/core/websocket/useMarimoKernelConnection.tsx
@@ -304,6 +304,8 @@ export function useMarimoKernelConnection(opts: {
case "completed-run":
setInitialRunCompleted(true);
return;
+ case "execution":
+ return;
case "interrupted":
return;
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.py
index 1f9f62d92f..14e050d6c3 100644
--- a/marimo/_core/protocol.py
+++ b/marimo/_core/protocol.py
@@ -7,7 +7,7 @@
from __future__ import annotations
from datetime import datetime
-from typing import TYPE_CHECKING, Annotated, Literal, NewType, TypeAlias
+from typing import TYPE_CHECKING, Annotated, Any, Literal, NewType, TypeAlias
from msgspec import UNSET, Meta, Struct, UnsetType
@@ -48,11 +48,67 @@ class Binding(Struct):
)
+class CellConfig(Struct):
+ column: (
+ Annotated[
+ int,
+ Meta(
+ description="The column the cell sits in, for multi-column layouts. Null in a single column."
+ ),
+ ]
+ | None
+ )
+ disabled: Annotated[
+ bool, Meta(description="Whether the cell is kept from running.")
+ ]
+ expand_output: Annotated[
+ bool,
+ Meta(
+ description="Whether clients show the full output rather than a scrolled box."
+ ),
+ ]
+ hide_code: Annotated[
+ bool, Meta(description="Whether clients hide the code by default.")
+ ]
+
+
+class CellConfigInput(Struct):
+ column: int | UnsetType | None = UNSET
+ disabled: bool | UnsetType = False
+ expand_output: bool | UnsetType = False
+ hide_code: bool | UnsetType = False
+
+
+class CellInput(Struct):
+ code: Annotated[str, Meta(description="The cell's source code.")]
+ id: Annotated[
+ str,
+ Meta(
+ description="The cell's id. A client chooses the id of a cell it creates."
+ ),
+ ]
+ config: CellConfigInput | UnsetType = UNSET
+ name: (
+ Annotated[
+ str,
+ Meta(description="The cell's name. `_` for an anonymous cell."),
+ ]
+ | UnsetType
+ ) = "_"
+
+
class DecisionOption(Struct):
id: Annotated[str, Meta(description="Identifies this answer.")]
label: Annotated[str, Meta(description="Text to show a person.")]
+class DeleteCell(Struct, tag_field="kind", tag="delete_cell"):
+ base_etag: Annotated[
+ str, Meta(description="The cell's etag as last read, or `*`.")
+ ]
+ id: Annotated[str, Meta(description="The cell to remove.")]
+
+
class DisplayData(Struct):
data: Annotated[
str,
@@ -68,6 +124,14 @@ class DisplayData(Struct):
]
+Etag: TypeAlias = Annotated[
+ str,
+ Meta(
+ description="An identifier derived from content, so that every host, kernel,\nand store computes the same value for the same state. It is the\nfirst 16 hexadecimal characters, in lower case, of SHA-256 over\nthe UTF-8 encoding of a canonical text. Each etag says what its\ntext is; a text made of several values is those values joined by\nnewlines. Clients do not compute etags. They read them from the\nstream and from responses, and send them back as preconditions.\n"
+ ),
+]
+
+
if TYPE_CHECKING:
ExecutionId = NewType("ExecutionId", str)
else:
@@ -161,6 +225,8 @@ ObjectType: TypeAlias = Annotated[
"host",
"project",
"notebook",
+ "document",
+ "cell",
"runtime",
"attachment",
"run",
@@ -169,7 +235,7 @@ ObjectType: TypeAlias = Annotated[
"display",
],
Meta(
- description="The kinds a stream carries, and the values `types` accepts. The\ncatalog stream carries host, project, notebook, runtime, and\nattachment. A notebook's stream carries notebook, runtime,\nattachment, run, execution, console, and display.\n"
+ description="The kinds a stream carries, and the values `types` accepts. The\ncatalog stream carries host, project, notebook, runtime, and\nattachment. A notebook's stream carries notebook, document, cell,\nruntime, attachment, run, execution, console, and display.\n"
),
]
@@ -226,6 +292,37 @@ ProjectStatus: TypeAlias = Annotated[
]
+class PutCell(Struct, tag_field="kind", tag="put_cell"):
+ base_etag: (
+ Annotated[
+ str,
+ Meta(
+ description="The cell's etag as last read, `*` to skip the check, or null to create the cell. Null when the cell exists, or an etag when it does not, is a `conflict`."
+ ),
+ ]
+ | None
+ )
+ cell: CellInput
+ after: (
+ Annotated[
+ str,
+ Meta(
+ description="The cell a created cell goes after. Ignored for an existing cell."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ before: (
+ Annotated[
+ str,
+ Meta(
+ description="The cell a created cell goes before. Ignored for an existing cell. With neither `after` nor `before`, a created cell goes at the end."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
class Range(Struct):
end: Annotated[
Position,
@@ -326,6 +423,43 @@ RuntimeStatus: TypeAlias = Annotated[
]
+class SaveRequest(Struct):
+ decisions: (
+ Annotated[
+ dict[str, str],
+ Meta(
+ description="Answers to the questions in a `decision-required` problem, as for `runtime.start`."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class SetAppConfig(Struct, tag_field="kind", tag="set_app_config"):
+ app_config: Annotated[
+ dict[str, Any], Meta(description="The new app config, whole.")
+ ]
+ base_etag: Annotated[
+ str,
+ Meta(
+ description="The document's `app_config_etag` as last read, or `*`."
+ ),
+ ]
+
+
+class SetOrder(Struct, tag_field="kind", tag="set_order"):
+ base_etag: Annotated[
+ str,
+ Meta(description="The document's `order_etag` as last read, or `*`."),
+ ]
+ order: Annotated[
+ list[str],
+ Meta(
+ description="Every cell id exactly once, in the new order, counting cells this edit creates and leaving out cells it deletes."
+ ),
+ ]
+
+
class StartRuntimeRequest(Struct):
decisions: (
Annotated[
@@ -409,6 +543,17 @@ class AttachmentMessage(Struct):
) = UNSET
+class CellEtags(Struct):
+ code_hash: Etag
+ etag: Etag
+
+
+Change: TypeAlias = Annotated[
+ PutCell | DeleteCell | SetOrder | SetAppConfig,
+ Meta(description="One change to the document, tagged on `kind`."),
+]
+
+
class Console(Struct):
execution_id: ExecutionId
id: ItemId
@@ -528,11 +673,101 @@ class DisplayMessage(Struct):
) = UNSET
+class Document(Struct):
+ app_config: Annotated[
+ dict[str, Any],
+ Meta(
+ description="Notebook-level settings, the keyword arguments to `marimo.App` such as `width` and `title`."
+ ),
+ ]
+ app_config_etag: Annotated[
+ Etag,
+ Meta(
+ description="Identifies the app config alone. Its text is the app config as canonical JSON, with keys sorted by code point, no whitespace, and strings carrying only the escapes JSON requires."
+ ),
+ ]
+ etag: Annotated[
+ Etag,
+ Meta(
+ description="Identifies the document as currently applied. Its text is `order_etag`, `app_config_etag`, and every cell's `etag` in order, so it changes when any of them does."
+ ),
+ ]
+ id: Annotated[
+ NotebookId, Meta(description="The notebook this document belongs to.")
+ ]
+ order: Annotated[
+ list[str],
+ Meta(
+ description="Cell ids in display order. A permutation of the notebook's cells, each appearing exactly once."
+ ),
+ ]
+ order_etag: Annotated[
+ Etag,
+ Meta(
+ description="Identifies the order alone. Its text is the cell ids in order. Editing a cell does not change it."
+ ),
+ ]
+ policy: Annotated[
+ Literal["autorun", "lazy"],
+ Meta(
+ description="When dependents of an evaluated cell run. `autorun` runs them on every change; `lazy` marks them stale and runs them when asked. Set by the host."
+ ),
+ ]
+ saved_etag: (
+ Annotated[
+ Etag,
+ Meta(
+ description="Identifies the document as last written to the host's store, computed the same way over that state. Equal to `etag` when every accepted change has been persisted. Null when nothing has been persisted, which is the case for a scratch copy."
+ ),
+ ]
+ | None
+ )
+
+
+class DocumentMessage(Struct):
+ document: Document
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class EditRequest(Struct):
+ changes: Annotated[
+ list[Change],
+ Meta(description="The changes, applied in order as one unit."),
+ ]
+
+
+class EditResponse(Struct):
+ cells: Annotated[
+ dict[str, CellEtags | None],
+ Meta(
+ description="The etags of each cell the request created or changed, by id, and null for each cell it deleted."
+ ),
+ ]
+ document: Document
+
+
class Error(Struct):
kind: Annotated[
str,
Meta(
- description="The producer's identifier, scoped by source. Open; this RFC defines `exception`, `interrupted`, and `internal`. Clients show unrecognized kinds as plain errors."
+ description="The producer's identifier, scoped by source. Open; this protocol defines `exception`, `interrupted`, and `internal` for executions, and reserves `multiple-definitions` and `cycle-dependencies` for analysis, because every host schedules them the same way. Clients show unrecognized kinds as plain errors."
),
]
message: Annotated[
@@ -627,7 +862,7 @@ class Notebook(Struct):
operations: Annotated[
list[str],
Meta(
- description="Operations this client may call on the notebook. A subset of `host.operations`, narrowed by permission and never by state; whether a runtime is attached shows in the `runtime` object, and preconditions still apply when an operation is called. The host sends the notebook again when it changes."
+ description="Operations this client may call on the notebook, such as `notebook.edit` or `runtime.start`. A subset of `host.operations`, narrowed by permission and never by state; whether a runtime is attached shows in the `runtime` object, and preconditions still apply when an operation is called. The host sends the notebook again when it changes."
),
]
path: (
@@ -681,45 +916,6 @@ Outcome: TypeAlias = Annotated[
]
-class Problem(Struct):
- status: Annotated[
- int,
- Meta(
- description="The HTTP status code of the response.", ge=400, le=599
- ),
- ]
- title: Annotated[
- str,
- Meta(
- description="A short, human-readable name for the kind of problem."
- ),
- ]
- type: Annotated[
- str,
- Meta(
- description="What kind of problem this is, as a URI. The kinds this\nprotocol defines all start with `tag:marimo.io,2026:host/` and\nend with one of `invalid-request` (400), `unauthorized` (401),\n`forbidden` (403), `not-found` (404), `not-acceptable` (406),\n`conflict` (409), `no-runtime` (409), `decision-required`\n(409), `internal` (500), or `unsupported-operation` (501). A\nclient that sees a kind it does not recognize falls back to\n`status`.\n"
- ),
- ]
- decisions: (
- Annotated[
- list[Decision],
- Meta(
- description="The choices the client has to make before the host can carry out the request. Only present for `decision-required`."
- ),
- ]
- | UnsetType
- ) = UNSET
- detail: (
- Annotated[
- str,
- Meta(
- description="A human-readable explanation of what went wrong this time."
- ),
- ]
- | UnsetType
- ) = UNSET
-
-
class Project(Struct):
id: ProjectId
message: (
@@ -895,6 +1091,105 @@ class RuntimeMessage(Struct):
) = UNSET
+class Analysis(Struct):
+ defs: Annotated[list[str], Meta(description="Names this cell defines.")]
+ errors: Annotated[
+ list[Error],
+ Meta(
+ description="Diagnostics about the code. Only an `error` affects scheduling. `multiple-definitions` lists the definers in `related`, each `range` at its definition; `cycle-dependencies` lists the cycle. Both are reported on every cell involved, differing only in `range`. Every other kind belongs to the analyzer named in `source`."
+ ),
+ ]
+ refs: Annotated[
+ list[str], Meta(description="Names this cell reads from other cells.")
+ ]
+
+
+class Cell(Struct):
+ analysis: (
+ Annotated[
+ Analysis,
+ Meta(
+ description="Derived from the code by the host. Null when the host has no analyzer."
+ ),
+ ]
+ | None
+ )
+ code: Annotated[
+ str,
+ Meta(
+ description="The cell's source code, with newline line endings. A host normalizes other line endings when it loads a file."
+ ),
+ ]
+ code_hash: Annotated[
+ Etag,
+ Meta(
+ description="Identifies the code alone. Its text is `code`. Unchanged by renaming the cell or editing its config. Compare with an execution's `code_hash` to tell whether a result came from the current code."
+ ),
+ ]
+ config: CellConfig
+ etag: Annotated[
+ Etag,
+ Meta(
+ description="Identifies code, name, and config together, and is the precondition for editing the cell. Its text is `code_hash`, `name`, and the config values `column`, `disabled`, `hide_code`, and `expand_output` in that order, each written as a JSON scalar such as `null`, `0`, or `true`."
+ ),
+ ]
+ id: Annotated[
+ str,
+ Meta(
+ description="Identifies the cell within its notebook. Stable while the host serves the notebook; whether it survives a reload of the store depends on the format. `setup` is the setup cell."
+ ),
+ ]
+ name: Annotated[
+ str,
+ Meta(
+ description="The cell's name. `_` for an anonymous cell; otherwise a Python identifier, unique within the notebook."
+ ),
+ ]
+ notebook_id: NotebookId
+
+
+class CellMessage(Struct):
+ cell: Cell
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
+class EditConflict(Struct):
+ cell: (
+ Annotated[
+ Cell,
+ Meta(
+ description="The cell the change named, as it now is. Null when it no longer exists, or when the change named the order or the app config."
+ ),
+ ]
+ | None
+ )
+ change: Annotated[
+ int,
+ Meta(
+ description="The index of the stale change in the request's `changes`. `0` for a save with a stale `If-Match`.",
+ ge=0,
+ ),
+ ]
+ document: Document
+
+
class Execution(Struct):
bindings: Annotated[
list[Binding],
@@ -930,7 +1225,10 @@ class Execution(Struct):
| None
)
code_hash: Annotated[
- str, Meta(description="A hash of the code that was evaluated.")
+ Etag,
+ Meta(
+ description="The `code_hash` of the code that was evaluated, computed as a cell's is."
+ ),
]
completed_at: (
Annotated[
@@ -1010,3 +1308,51 @@ class ExecutionMessage(Struct):
]
| UnsetType
) = UNSET
+
+
+class Problem(Struct):
+ status: Annotated[
+ int,
+ Meta(
+ description="The HTTP status code of the response.", ge=400, le=599
+ ),
+ ]
+ title: Annotated[
+ str,
+ Meta(
+ description="A short, human-readable name for the kind of problem."
+ ),
+ ]
+ type: Annotated[
+ str,
+ Meta(
+ description="What kind of problem this is, as a URI. The kinds this\nprotocol defines all start with `tag:marimo.io,2026:host/` and\nend with one of `invalid-request` (400), `unauthorized` (401),\n`forbidden` (403), `not-found` (404), `not-acceptable` (406),\n`conflict` (409), `no-runtime` (409), `decision-required`\n(409), `internal` (500), or `unsupported-operation` (501). A\nclient that sees a kind it does not recognize falls back to\n`status`.\n"
+ ),
+ ]
+ decisions: (
+ Annotated[
+ list[Decision],
+ Meta(
+ description="The choices the client has to make before the host can carry out the request. Only present for `decision-required`."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ detail: (
+ Annotated[
+ str,
+ Meta(
+ description="A human-readable explanation of what went wrong this time."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ edit: (
+ Annotated[
+ EditConflict,
+ Meta(
+ description="Which change was stale and what the host holds instead. Only present for a `conflict` answering an edit or a save."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
diff --git a/marimo/_messaging/console_output_worker.py b/marimo/_messaging/console_output_worker.py
index 47d532570e..7345e15048 100644
--- a/marimo/_messaging/console_output_worker.py
+++ b/marimo/_messaging/console_output_worker.py
@@ -7,6 +7,7 @@ from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Literal
from marimo._messaging.cell_output import CellChannel, CellOutput
+from marimo._messaging.context import RUN_ID_CTX, execution_id_for
from marimo._messaging.mimetypes import ConsoleMimeType
from marimo._types.ids import CellId_t
@@ -28,6 +29,12 @@ class ConsoleMsg:
cell_id: CellId_t
data: str
mimetype: ConsoleMimeType
+ run_id: str | None = field(default_factory=lambda: RUN_ID_CTX.get(None))
+ execution_id: str | None = None
+
+ def __post_init__(self) -> None:
+ if self.execution_id is None:
+ self.execution_id = execution_id_for(self.cell_id)
@dataclass
@@ -43,6 +50,8 @@ def _write_console_output(
cell_id: CellId_t,
data: str,
mimetype: ConsoleMimeType,
+ run_id: str | None = None,
+ execution_id: str | None = None,
) -> None:
from marimo._messaging.notification import CellNotification
from marimo._messaging.notification_utils import broadcast_notification
@@ -50,6 +59,8 @@ def _write_console_output(
broadcast_notification(
CellNotification(
cell_id=cell_id,
+ run_id=run_id,
+ execution_id=execution_id,
console=CellOutput(
channel=stream_type,
mimetype=mimetype,
@@ -61,7 +72,12 @@ def _write_console_output(
def _can_merge_outputs(first: ConsoleMsg, second: ConsoleMsg) -> bool:
- return first.stream == second.stream and first.mimetype == second.mimetype
+ return (
+ first.stream == second.stream
+ and first.mimetype == second.mimetype
+ and first.run_id == second.run_id
+ and first.execution_id == second.execution_id
+ )
def _add_output_to_buffer(
@@ -90,6 +106,8 @@ def _flush_outputs(
cell_id,
output.data,
output.mimetype,
+ output.run_id,
+ output.execution_id,
)
outputs_buffered_per_cell.clear()
diff --git a/marimo/_messaging/context.py b/marimo/_messaging/context.py
index dec33d97b2..071043c7d4 100644
--- a/marimo/_messaging/context.py
+++ b/marimo/_messaging/context.py
@@ -11,6 +11,24 @@ from marimo._runtime.commands import HTTPRequest
RunId_t = str
RUN_ID_CTX = ContextVar[RunId_t | None]("run_id")
+
+@dataclass(frozen=True)
+class ExecutionTag:
+ """The evaluation producing a cell's notifications."""
+
+ id: str
+ cell_id: str
+ run_id: str | None = None
+
+
+EXECUTION_CTX = ContextVar[ExecutionTag | None]("execution", default=None)
+
+
+def execution_id_for(cell_id: str) -> str | None:
+ execution = EXECUTION_CTX.get()
+ return execution.id if execution and execution.cell_id == cell_id else None
+
+
HTTP_REQUEST_CTX = ContextVar[HTTPRequest | None]("http_request")
@@ -20,8 +38,8 @@ class run_id_context:
run_id: RunId_t
- def __init__(self) -> None:
- self.run_id = str(uuid.uuid4())
+ def __init__(self, run_id: RunId_t | None = None) -> None:
+ self.run_id = run_id if run_id is not None else str(uuid.uuid4())
def __enter__(self) -> None:
self.token = RUN_ID_CTX.set(self.run_id)
@@ -30,6 +48,26 @@ class run_id_context:
RUN_ID_CTX.reset(self.token)
+@dataclass
+class execution_id_context:
+ """Identify one evaluation, including its buffered and background output."""
+
+ cell_id: str
+ id: str | None = None
+
+ def __enter__(self) -> None:
+ self.token = EXECUTION_CTX.set(
+ ExecutionTag(
+ self.id or str(uuid.uuid4()),
+ self.cell_id,
+ RUN_ID_CTX.get(None),
+ )
+ )
+
+ def __exit__(self, *_: object) -> None:
+ EXECUTION_CTX.reset(self.token)
+
+
@dataclass
class http_request_context:
"""Context manager for setting and unsetting the HTTP request."""
diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.py
index 629e5a98f3..665fd76ea4 100644
--- a/marimo/_messaging/notification.py
+++ b/marimo/_messaging/notification.py
@@ -32,7 +32,7 @@ from marimo._data.models import (
from marimo._dependencies.dependencies import DependencyManager
from marimo._messaging.cell_output import CellOutput
from marimo._messaging.completion_option import CompletionOption
-from marimo._messaging.context import RUN_ID_CTX, RunId_t
+from marimo._messaging.context import RUN_ID_CTX, RunId_t, execution_id_for
from marimo._messaging.notebook.changes import Transaction
from marimo._plugins.core.web_component import JSONType
from marimo._runtime.layout.layout import LayoutConfig
@@ -85,6 +85,24 @@ class Notification(msgspec.Struct, tag_field="op"):
name: ClassVar[str]
+class ExecutionNotification(Notification, tag="execution"):
+ """An attempt's lifecycle, independent of a cell's displayed status.
+
+ `planned` supplies the source and identity before output is reported.
+ `running` means evaluation began. `completed` follows the final output
+ and errors, including for attempts that never ran. Buffered and background
+ console output may still arrive with the completed attempt's identity.
+ """
+
+ name: ClassVar[str] = "execution"
+ execution_id: str
+ cell_id: CellId_t
+ run_id: str | None
+ phase: Literal["planned", "running", "completed"]
+ code: str | None = None
+ caused_by: str | None = None
+
+
class CellNotification(Notification, tag="cell-op"):
"""Updates a cell's state in the frontend.
@@ -100,6 +118,7 @@ class CellNotification(Notification, tag="cell-op"):
status: Execution status (idle/running/stale/queued/disabled-transitively).
stale_inputs: Whether cell has stale inputs from changed dependencies.
run_id: Execution run ID for tracing. Auto-set from context.
+ execution_id: Evaluation of this cell producing the update, when known.
serialization: Top-level reusability hint. UNSET unchanged, None clears, str sets.
timestamp: Creation timestamp, auto-set.
"""
@@ -111,6 +130,7 @@ class CellNotification(Notification, tag="cell-op"):
status: RuntimeStateType | None = None
stale_inputs: bool | None = None
run_id: RunId_t | None = None
+ execution_id: str | None = None
# Tri-state partial update: UNSET (omitted on the wire) leaves the cell's
# serialization hint unchanged; None explicitly clears it (cell is no
# longer a top-level definition); a string sets it.
@@ -118,14 +138,11 @@ class CellNotification(Notification, tag="cell-op"):
timestamp: float = msgspec.field(default_factory=lambda: time.time())
def __post_init__(self) -> None:
+ if self.execution_id is None:
+ self.execution_id = execution_id_for(self.cell_id)
if self.run_id is not None:
return
- # We currently don't support tracing for replayed cell ops (previous session runs)
- if self.status == "idle":
- self.run_id = None
- return
-
try:
self.run_id = RUN_ID_CTX.get()
except LookupError:
@@ -329,21 +346,18 @@ class InterruptedNotification(Notification, tag="interrupted"):
"""Kernel was interrupted by user (SIGINT/Ctrl+C)."""
name: ClassVar[str] = "interrupted"
+ run_id: str | None = msgspec.field(
+ default_factory=lambda: RUN_ID_CTX.get(None)
+ )
class CompletedRunNotification(Notification, tag="completed-run"):
- """Run of submitted cells and descendants completed.
-
- Attributes:
- run_id: Correlation ID echoed from the command that triggered
- this completion. `None` for handlers that don't take a
- `run_id` (everything except `handle_execute_scratchpad`
- today). Consumers that want to wait for a specific command's
- completion filter on this field.
- """
+ """The command's reactive cycle ended, after its console was flushed."""
name: ClassVar[str] = "completed-run"
run_id: str | None = None
+ outcome: Literal["succeeded", "failed", "interrupted"] = "succeeded"
+ error: str | None = None
class KernelCapabilitiesNotification(msgspec.Struct):
@@ -1092,6 +1106,7 @@ class NotebookDocumentTransactionNotification(
NotificationMessage = (
# Cell operations
CellNotification
+ | ExecutionNotification
| FunctionCallResultNotification
| UIElementMessageNotification
| ModelLifecycleNotification
diff --git a/marimo/_messaging/notification_utils.py b/marimo/_messaging/notification_utils.py
index 267dcdb109..d2e79fbf06 100644
--- a/marimo/_messaging/notification_utils.py
+++ b/marimo/_messaging/notification_utils.py
@@ -217,6 +217,7 @@ class CellNotificationUtils:
data: Sequence[Error],
clear_console: bool,
cell_id: CellId_t,
+ execution_id: str | None = None,
) -> None:
# Import here to avoid circular dependency
from marimo._messaging.notification import CellNotification
@@ -267,6 +268,7 @@ class CellNotificationUtils:
output=CellOutput.errors(safe_errors),
console=console,
status=None,
+ execution_id=execution_id,
)
)
diff --git a/marimo/_runtime/commands.py b/marimo/_runtime/commands.py
index 44d36705a0..67e87b55a8 100644
--- a/marimo/_runtime/commands.py
+++ b/marimo/_runtime/commands.py
@@ -394,6 +394,8 @@ class ExecuteScratchpadCommand(Command):
`ScratchCellListener` can filter for *its* completion and
ignore `CompletedRun` events from unrelated commands on the
same session.
+ allow_stdin: Whether code may request interactive input. When false,
+ input reads receive EOF for the duration of this command.
"""
code: str
@@ -404,6 +406,7 @@ class ExecuteScratchpadCommand(Command):
# Output snapshot — set by the execution endpoint from session.session_view.
cell_outputs: CellOutputs | None = None
run_id: str | None = None
+ allow_stdin: bool = True
class RenameNotebookCommand(Command):
diff --git a/marimo/_runtime/execution.py b/marimo/_runtime/execution.py
new file mode 100644
index 0000000000..261b87d3b5
--- /dev/null
+++ b/marimo/_runtime/execution.py
@@ -0,0 +1,76 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Execution attempts reported by the kernel.
+
+An attempt has one identity from planning through completion, even when
+compilation fails or the cell is skipped. Output keeps that identity after
+completion, so a background thread cannot write into a later attempt.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+from uuid import uuid4
+
+from marimo._messaging.context import (
+ EXECUTION_CTX,
+ RUN_ID_CTX,
+ execution_id_context,
+)
+from marimo._messaging.notification import ExecutionNotification
+from marimo._messaging.notification_utils import broadcast_notification
+from marimo._runtime.context.utils import get_mode
+from marimo._types.ids import CellId_t
+
+
+@dataclass
+class ExecutionAttempt:
+ """One planned evaluation of a cell, including its output identity."""
+
+ cell_id: CellId_t
+ id: str = field(default_factory=lambda: str(uuid4()))
+ run_id: str | None = field(default_factory=lambda: RUN_ID_CTX.get(None))
+ completed: bool = False
+
+ @classmethod
+ def plan(cls, cell_id: CellId_t, code: str) -> ExecutionAttempt:
+ attempt = cls(cell_id)
+ parent = EXECUTION_CTX.get()
+ broadcast_notification(
+ ExecutionNotification(
+ execution_id=attempt.id,
+ cell_id=cell_id,
+ run_id=attempt.run_id,
+ phase="planned",
+ code=code if get_mode() != "run" else None,
+ caused_by=(
+ parent.id
+ if parent is not None and parent.run_id == attempt.run_id
+ else None
+ ),
+ )
+ )
+ return attempt
+
+ def activate(self) -> execution_id_context:
+ """Attribute output in this context to the attempt."""
+ return execution_id_context(self.cell_id, self.id)
+
+ def start(self) -> None:
+ self._notify("running")
+
+ def finish(self) -> None:
+ """Complete the attempt after its output and errors are reported."""
+ if not self.completed:
+ self.completed = True
+ self._notify("completed")
+
+ def _notify(self, phase: Literal["running", "completed"]) -> None:
+ broadcast_notification(
+ ExecutionNotification(
+ execution_id=self.id,
+ cell_id=self.cell_id,
+ run_id=self.run_id,
+ phase=phase,
+ )
+ )
diff --git a/marimo/_runtime/kernel_request_handlers.py b/marimo/_runtime/kernel_request_handlers.py
index c2cf3a69ba..db78ae96cd 100644
--- a/marimo/_runtime/kernel_request_handlers.py
+++ b/marimo/_runtime/kernel_request_handlers.py
@@ -1,10 +1,17 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from typing import TYPE_CHECKING
+import asyncio
+import contextlib
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
from marimo import _loggers
-from marimo._messaging.context import http_request_context
+from marimo._messaging.context import (
+ http_request_context,
+ run_id_context,
+)
from marimo._messaging.notebook.document import (
NotebookDocument,
notebook_document_context,
@@ -32,15 +39,34 @@ from marimo._runtime.commands import (
UpdateUIElementCommand,
UpdateUserConfigCommand,
)
+from marimo._runtime.context import safe_get_context
+from marimo._runtime.context.kernel_context import KernelRuntimeContext
+from marimo._runtime.redirect_streams import stdin_context
from marimo._types.ids import UIElementId
if TYPE_CHECKING:
+ from collections.abc import Iterator
+
from marimo._runtime.request_router import RequestRouter
from marimo._runtime.runtime import Kernel
LOGGER = _loggers.marimo_logger()
+@dataclass
+class _CommandCycle:
+ run_id: str
+ owner: asyncio.Task[object] | None
+ active: bool = True
+ outcome: Literal["succeeded", "failed", "interrupted"] = "succeeded"
+ error: str | None = None
+
+
+_COMMAND_CYCLE: ContextVar[_CommandCycle | None] = ContextVar(
+ "command_cycle", default=None
+)
+
+
class KernelRequestHandlers:
"""Kernel-owned command handlers.
@@ -52,9 +78,8 @@ class KernelRequestHandlers:
self._kernel = kernel
def register(self, router: RequestRouter) -> None:
- k = self._kernel
router.register(CreateNotebookCommand, self._handle_instantiate)
- router.register(DeleteCellCommand, k.delete_cell)
+ router.register(DeleteCellCommand, self._handle_delete_cell)
router.register(ExecuteCellsCommand, self._handle_execute_multiple)
router.register(SyncGraphCommand, self._handle_sync_graph)
router.register(
@@ -64,7 +89,7 @@ class KernelRequestHandlers:
router.register(InvokeFunctionCommand, self._handle_function_call)
router.register(DebugCellCommand, self._handle_pdb_request)
router.register(RenameNotebookCommand, self._handle_rename)
- router.register(UpdateCellConfigCommand, k.set_cell_config)
+ router.register(UpdateCellConfigCommand, self._handle_cell_config)
router.register(
UpdateUIElementCommand, self._handle_set_ui_element_value
)
@@ -72,26 +97,88 @@ class KernelRequestHandlers:
router.register(UpdateUserConfigCommand, self._handle_set_user_config)
router.register(StopKernelCommand, self._handle_stop)
+ @contextlib.contextmanager
+ def _run_context(self, run_id: str | None = None) -> Iterator[None]:
+ """Own one command's propagation through its final notification."""
+ parent = _COMMAND_CYCLE.get()
+ owner = asyncio.current_task()
+ runtime_context = safe_get_context()
+ scheduler = (
+ runtime_context.active_scheduler
+ if isinstance(runtime_context, KernelRuntimeContext)
+ else None
+ )
+ # Copied context is provenance, not ownership. Only this task and
+ # evaluations awaited by the reactive scheduler can extend the cycle.
+ if (
+ parent is not None
+ and parent.active
+ and (
+ parent.owner is owner
+ or scheduler is not None
+ and scheduler.owns_task(owner)
+ )
+ ):
+ cycle, nested = parent, True
+ context = run_id_context(parent.run_id)
+ else:
+ context = run_id_context(run_id)
+ cycle, nested = _CommandCycle(context.run_id, owner), False
+ token = _COMMAND_CYCLE.set(cycle)
+ try:
+ with context:
+ try:
+ yield
+ except BaseException as exc:
+ if isinstance(
+ exc, (KeyboardInterrupt, asyncio.CancelledError)
+ ):
+ cycle.outcome = "interrupted"
+ elif cycle.outcome != "interrupted":
+ cycle.outcome = "failed"
+ cycle.error = str(exc) or type(exc).__name__
+ raise
+ finally:
+ if not nested:
+ cycle.active = False
+ self._kernel.stream.flush_console()
+ broadcast_notification(
+ CompletedRunNotification(
+ run_id=cycle.run_id,
+ outcome=cycle.outcome,
+ error=cycle.error,
+ )
+ )
+ finally:
+ _COMMAND_CYCLE.reset(token)
+
+ async def _handle_delete_cell(self, request: DeleteCellCommand) -> None:
+ with self._run_context():
+ await self._kernel.delete_cell(request)
+
+ async def _handle_cell_config(
+ self, request: UpdateCellConfigCommand
+ ) -> None:
+ with self._run_context():
+ await self._kernel.set_cell_config(request)
+
async def _handle_instantiate(
self, request: CreateNotebookCommand
) -> None:
- with http_request_context(request.request):
+ with self._run_context(), http_request_context(request.request):
await self._kernel.instantiate(request)
- broadcast_notification(CompletedRunNotification())
async def _handle_execute_multiple(
self, request: ExecuteCellsCommand
) -> None:
- with http_request_context(request.request):
+ with self._run_context(), http_request_context(request.request):
await self._kernel.run(request.execution_requests)
- broadcast_notification(CompletedRunNotification())
async def _handle_sync_graph(self, request: SyncGraphCommand) -> None:
- with http_request_context(None):
+ with self._run_context(), http_request_context(None):
await self._kernel.sync_graph(
request.cells, request.run_ids, request.delete_ids
)
- broadcast_notification(CompletedRunNotification())
async def _handle_execute_scratchpad(
self, request: ExecuteScratchpadCommand
@@ -101,82 +188,78 @@ class KernelRequestHandlers:
if request.notebook_cells is not None
else None
)
- try:
- with (
- notebook_document_context(doc),
- notebook_outputs_context(request.cell_outputs),
- http_request_context(request.request),
- ):
- await self._kernel.run_scratchpad(request.code)
- finally:
- # Always emit completion so a waiting `ScratchCellListener`
- # doesn't block forever if `run_scratchpad` raises.
- broadcast_notification(
- CompletedRunNotification(run_id=request.run_id)
- )
+ with (
+ self._run_context(request.run_id),
+ stdin_context(request.allow_stdin),
+ notebook_document_context(doc),
+ notebook_outputs_context(request.cell_outputs),
+ http_request_context(request.request),
+ ):
+ await self._kernel.run_scratchpad(request.code)
async def _handle_execute_stale(
self, request: ExecuteStaleCellsCommand
) -> None:
- with http_request_context(request.request):
+ with self._run_context(), http_request_context(request.request):
await self._kernel.run_stale_cells()
- broadcast_notification(CompletedRunNotification())
async def _handle_set_ui_element_value(
self, request: UpdateUIElementCommand
) -> None:
- with http_request_context(request.request):
+ with self._run_context(), http_request_context(request.request):
await self._kernel.set_ui_element_value(
request, notify_frontend=False
)
- broadcast_notification(CompletedRunNotification())
async def _handle_pdb_request(self, request: DebugCellCommand) -> None:
await self._kernel.pdb_request(request.cell_id)
async def _handle_rename(self, request: RenameNotebookCommand) -> None:
- await self._kernel.rename_file(request.filename)
+ with self._run_context():
+ await self._kernel.rename_file(request.filename)
async def _handle_receive_model_message(
self, request: ModelCommand
) -> None:
- ui_element_id, state = WIDGET_COMM_MANAGER.receive_comm_message(
- request
- )
-
- # Directly handle the UI element update instead of
- # re-enqueuing it as a separate command. Re-enqueuing
- # caused Model+UI interleaving that the batch merger
- # couldn't collapse (different types), leading to every
- # drag tick getting its own full cell re-execution.
- if ui_element_id and state:
- await self._kernel.set_ui_element_value(
- UpdateUIElementCommand.from_ids_and_values(
- [(UIElementId(ui_element_id), state)]
- ),
- notify_frontend=False,
+ with self._run_context():
+ ui_element_id, state = WIDGET_COMM_MANAGER.receive_comm_message(
+ request
)
- broadcast_notification(CompletedRunNotification())
- elif self._kernel.state_updates:
- # Callbacks during message processing (e.g. widget observe
- # handlers) may have called mo.state setters. Process
- # those pending state updates now.
- await self._kernel._run_cells(set())
- broadcast_notification(CompletedRunNotification())
+
+ # Directly handle the UI element update instead of
+ # re-enqueuing it as a separate command. Re-enqueuing
+ # caused Model+UI interleaving that the batch merger
+ # couldn't collapse (different types), leading to every
+ # drag tick getting its own full cell re-execution.
+ if ui_element_id and state:
+ await self._kernel.set_ui_element_value(
+ UpdateUIElementCommand.from_ids_and_values(
+ [(UIElementId(ui_element_id), state)]
+ ),
+ notify_frontend=False,
+ )
+ elif self._kernel.state_updates:
+ # Callbacks during message processing (e.g. widget observe
+ # handlers) may have called mo.state setters. Process
+ # those pending state updates now.
+ await self._kernel._run_cells(set())
async def _handle_function_call(
self, request: InvokeFunctionCommand
) -> None:
- status, ret, found = await self._kernel.function_call_request(request)
- LOGGER.debug("Function returned with status %s", status)
- broadcast_notification(
- FunctionCallResultNotification(
- function_call_id=request.function_call_id,
- return_value=ret,
- status=status,
- found=found,
- ),
- )
+ with self._run_context():
+ status, ret, found = await self._kernel.function_call_request(
+ request
+ )
+ LOGGER.debug("Function returned with status %s", status)
+ broadcast_notification(
+ FunctionCallResultNotification(
+ function_call_id=request.function_call_id,
+ return_value=ret,
+ status=status,
+ found=found,
+ ),
+ )
async def _handle_set_user_config(
self, request: UpdateUserConfigCommand
diff --git a/marimo/_runtime/redirect_streams.py b/marimo/_runtime/redirect_streams.py
index 2ab7371f39..e1b0c99803 100644
--- a/marimo/_runtime/redirect_streams.py
+++ b/marimo/_runtime/redirect_streams.py
@@ -2,8 +2,10 @@
from __future__ import annotations
import contextlib
+import io
import os
import sys
+from contextvars import ContextVar
from typing import TYPE_CHECKING
from marimo._messaging.streams import redirect
@@ -20,6 +22,33 @@ if TYPE_CHECKING:
from collections.abc import Iterator
+_STDIN_ALLOWED = ContextVar("stdin_allowed", default=True)
+
+
+class _EOFStdin(io.StringIO):
+ def _readline_with_prompt(
+ self, prompt: str = "", password: bool = False
+ ) -> str:
+ del prompt, password
+ raise EOFError("EOF when reading a line")
+
+
+def stdin_context(allow_stdin: bool) -> Iterator[None]:
+ """Give noninteractive commands an empty stdin, including nested cells."""
+ if allow_stdin:
+ yield
+ return
+ token = _STDIN_ALLOWED.set(False)
+ previous = sys.stdin
+ sys.stdin = _EOFStdin()
+ try:
+ yield
+ finally:
+ sys.stdin = previous
+ _STDIN_ALLOWED.reset(token)
+
+
def forward_os_stream(stream_object: Stdout | Stderr, fd: int) -> None:
while True:
data = os.read(fd, 1024)
@@ -102,7 +131,8 @@ def redirect_streams(
py_stdin = sys.stdin
sys.stdout = stdout # type: ignore
sys.stderr = stderr # type: ignore
- sys.stdin = stdin # type: ignore
+ if _STDIN_ALLOWED.get():
+ sys.stdin = stdin # type: ignore
try:
with redirect(stdout), redirect(stderr):
diff --git a/marimo/_runtime/runner/cell_runner.py b/marimo/_runtime/runner/cell_runner.py
index 65f5dfd93f..b524ce42e2 100644
--- a/marimo/_runtime/runner/cell_runner.py
+++ b/marimo/_runtime/runner/cell_runner.py
@@ -35,6 +35,7 @@ from marimo._runtime.exceptions import (
MarimoRuntimeException,
unwrap_user_exception,
)
+from marimo._runtime.execution import ExecutionAttempt
from marimo._runtime.executor import (
DebuggerLifecycle,
Evaluator,
@@ -153,6 +154,7 @@ class Runner:
excluded_cells: set[CellId_t] | None = None,
execution_context: ExecutionContextManager | None = None,
user_config: MarimoConfig | None = None,
+ executions: dict[CellId_t, ExecutionAttempt] | None = None,
):
self.graph = graph
self.debugger = debugger
@@ -160,6 +162,7 @@ class Runner:
self.execution_context = execution_context
self._hooks = hooks
self.user_config = user_config
+ self._executions = executions if executions is not None else {}
# runtime globals
self.glbls = glbls
@@ -789,6 +792,26 @@ class Runner:
cell_id: CellId_t,
pre_exec_ctx: Any,
post_exec_ctx: Any,
+ ) -> None:
+ # Nested commands can evaluate a queued cell before this runner does.
+ # Capture the attempt and its source only when it is about to run.
+ execution = self._executions.pop(
+ cell_id, None
+ ) or ExecutionAttempt.plan(cell_id, self.graph.cells[cell_id].code)
+ with execution.activate():
+ execution.start()
+ try:
+ await self._run_one_in_context(
+ cell_id, pre_exec_ctx, post_exec_ctx
+ )
+ finally:
+ execution.finish()
+
+ async def _run_one_in_context(
+ self,
+ cell_id: CellId_t,
+ pre_exec_ctx: Any,
+ post_exec_ctx: Any,
) -> None:
cell = self.graph.cells[cell_id]
for pre_hook in self._hooks.pre_execution_hooks:
@@ -874,16 +897,32 @@ class Runner:
# the stream lock that this broadcast needs.
broadcast_notification(InterruptedNotification())
+ # Interrupted and cancelled cells share one attempt across the
+ # finish hooks, which may report more than one error for a cell.
+ skipped = set(self.cells_to_run).union(
+ *(self.cancelled_cells[cid] for cid in self.cancelled_cells)
+ )
+ for cell_id in sorted(skipped):
+ if cell_id not in self._executions:
+ self._executions[cell_id] = ExecutionAttempt.plan(
+ cell_id, self.graph.cells[cell_id].code
+ )
finish_ctx = OnFinishHookContext(
graph=self.graph,
cells_to_run=self.cells_to_run,
interrupted=self.interrupted,
cancelled_cells=self.cancelled_cells,
exceptions=self.exceptions,
+ execution_ids={
+ cid: execution.id
+ for cid, execution in self._executions.items()
+ },
)
LOGGER.debug("Running on_finish hooks")
for finish_hook in self._hooks.on_finish_hooks:
finish_hook(finish_ctx)
+ for execution in self._executions.values():
+ execution.finish()
async def _dispatch_runnable(
self,
diff --git a/marimo/_runtime/runner/hook_context.py b/marimo/_runtime/runner/hook_context.py
index 0b7d19be59..a13317e43c 100644
--- a/marimo/_runtime/runner/hook_context.py
+++ b/marimo/_runtime/runner/hook_context.py
@@ -2,7 +2,7 @@
from __future__ import annotations
from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any, TypeAlias, Union
from marimo._config.config import MarimoConfig, OnCellChangeType
@@ -115,3 +115,4 @@ class OnFinishHookContext:
interrupted: bool
cancelled_cells: CancelledCells
exceptions: Mapping[CellId_t, ExceptionOrError]
+ execution_ids: Mapping[CellId_t, str] = field(default_factory=dict)
diff --git a/marimo/_runtime/runner/hooks_on_finish.py b/marimo/_runtime/runner/hooks_on_finish.py
index 740af0a984..862dac1493 100644
--- a/marimo/_runtime/runner/hooks_on_finish.py
+++ b/marimo/_runtime/runner/hooks_on_finish.py
@@ -33,6 +33,7 @@ def _send_interrupt_errors(ctx: OnFinishHookContext) -> None:
# reflect a previous run and should be cleared
clear_console=True,
cell_id=cid,
+ execution_id=ctx.execution_ids.get(cid),
)
@@ -83,6 +84,7 @@ def _send_cancellation_errors(ctx: OnFinishHookContext) -> None:
# reflect a previous run and should be cleared
clear_console=True,
cell_id=cid,
+ execution_id=ctx.execution_ids.get(cid),
)
diff --git a/marimo/_runtime/runner/scheduler.py b/marimo/_runtime/runner/scheduler.py
index 6d5ea73c4f..f93eb2c7d5 100644
--- a/marimo/_runtime/runner/scheduler.py
+++ b/marimo/_runtime/runner/scheduler.py
@@ -67,6 +67,7 @@ class Scheduler(Protocol):
coro: Coroutine[Any, Any, RunResult],
) -> AbstractAsyncContextManager[asyncio.Task[RunResult]]: ...
def has_active_tasks(self) -> bool: ...
+ def owns_task(self, task: asyncio.Task[Any] | None) -> bool: ...
def cancel_all(self) -> None: ...
async def __aenter__(self) -> Self: ...
@@ -205,6 +206,10 @@ class SequentialScheduler:
def has_active_tasks(self) -> bool:
return any(not t.done() for t in self._active.values())
+ def owns_task(self, task: asyncio.Task[Any] | None) -> bool:
+ """Whether this task is a cell evaluation the scheduler awaits."""
+ return task is not None and task in self._active.values()
+
def cancel_all(self) -> None:
# Set `_interrupted` first so a SIGINT arriving between cells
# (no task registered) still halts the queue.
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index ee03235467..c3aab16e11 100644
--- a/marimo/_runtime/runtime.py
+++ b/marimo/_runtime/runtime.py
@@ -40,6 +40,7 @@ from marimo._entrypoints.registry import EntryPointRegistry
from marimo._lint.validate_graph import check_for_errors
from marimo._messaging.cell_output import CellChannel
from marimo._messaging.context import (
+ RUN_ID_CTX,
run_id_context,
)
from marimo._messaging.errors import (
@@ -126,6 +127,7 @@ from marimo._runtime.context.kernel_context import (
)
from marimo._runtime.context.utils import get_mode
from marimo._runtime.control_flow import MarimoInterrupt
+from marimo._runtime.execution import ExecutionAttempt
from marimo._runtime.input_override import getpass_override
from marimo._runtime.kernel_request_handlers import KernelRequestHandlers
from marimo._runtime.packages.module_registry import ModuleRegistry
@@ -1363,6 +1365,7 @@ class Kernel:
self._invalidate_cell_state(cid, exclude_defs=keep_alive_defs)
self.errors = all_errors
+ submitted_code = {er.cell_id: er.code for er in execution_requests}
for cid in self.errors:
cell = self.graph.cells.get(cid, None)
if (
@@ -1381,11 +1384,14 @@ class Kernel:
# On syntax errors, we don't have a cell object.
CellNotificationUtils.broadcast_stale(cell_id=cid, stale=False)
- CellNotificationUtils.broadcast_error(
- data=self.errors[cid],
- clear_console=True,
- cell_id=cid,
+ execution = ExecutionAttempt.plan(
+ cid, submitted_code.get(cid, cell.code if cell else "")
)
+ with execution.activate():
+ CellNotificationUtils.broadcast_error(
+ data=self.errors[cid], clear_console=True, cell_id=cid
+ )
+ execution.finish()
# Always broadcast Variables message after graph mutation to ensure
# frontend has the latest dependency information
@@ -1440,7 +1446,7 @@ class Kernel:
async def _run_cells(self, cell_ids: set[CellId_t]) -> None:
"""Run cells and any state updates they trigger"""
- with run_id_context():
+ with run_id_context(RUN_ID_CTX.get(None)):
# This patch is an attempt to mitigate problems caused by the fact
# that in run mode, kernels run in threads and share the same
# sys.modules. Races can still happen, but this should help in most
@@ -1812,6 +1818,16 @@ class Kernel:
@kernel_tracer.start_as_current_span("run_scratchpad")
async def run_scratchpad(self, code: str) -> None:
+ execution = ExecutionAttempt.plan(SCRATCH_CELL_ID, code)
+ with execution.activate():
+ try:
+ await self._run_scratchpad(code, execution)
+ finally:
+ execution.finish()
+
+ async def _run_scratchpad(
+ self, code: str, execution: ExecutionAttempt
+ ) -> None:
roots = {SCRATCH_CELL_ID}
# If cannot compile, don't run
@@ -1864,6 +1880,7 @@ class Kernel:
execution_type=self.execution_type,
execution_context=self._install_execution_context,
hooks=scratchpad_hooks,
+ executions={SCRATCH_CELL_ID: execution},
user_config=self.user_config,
)
diff --git a/marimo/_runtime/threads.py b/marimo/_runtime/threads.py
index 1f2643b0f9..0dfc0d5ecb 100644
--- a/marimo/_runtime/threads.py
+++ b/marimo/_runtime/threads.py
@@ -6,6 +6,7 @@ import threading
from dataclasses import replace
from typing import TYPE_CHECKING, Any
+from marimo._messaging.context import EXECUTION_CTX, RUN_ID_CTX
from marimo._output.rich_help import mddoc
from marimo._runtime.cell_lifecycle_item import CellLifecycleItem
from marimo._runtime.cell_output_list import CellOutputList
@@ -75,6 +76,8 @@ class Thread(threading.Thread):
def __init__(self, *args: Any, **kwargs: Any) -> None:
super().__init__(*args, **kwargs)
+ self._run_id = RUN_ID_CTX.get(None)
+ self._execution_tag = EXECUTION_CTX.get()
self._marimo_ctx: RuntimeContext | None = None
exit_event = threading.Event()
@@ -151,9 +154,13 @@ class Thread(threading.Thread):
context_initialized: bool,
thread_id: int,
) -> Any:
+ run_id_token = RUN_ID_CTX.set(self._run_id)
+ execution_token = EXECUTION_CTX.set(self._execution_tag)
try:
return await awaitable
finally:
+ EXECUTION_CTX.reset(execution_token)
+ RUN_ID_CTX.reset(run_id_token)
THREADS.discard(thread_id)
if context_initialized:
teardown_context()
@@ -187,6 +194,8 @@ class Thread(threading.Thread):
output=output,
)
thread_id = threading.get_ident()
+ run_id_token = RUN_ID_CTX.set(self._run_id)
+ execution_token = EXECUTION_CTX.set(self._execution_tag)
try:
if managed_thread:
THREADS.add(thread_id)
@@ -200,6 +209,8 @@ class Thread(threading.Thread):
)
return result
finally:
+ EXECUTION_CTX.reset(execution_token)
+ RUN_ID_CTX.reset(run_id_token)
if not defer_cleanup:
if managed_thread:
THREADS.discard(thread_id)
diff --git a/marimo/_server/host/__init__.py b/marimo/_server/host/__init__.py
new file mode 100644
index 0000000000..28e1258f52
--- /dev/null
+++ b/marimo/_server/host/__init__.py
@@ -0,0 +1,17 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Host API routes and session integration for `marimo edit`."""
+
+HOST_API_PATH = "/api/marimo/v1"
+"""Host API path relative to the server's base URL."""
+
+OPERATIONS = [
+ "notebook.create",
+ "notebook.update",
+ "notebook.delete",
+ "notebook.open",
+ "runtime.start",
+ "runtime.stop",
+ "runtime.restart",
+ "runtime.run",
+]
+"""Supported operations advertised in the `host` object."""
diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.py
new file mode 100644
index 0000000000..7773a34baa
--- /dev/null
+++ b/marimo/_server/host/api.py
@@ -0,0 +1,497 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""HTTP routes for notebooks, runtimes, runs, and event streams."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import threading
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from pathlib import Path
+from typing import TYPE_CHECKING, TypeAlias, TypeVar
+from urllib.parse import quote
+
+import msgspec
+from starlette.exceptions import HTTPException
+from starlette.responses import Response, StreamingResponse
+from starlette.routing import Route, Router
+
+from marimo import _loggers
+from marimo._core import protocol
+from marimo._core.errors import Conflict, NoRuntime, NotFound
+from marimo._server.api.auth import TOKEN_QUERY_PARAM
+from marimo._server.api.deps import AppStateBase
+from marimo._server.api.utils import format_url_host, open_url_in_browser
+from marimo._server.host.context import CachedMutation
+from marimo._server.sse import SSE_HEADERS
+from marimo._server.tokens import AuthToken
+
+if TYPE_CHECKING:
+ from collections.abc import AsyncIterator
+
+ from starlette.requests import Request
+ from starlette.types import ASGIApp
+
+ from marimo._core.notebook import Notebook
+ from marimo._core.stream import Event
+ from marimo._server.host.context import HostContext
+
+LOGGER = _loggers.marimo_logger()
+
+_Endpoint: TypeAlias = Callable[["Request"], Awaitable[Response]]
+_Body = TypeVar("_Body", bound=msgspec.Struct)
+
+PROBLEM_TYPE_PREFIX = "tag:marimo.io,2026:host/"
+"""Prefix for host protocol problem types."""
+
+PING = b": ping\n\n"
+PING_SECONDS = 15.0
+
+_TITLES = {
+ "invalid-request": "Invalid request",
+ "unauthorized": "Unauthorized",
+ "forbidden": "Forbidden",
+ "not-found": "Not found",
+ "conflict": "Conflict",
+ "no-runtime": "No runtime",
+ "unsupported-operation": "Unsupported operation",
+ "internal": "Internal error",
+}
+
+
+def problem(status: int, kind: str, detail: str | None = None) -> Response:
+ """Return a protocol error as an HTTP problem response."""
+ body = protocol.Problem(
+ type=PROBLEM_TYPE_PREFIX + kind,
+ title=_TITLES[kind],
+ status=status,
+ detail=msgspec.UNSET if detail is None else detail,
+ )
+ return Response(
+ msgspec.json.encode(body),
+ status_code=status,
+ media_type="application/problem+json",
+ )
+
+
+def build_app() -> ASGIApp:
+ """Build the host API router."""
+ return Router(
+ routes=[
+ Route("/events", _events, methods=["GET"]),
+ Route("/notebooks", _create_notebook, methods=["POST"]),
+ Route("/notebooks/{id}", _update_notebook, methods=["PATCH"]),
+ Route("/notebooks/{id}", _delete_notebook, methods=["DELETE"]),
+ Route("/notebooks/{id}/events", _notebook_events, methods=["GET"]),
+ Route("/notebooks/{id}/open", _open_notebook, methods=["POST"]),
+ Route("/notebooks/{id}/runtime", _start_runtime, methods=["PUT"]),
+ Route(
+ "/notebooks/{id}/runtime", _stop_runtime, methods=["DELETE"]
+ ),
+ Route(
+ "/notebooks/{id}/runtime/restart",
+ _restart_runtime,
+ methods=["POST"],
+ ),
+ Route("/notebooks/{id}/runtime/runs", _run, methods=["POST"]),
+ Route(
+ "/notebooks/{id}/runtime/runs/{run_id}",
+ _interrupt,
+ methods=["DELETE"],
+ ),
+ ],
+ default=_not_found,
+ )
+
+
+async def _not_found(scope, receive, send) -> None: # type: ignore[no-untyped-def]
+ await problem(404, "not-found", "No such route")(scope, receive, send)
+
+
+def _context(request: Request) -> 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]
+
+
+def _notebook(request: Request) -> Notebook:
+ return _context(request).bridge.host.notebook(request.path_params["id"])
+
+
+def _record(request: Request) -> protocol.Notebook:
+ notebook_id = request.path_params["id"]
+ host = _context(request).bridge.host
+ record = host.notebooks.get(notebook_id)
+ if record is None:
+ raise NotFound(f"no notebook {notebook_id}")
+ return record
+
+
+def _mutation(operation: str) -> Callable[[_Endpoint], _Endpoint]:
+ """Apply capability checks, idempotency, and protocol errors to a command."""
+
+ def decorate(endpoint: _Endpoint) -> _Endpoint:
+ @wraps(endpoint)
+ async def handle(request: Request) -> Response:
+ context = _context(request)
+ if operation not in context.bridge.host.operations:
+ return problem(
+ 501,
+ "unsupported-operation",
+ f"This host does not offer {operation}",
+ )
+ key = request.headers.get("Idempotency-Key", "")
+ if not key:
+ return problem(
+ 400, "invalid-request", "Idempotency-Key is required"
+ )
+ digest = hashlib.sha256(await request.body()).hexdigest()
+ fingerprint = f"{request.method} {request.url.path} {digest}"
+ remembered = context.replies.get(key)
+ if remembered is not None:
+ if remembered.fingerprint != fingerprint:
+ return problem(
+ 409,
+ "conflict",
+ f"Idempotency-Key {key} was used for another request",
+ )
+ response = await asyncio.shield(remembered.task)
+ if remembered.run is not None:
+ return _reply(202, remembered.run)
+ return response
+
+ task = asyncio.create_task(_execute_mutation(endpoint, request))
+ mutation = CachedMutation(fingerprint, task)
+ context.replies[key] = mutation
+ unsubscribe: Callable[[], None] | None = None
+ if operation == "runtime.run" and request.method == "POST":
+ # Retain the last run state even after a restart removes it
+ # from the notebook. Replaying the key must never execute again.
+ def updated(event: Event) -> None:
+ if isinstance(event.data, protocol.RunMessage):
+ run = event.data.run
+ if run.id == key:
+ mutation.run = run
+ if (
+ run.status == "completed"
+ and unsubscribe is not None
+ ):
+ unsubscribe()
+
+ unsubscribe = context.bridge.host.subscribe(
+ updated,
+ notebook_id=request.path_params["id"],
+ types={"run"},
+ )
+
+ def completed(task: asyncio.Task[Response]) -> None:
+ if (
+ task.cancelled()
+ or task.exception() is not None
+ or task.result().status_code >= 400
+ ):
+ context.replies.pop(key, None)
+ if unsubscribe is not None:
+ unsubscribe()
+
+ task.add_done_callback(completed)
+ # A disconnected waiter must not cancel a shared mutation.
+ return await asyncio.shield(task)
+
+ return handle
+
+ return decorate
+
+
+async def _execute_mutation(endpoint: _Endpoint, request: Request) -> Response:
+ try:
+ return await endpoint(request)
+ except NoRuntime as e:
+ return problem(409, "no-runtime", str(e))
+ except Conflict as e:
+ return problem(409, "conflict", str(e))
+ except NotFound as e:
+ return problem(404, "not-found", str(e))
+ except msgspec.DecodeError as e:
+ return problem(400, "invalid-request", str(e))
+ except HTTPException as e:
+ kind = {
+ 400: "invalid-request",
+ 404: "not-found",
+ 409: "conflict",
+ }[e.status_code]
+ return problem(e.status_code, kind, e.detail)
+
+
+def _reply(status: int, body: msgspec.Struct | None = None) -> Response:
+ return Response(
+ b"" if body is None else msgspec.json.encode(body),
+ status_code=status,
+ media_type="application/json" if body is not None else None,
+ )
+
+
+async def _decode(request: Request, kind: type[_Body]) -> _Body:
+ return msgspec.json.decode(await request.body() or b"{}", type=kind)
+
+
+# ---- streams -------------------------------------------------------------------
+
+
+async def _events(request: Request) -> Response:
+ """Stream catalog snapshots and updates.
+
+ `Last-Event-ID` resumes from a cursor; `types` filters event kinds.
+ """
+ context = _context(request)
+ cursor = _cursor(request)
+ if isinstance(cursor, Response):
+ return cursor
+ # Refresh on connection because the catalog has no directory watcher.
+ await context.bridge.refresh()
+ return _stream(context, cursor, _types(request), notebook_id=None)
+
+
+async def _notebook_events(request: Request) -> Response:
+ """Stream notebook events, attaching the client until disconnect."""
+ context = _context(request)
+ try:
+ notebook = _notebook(request)
+ except NotFound as e:
+ return problem(404, "not-found", str(e))
+ cursor = _cursor(request)
+ if isinstance(cursor, Response):
+ return cursor
+ run_id = request.query_params.get("run_id")
+ if run_id == "":
+ return problem(400, "invalid-request", "run_id must not be empty")
+ attachment = notebook.attach()
+ return _stream(
+ context,
+ cursor,
+ _types(request),
+ notebook_id=notebook.id,
+ run_id=run_id,
+ on_close=lambda: notebook.detach(attachment.id),
+ )
+
+
+def _cursor(request: Request) -> int | Response | None:
+ raw = request.headers.get("Last-Event-ID")
+ if raw is None:
+ return None
+ if not raw.isdigit():
+ return problem(400, "invalid-request", "Last-Event-ID must be an id")
+ return int(raw)
+
+
+def _types(request: Request) -> set[str] | None:
+ asked = request.query_params.get("types")
+ if not asked:
+ return None
+ return {kind for kind in asked.split(",") if kind}
+
+
+def _stream(
+ context: HostContext,
+ cursor: int | None,
+ types: set[str] | None,
+ *,
+ notebook_id: str | 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)
+ finally:
+ unsubscribe()
+ if on_close is not None:
+ on_close()
+
+ return StreamingResponse(
+ body(), media_type="text/event-stream", headers=SSE_HEADERS
+ )
+
+
+def _frame(event: Event) -> bytes:
+ """Encode an event as an SSE frame."""
+ lines = []
+ if event.id is not None:
+ lines.append(f"id: {event.id}")
+ lines.append(f"event: {event.name}")
+ data = b"{}" if event.data is None else msgspec.json.encode(event.data)
+ lines.append(f"data: {data.decode()}")
+ return ("\n".join(lines) + "\n\n").encode()
+
+
+# ---- notebooks -----------------------------------------------------------------
+
+
+def _inside_project(path: str) -> Path:
+ relative = Path(path)
+ if relative.is_absolute() or ".." in relative.parts:
+ raise HTTPException(400, "path must stay in the project")
+ return relative
+
+
+@_mutation("notebook.create")
+async def _create_notebook(request: Request) -> Response:
+ """Create an empty notebook in the project."""
+ context = _context(request)
+ key = request.headers["Idempotency-Key"]
+ body = await _decode(request, protocol.CreateNotebookRequest)
+
+ index = context.bridge.index
+ if index.root is None or body.project_id != index.project_id:
+ raise HTTPException(404, f"No project {body.project_id}")
+ if body.path is msgspec.UNSET:
+ raise HTTPException(400, "path is required")
+ relative = _inside_project(body.path)
+ file = index.root / relative
+ notebook = await context.bridge.create(
+ file,
+ name=None if body.name is msgspec.UNSET else body.name,
+ request_id=key,
+ )
+ return _reply(201, notebook)
+
+
+@_mutation("notebook.update")
+async def _update_notebook(request: Request) -> Response:
+ """Change a notebook's path or display name, preserving its runtime."""
+ context = _context(request)
+ key = request.headers["Idempotency-Key"]
+ record = _record(request)
+ body = await _decode(request, protocol.UpdateNotebookRequest)
+
+ index = context.bridge.index
+ target = None
+ if body.path is not msgspec.UNSET:
+ if index.root is None:
+ raise HTTPException(409, "The notebook has no file to move")
+ relative = _inside_project(body.path)
+ target = index.root / relative
+ notebook = await context.bridge.update(
+ record.id,
+ target=target,
+ name=None if body.name is msgspec.UNSET else body.name,
+ request_id=key,
+ )
+ return _reply(200, notebook)
+
+
+@_mutation("notebook.delete")
+async def _delete_notebook(request: Request) -> Response:
+ """Delete the notebook and file; return 409 while a runtime exists."""
+ context = _context(request)
+ key = request.headers["Idempotency-Key"]
+ await context.bridge.delete(_notebook(request).id, request_id=key)
+ return _reply(204, None)
+
+
+@_mutation("notebook.open")
+async def _open_notebook(request: Request) -> Response:
+ """Open the notebook in the configured browser."""
+ record = _record(request)
+ file = _context(request).bridge.index.file_of(record.id)
+ if file is None:
+ raise HTTPException(409, "The notebook has no file to open")
+
+ state = AppStateBase.from_app(request.app)
+ authority = f"{format_url_host(state.host, state.port)}:{state.port}"
+ url = f"http://{authority}{state.base_url}/?file={quote(str(file))}"
+ auth_token = state.session_manager.auth_token
+ if not AuthToken.is_empty(auth_token):
+ url += f"&{TOKEN_QUERY_PARAM}={quote(str(auth_token))}"
+ browser = state.config_manager.get_config()["server"]["browser"]
+ # Keep blocking browser discovery off the event loop.
+ threading.Thread(
+ target=_open_quietly, args=(browser, url), daemon=True
+ ).start()
+ return _reply(200, protocol.OpenNotebookResponse(url=url))
+
+
+def _open_quietly(browser: str, url: str) -> None:
+ try:
+ open_url_in_browser(browser, url)
+ except Exception as e:
+ LOGGER.warning("Could not open the notebook in a browser: %s", e)
+
+
+# ---- runtimes ------------------------------------------------------------------
+
+
+@_mutation("runtime.start")
+async def _start_runtime(request: Request) -> Response:
+ """Start a runtime: 202 if created, 200 if already present."""
+ key = request.headers["Idempotency-Key"]
+ notebook = _notebook(request)
+ await _decode(request, protocol.StartRuntimeRequest)
+ runtime, created = notebook.start(request_id=key)
+ return _reply(202 if created else 200, runtime)
+
+
+@_mutation("runtime.stop")
+async def _stop_runtime(request: Request) -> Response:
+ """Request shutdown and return 202 with the runtime marked terminating."""
+ key = request.headers["Idempotency-Key"]
+ notebook = _notebook(request)
+ runtime = notebook.stop(request_id=key)
+ return _reply(202, runtime)
+
+
+@_mutation("runtime.restart")
+async def _restart_runtime(request: Request) -> Response:
+ """Return 202 with the replacement runtime in its starting state."""
+ key = request.headers["Idempotency-Key"]
+ notebook = _notebook(request)
+ runtime = notebook.restart(request_id=key)
+ return _reply(202, runtime)
+
+
+# ---- runs ----------------------------------------------------------------------
+
+
+@_mutation("runtime.run")
+async def _run(request: Request) -> Response:
+ """Queue a run and return 202; stream results through notebook events."""
+ key = request.headers["Idempotency-Key"]
+ notebook = _notebook(request)
+ body = await _decode(request, protocol.RunRequest)
+ started = notebook.run(body.code, request_id=key)
+ return _reply(202, started)
+
+
+@_mutation("runtime.run")
+async def _interrupt(request: Request) -> Response:
+ """Request a run interruption: 202 if active, 409 if completed."""
+ notebook = _notebook(request)
+ interrupted = notebook.interrupt(request.path_params["run_id"])
+ return _reply(202, interrupted)
diff --git a/marimo/_server/host/backend.py b/marimo/_server/host/backend.py
new file mode 100644
index 0000000000..6b1e247648
--- /dev/null
+++ b/marimo/_server/host/backend.py
@@ -0,0 +1,284 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Kernel commands and updates using marimo sessions."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from marimo import _loggers
+from marimo._core import backend as be, protocol
+from marimo._messaging.notification import (
+ CellNotification,
+ CompletedRunNotification,
+ ExecutionNotification,
+ InterruptedNotification,
+ StartupProgressNotification,
+)
+from marimo._messaging.serde import deserialize_kernel_message
+from marimo._runtime.commands import ExecuteScratchpadCommand
+from marimo._runtime.scratch import SCRATCH_CELL_ID
+from marimo._server.host.translate import RunTranslator
+from marimo._server.scratchpad import snapshot_for_scratchpad
+from marimo._session.consumer import SessionConsumer
+from marimo._session.model import ConnectionState
+from marimo._session.requests import InstantiateNotebookRequest
+from marimo._session.types import KernelState
+from marimo._types.ids import ConsumerId, SessionId
+from marimo._version import __version__
+
+if TYPE_CHECKING:
+ from marimo._messaging.types import KernelMessage
+ from marimo._server.session_manager import SessionManager
+ from marimo._session.events import SessionEventBus
+ from marimo._session.session import Session
+
+LOGGER = _loggers.marimo_logger()
+
+_PHASES = {
+ "preparing-environment": "Preparing the environment",
+ "starting-kernel": "Starting the kernel",
+}
+
+Observe = Callable[[be.Message], None]
+
+
+@dataclass
+class _Run:
+ session: Session
+ translator: RunTranslator
+ done: asyncio.Event = field(default_factory=asyncio.Event)
+ task: asyncio.Task[None] | None = None
+ submitted: bool = False
+
+
+class SessionBackend(SessionConsumer):
+ """A notebook backend that reports updates from a session.
+
+ Connects as a secondary consumer to receive startup, execution,
+ and shutdown notifications.
+ """
+
+ def __init__(
+ self,
+ notebook_id: protocol.NotebookId,
+ file: Callable[[], str | None],
+ manager: SessionManager,
+ observe: Observe,
+ ) -> None:
+ self._notebook_id = notebook_id
+ self._file = file
+ """Resolve the notebook's current path after file moves."""
+ self._manager = manager
+ self._observe = observe
+ self.session: Session | None = None
+ self._stop_requested = False
+ self._run: _Run | None = None
+ self._translators: dict[str, RunTranslator] = {}
+
+ # Backend commands
+
+ def start(self, runtime_id: protocol.RuntimeId) -> None:
+ self._stop_requested = False
+ asyncio.get_running_loop().create_task(
+ self._start(SessionId(f"host-{runtime_id}")),
+ name=f"host.start.{runtime_id}",
+ )
+
+ async def _start(self, session_id: SessionId) -> None:
+ file = self._file()
+ if file is None:
+ self._observe(be.Exited("The notebook has no file to run"))
+ return
+ try:
+ await self._manager.create_session(
+ session_id,
+ self,
+ {},
+ file,
+ auto_instantiate=False,
+ main=False,
+ )
+ except Exception as e:
+ LOGGER.warning(
+ "Kernel for %s failed to start", file, exc_info=True
+ )
+ self._observe(be.Exited(str(e) or type(e).__name__))
+ return
+ # Apply a stop requested during startup.
+ if self._stop_requested:
+ self.stop()
+
+ def stop(self) -> None:
+ session = self.session
+ if session is None:
+ self._stop_requested = True
+ return
+ for session_id, candidate in self._manager.sessions.items():
+ if candidate is session:
+ self._manager.close_session(session_id)
+ return
+ # Closing an unregistered session still detaches its consumers.
+ session.close()
+
+ def run(self, run_id: protocol.RunId, code: str) -> None:
+ session = self.session
+ if session is None:
+ return
+ run = _Run(session, RunTranslator(run_id, code))
+ self._run = run
+ run.task = asyncio.get_running_loop().create_task(
+ self._run_code(run, code), name=f"host.run.{run_id}"
+ )
+ # A callback also finalizes cancellation before the coroutine starts.
+ run.task.add_done_callback(lambda task: self._finish_run(run, task))
+
+ async def _run_code(self, run: _Run, code: str) -> None:
+ session = run.session
+ async with session.scratchpad_lock:
+ # Register notebook definitions once, without executing cells.
+ session.instantiate(
+ InstantiateNotebookRequest(
+ object_ids=[], values=[], auto_run=False
+ ),
+ http_request=None,
+ )
+ cells, outputs = snapshot_for_scratchpad(session)
+ run.submitted = True
+ self._translators[run.translator.run_id] = run.translator
+ session.put_control_request(
+ ExecuteScratchpadCommand(
+ code=code,
+ request=None,
+ notebook_cells=cells,
+ cell_outputs=outputs,
+ run_id=run.translator.run_id,
+ allow_stdin=False,
+ ),
+ from_consumer_id=None,
+ )
+ await run.done.wait()
+
+ def _finish_run(self, run: _Run, task: asyncio.Task[None]) -> None:
+ if self._run is run:
+ self._run = None
+ error = None
+ if task.cancelled():
+ run.translator.interrupted = True
+ elif (exception := task.exception()) is not None:
+ LOGGER.error("Scratch run failed in the host: %s", exception)
+ error = protocol.Error(
+ kind="internal",
+ name=None,
+ message=str(exception) or type(exception).__name__,
+ traceback=None,
+ source="marimo",
+ severity="error",
+ range=None,
+ related=[],
+ )
+ # Detachment already ended this session's runs in the core model.
+ if self.session is run.session:
+ for message in run.translator.finish(error=error):
+ self._observe(message)
+
+ def interrupt(self, run_id: protocol.RunId) -> None:
+ run = self._run
+ if run is None or run.translator.run_id != run_id:
+ translator = self._translators.get(run_id)
+ if (
+ translator is not None
+ and not translator.completed
+ and self.session is not None
+ ):
+ self.session.try_interrupt()
+ return
+ if run.done.is_set():
+ return
+ if run.submitted:
+ run.session.try_interrupt()
+ elif run.task is not None:
+ run.task.cancel()
+
+ # Existing sessions
+
+ def adopt(self, session: Session) -> None:
+ """Observe an existing session."""
+ if self.session is not None:
+ return
+ session.connect_consumer(self, main=False)
+
+ # Session consumer
+
+ @property
+ def consumer_id(self) -> ConsumerId:
+ return ConsumerId(f"host-{self._notebook_id}")
+
+ def connection_state(self) -> ConnectionState:
+ return ConnectionState.OPEN
+
+ def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:
+ del event_bus
+ self.session = session
+ self._observe(be.Running(__version__))
+
+ def on_detach(self) -> None:
+ """Report session closure and release any waiting run."""
+ session, self.session = self.session, None
+ if session is None:
+ return
+ reason = None
+ if session.kernel_state() is KernelState.STOPPED:
+ info = session.kernel_exit_info()
+ reason = info.message if info is not None else "The kernel died"
+ run = self._run
+ if run is not None and run.task is not None:
+ run.task.cancel()
+ self._translators.clear()
+ self._observe(be.Exited(reason))
+
+ def notify(self, notification: KernelMessage) -> None:
+ message = deserialize_kernel_message(notification)
+ if isinstance(message, StartupProgressNotification):
+ self._observe(
+ be.Starting(_PHASES.get(message.phase, message.phase))
+ )
+ return
+ if not isinstance(
+ message,
+ (
+ CellNotification,
+ ExecutionNotification,
+ CompletedRunNotification,
+ InterruptedNotification,
+ ),
+ ):
+ return
+ run_id = message.run_id
+ if run_id is None:
+ return
+ run = self._run
+ translator = self._translators.get(run_id)
+ if translator is None:
+ if (
+ not isinstance(message, ExecutionNotification)
+ or message.phase != "planned"
+ or self.session is None
+ ):
+ return
+ translator = RunTranslator(
+ protocol.RunId(run_id),
+ message.code if message.cell_id == SCRATCH_CELL_ID else None,
+ )
+ self._translators[run_id] = translator
+ self._observe(be.Scheduled(translator.run_id))
+ for out in translator.feed(message):
+ self._observe(out)
+ if translator.completed:
+ if run is not None and translator is run.translator:
+ run.done.set()
+ else:
+ for out in translator.finish():
+ self._observe(out)
diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.py
new file mode 100644
index 0000000000..6a352d875d
--- /dev/null
+++ b/marimo/_server/host/bridge.py
@@ -0,0 +1,223 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Workspace notebooks and session updates for the host API."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from marimo import _loggers
+from marimo._core import protocol
+from marimo._core.errors import Conflict, NotFound
+from marimo._core.host import Host
+from marimo._runtime.commands import RenameNotebookCommand
+from marimo._server.host import OPERATIONS
+from marimo._server.host.backend import SessionBackend
+from marimo._server.host.index import WorkspaceIndex
+from marimo._session.events import SessionEventListener
+from marimo._session.notebook.storage import rename_no_replace
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from marimo._core.backend import Message
+ from marimo._server.session_manager import SessionManager
+ from marimo._session.session import Session
+
+LOGGER = _loggers.marimo_logger()
+
+
+class SessionBridge(SessionEventListener):
+ """Connect a host's notebook catalog to a session manager."""
+
+ def __init__(self, manager: SessionManager) -> None:
+ self._manager = manager
+ self._files_lock = asyncio.Lock()
+ self.host = Host(operations=OPERATIONS)
+ self._backends: dict[protocol.NotebookId, SessionBackend] = {}
+ self.index = WorkspaceIndex(
+ self.host, manager.workspace, self._make_backend
+ )
+
+ def open(self) -> None:
+ """Index notebooks, adopt sessions, and subscribe to session events."""
+ self.index.refresh()
+ for session in list(self._manager.sessions.values()):
+ self._adopt(session)
+ self._manager.event_bus.subscribe(self)
+
+ def close(self) -> None:
+ self._manager.event_bus.unsubscribe(self)
+
+ async def refresh(self) -> None:
+ """Refresh the catalog without observing a half-finished file move."""
+ async with self._files_lock:
+ await self.index.refresh_async()
+
+ def _project_path(self, path: Path) -> Path:
+ root = self.index.root
+ if root is None:
+ raise Conflict("The project has no directory")
+ resolved = path.resolve()
+ if not resolved.is_relative_to(root.resolve()):
+ raise Conflict("The path must stay in the project")
+ return resolved
+
+ async def create(
+ self, target: Path, *, name: str | None, request_id: str
+ ) -> protocol.Notebook:
+ """Create a notebook only after validating its destination."""
+ from marimo._convert.converters import MarimoConvert
+ from marimo._session.notebook import AppFileManager
+
+ def write() -> None:
+ file = self._project_path(target)
+ if target.is_symlink():
+ raise Conflict(f"{target.name} already exists")
+ file.parent.mkdir(parents=True, exist_ok=True)
+ content = MarimoConvert.from_ir(
+ AppFileManager(None).app.to_ir()
+ ).to_py()
+ with file.open("x", encoding="utf-8") as output:
+ output.write(content)
+
+ async with self._files_lock:
+ try:
+ await asyncio.to_thread(write)
+ except OSError as e:
+ raise Conflict(f"The notebook cannot be created: {e}") from e
+ notebook = self.index.ensure(str(target), request_id=request_id)
+ assert notebook is not None
+ if name is not None:
+ self.index.rename(notebook.id, name, request_id=request_id)
+ return self.host.notebooks[notebook.id]
+
+ async def update(
+ self,
+ notebook_id: protocol.NotebookId,
+ *,
+ target: Path | None = None,
+ name: str | None = None,
+ request_id: str,
+ ) -> protocol.Notebook:
+ """Update a notebook's file and label, preserving its runtime."""
+ async with self._files_lock:
+ self.host.notebook(notebook_id)
+ if target is not None:
+ await self._move(notebook_id, target, request_id=request_id)
+ if name is not None:
+ self.index.rename(notebook_id, name, request_id=request_id)
+ return self.host.notebooks[notebook_id]
+
+ async def delete(
+ self, notebook_id: protocol.NotebookId, *, request_id: str
+ ) -> None:
+ """Remove a notebook without a runtime and its backing file."""
+ async with self._files_lock:
+ notebook = self.host.notebook(notebook_id)
+ if notebook.runtime is not None:
+ raise Conflict("The notebook has a runtime")
+ file = self.index.file_of(notebook_id)
+ if file is not None:
+ try:
+ self._project_path(file)
+ file.unlink(missing_ok=True)
+ except OSError as e:
+ raise Conflict(f"The file cannot be removed: {e}") from e
+ self.index.forget(notebook_id, request_id=request_id)
+
+ async def _move(
+ self,
+ notebook_id: protocol.NotebookId,
+ target: Path,
+ *,
+ request_id: str,
+ ) -> None:
+ source = self.index.file_of(notebook_id)
+ if source is None:
+ raise Conflict("The notebook has no file to move")
+ target = await asyncio.to_thread(self._project_path, target)
+ if await asyncio.to_thread(target.exists):
+ raise Conflict(f"{target.name} already exists")
+ backend = self._backends.get(notebook_id)
+ session = None if backend is None else backend.session
+ session_id = next(
+ (
+ sid
+ for sid, candidate in self._manager.sessions.items()
+ if candidate is session
+ ),
+ None,
+ )
+ try:
+ await asyncio.to_thread(
+ target.parent.mkdir, parents=True, exist_ok=True
+ )
+ if session_id is None:
+ await asyncio.to_thread(rename_no_replace, source, target)
+ else:
+ ok, error = await self._manager.rename_session(
+ session_id, str(target)
+ )
+ if not ok:
+ raise Conflict(error or "The notebook cannot be moved")
+ assert session is not None
+ session.put_control_request(
+ RenameNotebookCommand(filename=str(target)),
+ from_consumer_id=None,
+ )
+ except OSError as e:
+ raise Conflict(f"The notebook cannot be moved: {e}") from e
+ self.index.moved(notebook_id, str(target), request_id=request_id)
+
+ def _make_backend(
+ self, notebook_id: protocol.NotebookId
+ ) -> SessionBackend:
+ def file() -> str | None:
+ path = self.index.file_of(notebook_id)
+ return None if path is None else str(path)
+
+ def observe(message: Message) -> None:
+ try:
+ notebook = self.host.notebook(notebook_id)
+ except NotFound:
+ # Sessions can report shutdown after their catalog removal.
+ return
+ notebook.observe(message)
+
+ backend = SessionBackend(
+ notebook_id,
+ file,
+ self._manager,
+ observe,
+ )
+ self._backends[notebook_id] = backend
+ return backend
+
+ def _adopt(self, session: Session) -> None:
+ 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)
+ if notebook is None:
+ LOGGER.debug("Not publishing session for %s", path)
+ return
+ self._backends[notebook.id].adopt(session)
+
+ # Session events
+
+ async def on_session_created(self, session: Session) -> None:
+ self._adopt(session)
+
+ async def on_session_notebook_renamed(
+ self, session: Session, old_path: str | None
+ ) -> None:
+ notebook = self.index.notebook_for(old_path)
+ path = session.app_file_manager.path
+ if path is None:
+ return
+ if notebook is None:
+ # Add notebooks to the catalog when first saved.
+ self._adopt(session)
+ return
+ self.index.moved(notebook.id, path)
diff --git a/marimo/_server/host/context.py b/marimo/_server/host/context.py
new file mode 100644
index 0000000000..069e7b1be3
--- /dev/null
+++ b/marimo/_server/host/context.py
@@ -0,0 +1,34 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Shared state for host API routes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ import asyncio
+
+ from starlette.responses import Response
+
+ from marimo._core import protocol
+ from marimo._server.host.bridge import SessionBridge
+
+
+@dataclass
+class CachedMutation:
+ """One accepted request, including its in-flight or completed reply."""
+
+ fingerprint: str
+ task: asyncio.Task[Response]
+ run: protocol.Run | None = None
+
+
+@dataclass
+class HostContext:
+ """Host API token, address, session bridge, and cached replies."""
+
+ bridge: SessionBridge
+ token: str
+ port: int
+ replies: dict[str, CachedMutation] = field(default_factory=dict)
diff --git a/marimo/_server/host/index.py b/marimo/_server/host/index.py
new file mode 100644
index 0000000000..4970253596
--- /dev/null
+++ b/marimo/_server/host/index.py
@@ -0,0 +1,242 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Workspace files indexed as a host project.
+
+Notebook IDs persist across rescans and recorded file moves.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from msgspec.structs import replace
+
+from marimo._core import protocol
+from marimo._core.ids import mint
+from marimo._server.host import OPERATIONS
+from marimo._server.workspace import flatten_files
+
+if TYPE_CHECKING:
+ from marimo._core.backend import Backend
+ from marimo._core.host import Host
+ from marimo._server.models.files import FileInfo
+ from marimo._server.workspace import NotebookWorkspace
+
+_TRUNCATED = "The scan stopped at its depth, file count, or time limit"
+
+MakeBackend = Callable[[protocol.NotebookId], "Backend"]
+
+
+class WorkspaceIndex:
+ """A host project and its indexed notebook files."""
+
+ def __init__(
+ self,
+ host: Host,
+ workspace: NotebookWorkspace,
+ make_backend: MakeBackend,
+ ) -> None:
+ self._host = host
+ self._workspace = workspace
+ self._make_backend = make_backend
+ self._root = _root_of(workspace)
+ self.project_id = mint(protocol.ProjectId, "proj")
+ self._ids: dict[Path, protocol.NotebookId] = {}
+ self._names: dict[protocol.NotebookId, str] = {}
+ """Client-selected names preserved across rescans."""
+ self._refresh_lock = asyncio.Lock()
+
+ @property
+ def root(self) -> Path | None:
+ """The project directory, if the workspace has one."""
+ return self._root
+
+ def refresh(self) -> None:
+ """Rescan notebook files and publish catalog changes.
+
+ Keep unlisted notebooks while their files still exist, since scans
+ may be incomplete.
+ """
+ self._apply_scan(*self._scan())
+
+ async def refresh_async(self) -> None:
+ """Scan off-thread, then apply catalog changes on the event loop."""
+ async with self._refresh_lock:
+ files, truncated = await asyncio.to_thread(self._scan)
+ self._apply_scan(files, truncated)
+
+ def _scan(self) -> tuple[list[FileInfo], bool]:
+ self._workspace.invalidate()
+ files = [
+ f for f in flatten_files(self._workspace.files) if f.is_marimo_file
+ ]
+ return files, self._workspace.is_truncated
+
+ def _apply_scan(self, files: list[FileInfo], truncated: bool) -> None:
+ self._host.update_project(
+ protocol.Project(
+ id=self.project_id,
+ name="workspace" if self._root is None else self._root.name,
+ root=None if self._root is None else str(self._root),
+ status="partial" if truncated else "indexed",
+ message=_TRUNCATED if truncated else None,
+ operations=list(OPERATIONS),
+ )
+ )
+ seen: set[protocol.NotebookId] = set()
+ for file in files:
+ notebook = self._publish(Path(file.path), file.last_modified)
+ if notebook is not None:
+ seen.add(notebook.id)
+ for notebook in list(self._host.notebooks.values()):
+ if notebook.project_id != self.project_id:
+ continue
+ if notebook.id in seen or self._exists(notebook):
+ continue
+ if self._host.notebook(notebook.id).runtime is not None:
+ self._host.update_notebook(
+ replace(notebook, path=None, updated_at=None)
+ )
+ else:
+ self.forget(notebook.id)
+
+ def ensure(
+ self, path: str, *, request_id: str | None = None
+ ) -> protocol.Notebook | None:
+ """Add or update a notebook file under the project root.
+
+ Return `None` if the file is missing or outside the project.
+ """
+ file = Path(path)
+ try:
+ modified: float | None = file.stat().st_mtime
+ except OSError:
+ return None
+ return self._publish(file, modified, request_id=request_id)
+
+ def moved(
+ self,
+ notebook_id: protocol.NotebookId,
+ path: str,
+ *,
+ request_id: str | None = None,
+ ) -> protocol.Notebook | None:
+ """Update a notebook's file path, keeping its ID.
+
+ Return `None` for a path outside the project.
+ """
+ relative = self._relative(Path(path))
+ if relative is None:
+ return None
+ for old, known in list(self._ids.items()):
+ if known == notebook_id:
+ del self._ids[old]
+ self._ids[relative] = notebook_id
+ assert self._root is not None
+ file = self._root / relative
+ try:
+ modified: float | None = file.stat().st_mtime
+ except OSError:
+ modified = None
+ return self._publish(file, modified, request_id=request_id)
+
+ def rename(
+ self,
+ notebook_id: protocol.NotebookId,
+ name: str,
+ *,
+ request_id: str | None = None,
+ ) -> None:
+ """Set a notebook's display name independently of its filename."""
+ record = self._host.notebooks[notebook_id]
+ self._names[notebook_id] = name
+ self._host.update_notebook(
+ replace(record, name=name), request_id=request_id
+ )
+
+ def forget(
+ self,
+ notebook_id: protocol.NotebookId,
+ *,
+ request_id: str | None = None,
+ ) -> None:
+ """Discard a notebook's catalog entry, stored ID, and display name."""
+ for path, known in list(self._ids.items()):
+ if known == notebook_id:
+ del self._ids[path]
+ self._names.pop(notebook_id, None)
+ self._host.remove_notebook(notebook_id, request_id=request_id)
+
+ def notebook_for(self, path: str | None) -> protocol.Notebook | None:
+ """Look up a cataloged notebook by file path."""
+ if path is None:
+ return None
+ relative = self._relative(Path(path))
+ if relative is None or relative not in self._ids:
+ return None
+ return self._host.notebooks.get(self._ids[relative])
+
+ def file_of(self, notebook_id: protocol.NotebookId) -> Path | None:
+ """Return a notebook's absolute file path, if available."""
+ record = self._host.notebooks.get(notebook_id)
+ if record is None or record.path is None or self._root is None:
+ return None
+ return self._root / record.path
+
+ def _publish(
+ self,
+ file: Path,
+ modified: float | None,
+ *,
+ request_id: str | None = None,
+ ) -> protocol.Notebook | None:
+ relative = self._relative(file)
+ if relative is None:
+ return None
+ notebook_id = self._ids.get(relative)
+ if notebook_id is None:
+ notebook_id = mint(protocol.NotebookId, "nb")
+ self._ids[relative] = notebook_id
+ record = protocol.Notebook(
+ id=notebook_id,
+ project_id=self.project_id,
+ path=str(relative),
+ name=self._names.get(notebook_id, relative.stem),
+ operations=[op for op in OPERATIONS if op != "notebook.create"],
+ updated_at=None
+ if modified is None
+ else datetime.fromtimestamp(modified, tz=timezone.utc),
+ )
+ if notebook_id in self._host.notebooks:
+ self._host.update_notebook(record, request_id=request_id)
+ else:
+ backend = self._make_backend(notebook_id)
+ self._host.add_notebook(record, backend, request_id=request_id)
+ return record
+
+ def _exists(self, notebook: protocol.Notebook) -> bool:
+ file = self.file_of(notebook.id)
+ return file is not None and file.exists()
+
+ def _relative(self, file: Path) -> Path | None:
+ """Return the root-relative path, or `None` outside the project."""
+ if self._root is None:
+ return None
+ if not file.is_absolute():
+ file = self._root / file
+ try:
+ return file.resolve().relative_to(self._root.resolve())
+ except ValueError:
+ return None
+
+
+def _root_of(workspace: NotebookWorkspace) -> Path | None:
+ if workspace.directory is not None:
+ return Path(workspace.directory)
+ single = workspace.single_file()
+ if single is not None:
+ return Path(single.path).parent
+ return None
diff --git a/marimo/_server/host/lifespan.py b/marimo/_server/host/lifespan.py
new file mode 100644
index 0000000000..84e5e29b2c
--- /dev/null
+++ b/marimo/_server/host/lifespan.py
@@ -0,0 +1,51 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Host API startup and shutdown."""
+
+from __future__ import annotations
+
+import contextlib
+import secrets
+from typing import TYPE_CHECKING
+
+from marimo import _loggers
+from marimo._server.api.deps import AppStateBase
+from marimo._server.host.bridge import SessionBridge
+from marimo._server.host.context import HostContext
+from marimo._server.host.record import HostRecordFile, host_url
+from marimo._session.model import SessionMode
+
+if TYPE_CHECKING:
+ from collections.abc import AsyncIterator
+
+ from starlette.applications import Starlette
+
+LOGGER = _loggers.marimo_logger()
+
+
+async def host(app: Starlette) -> AsyncIterator[None]:
+ """Initialize the host API and discovery record in edit mode."""
+ state = AppStateBase.from_app(app)
+ if state.mode is not SessionMode.EDIT:
+ yield
+ return
+
+ bridge = SessionBridge(state.session_manager)
+ bridge.open()
+ token = secrets.token_urlsafe(32)
+ server = state.server.config
+ url = host_url(server.host, server.port, state.base_url)
+ app.state.host_context = HostContext(
+ bridge=bridge, token=token, port=server.port
+ )
+ record = HostRecordFile(url=url, token=token)
+ try:
+ record.write()
+ except Exception as e:
+ LOGGER.warning("Could not write the host record: %s", e)
+ try:
+ yield
+ finally:
+ record.remove()
+ bridge.close()
+ app.state.host_context = None
diff --git a/marimo/_server/host/middleware.py b/marimo/_server/host/middleware.py
new file mode 100644
index 0000000000..5fc706f745
--- /dev/null
+++ b/marimo/_server/host/middleware.py
@@ -0,0 +1,111 @@
+# 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.
+"""
+
+from __future__ import annotations
+
+import hmac
+from ipaddress import IPv6Address, ip_address
+from typing import TYPE_CHECKING
+
+from starlette.requests import Request
+
+from marimo import _loggers
+from marimo._server.host import HOST_API_PATH
+from marimo._server.host.api import build_app, problem
+
+if TYPE_CHECKING:
+ from starlette.types import ASGIApp, Receive, Scope, Send
+
+LOGGER = _loggers.marimo_logger()
+
+
+class HostApiMiddleware:
+ """Authenticate and route host API requests."""
+
+ def __init__(self, app: ASGIApp, *, base_url: str = "") -> None:
+ self.app = app
+ self.prefix = base_url + HOST_API_PATH
+ self.host_app = build_app()
+
+ async def __call__(
+ self, scope: Scope, receive: Receive, send: Send
+ ) -> None:
+ if scope["type"] != "http" or not self._is_host_path(scope["path"]):
+ await self.app(scope, receive, send)
+ return
+
+ request = Request(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 client is None or not _is_loopback(client[0]):
+ response = problem(
+ 403, "forbidden", "The host API answers only this machine"
+ )
+ elif not _host_header_ok(request.headers.get("host"), context.port):
+ # Reject remote domain names to prevent DNS rebinding attacks.
+ response = problem(
+ 403, "forbidden", "The host API answers only its own address"
+ )
+ elif not _bearer_matches(
+ request.headers.get("Authorization"), context.token
+ ):
+ response = problem(
+ 401, "unauthorized", "Send the host record's token as a bearer"
+ )
+ else:
+ scope = {**scope, "root_path": self.prefix}
+ try:
+ await self.host_app(scope, receive, send)
+ except Exception:
+ LOGGER.exception("The host API failed on %s", scope["path"])
+ response = problem(500, "internal", "The host failed")
+ await response(scope, receive, send)
+ return
+ await response(scope, receive, send)
+
+ def _is_host_path(self, path: str) -> bool:
+ return path == self.prefix or path.startswith(self.prefix + "/")
+
+
+def _is_loopback(host: str) -> bool:
+ if host == "localhost":
+ return True
+ try:
+ address = ip_address(host)
+ except ValueError:
+ return False
+ if isinstance(address, IPv6Address) and address.ipv4_mapped is not None:
+ address = address.ipv4_mapped
+ return address.is_loopback
+
+
+def _host_header_ok(header: str | None, port: int) -> bool:
+ """Check that the Host header names a loopback address and server port."""
+ if header is None:
+ return False
+ if header.startswith("["):
+ name, _, after = header.partition("]")
+ name = name[1:]
+ given = after[1:] if after.startswith(":") else ""
+ else:
+ name, _, given = header.partition(":")
+ if not _is_loopback(name):
+ return False
+ if given == "":
+ return port == 80
+ return given.isdigit() and int(given) == port
+
+
+def _bearer_matches(authorization: str | None, token: str) -> bool:
+ if authorization is None:
+ return False
+ scheme, _, credentials = authorization.partition(" ")
+ if scheme.lower() != "bearer":
+ return False
+ return hmac.compare_digest(credentials.strip(), token)
diff --git a/marimo/_server/host/record.py b/marimo/_server/host/record.py
new file mode 100644
index 0000000000..f8bcd31fed
--- /dev/null
+++ b/marimo/_server/host/record.py
@@ -0,0 +1,94 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Host discovery records with the API URL, token, and process identity."""
+
+from __future__ import annotations
+
+import atexit
+import os
+import tempfile
+from datetime import datetime, timezone
+from uuid import uuid4
+
+import msgspec
+
+from marimo import _loggers
+from marimo._core import protocol
+from marimo._server.host import HOST_API_PATH
+from marimo._utils.xdg import marimo_state_dir
+
+LOGGER = _loggers.marimo_logger()
+
+
+def host_url(host: str, port: int, base_url: str) -> str:
+ """Build a loopback URL for the host API."""
+ loopback = "[::1]" if host.strip("[]") == "::1" else "127.0.0.1"
+ return f"http://{loopback}:{port}{base_url}{HOST_API_PATH}"
+
+
+def _process_started_at() -> datetime:
+ try:
+ import psutil
+
+ started = psutil.Process(os.getpid()).create_time()
+ return datetime.fromtimestamp(started, tz=timezone.utc)
+ except Exception:
+ # The fallback allows discovery but cannot verify process identity.
+ return datetime.now(timezone.utc)
+
+
+class HostRecordFile:
+ """A discovery record written at startup and removed at shutdown."""
+
+ def __init__(self, *, url: str, token: str) -> None:
+ self._record = protocol.HostRecord(
+ version=1,
+ process=protocol.Process(
+ pid=os.getpid(), started_at=_process_started_at()
+ ),
+ name="marimo",
+ url=url,
+ token=token,
+ )
+ self._path = marimo_state_dir() / "hosts-v1" / f"{uuid4()}.json"
+ self._written = False
+
+ def write(self) -> None:
+ """Write atomically, with owner-only access on POSIX."""
+ directory = self._path.parent
+ directory.mkdir(parents=True, exist_ok=True)
+ if os.name == "posix":
+ os.chmod(directory, 0o700)
+
+ data = msgspec.json.format(msgspec.json.encode(self._record))
+ fd, tmp_path = tempfile.mkstemp(dir=str(directory), suffix=".tmp")
+ try:
+ try:
+ os.write(fd, data)
+ finally:
+ os.close(fd)
+ if os.name == "posix":
+ os.chmod(tmp_path, 0o600)
+ os.replace(tmp_path, self._path)
+ except Exception:
+ try:
+ os.unlink(tmp_path)
+ except OSError:
+ pass
+ raise
+
+ self._written = True
+ atexit.register(self.remove)
+ LOGGER.debug("Wrote host record %s", self._path)
+
+ def remove(self) -> None:
+ """Remove the record. Safe to call more than once."""
+ if not self._written:
+ return
+ self._written = False
+ try:
+ self._path.unlink(missing_ok=True)
+ LOGGER.debug("Removed host record %s", self._path)
+ except OSError as e:
+ LOGGER.warning(
+ "Could not remove host record %s: %s", self._path, e
+ )
diff --git a/marimo/_server/host/translate.py b/marimo/_server/host/translate.py
new file mode 100644
index 0000000000..4e3e4af8f4
--- /dev/null
+++ b/marimo/_server/host/translate.py
@@ -0,0 +1,310 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Kernel notifications translated into runs and their member executions."""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import json
+import re
+from dataclasses import dataclass, field
+
+from marimo._core import backend as be, protocol
+from marimo._messaging.cell_output import CellChannel
+from marimo._messaging.errors import (
+ Error,
+ MarimoExceptionRaisedError,
+ MarimoInterruptionError,
+ MarimoSyntaxError,
+ UnknownError,
+)
+from marimo._messaging.notification import (
+ CellNotification,
+ CompletedRunNotification,
+ ExecutionNotification,
+ InterruptedNotification,
+ NotificationMessage,
+)
+from marimo._messaging.tracebacks import is_code_highlighting
+from marimo._runtime.scratch import SCRATCH_CELL_ID
+
+
+@dataclass
+class _Execution:
+ id: protocol.ExecutionId
+ cell_id: str
+ ended: bool = False
+ reported: bool = False
+ outcome: protocol.Outcome = field(
+ default_factory=lambda: protocol.ValueOutcome(None)
+ )
+ errors: list[Error] = field(default_factory=list)
+ seq: int = 0
+
+
+class RunTranslator:
+ """Track evaluations within one bounded reactive cycle."""
+
+ def __init__(self, run_id: protocol.RunId, code: str | None) -> None:
+ self.run_id = run_id
+ self._code = code
+ self._finished = False
+ self.completed = False
+ self.interrupted = False
+ self._failed = False
+ self._error: protocol.Error | None = None
+ self._executions: dict[str, _Execution] = {}
+
+ def feed(self, notification: NotificationMessage) -> list[be.Message]:
+ """Translate an attempt's lifecycle and output by its kernel identity."""
+ if isinstance(notification, InterruptedNotification):
+ if notification.run_id == self.run_id and not self._finished:
+ self.interrupted = True
+ return []
+ if isinstance(notification, CompletedRunNotification):
+ if notification.run_id == self.run_id and not self._finished:
+ self.completed = True
+ self.interrupted |= notification.outcome == "interrupted"
+ self._failed |= notification.outcome == "failed"
+ if notification.error and notification.outcome == "failed":
+ self._error = _describe(UnknownError(notification.error))
+ return []
+ if not isinstance(
+ notification, (CellNotification, ExecutionNotification)
+ ):
+ return []
+ if notification.run_id != self.run_id:
+ return []
+ if isinstance(notification, ExecutionNotification):
+ if self._finished:
+ return []
+ if notification.phase == "planned":
+ if notification.execution_id in self._executions:
+ return []
+ return [self._plan(notification)]
+ execution = self._executions.get(notification.execution_id)
+ if execution is None or execution.ended:
+ return []
+ if notification.phase == "running":
+ return [be.Status(execution.id, "running")]
+ return self._conclude(execution)
+
+ execution = self._executions.get(notification.execution_id or "")
+ if execution is None:
+ return []
+ out = self._console(execution, notification)
+ if execution.ended or self._finished:
+ return out
+ if notification.output is not None:
+ output = notification.output
+ if output.channel == CellChannel.MARIMO_ERROR and isinstance(
+ output.data, list
+ ):
+ execution.errors.extend(output.data)
+ elif output.channel == CellChannel.OUTPUT:
+ text = (
+ output.data
+ if isinstance(output.data, str)
+ else json.dumps(output.data)
+ )
+ execution.outcome = protocol.ValueOutcome(
+ None
+ if output.mimetype == "text/plain" and text == ""
+ else protocol.DisplayData(
+ mimetype=str(output.mimetype), data=text
+ )
+ )
+ execution.reported = True
+ out.append(be.Concluded(execution.id, execution.outcome))
+ return out
+
+ def _plan(self, notification: ExecutionNotification) -> be.Planned:
+ execution = _Execution(
+ protocol.ExecutionId(f"{self.run_id}-{len(self._executions) + 1}"),
+ notification.cell_id,
+ )
+ self._executions[notification.execution_id] = execution
+ parent = self._executions.get(notification.caused_by or "")
+ code = notification.code or ""
+ return be.Planned(
+ self.run_id,
+ (
+ be.PlannedExecution(
+ execution.id,
+ None
+ if execution.cell_id == SCRATCH_CELL_ID
+ else execution.cell_id,
+ hashlib.sha256(code.encode()).hexdigest(),
+ code if execution.cell_id == SCRATCH_CELL_ID else None,
+ caused_by=parent.id if parent is not None else None,
+ ),
+ ),
+ )
+
+ def _conclude(
+ self,
+ execution: _Execution,
+ *,
+ error: protocol.Error | None = None,
+ interrupted: bool = False,
+ ) -> list[be.Message]:
+ if execution.ended:
+ return []
+ previous = execution.outcome
+ exceptions = [
+ e
+ for e in execution.errors
+ if not isinstance(e, MarimoInterruptionError)
+ ]
+ if error is not None:
+ execution.outcome = protocol.ErrorOutcome(error)
+ elif exceptions:
+ execution.outcome = protocol.ErrorOutcome(_describe(exceptions[0]))
+ elif interrupted or execution.errors:
+ execution.outcome = protocol.InterruptedOutcome()
+ execution.ended = True
+ out: list[be.Message] = []
+ if not execution.reported or execution.outcome != previous:
+ out.append(be.Concluded(execution.id, execution.outcome))
+ out.append(be.Status(execution.id, "completed"))
+ return out
+
+ def finish(
+ self, *, error: protocol.Error | None = None
+ ) -> list[be.Message]:
+ """Close the cycle after the kernel's completion boundary."""
+ if self._finished:
+ return []
+ self._finished = True
+ error = error or self._error
+ out: list[be.Message] = []
+ if self._code is not None and not self._executions:
+ out.append(
+ self._plan(
+ ExecutionNotification(
+ execution_id="unsubmitted",
+ cell_id=SCRATCH_CELL_ID,
+ run_id=self.run_id,
+ phase="planned",
+ code=self._code,
+ )
+ )
+ )
+ for execution in self._executions.values():
+ out.extend(
+ self._conclude(
+ execution, error=error, interrupted=self.interrupted
+ )
+ )
+ outcome: protocol.RunOutcome = "succeeded"
+ if (
+ error is not None
+ or self._failed
+ or any(
+ isinstance(e.outcome, protocol.ErrorOutcome)
+ for e in self._executions.values()
+ )
+ ):
+ outcome = "failed"
+ if self.interrupted or any(
+ isinstance(e.outcome, protocol.InterruptedOutcome)
+ for e in self._executions.values()
+ ):
+ outcome = "interrupted"
+ out.append(be.Done(self.run_id, outcome))
+ return out
+
+ def _console(
+ self, execution: _Execution, notification: CellNotification
+ ) -> list[be.Message]:
+ if notification.console is None:
+ return []
+ entries = (
+ notification.console
+ if isinstance(notification.console, list)
+ else [notification.console]
+ )
+ out: list[be.Message] = []
+ for entry in entries:
+ if entry is None or entry.channel not in (
+ CellChannel.STDOUT,
+ CellChannel.STDERR,
+ ):
+ continue
+ out.append(
+ be.Produced(
+ protocol.Console(
+ id=protocol.ItemId(f"{execution.id}-{execution.seq}"),
+ execution_id=execution.id,
+ seq=execution.seq,
+ name="stdout"
+ if entry.channel == CellChannel.STDOUT
+ else "stderr",
+ text=_plain(str(entry.data)),
+ )
+ )
+ )
+ execution.seq += 1
+ return out
+
+
+def _plain(text: str) -> str:
+ """Remove marimo's HTML syntax highlighting from console text."""
+ if not is_code_highlighting(text):
+ return text
+ return html.unescape(re.sub(r"<[^>]+>", "", text))
+
+
+def _describe(error: Error) -> protocol.Error:
+ """Convert a kernel error to a host protocol error."""
+ if isinstance(error, MarimoExceptionRaisedError):
+ traceback = None
+ if error.traceback:
+ traceback = protocol.DisplayData(
+ mimetype="text/html"
+ if is_code_highlighting(error.traceback)
+ else "text/plain",
+ data=error.traceback,
+ )
+ return protocol.Error(
+ kind="exception",
+ name=error.exception_type,
+ message=error.msg,
+ traceback=traceback,
+ source="marimo",
+ severity="error",
+ range=None,
+ related=[],
+ )
+ if isinstance(error, MarimoSyntaxError):
+ return protocol.Error(
+ kind="syntax",
+ name=None,
+ message=error.msg,
+ traceback=None,
+ source="marimo",
+ severity="error",
+ range=None,
+ related=[],
+ )
+ if isinstance(error, UnknownError):
+ return protocol.Error(
+ kind="internal",
+ name=error.error_type,
+ message=error.msg,
+ traceback=None,
+ source="marimo",
+ severity="error",
+ range=None,
+ related=[],
+ )
+ return protocol.Error(
+ kind="internal",
+ name=None,
+ message=error.describe(),
+ traceback=None,
+ source="marimo",
+ severity="error",
+ range=None,
+ related=[],
+ )
diff --git a/marimo/_server/main.py b/marimo/_server/main.py
index f78f38852b..ac98876be0 100644
--- a/marimo/_server/main.py
+++ b/marimo/_server/main.py
@@ -26,6 +26,7 @@ from marimo._server.api.middleware import (
)
from marimo._server.api.router import build_routes
from marimo._server.errors import handle_error
+from marimo._server.host.middleware import HostApiMiddleware
from marimo._server.lsp import LspServer
from marimo._server.registry import MIDDLEWARE_REGISTRY
from marimo._utils.http import (
@@ -59,7 +60,10 @@ def create_starlette_app(
skew_protection: bool = True,
timeout: float | None = None,
) -> Starlette:
- final_middlewares: list[Middleware] = []
+ # Handle host API requests first to bypass the editor's middleware.
+ final_middlewares: list[Middleware] = [
+ Middleware(HostApiMiddleware, base_url=base_url)
+ ]
if allow_origins is None:
allow_origins = ("localhost", "127.0.0.1") + (
diff --git a/marimo/_server/session_manager.py b/marimo/_server/session_manager.py
index 3fbc0a6285..6e7b9749bd 100644
--- a/marimo/_server/session_manager.py
+++ b/marimo/_server/session_manager.py
@@ -168,6 +168,11 @@ class SessionManager:
self.watch = watch
self._file_change_coordinator = self._create_file_change_coordinator()
+ @property
+ def event_bus(self) -> SessionEventBus:
+ """Session lifecycle notifications."""
+ return self._event_bus
+
@property
def auth_token(self) -> AuthToken:
"""Get the auth token."""
diff --git a/marimo/_server/start.py b/marimo/_server/start.py
index aac6560d4f..c3ccbb6b1d 100644
--- a/marimo/_server/start.py
+++ b/marimo/_server/start.py
@@ -22,6 +22,7 @@ from marimo._server.api import lifespans
from marimo._server.config import (
StarletteServerStateInit,
)
+from marimo._server.host.lifespan import host as host_lifespan
from marimo._server.lsp import CompositeLspServer, NoopLspServer
from marimo._server.main import create_starlette_app
from marimo._server.registry import LIFESPAN_REGISTRY
@@ -346,6 +347,7 @@ def start(
lifespans.tool_manager,
lifespans.server_registry,
lifespans.reap_subprocesses,
+ host_lifespan,
*LIFESPAN_REGISTRY.get_all(),
]
diff --git a/marimo/_session/notebook/storage.py b/marimo/_session/notebook/storage.py
index f1e16666fe..b5d379a97b 100644
--- a/marimo/_session/notebook/storage.py
+++ b/marimo/_session/notebook/storage.py
@@ -3,6 +3,7 @@
from __future__ import annotations
+import os
from pathlib import Path
from typing import Protocol
@@ -12,6 +13,23 @@ from marimo._utils.http import HTTPException, HTTPStatus
LOGGER = _loggers.marimo_logger()
+def rename_no_replace(source: Path, target: Path) -> None:
+ """Move a file without replacing an existing destination.
+
+ On POSIX, linking claims the destination atomically before removing the
+ source. Unlike `rename`, it cannot overwrite a concurrently created file.
+ """
+ if os.name == "nt":
+ source.rename(target)
+ return
+ os.link(source, target)
+ try:
+ source.unlink()
+ except OSError:
+ target.unlink()
+ raise
+
+
class StorageInterface(Protocol):
"""Interface for storage operations."""
@@ -144,7 +162,7 @@ class FilesystemStorage(StorageInterface):
new_path = _ensure_path(new_path)
self.ensure_parent_dirs(new_path)
try:
- old_path.rename(new_path)
+ rename_no_replace(old_path, new_path)
except Exception as err:
raise HTTPException(
status_code=HTTPStatus.SERVER_ERROR,
diff --git a/marimo/_session/session.py b/marimo/_session/session.py
index 7727b6fbef..53f6fe6fcc 100644
--- a/marimo/_session/session.py
+++ b/marimo/_session/session.py
@@ -9,12 +9,12 @@ from __future__ import annotations
import asyncio
import contextlib
-import secrets
from typing import TYPE_CHECKING
from uuid import uuid4
from marimo import _loggers
from marimo._config.manager import MarimoConfigManager, ScriptConfigManager
+from marimo._core.ids import mint
from marimo._messaging.notebook.document import NotebookDocument
from marimo._messaging.notification import (
NotificationMessage,
@@ -77,17 +77,10 @@ if TYPE_CHECKING:
LOGGER = _loggers.marimo_logger()
_DEFAULT_TTL_SECONDS = 120
-_SESSION_ID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz"
__all__ = ["Session", "SessionImpl"]
-def _new_stable_session_id() -> StableSessionId:
- """Match Hub's session IDs: sess- plus 80 random bits in Crockford Base32."""
- body = "".join(secrets.choice(_SESSION_ID_ALPHABET) for _ in range(16))
- return StableSessionId(f"sess-{body}")
-
-
class SessionImpl(Session):
"""A client session.
@@ -251,7 +244,7 @@ class SessionImpl(Session):
"""Initialize kernel and client connection to it."""
# The notebook's creation key is used to find resumable sessions.
self.initialization_id = initialization_id
- self._stable_id = _new_stable_session_id()
+ self._stable_id = mint(StableSessionId, "sess")
self.app_file_manager = app_file_manager
self.room = Room()
self._kernel_manager = kernel_manager
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 3b8013da27..d85c71402a 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -461,8 +461,9 @@ components:
\ appends, [] clears, None unchanged.\n status: Execution status (idle/running/stale/queued/disabled-transitively).\n\
\ stale_inputs: Whether cell has stale inputs from changed dependencies.\n\
\ run_id: Execution run ID for tracing. Auto-set from context.\n \
- \ serialization: Top-level reusability hint. UNSET unchanged, None clears,\
- \ str sets.\n timestamp: Creation timestamp, auto-set."
+ \ execution_id: Evaluation of this cell producing the update, when known.\n\
+ \ serialization: Top-level reusability hint. UNSET unchanged, None\
+ \ clears, str sets.\n timestamp: Creation timestamp, auto-set."
properties:
cell_id:
$ref: '#/components/schemas/CellId'
@@ -474,6 +475,11 @@ components:
- $ref: '#/components/schemas/CellOutput'
- type: 'null'
default: null
+ execution_id:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
op:
enum:
- cell-op
@@ -841,16 +847,22 @@ components:
title: ColumnStats
type: object
CompletedRunNotification:
- description: "Run of submitted cells and descendants completed.\n\n Attributes:\n\
- \ run_id: Correlation ID echoed from the command that triggered\n \
- \ this completion. `None` for handlers that don't take a\n \
- \ `run_id` (everything except `handle_execute_scratchpad`\n \
- \ today). Consumers that want to wait for a specific command's\n \
- \ completion filter on this field."
+ description: The command's reactive cycle ended, after its console was flushed.
properties:
+ error:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
op:
enum:
- completed-run
+ outcome:
+ default: succeeded
+ enum:
+ - failed
+ - interrupted
+ - succeeded
run_id:
anyOf:
- type: string
@@ -2005,8 +2017,13 @@ components:
\ `CompletedRunNotification` emitted at the end of this command\n \
\ carries the same `run_id` so a caller holding a\n `ScratchCellListener`\
\ can filter for *its* completion and\n ignore `CompletedRun` events\
- \ from unrelated commands on the\n same session."
+ \ from unrelated commands on the\n same session.\n allow_stdin:\
+ \ Whether code may request interactive input. When false,\n input\
+ \ reads receive EOF for the duration of this command."
properties:
+ allowStdin:
+ default: true
+ type: boolean
cellOutputs:
anyOf:
- $ref: '#/components/schemas/CellOutputs'
@@ -2041,6 +2058,9 @@ components:
type: object
ExecuteScratchpadRequest:
properties:
+ allowStdin:
+ default: true
+ type: boolean
cellOutputs:
anyOf:
- $ref: '#/components/schemas/CellOutputs'
@@ -2087,6 +2107,47 @@ components:
- type
title: ExecuteStaleCellsCommand
type: object
+ ExecutionNotification:
+ description: "An attempt's lifecycle, independent of a cell's displayed status.\n\
+ \n `planned` supplies the source and identity before output is reported.\n\
+ \ `running` means evaluation began. `completed` follows the final output\n\
+ \ and errors, including for attempts that never ran. Buffered and background\n\
+ \ console output may still arrive with the completed attempt's identity."
+ properties:
+ caused_by:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
+ cell_id:
+ type: string
+ code:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
+ execution_id:
+ type: string
+ op:
+ enum:
+ - execution
+ phase:
+ enum:
+ - completed
+ - planned
+ - running
+ run_id:
+ anyOf:
+ - type: string
+ - type: 'null'
+ required:
+ - op
+ - execution_id
+ - cell_id
+ - run_id
+ - phase
+ title: ExecutionNotification
+ type: object
ExportAsHTMLRequest:
description: "Request a static HTML export.\n\n `layout` carries the current\
\ client layout. An omitted field reads the\n saved layout file, `null`\
@@ -2926,6 +2987,10 @@ components:
op:
enum:
- interrupted
+ run_id:
+ anyOf:
+ - type: string
+ - type: 'null'
required:
- op
title: InterruptedNotification
@@ -3277,6 +3342,7 @@ components:
notification:
anyOf:
- $ref: '#/components/schemas/CellNotification'
+ - $ref: '#/components/schemas/ExecutionNotification'
- $ref: '#/components/schemas/FunctionCallResultNotification'
- $ref: '#/components/schemas/UIElementMessageNotification'
- $ref: '#/components/schemas/ModelLifecycleNotification'
@@ -3336,6 +3402,7 @@ components:
datasets: '#/components/schemas/DatasetsNotification'
environment-operation: '#/components/schemas/EnvironmentOperationNotification'
environment-state: '#/components/schemas/EnvironmentStateNotification'
+ execution: '#/components/schemas/ExecutionNotification'
focus-cell: '#/components/schemas/FocusCellNotification'
function-call-result: '#/components/schemas/FunctionCallResultNotification'
interrupted: '#/components/schemas/InterruptedNotification'
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 378529d3dc..f86f93e852 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -4137,6 +4137,7 @@ export interface components {
* status: Execution status (idle/running/stale/queued/disabled-transitively).
* stale_inputs: Whether cell has stale inputs from changed dependencies.
* run_id: Execution run ID for tracing. Auto-set from context.
+ * execution_id: Evaluation of this cell producing the update, when known.
* serialization: Top-level reusability hint. UNSET unchanged, None clears, str sets.
* timestamp: Creation timestamp, auto-set.
*/
@@ -4147,6 +4148,8 @@ export interface components {
| components["schemas"]["CellOutput"][]
| components["schemas"]["CellOutput"]
| null;
+ /** @default null */
+ execution_id?: string | null;
/** @enum {unknown} */
op: "cell-op";
/** @default null */
@@ -4352,18 +4355,18 @@ export interface components {
};
/**
* CompletedRunNotification
- * @description Run of submitted cells and descendants completed.
- *
- * Attributes:
- * run_id: Correlation ID echoed from the command that triggered
- * this completion. `None` for handlers that don't take a
- * `run_id` (everything except `handle_execute_scratchpad`
- * today). Consumers that want to wait for a specific command's
- * completion filter on this field.
+ * @description The command's reactive cycle ended, after its console was flushed.
*/
CompletedRunNotification: {
+ /** @default null */
+ error?: string | null;
/** @enum {unknown} */
op: "completed-run";
+ /**
+ * @default succeeded
+ * @enum {unknown}
+ */
+ outcome?: "failed" | "interrupted" | "succeeded";
/** @default null */
run_id?: string | null;
};
@@ -5059,8 +5062,12 @@ export interface components {
* `ScratchCellListener` can filter for *its* completion and
* ignore `CompletedRun` events from unrelated commands on the
* same session.
+ * allow_stdin: Whether code may request interactive input. When false,
+ * input reads receive EOF for the duration of this command.
*/
ExecuteScratchpadCommand: {
+ /** @default true */
+ allowStdin?: boolean;
/** @default null */
cellOutputs?: components["schemas"]["CellOutputs"] | null;
code: string;
@@ -5075,6 +5082,8 @@ export interface components {
};
/** ExecuteScratchpadRequest */
ExecuteScratchpadRequest: {
+ /** @default true */
+ allowStdin?: boolean;
/** @default null */
cellOutputs?: components["schemas"]["CellOutputs"] | null;
code: string;
@@ -5101,6 +5110,28 @@ export interface components {
/** @enum {unknown} */
type: "execute-stale-cells";
};
+ /**
+ * ExecutionNotification
+ * @description An attempt's lifecycle, independent of a cell's displayed status.
+ *
+ * `planned` supplies the source and identity before output is reported.
+ * `running` means evaluation began. `completed` follows the final output
+ * and errors, including for attempts that never ran. Buffered and background
+ * console output may still arrive with the completed attempt's identity.
+ */
+ ExecutionNotification: {
+ /** @default null */
+ caused_by?: string | null;
+ cell_id: string;
+ /** @default null */
+ code?: string | null;
+ execution_id: string;
+ /** @enum {unknown} */
+ op: "execution";
+ /** @enum {unknown} */
+ phase: "completed" | "planned" | "running";
+ run_id: string | null;
+ };
/**
* ExportAsHTMLRequest
* @description Request a static HTML export.
@@ -5594,6 +5625,7 @@ export interface components {
InterruptedNotification: {
/** @enum {unknown} */
op: "interrupted";
+ run_id?: string | null;
};
/** InvokeAiToolRequest */
InvokeAiToolRequest: {
@@ -5802,6 +5834,7 @@ export interface components {
| components["schemas"]["UnknownError"];
notification:
| components["schemas"]["CellNotification"]
+ | components["schemas"]["ExecutionNotification"]
| components["schemas"]["FunctionCallResultNotification"]
| components["schemas"]["UIElementMessageNotification"]
| components["schemas"]["ModelLifecycleNotification"]
diff --git a/tests/_messaging/test_console_output_worker.py b/tests/_messaging/test_console_output_worker.py
index 33e4794b3a..d4b49db55e 100644
--- a/tests/_messaging/test_console_output_worker.py
+++ b/tests/_messaging/test_console_output_worker.py
@@ -12,13 +12,59 @@ from marimo._messaging.console_output_worker import (
FlushMarker,
_add_output_to_buffer,
_can_merge_outputs,
+ _flush_outputs,
_write_console_output,
buffered_writer,
)
+from marimo._messaging.context import run_id_context
from tests._messaging.mocks import MockStream
class TestConsoleOutputWorker:
+ def test_repeated_evaluations_keep_separate_buffered_output(self) -> None:
+ buffered = {}
+ for execution_id in ("first", "second"):
+ _add_output_to_buffer(
+ ConsoleMsg(
+ CellChannel.STDOUT,
+ "cell1",
+ execution_id,
+ "text/plain",
+ run_id="same-run",
+ execution_id=execution_id,
+ ),
+ buffered,
+ )
+ stream = MockStream()
+ _flush_outputs(buffered, stream)
+ assert [
+ (n.execution_id, n.console.data) for n in stream.cell_notifications
+ ] == [
+ ("first", "first"),
+ ("second", "second"),
+ ]
+
+ def test_buffer_preserves_run_ids_across_execution_boundaries(
+ self,
+ ) -> None:
+ buffered = {}
+ for run_id in ("first", "second"):
+ with run_id_context(run_id):
+ _add_output_to_buffer(
+ ConsoleMsg(
+ CellChannel.STDOUT, "cell1", run_id, "text/plain"
+ ),
+ buffered,
+ )
+ stream = MockStream()
+ _flush_outputs(buffered, stream)
+ assert [
+ notification.run_id for notification in stream.cell_notifications
+ ] == [
+ "first",
+ "second",
+ ]
+
def test_can_merge_outputs(self) -> None:
# Same stream and mimetype should be mergeable
msg1 = ConsoleMsg(
diff --git a/tests/_runtime/test_execution_lifecycle.py b/tests/_runtime/test_execution_lifecycle.py
new file mode 100644
index 0000000000..31470d165e
--- /dev/null
+++ b/tests/_runtime/test_execution_lifecycle.py
@@ -0,0 +1,185 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Execution lifecycles emitted by the kernel."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from unittest.mock import patch
+
+import pytest
+from inline_snapshot import snapshot
+
+from marimo._messaging.notification import ExecutionNotification
+from marimo._runtime.commands import (
+ ExecuteCellsCommand,
+ ExecuteScratchpadCommand,
+)
+from marimo._runtime.kernel_request_handlers import KernelRequestHandlers
+from tests._messaging.mocks import MockStream
+
+if TYPE_CHECKING:
+ from tests.conftest import MockedKernel
+
+
[email protected]("code", ["3 * 3", "if !!!"])
+async def test_scratch_is_planned_before_compilation(
+ mocked_kernel: MockedKernel, code: str
+) -> None:
+ kernel = mocked_kernel.k
+ compile_cell = kernel._try_compiling_cell
+
+ def compile_after_planning(*args: Any, **kwargs: Any) -> Any:
+ messages = MockStream(mocked_kernel.stream).operations
+ assert [
+ (m["op"], m.get("phase"), m.get("code")) for m in messages
+ ] == [("execution", "planned", code)]
+ return compile_cell(*args, **kwargs)
+
+ with patch.object(
+ kernel, "_try_compiling_cell", side_effect=compile_after_planning
+ ):
+ await KernelRequestHandlers(kernel)._handle_execute_scratchpad(
+ ExecuteScratchpadCommand(code=code)
+ )
+
+
[email protected]("failed_code", ["if !!!", "1 / 0"])
+async def test_a_retry_has_its_own_identity_and_source(
+ mocked_kernel: MockedKernel, failed_code: str
+) -> None:
+ await KernelRequestHandlers(mocked_kernel.k)._handle_execute_scratchpad(
+ ExecuteScratchpadCommand(
+ run_id="retry",
+ notebook_cells=(),
+ code=(
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteCellsCommand\n"
+ f"await cm.get_context().execute_command(ExecuteCellsCommand(cell_ids=['child'], codes=[{failed_code!r}]))\n"
+ "await cm.get_context().execute_command(ExecuteCellsCommand(cell_ids=['child'], codes=['x = 42']))\n"
+ ),
+ )
+ )
+ messages = MockStream(mocked_kernel.stream).parsed_operations
+ attempts = [
+ m
+ for m in messages
+ if isinstance(m, ExecutionNotification) and m.cell_id == "child"
+ ]
+ planned = [m for m in attempts if m.phase == "planned"]
+ assert len({m.execution_id for m in planned}) == 2
+ assert [(m.phase, m.code) for m in attempts] == (
+ [("planned", failed_code)]
+ + ([] if failed_code == "if !!!" else [("running", None)])
+ + [
+ ("completed", None),
+ ("planned", "x = 42"),
+ ("running", None),
+ ("completed", None),
+ ]
+ )
+ assert {m.run_id for m in attempts} == {"retry"}
+
+
[email protected]("mode", ["edit", "run"])
+async def test_execution_source_is_private_in_app_mode(
+ mocked_kernel: MockedKernel, mode: str
+) -> None:
+ with patch("marimo._runtime.execution.get_mode", return_value=mode):
+ await KernelRequestHandlers(
+ mocked_kernel.k
+ )._handle_execute_scratchpad(
+ ExecuteScratchpadCommand(code="secret = 42")
+ )
+ attempts = [
+ m
+ for m in MockStream(mocked_kernel.stream).parsed_operations
+ if isinstance(m, ExecutionNotification)
+ ]
+ assert [m.code for m in attempts] == [
+ "secret = 42" if mode == "edit" else None,
+ None,
+ None,
+ ]
+
+
+async def test_skipped_attempt_completes_without_starting(
+ mocked_kernel: MockedKernel,
+) -> None:
+ await KernelRequestHandlers(mocked_kernel.k)._handle_execute_scratchpad(
+ ExecuteScratchpadCommand(
+ run_id="skipped",
+ notebook_cells=(),
+ code=(
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteCellsCommand\n"
+ "await cm.get_context().execute_command(ExecuteCellsCommand("
+ "cell_ids=['parent', 'child'], codes=['x = 1 / 0', 'y = x']))"
+ ),
+ )
+ )
+ messages = MockStream(mocked_kernel.stream).operations
+ child = [m for m in messages if m.get("cell_id") == "child"]
+ assert [m["phase"] for m in child if m["op"] == "execution"] == snapshot(
+ ["planned", "completed"]
+ )
+ planned = next(m for m in child if m.get("phase") == "planned")
+ error = next(m for m in child if m.get("output"))
+ assert error["execution_id"] == planned["execution_id"]
+ assert child[-1]["phase"] == "completed"
+
+
+async def test_nested_commands_can_evaluate_an_outer_queued_cell(
+ mocked_kernel: MockedKernel,
+) -> None:
+ inner = (
+ "x = 42\n"
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteCellsCommand\n"
+ "await cm.get_context().execute_command(ExecuteCellsCommand("
+ "cell_ids=['b'], codes=['print(x)']))"
+ )
+ await KernelRequestHandlers(mocked_kernel.k)._handle_execute_scratchpad(
+ ExecuteScratchpadCommand(
+ run_id="nested",
+ notebook_cells=(),
+ code=(
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteCellsCommand\n"
+ "await cm.get_context().execute_command(ExecuteCellsCommand("
+ f"cell_ids=['a', 'b'], codes=[{inner!r}, 'print(x)']))"
+ ),
+ )
+ )
+ attempts = [
+ m
+ for m in MockStream(mocked_kernel.stream).parsed_operations
+ if isinstance(m, ExecutionNotification) and m.cell_id == "b"
+ ]
+ assert [m.phase for m in attempts] == snapshot(
+ ["planned", "running", "completed", "planned", "running", "completed"]
+ )
+ assert len({m.execution_id for m in attempts}) == 2
+
+
[email protected]("second", ["y = 1 / 0", "raise KeyboardInterrupt"])
+async def test_skipped_attempt_can_report_multiple_errors(
+ mocked_kernel: MockedKernel, second: str
+) -> None:
+ await KernelRequestHandlers(mocked_kernel.k)._handle_execute_multiple(
+ ExecuteCellsCommand(
+ cell_ids=["a", "b", "c"],
+ codes=["x = 1 / 0", second, "z = x + y"],
+ )
+ )
+ messages = [
+ m
+ for m in MockStream(mocked_kernel.stream).operations
+ if m.get("cell_id") == "c"
+ ]
+ assert [
+ m["phase"] for m in messages if m["op"] == "execution"
+ ] == snapshot(["planned", "completed"])
+ errors = [m for m in messages if m.get("output")]
+ assert len(errors) == 2
+ planned = next(m for m in messages if m.get("phase") == "planned")
+ assert {m["execution_id"] for m in errors} == {planned["execution_id"]}
diff --git a/tests/_runtime/test_kernel_request_handlers.py b/tests/_runtime/test_kernel_request_handlers.py
index 9dd52da484..1b091d0b62 100644
--- a/tests/_runtime/test_kernel_request_handlers.py
+++ b/tests/_runtime/test_kernel_request_handlers.py
@@ -6,14 +6,99 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
-from marimo._runtime.commands import ModelCommand, ModelUpdateMessage
+from marimo._runtime.commands import (
+ ExecuteCellsCommand,
+ ExecuteScratchpadCommand,
+ ModelCommand,
+ ModelUpdateMessage,
+)
from marimo._runtime.kernel_request_handlers import KernelRequestHandlers
from marimo._types.ids import WidgetModelId
+from tests._messaging.mocks import MockStream
if TYPE_CHECKING:
from tests.conftest import MockedKernel
+async def test_nested_commands_complete_the_run_once(
+ mocked_kernel: MockedKernel,
+) -> None:
+ await KernelRequestHandlers(mocked_kernel.k)._handle_execute_scratchpad(
+ ExecuteScratchpadCommand(
+ run_id="outer",
+ notebook_cells=(),
+ code=(
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteCellsCommand\n"
+ "await cm.get_context().execute_command(ExecuteCellsCommand("
+ "cell_ids=['child'], codes=['x = 42']))"
+ ),
+ )
+ )
+ messages = MockStream(mocked_kernel.stream).operations
+ assert [m["run_id"] for m in messages if m["op"] == "completed-run"] == [
+ "outer"
+ ]
+ assert {m["run_id"] for m in messages if m["op"] == "cell-op"} == {"outer"}
+ assert messages[-1]["op"] == "completed-run"
+
+
+async def test_a_failed_command_flushes_before_completing(
+ mocked_kernel: MockedKernel,
+) -> None:
+ stream = MockStream(mocked_kernel.stream)
+ flushed = []
+
+ def flush() -> None:
+ flushed.append(list(stream.operations))
+
+ with (
+ patch.object(
+ mocked_kernel.k, "run", side_effect=RuntimeError("failed")
+ ),
+ patch.object(mocked_kernel.stream, "flush_console", side_effect=flush),
+ pytest.raises(RuntimeError, match="failed"),
+ ):
+ await KernelRequestHandlers(mocked_kernel.k)._handle_execute_multiple(
+ ExecuteCellsCommand(cell_ids=[], codes=[])
+ )
+ assert flushed == [[]]
+ assert [
+ (m["op"], m["outcome"], m["error"]) for m in stream.operations
+ ] == [("completed-run", "failed", "failed")]
+
+
+async def test_independent_task_does_not_own_the_enclosing_cycle(
+ mocked_kernel: MockedKernel,
+) -> None:
+ handlers = KernelRequestHandlers(mocked_kernel.k)
+ await handlers._handle_execute_scratchpad(
+ ExecuteScratchpadCommand(
+ run_id="outer",
+ notebook_cells=(),
+ code=(
+ "import asyncio\n"
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteScratchpadCommand\n"
+ "await asyncio.gather(cm.get_context().execute_command(\n"
+ " ExecuteScratchpadCommand(code='3 * 3', request=None)))\n"
+ "42"
+ ),
+ )
+ )
+ messages = MockStream(mocked_kernel.stream).operations
+ completed = [m for m in messages if m["op"] == "completed-run"]
+ assert len(completed) == 2
+ assert completed[0]["run_id"] != "outer"
+ assert completed[1]["run_id"] == "outer"
+ running = [
+ m["run_id"]
+ for m in messages
+ if m["op"] == "cell-op" and m["status"] == "running"
+ ]
+ assert running == ["outer", completed[0]["run_id"]]
+
+
class TestReceiveModelMessage:
@pytest.fixture
def model_command(self) -> ModelCommand:
@@ -78,3 +163,29 @@ class TestReceiveModelMessage:
await handlers._handle_receive_model_message(model_command)
mock_set_ui.assert_awaited_once()
+
+
+ "read",
+ [
+ "input('prompt')",
+ "__import__('builtins').input()",
+ "__import__('getpass').getpass()",
+ ],
+)
+async def test_noninteractive_scratch_input_is_scoped_to_the_command(
+ mocked_kernel: MockedKernel, read: str
+) -> None:
+ kernel = mocked_kernel.k
+ handlers = KernelRequestHandlers(kernel)
+ kernel.globals["observed"] = []
+ await handlers._handle_execute_scratchpad(
+ ExecuteScratchpadCommand(
+ code=f"try:\n {read}\nexcept EOFError:\n observed.append('EOF')",
+ allow_stdin=False,
+ )
+ )
+ await handlers._handle_execute_scratchpad(
+ ExecuteScratchpadCommand(code="observed.append(input('interactive'))")
+ )
+ assert kernel.globals["observed"] == ["EOF", "interactive"]
diff --git a/tests/_runtime/test_runtime.py b/tests/_runtime/test_runtime.py
index 943cea07e0..a76b6df60f 100644
--- a/tests/_runtime/test_runtime.py
+++ b/tests/_runtime/test_runtime.py
@@ -1689,19 +1689,18 @@ except NameError:
assert "C" not in k.globals
stream = MockStream(k.stream)
stderr = MockStderr(k.stderr)
+ errors = [
+ m["output"]["data"][0]["msg"]
+ for m in stream.operations
+ if m.get("output") and m["output"]["channel"] == "marimo-error"
+ ]
if k.execution_type == "strict":
- assert (
- "name `R` is referenced before definition."
- in stream.operations[-4]["output"]["data"][0]["msg"]
- )
- assert (
- "This cell wasn't run"
- in stream.operations[-1]["output"]["data"][0]["msg"]
- )
+ assert "name `R` is referenced before definition." in errors[0]
+ assert "This cell wasn't run" in errors[-1]
else:
assert (
"Name `C` is not defined. It was expected to be defined in"
- in stream.operations[-2]["output"]["data"][0]["msg"]
+ in errors[-1]
)
assert "NameError" in stderr.messages[0]
assert "NameError" in stderr.messages[-1]
@@ -1713,9 +1712,9 @@ except NameError:
# Has no errors
assert not k.errors
stream = MockStream(mocked_kernel.stream)
- (m1, m2, m3, m4) = stream.operations
- assert all(m["op"] == "cell-op" for m in stream.operations)
- assert all(m["cell_id"] == SCRATCH_CELL_ID for m in stream.operations)
+ messages = [m for m in stream.operations if m["op"] == "cell-op"]
+ (m1, m2, m3, m4) = messages
+ assert all(m["cell_id"] == SCRATCH_CELL_ID for m in messages)
assert m1["status"] == "queued"
assert m2["status"] == "running"
assert m3["status"] is None
@@ -1743,8 +1742,9 @@ except NameError:
# Has no errors
assert not k.errors
stream = MockStream(mocked_kernel.stream)
- messages = stream.operations
- output_message = messages[-2]
+ output_message = next(
+ m for m in reversed(stream.operations) if m.get("output")
+ )
assert (
output_message["output"]["data"] == "<pre class='text-xs'>20</pre>"
)
@@ -1771,8 +1771,9 @@ except NameError:
# Has no errors
assert not k.errors
stream = MockStream(mocked_kernel.stream)
- messages = stream.operations
- output_message = messages[-2]
+ output_message = next(
+ m for m in reversed(stream.operations) if m.get("output")
+ )
assert (
output_message["output"]["data"] == "<pre class='text-xs'>20</pre>"
)
@@ -2049,11 +2050,21 @@ except NameError:
assert (
len(cell_notifications) == 4
) # queued -> running -> output -> idle
- for cell_notification in cell_notifications:
- if cell_notification.status == "idle":
- assert cell_notification.run_id is None
- else:
- assert cell_notification.run_id is not None
+ assert cell_notifications[0].run_id is not None
+ assert (
+ len({notification.run_id for notification in cell_notifications})
+ == 1
+ )
+ assert cell_notifications[1].execution_id is not None
+ assert (
+ len(
+ {
+ notification.execution_id
+ for notification in cell_notifications[1:]
+ }
+ )
+ == 1
+ )
async def test_serialization_hint_cleared_only_on_demotion(
self, mocked_kernel: MockedKernel, exec_req: ExecReqProvider
diff --git a/tests/_runtime/test_trace.py b/tests/_runtime/test_trace.py
index 336ec76b6a..995175f335 100644
--- a/tests/_runtime/test_trace.py
+++ b/tests/_runtime/test_trace.py
@@ -277,22 +277,18 @@ class TestAppTrace:
stream_messages = MockStream(k.stream)
stderr_messages = MockStderr(k.stderr)
+ errors = {
+ m["cell_id"]: m["output"]["data"][0]["msg"]
+ for m in stream_messages.operations
+ if m.get("output") and m["output"]["channel"] == "marimo-error"
+ }
assert "C" not in k.globals
if k.execution_type == "strict":
- assert (
- "name `R` is referenced before definition."
- in stream_messages.operations[-4]["output"]["data"][0]["msg"]
- )
- assert (
- "This cell wasn't run"
- in stream_messages.operations[-1]["output"]["data"][0]["msg"]
- )
+ assert "name `R` is referenced before definition." in errors["0"]
+ assert "This cell wasn't run" in errors["1"]
else:
- assert (
- "Name `C` is not defined."
- in stream_messages.operations[-2]["output"]["data"][0]["msg"]
- )
+ assert "Name `C` is not defined." in errors["1"]
assert "NameError" in stderr_messages.messages[0]
assert "NameError" in stderr_messages.messages[-1]
diff --git a/tests/_server/host/conftest.py b/tests/_server/host/conftest.py
new file mode 100644
index 0000000000..b5fd12d4d2
--- /dev/null
+++ b/tests/_server/host/conftest.py
@@ -0,0 +1,155 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Session fakes for host backend tests."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+from marimo._core import backend as be
+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.types import KernelState
+
+
+class FakeSession:
+ """A session fake with a real scratchpad lock and event bus."""
+
+ def __init__(self, path: str | None = "/ws/forecasts.py") -> None:
+ self.scratchpad_lock = asyncio.Lock()
+ self.event_bus = SessionEventBus()
+ self.consumers: list[tuple[SessionConsumer, bool]] = []
+ self.commands: list[Any] = []
+ self.submitted = asyncio.Event()
+ self.interrupts = 0
+ self.closed = False
+ self.state = KernelState.RUNNING
+ self.exit_info: Any = None
+ self.app_file_manager = MagicMock()
+ self.app_file_manager.path = path
+ self.document = MagicMock()
+ self.document.cell_ids = []
+ self.document.cells = []
+ self.session_view = MagicMock()
+
+ def connect_consumer(
+ self, consumer: SessionConsumer, *, main: bool
+ ) -> None:
+ self.consumers.append((consumer, main))
+ consumer.on_attach(self, self.event_bus) # type: ignore[arg-type]
+
+ def instantiate(self, request: Any, *, http_request: Any) -> None:
+ del request, http_request
+
+ def put_control_request(self, request: Any, from_consumer_id: Any) -> None:
+ del from_consumer_id
+ self.commands.append(request)
+ self.submitted.set()
+
+ def try_interrupt(self) -> None:
+ self.interrupts += 1
+
+ def kernel_state(self) -> KernelState:
+ return self.state
+
+ def kernel_exit_info(self) -> Any:
+ return self.exit_info
+
+ def connection_state(self) -> ConnectionState:
+ return ConnectionState.OPEN
+
+ def close(self, *, graceful: bool = False) -> None:
+ del graceful
+ self.closed = True
+ for consumer, _ in self.consumers:
+ consumer.on_detach()
+ self.consumers.clear()
+
+ def broadcast(self, notification: Any) -> None:
+ """Send a notification to every consumer."""
+ message = serialize_kernel_message(notification)
+ for consumer, _ in list(self.consumers):
+ consumer.notify(message)
+
+
+class FakeManager:
+ """A session manager with configurable startup results and timing."""
+
+ def __init__(self) -> None:
+ self.sessions: dict[str, FakeSession] = {}
+ self.event_bus = SessionEventBus()
+ self.workspace: Any = MagicMock()
+ self.starts: list[dict[str, Any]] = []
+ self.next_session: Any = FakeSession()
+ self.started = asyncio.Event()
+ self.release = asyncio.Event()
+ self.release.set()
+
+ async def create_session(
+ self,
+ session_id: str,
+ session_consumer: SessionConsumer,
+ query_params: Any,
+ file_key: str,
+ auto_instantiate: bool,
+ *,
+ main: bool = True,
+ ) -> FakeSession:
+ del query_params
+ self.starts.append(
+ {
+ "file_key": file_key,
+ "auto_instantiate": auto_instantiate,
+ "main": main,
+ }
+ )
+ self.started.set()
+ await self.release.wait()
+ if isinstance(self.next_session, Exception):
+ raise self.next_session
+ session: FakeSession = self.next_session
+ self.sessions[session_id] = session
+ session.connect_consumer(session_consumer, main=main)
+ return session
+
+ def close_session(self, session_id: str) -> bool:
+ session = self.sessions.pop(session_id, None)
+ if session is None:
+ return False
+ session.close()
+ return True
+
+
+class Observed:
+ """Collects the messages a backend reports."""
+
+ def __init__(self) -> None:
+ self.messages: list[be.Message] = []
+ self.changed = asyncio.Event()
+
+ def __call__(self, message: be.Message) -> None:
+ self.messages.append(message)
+ self.changed.set()
+
+ async def wait_for(self, kind: type[be.Message]) -> None:
+ while not any(isinstance(message, kind) for message in self.messages):
+ self.changed.clear()
+ await asyncio.wait_for(self.changed.wait(), 5)
+
+ def kinds(self) -> list[str]:
+ return [type(m).__name__ for m in self.messages]
+
+
+def manager() -> FakeManager:
+ return FakeManager()
+
+
+def observed() -> Observed:
+ return Observed()
diff --git a/tests/_server/host/drive.py b/tests/_server/host/drive.py
new file mode 100644
index 0000000000..d589a15837
--- /dev/null
+++ b/tests/_server/host/drive.py
@@ -0,0 +1,155 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""ASGI test requests with incremental access to event streams.
+
+Direct ASGI requests let tests read events while a response remains open.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import TYPE_CHECKING, Any
+
+from marimo._server.host import HOST_API_PATH
+
+if TYPE_CHECKING:
+ from collections.abc import Callable, MutableMapping
+
+ from starlette.applications import Starlette
+
+PORT = 1234
+"""Server port used to validate the request's Host header."""
+
+AUTHORITY = f"127.0.0.1:{PORT}"
+LOOPBACK = ("127.0.0.1", 50000)
+
+
+class Response:
+ def __init__(self) -> None:
+ self.status = 0
+ self.headers: dict[str, str] = {}
+ self.records: list[dict[str, Any]] = []
+ self.body = b""
+ self.changed = asyncio.Event()
+ self._buffer = ""
+
+ def feed(self, chunk: bytes) -> None:
+ self.body += chunk
+ self._buffer += chunk.decode()
+ while "\n\n" in self._buffer:
+ raw, self._buffer = self._buffer.split("\n\n", 1)
+ self.records.append(parse(raw))
+ self.changed.set()
+
+ def json(self) -> Any:
+ return json.loads(self.body)
+
+ def names(self) -> list[str]:
+ return [r["event"] for r in self.records if "event" in r]
+
+
+def parse(raw: str) -> dict[str, Any]:
+ record: dict[str, Any] = {}
+ for line in raw.split("\n"):
+ if line.startswith(":"):
+ record["comment"] = line[1:].strip()
+ elif ":" in line:
+ field, _, value = line.partition(":")
+ record[field] = value.strip()
+ if "data" in record:
+ record["data"] = json.loads(record["data"])
+ return record
+
+
+def request(
+ app: Starlette,
+ method: str,
+ path: str,
+ *,
+ headers: dict[str, str] | None = None,
+ body: bytes = b"",
+ query: str = "",
+ client: tuple[str, int] = LOOPBACK,
+ host: str = AUTHORITY,
+) -> tuple[Response, asyncio.Task[None], Callable[[], None]]:
+ """Return the response, request task, and disconnect callback.
+
+ `path` is relative to the host API's prefix.
+ """
+ scope = {
+ "type": "http",
+ "asgi": {"version": "3.0"},
+ "http_version": "1.1",
+ "method": method,
+ "scheme": "http",
+ "path": HOST_API_PATH + path,
+ "raw_path": (HOST_API_PATH + path).encode(),
+ "query_string": query.encode(),
+ "root_path": "",
+ "headers": [
+ (b"host", host.encode()),
+ (b"content-type", b"application/json"),
+ *(
+ (k.lower().encode(), v.encode())
+ for k, v in (headers or {}).items()
+ ),
+ ],
+ "client": client,
+ "server": ("127.0.0.1", PORT),
+ "state": {},
+ }
+ response = Response()
+ receive_queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+ receive_queue.put_nowait(
+ {"type": "http.request", "body": body, "more_body": False}
+ )
+
+ async def receive() -> dict[str, Any]:
+ return await receive_queue.get()
+
+ async def send(message: MutableMapping[str, Any]) -> None:
+ if message["type"] == "http.response.start":
+ response.status = message["status"]
+ response.headers = {
+ k.decode(): v.decode() for k, v in message.get("headers", [])
+ }
+ elif message["type"] == "http.response.body":
+ response.feed(message.get("body", b""))
+
+ task = asyncio.get_running_loop().create_task(app(scope, receive, send))
+
+ def disconnect() -> None:
+ receive_queue.put_nowait({"type": "http.disconnect"})
+
+ return response, task, disconnect
+
+
+async def finished(
+ app: Starlette, method: str, path: str, **kwargs: Any
+) -> Response:
+ """Await a complete response to a non-streaming request."""
+ response, task, _ = request(app, method, path, **kwargs)
+ await asyncio.wait_for(task, 5)
+ return response
+
+
+async def wait_for(
+ response: Response,
+ condition: Callable[[Response], bool],
+ timeout: float = 5,
+) -> None:
+ """Wait until `condition` holds for the records read so far."""
+ deadline = asyncio.get_running_loop().time() + timeout
+ while not condition(response):
+ remaining = deadline - asyncio.get_running_loop().time()
+ if remaining <= 0:
+ raise TimeoutError(f"gave up waiting; saw {response.names()}")
+ response.changed.clear()
+ try:
+ await asyncio.wait_for(response.changed.wait(), remaining)
+ except asyncio.TimeoutError:
+ continue
+
+
+def until_ready(response: Response) -> bool:
+ return "ready" in response.names()
diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.py
new file mode 100644
index 0000000000..bf657e0dd9
--- /dev/null
+++ b/tests/_server/host/test_host_api.py
@@ -0,0 +1,725 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Host API authorization, event streams, and commands."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from pathlib import Path
+from typing import TYPE_CHECKING
+from urllib.parse import parse_qs, urlsplit
+
+import pytest
+
+from marimo._core import backend as be, protocol
+from marimo._core.host import Host
+from marimo._core.protocol import ProjectMessage
+from marimo._server.host import api as api_module
+from marimo._server.host.bridge import SessionBridge
+from marimo._server.host.context import HostContext
+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
+from tests._core.conftest import ScriptedBackend
+from tests._server.host.drive import (
+ PORT,
+ finished,
+ request,
+ until_ready,
+ wait_for,
+)
+from tests._server.mocks import (
+ get_mock_session_manager,
+ get_starlette_server_state_init,
+)
+
+if TYPE_CHECKING:
+ from starlette.applications import Starlette
+
+TOKEN = "record-token"
+AUTH = {"Authorization": f"Bearer {TOKEN}"}
+
+
+def key(value: str) -> dict[str, str]:
+ return {**AUTH, "Idempotency-Key": value}
+
+
+class Harness:
+ def __init__(
+ self, app: Starlette, bridge: SessionBridge, root: Path
+ ) -> None:
+ self.app = app
+ self.bridge = bridge
+ self.root = root
+ self.backends: dict[str, ScriptedBackend] = {}
+
+ @property
+ def host(self) -> Host:
+ return self.bridge.host
+
+ @property
+ def notebook_id(self) -> str:
+ (notebook,) = [
+ n for n in self.host.notebooks.values() if n.path == "forecasts.py"
+ ]
+ return notebook.id
+
+ def backend(self) -> ScriptedBackend:
+ return self.backends[self.notebook_id]
+
+ async def running(self) -> str:
+ """Start a runtime and simulate the backend's running update."""
+ response = await finished(
+ self.app,
+ "PUT",
+ f"/notebooks/{self.notebook_id}/runtime",
+ headers=key("start"),
+ body=b"{}",
+ )
+ assert response.status == 202, response.body
+ self.host.notebook(self.notebook_id).observe(be.Running("0.25.0"))
+ return self.notebook_id
+
+
+def harness(tmp_path: Path) -> Harness:
+ (tmp_path / "forecasts.py").write_text("import marimo\n")
+ workspace = FixedFilesWorkspace(
+ [MarimoFile(name="forecasts.py", path=str(tmp_path / "forecasts.py"))],
+ directory=str(tmp_path),
+ )
+ app = create_starlette_app(base_url="", enable_auth=True)
+ manager = get_mock_session_manager()
+ get_starlette_server_state_init(session_manager=manager).apply(app.state)
+ bridge = SessionBridge(manager)
+ harness = Harness(app, bridge, tmp_path)
+
+ def make(notebook_id: str) -> ScriptedBackend:
+ backend = ScriptedBackend()
+ harness.backends[notebook_id] = backend
+ return backend
+
+ bridge.index = WorkspaceIndex(bridge.host, workspace, make)
+ bridge.index.refresh()
+ app.state.host_context = HostContext(
+ bridge=bridge,
+ token=TOKEN,
+ port=PORT,
+ )
+ return harness
+
+
+async def test_the_token_the_address_and_the_name_are_all_checked(
+ harness: Harness,
+) -> None:
+ app = harness.app
+ assert (await finished(app, "GET", "/events")).status == 401
+ assert (
+ await finished(
+ app, "GET", "/events", headers={"Authorization": "Bearer nope"}
+ )
+ ).status == 401
+ assert (
+ await finished(
+ app, "GET", "/events", headers=AUTH, client=("10.0.0.5", 1)
+ )
+ ).status == 403
+ assert (
+ await finished(
+ app, "GET", "/events", headers=AUTH, host="evil.example:1234"
+ )
+ ).status == 403
+ assert (
+ await finished(
+ app, "GET", "/events", headers=AUTH, host="127.0.0.1:9999"
+ )
+ ).status == 403
+ app.state.host_context = None
+ refused = await finished(app, "GET", "/events", headers=AUTH)
+ assert refused.status == 404
+ assert refused.json()["type"].endswith("/not-found")
+
+
+async def test_unknown_routes_are_problems(harness: Harness) -> None:
+ response = await finished(harness.app, "GET", "/nothing", headers=AUTH)
+ assert response.status == 404
+ assert response.headers["content-type"] == "application/problem+json"
+
+
+ ("host", "status"),
+ [
+ ("127.attacker.example:1234", 403),
+ ("127.1.2.3:1234", 202),
+ ("localhost:1234", 202),
+ ("[::1]:1234", 202),
+ ("[::ffff:127.0.0.1]:1234", 202),
+ ],
+)
+async def test_only_loopback_names_are_admitted(
+ harness: Harness, host: str, status: int
+) -> None:
+ response = await finished(
+ harness.app,
+ "PUT",
+ f"/notebooks/{harness.notebook_id}/runtime",
+ headers=key("start"),
+ body=b"{}",
+ host=host,
+ )
+ assert response.status == status
+
+
+async def test_the_catalog_stream_sends_a_snapshot_then_changes(
+ harness: Harness,
+) -> None:
+ response, _, disconnect = request(
+ harness.app, "GET", "/events", headers=AUTH
+ )
+ await wait_for(response, until_ready)
+ assert response.names() == ["host", "project", "notebook", "ready"]
+ assert "id" not in response.records[0]
+ cursor = int(response.records[-1]["id"])
+
+ notebook = harness.host.notebook(harness.notebook_id)
+ notebook.start()
+ await wait_for(response, lambda r: r.names()[-1] == "runtime")
+ live = response.records[-1]
+ assert int(live["id"]) > cursor
+ assert live["data"]["runtime"]["status"] == "starting"
+ assert "time" in live["data"]
+ disconnect()
+
+
+async def test_catalog_refresh_delivers_updates_on_the_event_loop(
+ harness: Harness,
+) -> None:
+ first, first_task, disconnect_first = request(
+ harness.app, "GET", "/events", headers=AUTH
+ )
+ await wait_for(first, until_ready)
+ threads: list[int] = []
+ unsubscribe = harness.host.subscribe(
+ lambda _: threads.append(threading.get_ident())
+ )
+ new_file = harness.root / "new.py"
+ new_file.write_text("import marimo\n")
+ harness.bridge.index._workspace = FixedFilesWorkspace(
+ [
+ MarimoFile(
+ name="forecasts.py", path=str(harness.root / "forecasts.py")
+ ),
+ MarimoFile(name="new.py", path=str(new_file)),
+ ],
+ directory=str(harness.root),
+ )
+ second, second_task, disconnect_second = request(
+ harness.app, "GET", "/events", headers=AUTH
+ )
+ try:
+ await wait_for(second, until_ready)
+ await wait_for(
+ first,
+ lambda response: any(
+ r.get("data", {}).get("notebook", {}).get("path") == "new.py"
+ for r in response.records
+ ),
+ )
+ assert threads
+ assert set(threads) == {threading.get_ident()}
+ finally:
+ unsubscribe()
+ disconnect_first()
+ disconnect_second()
+ await asyncio.gather(first_task, second_task)
+
+
+async def test_types_and_cursors_apply_to_the_stream(harness: Harness) -> None:
+ first, _, disconnect = request(
+ harness.app, "GET", "/events", headers=AUTH, query="types=notebook"
+ )
+ await wait_for(first, until_ready)
+ assert first.names() == ["notebook", "ready"]
+ cursor = first.records[-1]["id"]
+ disconnect()
+
+ harness.host.notebook(harness.notebook_id).start()
+ resumed, _, disconnect = request(
+ harness.app,
+ "GET",
+ "/events",
+ headers={**AUTH, "Last-Event-ID": cursor},
+ )
+ await wait_for(resumed, until_ready)
+ assert resumed.names() == ["runtime", "ready"]
+ disconnect()
+
+ bad = await finished(
+ harness.app, "GET", "/events", headers={**AUTH, "Last-Event-ID": "x"}
+ )
+ assert bad.status == 400
+
+
+async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:
+ notebook = harness.host.notebook(harness.notebook_id)
+ response, task, disconnect = request(
+ harness.app, "GET", f"/notebooks/{notebook.id}/events", headers=AUTH
+ )
+ await wait_for(response, until_ready)
+ assert response.names() == ["notebook", "attachment", "ready"]
+ assert response.records[1]["data"]["attachment"]["kind"] == "client"
+
+ disconnect()
+ await asyncio.wait_for(task, 5)
+ assert [e.name for e in harness.host.events(notebook_id=notebook.id)] == [
+ "notebook",
+ "ready",
+ ]
+
+ missing = await finished(
+ harness.app, "GET", "/notebooks/nope/events", headers=AUTH
+ )
+ assert missing.status == 404
+
+
+async def test_runtime_lifecycle_over_http(harness: Harness) -> None:
+ app, nid = harness.app, harness.notebook_id
+ path = f"/notebooks/{nid}/runtime"
+
+ started = await finished(app, "PUT", path, headers=key("k1"), body=b"{}")
+ assert started.status == 202
+ assert started.json()["status"] == "starting"
+ assert harness.backend().calls == [("start", started.json()["id"])]
+
+ again = await finished(app, "PUT", path, headers=key("k2"), body=b"{}")
+ assert again.status == 200
+ assert again.json()["id"] == started.json()["id"]
+
+ restart = await finished(app, "POST", path + "/restart", headers=key("k3"))
+ assert restart.status == 409
+ assert restart.json()["type"].endswith("/conflict")
+
+ harness.host.notebook(nid).observe(be.Running("0.25.0"))
+ restart = await finished(app, "POST", path + "/restart", headers=key("k4"))
+ assert restart.status == 202
+ assert restart.json()["status"] == "starting"
+ assert restart.json()["id"] != started.json()["id"]
+
+ harness.host.notebook(nid).observe(be.Exited())
+ harness.host.notebook(nid).observe(be.Running("0.25.0"))
+ stopped = await finished(app, "DELETE", path, headers=key("k5"))
+ assert stopped.status == 202
+ assert stopped.json()["status"] == "terminating"
+ assert stopped.json()["id"] != started.json()["id"]
+ assert stopped.json()["id"] == restart.json()["id"]
+
+ harness.host.notebook(nid).observe(be.Exited())
+ gone = await finished(app, "DELETE", path, headers=key("k6"))
+ assert gone.status == 409
+ assert gone.json()["type"].endswith("/no-runtime")
+
+
+async def test_run_filter_over_http(harness: Harness) -> None:
+ nid = await harness.running()
+ notebook = harness.host.notebook(nid)
+ notebook.run("1", request_id="first")
+ notebook.observe(be.Done(protocol.RunId("first"), "succeeded"))
+ notebook.run("2", request_id="second")
+ response, task, disconnect = request(
+ harness.app,
+ "GET",
+ f"/notebooks/{nid}/events",
+ headers=AUTH,
+ query="run_id=first",
+ )
+ try:
+ await wait_for(response, until_ready)
+ assert response.names() == ["run", "ready"]
+ assert response.records[0]["data"]["run"]["id"] == "first"
+ finally:
+ disconnect()
+ await asyncio.wait_for(task, 5)
+ invalid = await finished(
+ harness.app,
+ "GET",
+ f"/notebooks/{nid}/events",
+ headers=AUTH,
+ query="run_id=",
+ )
+ assert invalid.status == 400
+
+
+async def test_scratch_runs_over_http(harness: Harness) -> None:
+ app, nid = harness.app, harness.notebook_id
+ runs = f"/notebooks/{nid}/runtime/runs"
+ body = json.dumps({"code": "3 * 3"}).encode()
+
+ refused = await finished(app, "POST", runs, headers=key("r0"), body=body)
+ assert refused.status == 409
+ assert refused.json()["type"].endswith("/no-runtime")
+
+ await harness.running()
+ accepted = await finished(app, "POST", runs, headers=key("r1"), body=body)
+ assert accepted.status == 202
+ run_id = accepted.json()["id"]
+ assert accepted.json()["status"] == "queued"
+ assert harness.backend().calls[-1] == ("run", run_id, "3 * 3")
+
+ repeated = await finished(app, "POST", runs, headers=key("r1"), body=body)
+ assert repeated.status == 202
+ assert repeated.body == accepted.body
+ assert harness.backend().calls.count(("run", run_id, "3 * 3")) == 1
+ notebook = harness.host.notebook(nid)
+ notebook.observe(
+ be.Planned(run_id, (be.PlannedExecution("e1", None, "hash", "3 * 3"),))
+ )
+ notebook.observe(be.Status("e1", "running"))
+ running = await finished(app, "POST", runs, headers=key("r1"), body=body)
+ assert running.json()["status"] == "running"
+ reused = await finished(
+ app,
+ "POST",
+ runs,
+ headers=key("r1"),
+ body=json.dumps({"code": "4"}).encode(),
+ )
+ assert reused.status == 409
+
+ busy = await finished(app, "POST", runs, headers=key("r2"), body=body)
+ assert busy.status == 409
+ assert run_id in busy.json()["detail"]
+
+ interrupted = await finished(
+ app, "DELETE", f"{runs}/{run_id}", headers=key("i1")
+ )
+ assert interrupted.status == 202
+ assert harness.backend().calls[-1] == ("interrupt", run_id)
+
+ notebook.observe(be.Concluded("e1", protocol.InterruptedOutcome()))
+ notebook.observe(be.Status("e1", "completed"))
+ notebook.observe(be.Done(run_id, "interrupted"))
+ completed = await finished(app, "POST", runs, headers=key("r1"), body=body)
+ assert completed.json()["status"] == "completed"
+ assert completed.json()["outcome"] == "interrupted"
+ assert completed.json()["completed_at"] is not None
+ late = await finished(app, "DELETE", f"{runs}/{run_id}", headers=key("i2"))
+ assert late.status == 409
+ missing = await finished(app, "DELETE", runs + "/zz", headers=key("i3"))
+ assert missing.status == 404
+
+ invalid = await finished(app, "POST", runs, headers=key("r3"), body=b"{}")
+ assert invalid.status == 400
+ malformed = await finished(app, "POST", runs, headers=key("r4"), body=b"{")
+ assert malformed.status == 400
+ assert malformed.json()["type"].endswith("/invalid-request")
+ unkeyed = await finished(app, "POST", runs, headers=AUTH, body=body)
+ assert unkeyed.status == 400
+
+
[email protected]("cancel_waiter", [False, True])
+async def test_concurrent_retries_share_the_mutation(
+ harness: Harness, monkeypatch: pytest.MonkeyPatch, cancel_waiter: bool
+) -> None:
+ started, release = asyncio.Event(), asyncio.Event()
+ create = harness.bridge.create
+
+ async def delayed_create(
+ target: Path, *, name: str | None, request_id: str
+ ) -> protocol.Notebook:
+ started.set()
+ await release.wait()
+ return await create(target, name=name, request_id=request_id)
+
+ monkeypatch.setattr(harness.bridge, "create", delayed_create)
+ body = json.dumps(
+ {"project_id": harness.bridge.index.project_id, "path": "new.py"}
+ ).encode()
+ first, first_task, _ = request(
+ harness.app, "POST", "/notebooks", headers=key("create"), body=body
+ )
+ await asyncio.wait_for(started.wait(), 5)
+ try:
+ conflicting = await finished(
+ harness.app,
+ "POST",
+ "/notebooks",
+ headers=key("create"),
+ body=json.dumps(
+ {
+ "project_id": harness.bridge.index.project_id,
+ "path": "other.py",
+ }
+ ).encode(),
+ )
+ assert conflicting.status == 409
+ if cancel_waiter:
+ first_task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await first_task
+ retry, retry_task, _ = request(
+ harness.app, "POST", "/notebooks", headers=key("create"), body=body
+ )
+ # Queue the release after the retry has entered the request handler.
+ asyncio.get_running_loop().call_soon(release.set)
+ await asyncio.wait_for(retry_task, 5)
+ assert retry.status == 201
+ if not cancel_waiter:
+ await asyncio.wait_for(first_task, 5)
+ assert first.body == retry.body
+ assert (harness.root / "new.py").exists()
+ assert not (harness.root / "other.py").exists()
+ assert sorted(n.path for n in harness.host.notebooks.values()) == [
+ "forecasts.py",
+ "new.py",
+ ]
+ finally:
+ release.set()
+ await asyncio.gather(first_task, return_exceptions=True)
+
+
+async def test_rejected_mutations_do_not_reserve_the_key(
+ harness: Harness,
+) -> None:
+ path = f"/notebooks/{harness.notebook_id}"
+ rejected = await finished(
+ harness.app,
+ "PATCH",
+ path,
+ headers=key("move"),
+ body=b'{"path":"forecasts.py"}',
+ )
+ assert rejected.status == 409
+ corrected = await finished(
+ harness.app,
+ "PATCH",
+ path,
+ headers=key("move"),
+ body=b'{"path":"corrected.py"}',
+ )
+ assert corrected.status == 200
+ assert corrected.json()["path"] == "corrected.py"
+ assert (harness.root / "corrected.py").exists()
+ assert not (harness.root / "forecasts.py").exists()
+
+
+async def test_create_update_and_delete_notebooks(harness: Harness) -> None:
+ app, root = harness.app, harness.root
+ project = harness.bridge.index.project_id
+
+ created = await finished(
+ app,
+ "POST",
+ "/notebooks",
+ headers=key("c1"),
+ body=json.dumps(
+ {"project_id": project, "path": "new/one.py"}
+ ).encode(),
+ )
+ assert created.status == 201, created.body
+ record = created.json()
+ assert record["path"] == str(Path("new") / "one.py")
+ assert record["name"] == "one"
+ assert (root / "new" / "one.py").read_text().startswith("import marimo")
+ assert record["id"] in harness.host.notebooks
+
+ again = await finished(
+ app,
+ "POST",
+ "/notebooks",
+ headers=key("c2"),
+ body=json.dumps(
+ {"project_id": project, "path": "new/one.py"}
+ ).encode(),
+ )
+ assert again.status == 409
+ escaped = await finished(
+ app,
+ "POST",
+ "/notebooks",
+ headers=key("c3"),
+ body=json.dumps({"project_id": project, "path": "../x.py"}).encode(),
+ )
+ assert escaped.status == 400
+ elsewhere = await finished(
+ app,
+ "POST",
+ "/notebooks",
+ headers=key("c4"),
+ body=json.dumps({"project_id": "nope", "path": "y.py"}).encode(),
+ )
+ assert elsewhere.status == 404
+
+ moved = await finished(
+ app,
+ "PATCH",
+ f"/notebooks/{record['id']}",
+ headers=key("u1"),
+ body=json.dumps({"path": "two.py", "name": "Two"}).encode(),
+ )
+ assert moved.status == 200, moved.body
+ assert moved.json()["path"] == "two.py"
+ assert moved.json()["name"] == "Two"
+ assert (root / "two.py").exists()
+ assert not (root / "new" / "one.py").exists()
+ harness.bridge.index.refresh()
+ assert harness.host.notebooks[record["id"]].name == "Two"
+
+ onto = await finished(
+ app,
+ "PATCH",
+ f"/notebooks/{record['id']}",
+ headers=key("u2"),
+ body=json.dumps({"path": "forecasts.py"}).encode(),
+ )
+ assert onto.status == 409
+
+ deleted = await finished(
+ app, "DELETE", f"/notebooks/{record['id']}", headers=key("d1")
+ )
+ assert deleted.status == 204
+ assert not (root / "two.py").exists()
+ assert record["id"] not in harness.host.notebooks
+
+ repeated = await finished(
+ app, "DELETE", f"/notebooks/{record['id']}", headers=key("d1")
+ )
+ assert repeated.status == 204
+ assert repeated.body == deleted.body == b""
+
+ await harness.running()
+ busy = await finished(
+ app, "DELETE", f"/notebooks/{harness.notebook_id}", headers=key("d2")
+ )
+ assert busy.status == 409
+
+
+async def test_open_selects_the_notebook_outside_the_working_directory(
+ harness: Harness, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ file = harness.root / "forecasts.py"
+ workspace = SingleFileWorkspace(MarimoFile(name=file.name, path=str(file)))
+ harness.app.state.session_manager.workspace = workspace
+ launch = harness.root / "launch"
+ launch.mkdir()
+ (launch / file.name).write_text("another notebook")
+ monkeypatch.chdir(launch)
+ opened: list[str] = []
+ ready = threading.Event()
+
+ def open_browser(_browser: str, url: str) -> None:
+ opened.append(url)
+ ready.set()
+
+ monkeypatch.setattr(api_module, "open_url_in_browser", open_browser)
+ response = await finished(
+ harness.app,
+ "POST",
+ f"/notebooks/{harness.notebook_id}/open",
+ headers=key("o1"),
+ )
+
+ assert response.status == 200
+ url = response.json()["url"]
+ query = parse_qs(urlsplit(url).query)
+ assert workspace.resolve(query["file"][0]) == str(file)
+ assert query["access_token"] == ["fake-token"]
+ assert TOKEN not in url
+ assert await asyncio.to_thread(ready.wait, 5)
+ assert opened == [url]
+
+
+async def test_operations_the_host_does_not_offer_are_501(
+ harness: Harness,
+) -> None:
+ notebook = harness.host.notebook(harness.notebook_id)
+ host = Host(operations=[])
+ [project] = [
+ e.data.project
+ for e in harness.host.events()
+ if isinstance(e.data, ProjectMessage)
+ ]
+ host.update_project(project)
+ host.add_notebook(harness.host.notebooks[notebook.id], harness.backend())
+ harness.bridge.host = host
+ response = await finished(
+ harness.app,
+ "PUT",
+ f"/notebooks/{notebook.id}/runtime",
+ headers=key("x1"),
+ )
+ assert response.status == 501
+ assert response.json()["type"].endswith("/unsupported-operation")
+
+
+async def test_competing_moves_preserve_both_notebooks(
+ harness: Harness,
+) -> None:
+ first = harness.root / "forecasts.py"
+ second = harness.root / "second.py"
+ first.write_text("first notebook")
+ second.write_text("second notebook")
+ other = harness.bridge.index.ensure(str(second))
+ assert other is not None
+ ids = [harness.notebook_id, other.id]
+
+ responses = await asyncio.gather(
+ *(
+ finished(
+ harness.app,
+ "PATCH",
+ f"/notebooks/{nid}",
+ headers=key(f"move-{i}"),
+ body=b'{"path":"destination.py"}',
+ )
+ for i, nid in enumerate(ids)
+ )
+ )
+
+ assert sorted(r.status for r in responses) == [200, 409]
+ records = [harness.host.notebooks[nid] for nid in ids]
+ assert len({record.path for record in records}) == 2
+ assert {
+ (harness.root / record.path).read_text()
+ for record in records
+ if record.path is not None
+ } == {"first notebook", "second notebook"}
+
+
[email protected]("operation", ["create", "move"])
+async def test_symlink_escape_has_no_filesystem_side_effects(
+ harness: Harness, tmp_path: Path, operation: str
+) -> None:
+ outside = tmp_path.parent / f"{tmp_path.name}-outside"
+ outside.mkdir()
+ (harness.root / "link").symlink_to(outside, target_is_directory=True)
+ source = harness.root / "forecasts.py"
+ original = source.read_text()
+ if operation == "create":
+ response = await finished(
+ harness.app,
+ "POST",
+ "/notebooks",
+ headers=key("escape"),
+ body=json.dumps(
+ {
+ "project_id": harness.bridge.index.project_id,
+ "path": "link/nested/new.py",
+ }
+ ).encode(),
+ )
+ else:
+ response = await finished(
+ harness.app,
+ "PATCH",
+ f"/notebooks/{harness.notebook_id}",
+ headers=key("escape"),
+ body=b'{"path":"link/nested/new.py"}',
+ )
+ assert response.status == 409
+ assert list(outside.iterdir()) == []
+ assert source.read_text() == original
+ assert [n.path for n in harness.host.notebooks.values()] == [
+ "forecasts.py"
+ ]
diff --git a/tests/_server/host/test_host_backend.py b/tests/_server/host/test_host_backend.py
new file mode 100644
index 0000000000..53afe32fb8
--- /dev/null
+++ b/tests/_server/host/test_host_backend.py
@@ -0,0 +1,344 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Session backend commands and updates."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from marimo._core import backend as be, protocol
+from marimo._messaging.notification import (
+ CellNotification,
+ CompletedRunNotification,
+ ExecutionNotification,
+ StartupProgressNotification,
+)
+from marimo._messaging.serde import serialize_kernel_message
+from marimo._runtime.scratch import SCRATCH_CELL_ID
+from marimo._server.host.backend import SessionBackend
+from marimo._session.types import KernelExitInfo, KernelState
+from marimo._version import __version__
+from tests._server.host.conftest import (
+ FakeManager,
+ FakeSession,
+ Observed,
+)
+
+
+def backend(manager: FakeManager, observed: Observed) -> SessionBackend:
+ return SessionBackend(
+ protocol.NotebookId("n1"),
+ lambda: "/ws/forecasts.py",
+ manager, # type: ignore[arg-type]
+ observed,
+ )
+
+
+async def test_start_joins_the_session_as_a_secondary_consumer(
+ manager: FakeManager, observed: Observed
+) -> None:
+ b = backend(manager, observed)
+ manager.release.clear()
+
+ b.start(protocol.RuntimeId("rt1"))
+ await manager.started.wait()
+ progress = StartupProgressNotification(
+ phase="starting-kernel", logs="", log_mode="append"
+ )
+ b.notify(serialize_kernel_message(progress))
+ manager.release.set()
+ await observed.wait_for(be.Running)
+
+ assert manager.starts == [
+ {
+ "file_key": "/ws/forecasts.py",
+ "auto_instantiate": False,
+ "main": False,
+ }
+ ]
+ assert observed.messages == [
+ be.Starting("Starting the kernel"),
+ be.Running(__version__),
+ ]
+
+
+async def test_a_failed_start_reports_the_reason(
+ manager: FakeManager, observed: Observed
+) -> None:
+ manager.next_session = RuntimeError("no such environment")
+ backend(manager, observed).start(protocol.RuntimeId("rt1"))
+ await observed.wait_for(be.Exited)
+ assert observed.messages == [be.Exited("no such environment")]
+
+ observed.messages.clear()
+ manager.next_session = KeyError()
+ backend(manager, observed).start(protocol.RuntimeId("rt1"))
+ await observed.wait_for(be.Exited)
+ assert observed.messages == [be.Exited("KeyError")]
+
+
+async def test_a_notebook_without_a_file_cannot_start(
+ manager: FakeManager, observed: Observed
+) -> None:
+ SessionBackend(
+ protocol.NotebookId("n1"),
+ lambda: None,
+ manager, # type: ignore[arg-type]
+ observed,
+ ).start(protocol.RuntimeId("rt1"))
+ await observed.wait_for(be.Exited)
+ assert observed.messages == [be.Exited("The notebook has no file to run")]
+ assert manager.starts == []
+
+
+async def test_stop_closes_the_session_and_reports_the_exit(
+ manager: FakeManager, observed: Observed
+) -> None:
+ b = backend(manager, observed)
+ b.start(protocol.RuntimeId("rt1"))
+ await observed.wait_for(be.Running)
+ observed.messages.clear()
+
+ b.stop()
+
+ assert manager.sessions == {}
+ assert manager.next_session.closed
+ assert observed.messages == [be.Exited(None)]
+
+
+async def test_stop_before_the_session_exists_is_carried_out_after(
+ manager: FakeManager, observed: Observed
+) -> None:
+ b = backend(manager, observed)
+ manager.release.clear()
+ b.start(protocol.RuntimeId("rt1"))
+ await manager.started.wait()
+ b.stop()
+ manager.release.set()
+ await observed.wait_for(be.Exited)
+ assert observed.kinds() == ["Running", "Exited"]
+ assert manager.next_session.closed
+
+
+async def test_a_kernel_that_dies_reports_why(
+ manager: FakeManager, observed: Observed
+) -> None:
+ b = backend(manager, observed)
+ b.start(protocol.RuntimeId("rt1"))
+ await observed.wait_for(be.Running)
+ observed.messages.clear()
+ session = manager.next_session
+ session.state = KernelState.STOPPED
+ session.exit_info = KernelExitInfo(
+ exitcode=-9, cause="oom", message="Out of memory"
+ )
+
+ session.close() # what the heartbeat does
+
+ assert observed.messages == [be.Exited("Out of memory")]
+
+
+async def test_adopting_a_session_reports_it_running(
+ manager: FakeManager, observed: Observed
+) -> None:
+ b = backend(manager, observed)
+ session = FakeSession()
+ b.adopt(session) # type: ignore[arg-type]
+ b.adopt(session) # type: ignore[arg-type]
+ assert observed.kinds() == ["Running"]
+ assert len(session.consumers) == 1
+
+
[email protected]("takes_effect", [False, True])
+async def test_interrupt_waits_for_the_kernel_result(
+ manager: FakeManager,
+ observed: Observed,
+ takes_effect: bool,
+) -> None:
+ b = backend(manager, observed)
+ b.start(protocol.RuntimeId("rt1"))
+ await observed.wait_for(be.Running)
+ session = manager.next_session
+ b.run(protocol.RunId("run-1"), "while True: pass")
+ await asyncio.wait_for(session.submitted.wait(), 5)
+ observed.messages.clear()
+
+ b.interrupt(protocol.RunId("run-1"))
+ session.broadcast(
+ CellNotification(
+ cell_id=SCRATCH_CELL_ID, status="running", run_id="run-1"
+ )
+ )
+ session.broadcast(
+ CompletedRunNotification(
+ run_id="run-1",
+ outcome="interrupted" if takes_effect else "succeeded",
+ )
+ )
+ await observed.wait_for(be.Done)
+
+ assert session.interrupts == 1
+ concluded = [m for m in observed.messages if isinstance(m, be.Concluded)]
+ assert concluded[-1].outcome == (
+ protocol.InterruptedOutcome()
+ if takes_effect
+ else protocol.ValueOutcome(None)
+ )
+ assert observed.messages[-1] == be.Done(
+ protocol.RunId("run-1"), "interrupted" if takes_effect else "succeeded"
+ )
+
+
+async def test_a_session_closing_mid_run_releases_the_run(
+ manager: FakeManager, observed: Observed
+) -> None:
+ b = backend(manager, observed)
+ b.start(protocol.RuntimeId("rt1"))
+ await observed.wait_for(be.Running)
+ session = manager.next_session
+ b.run(protocol.RunId("run-1"), "1")
+ await asyncio.wait_for(session.submitted.wait(), 5)
+ observed.messages.clear()
+
+ session.close()
+ await asyncio.wait_for(session.scratchpad_lock.acquire(), 5)
+ session.scratchpad_lock.release()
+
+ # `Exited` tells the notebook to end the active run.
+ assert observed.kinds() == ["Exited"]
+ assert not session.scratchpad_lock.locked()
+
+
+async def test_interrupting_a_run_started_by_another_client(
+ manager: FakeManager, observed: Observed
+) -> None:
+ b = backend(manager, observed)
+ session = manager.next_session
+ b.adopt(session)
+ session.broadcast(
+ ExecutionNotification(
+ cell_id=SCRATCH_CELL_ID,
+ phase="planned",
+ execution_id="attempt",
+ code="while True: pass",
+ run_id="browser",
+ )
+ )
+ b.interrupt(protocol.RunId("browser"))
+ assert session.interrupts == 1
+ session.broadcast(
+ CompletedRunNotification(run_id="browser", outcome="interrupted")
+ )
+ assert observed.messages[-1] == be.Done(
+ protocol.RunId("browser"), "interrupted"
+ )
+ b.interrupt(protocol.RunId("browser"))
+ assert session.interrupts == 1
+
+
+async def test_external_scratch_is_adopted_before_compilation(
+ manager: FakeManager, observed: Observed
+) -> None:
+ b = backend(manager, observed)
+ session = manager.next_session
+ b.adopt(session)
+ observed.messages.clear()
+ session.broadcast(
+ ExecutionNotification(
+ cell_id=SCRATCH_CELL_ID,
+ phase="planned",
+ code="3 * 3",
+ execution_id="attempt",
+ run_id="browser",
+ )
+ )
+ assert observed.kinds() == ["Scheduled", "Planned"]
+ planned = observed.messages[-1]
+ assert isinstance(planned, be.Planned)
+ execution = planned.executions[0]
+ assert execution.code == "3 * 3"
+
+ session.broadcast(
+ ExecutionNotification(
+ cell_id=SCRATCH_CELL_ID,
+ phase="running",
+ execution_id="attempt",
+ run_id="browser",
+ )
+ )
+ assert observed.messages[-1] == be.Status(execution.id, "running")
+ assert observed.kinds() == ["Scheduled", "Planned", "Status"]
+ session.broadcast(CompletedRunNotification(run_id="browser"))
+ assert observed.messages[-1] == be.Done(
+ protocol.RunId("browser"), "succeeded"
+ )
+
+
[email protected]("before_start", [False, True])
+async def test_canceling_a_queued_run_preserves_other_execution(
+ manager: FakeManager, observed: Observed, before_start: bool
+) -> None:
+ class Lock(asyncio.Lock):
+ def __init__(self) -> None:
+ super().__init__()
+ self.entered = asyncio.Event()
+
+ async def acquire(self) -> bool:
+ self.entered.set()
+ return await super().acquire()
+
+ b = backend(manager, observed)
+ session = manager.next_session
+ session.scratchpad_lock = lock = Lock()
+ b.adopt(session)
+ observed.messages.clear()
+ async with lock:
+ lock.entered.clear()
+ b.run(protocol.RunId("canceled"), "must_not_execute()")
+ if not before_start:
+ await asyncio.wait_for(lock.entered.wait(), 5)
+ b.interrupt(protocol.RunId("canceled"))
+ await observed.wait_for(be.Done)
+ assert session.interrupts == 0
+ [outcome] = [
+ m.outcome for m in observed.messages if isinstance(m, be.Concluded)
+ ]
+ assert outcome == protocol.InterruptedOutcome()
+
+ observed.messages.clear()
+ b.run(protocol.RunId("next"), "42")
+ await asyncio.wait_for(session.submitted.wait(), 5)
+ assert [(c.run_id, c.code) for c in session.commands] == [("next", "42")]
+ session.broadcast(CompletedRunNotification(run_id="next"))
+ await observed.wait_for(be.Done)
+
+
+async def test_submission_failure_is_an_error(
+ manager: FakeManager, observed: Observed, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ b = backend(manager, observed)
+ session = manager.next_session
+ b.adopt(session)
+
+ def failed(*_args: object, **_kwargs: object) -> None:
+ raise RuntimeError("Kernel channel closed")
+
+ monkeypatch.setattr(session, "put_control_request", failed)
+ b.run(protocol.RunId("failed"), "42")
+ await observed.wait_for(be.Done)
+ [outcome] = [
+ m.outcome for m in observed.messages if isinstance(m, be.Concluded)
+ ]
+ assert outcome == protocol.ErrorOutcome(
+ protocol.Error(
+ kind="internal",
+ name=None,
+ message="Kernel channel closed",
+ traceback=None,
+ source="marimo",
+ severity="error",
+ range=None,
+ related=[],
+ )
+ )
diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.py
new file mode 100644
index 0000000000..ef678198b8
--- /dev/null
+++ b/tests/_server/host/test_host_bridge.py
@@ -0,0 +1,133 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Session discovery and updates in the host catalog."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from marimo._core.errors import Conflict
+from marimo._messaging.notification import StartupProgressNotification
+from marimo._server.host.bridge import SessionBridge
+from marimo._server.models.home import MarimoFile
+from marimo._server.workspace import FixedFilesWorkspace
+from tests._core.conftest import names
+from tests._server.host.conftest import FakeManager, FakeSession
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+
+def prepare(manager: FakeManager, root: Path, *names: str) -> None:
+ files = []
+ for name in names:
+ (root / name).write_text("")
+ files.append(MarimoFile(name=name, path=str(root / name)))
+ manager.workspace = FixedFilesWorkspace(files, directory=str(root))
+
+
+async def test_sessions_present_and_created_are_adopted(
+ manager: FakeManager, tmp_path: Path
+) -> None:
+ prepare(manager, tmp_path, "a.py", "b.py")
+ existing = FakeSession(str(tmp_path / "a.py"))
+ manager.sessions["browser-1"] = existing
+ bridge = SessionBridge(manager) # type: ignore[arg-type]
+
+ bridge.open()
+
+ a = bridge.index.notebook_for(str(tmp_path / "a.py"))
+ assert a is not None
+ runtime = bridge.host.notebook(a.id).runtime
+ assert runtime is not None
+ assert runtime.status == "running"
+ assert existing.consumers[0][1] is False
+
+ created = FakeSession(str(tmp_path / "b.py"))
+ await manager.event_bus.emit_session_created(created) # type: ignore[arg-type]
+ b = bridge.index.notebook_for(str(tmp_path / "b.py"))
+ assert b is not None
+ assert bridge.host.notebook(b.id).runtime is not None
+
+ unknown = FakeSession(str(tmp_path.parent / "elsewhere.py"))
+ await manager.event_bus.emit_session_created(unknown) # type: ignore[arg-type]
+ assert unknown.consumers == []
+ bridge.close()
+
+
+async def test_a_rename_keeps_the_notebook_id(
+ manager: FakeManager, tmp_path: Path
+) -> None:
+ prepare(manager, tmp_path, "a.py")
+ bridge = SessionBridge(manager) # type: ignore[arg-type]
+ bridge.open()
+ notebook = bridge.index.notebook_for(str(tmp_path / "a.py"))
+ assert notebook is not None
+ (tmp_path / "a.py").rename(tmp_path / "renamed.py")
+ session = FakeSession(str(tmp_path / "renamed.py"))
+
+ await manager.event_bus.emit_session_notebook_renamed(
+ session, # type: ignore[arg-type]
+ str(tmp_path / "a.py"),
+ )
+
+ assert bridge.host.notebooks[notebook.id].path == "renamed.py"
+ renamed = bridge.index.notebook_for(str(tmp_path / "renamed.py"))
+ assert renamed is not None
+ assert renamed.id == notebook.id
+
+
+async def test_session_updates_after_catalog_removal_are_ignored(
+ manager: FakeManager, tmp_path: Path
+) -> None:
+ prepare(manager, tmp_path, "a.py")
+ session = FakeSession(str(tmp_path / "a.py"))
+ manager.sessions["browser"] = session
+ bridge = SessionBridge(manager) # type: ignore[arg-type]
+ bridge.open()
+ record = bridge.index.notebook_for(str(tmp_path / "a.py"))
+ assert record is not None
+ notebook = bridge.host.notebook(record.id)
+ bridge.index.forget(record.id)
+ cursor = bridge.host.events()[-1].id
+ assert cursor is not None
+
+ session.broadcast(
+ StartupProgressNotification(
+ phase="starting-kernel", logs="", log_mode="append"
+ )
+ )
+ session.close()
+
+ assert names(bridge.host.events(cursor)) == ["ready"]
+ assert notebook.runtime is None
+ bridge.close()
+
+
+async def test_failed_session_move_preserves_the_notebook(
+ manager: FakeManager,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ prepare(manager, tmp_path, "a.py")
+ source, target = tmp_path / "a.py", tmp_path / "renamed.py"
+ session = FakeSession(str(source))
+ manager.sessions["browser"] = session
+ bridge = SessionBridge(manager) # type: ignore[arg-type]
+ bridge.open()
+ notebook = bridge.index.notebook_for(str(source))
+ assert notebook is not None
+ runtime = bridge.host.notebook(notebook.id).runtime
+
+ async def rename(_session_id: str, _path: str) -> tuple[bool, str | None]:
+ return False, "The notebook is busy"
+
+ monkeypatch.setattr(manager, "rename_session", rename, raising=False)
+ with pytest.raises(Conflict, match="busy"):
+ await bridge.update(notebook.id, target=target, request_id="move")
+ assert source.exists()
+ assert not target.exists()
+ assert bridge.host.notebooks[notebook.id].path == "a.py"
+ assert bridge.host.notebook(notebook.id).runtime is runtime
+ bridge.close()
diff --git a/tests/_server/host/test_host_execution.py b/tests/_server/host/test_host_execution.py
new file mode 100644
index 0000000000..46b716adf1
--- /dev/null
+++ b/tests/_server/host/test_host_execution.py
@@ -0,0 +1,875 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Host commands executed by real sessions and kernels."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from typing import TYPE_CHECKING
+
+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._server.workspace import SingleFileWorkspace
+from marimo._session.notebook import AppFileManager
+from marimo._session.requests import InstantiateNotebookRequest
+from marimo._utils.marimo_path import MarimoPath
+from tests._server.host.drive import PORT, finished, request, wait_for
+from tests._server.mocks import (
+ get_mock_session_manager,
+ get_starlette_server_state_init,
+)
+
+if TYPE_CHECKING:
+ from collections.abc import AsyncIterator
+ from pathlib import Path
+
+ from starlette.applications import Starlette
+
+ from tests._server.host.drive import Response
+
+AUTH = {"Authorization": "Bearer execution-test"}
+
+
+def key(value: str) -> dict[str, str]:
+ return {**AUTH, "Idempotency-Key": value}
+
+
+def notebook_source(request: pytest.FixtureRequest) -> str:
+ return getattr(
+ request,
+ "param",
+ (
+ "import marimo\napp = marimo.App()\n"
+ "@app.cell\ndef _():\n example = 7\n return (example,)\n"
+ ),
+ )
+
+
+async def live_host(
+ tmp_path: Path,
+ notebook_source: str,
+) -> AsyncIterator[tuple[Starlette, str, Response]]:
+ manager = get_mock_session_manager()
+ file = tmp_path / "notebook.py"
+ file.write_text(notebook_source)
+ manager.workspace = SingleFileWorkspace.from_path(MarimoPath(file))
+ manager.redirect_console_to_browser = True
+ app = create_starlette_app(base_url="", enable_auth=True)
+ get_starlette_server_state_init(session_manager=manager).apply(app.state)
+ bridge = SessionBridge(manager)
+ bridge.open()
+ app.state.host_context = HostContext(
+ bridge=bridge, token="execution-test", port=PORT
+ )
+ notebook = next(iter(bridge.host.notebooks.values()))
+ events, task, disconnect = request(
+ app, "GET", f"/notebooks/{notebook.id}/events", headers=AUTH
+ )
+ try:
+ started = await finished(
+ app,
+ "PUT",
+ f"/notebooks/{notebook.id}/runtime",
+ headers=key("start"),
+ )
+ assert started.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("runtime", {}).get("status") == "running"
+ for r in response.records
+ ),
+ timeout=15,
+ )
+ yield app, notebook.id, events
+ finally:
+ disconnect()
+ await asyncio.wait_for(task, 5)
+ bridge.close()
+ await manager.shutdown()
+
+
+async def test_move_preserves_the_running_notebook(
+ live_host: tuple[Starlette, str, Response], tmp_path: Path
+) -> None:
+ app, notebook_id, events = live_host
+ host = app.state.host_context.bridge.host
+ runtime = host.notebook(notebook_id).runtime
+ source, target = tmp_path / "notebook.py", tmp_path / "moved.py"
+ session = next(iter(app.state.session_manager.sessions.values()))
+ cells = list(session.app_file_manager.app.cell_manager.codes())
+
+ moved = await finished(
+ app,
+ "PATCH",
+ f"/notebooks/{notebook_id}",
+ headers=key("move"),
+ body=b'{"path":"moved.py"}',
+ )
+ assert moved.status == 200
+ assert (moved.json()["id"], moved.json()["path"]) == (
+ notebook_id,
+ "moved.py",
+ )
+ assert not source.exists()
+ assert list(AppFileManager(str(target)).app.cell_manager.codes()) == cells
+ assert session.app_file_manager.path == str(target)
+ assert host.notebook(notebook_id).runtime == runtime
+
+ accepted = await finished(
+ app,
+ "POST",
+ f"/notebooks/{notebook_id}/runtime/runs",
+ headers=key("after-move"),
+ body=b'{"code":"6 * 7"}',
+ )
+ assert accepted.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("status") == "completed"
+ for r in response.records
+ ),
+ )
+ [outcome] = [
+ r["data"]["execution"]["outcome"]
+ for r in events.records
+ if r.get("data", {}).get("execution", {}).get("status") == "completed"
+ ]
+ assert outcome == {
+ "kind": "value",
+ "display": {
+ "mimetype": "text/html",
+ "data": "<pre class='text-xs'>42</pre>",
+ },
+ }
+
+
+ ("code", "kind", "name", "value"),
+ [
+ (
+ "print('hello')\nimport marimo as mo\nmo.Html('<b>9</b>')",
+ "value",
+ None,
+ "<b>9</b>",
+ ),
+ ("", "value", None, None),
+ ("if !!!", "error", None, None),
+ ("1 / 0", "error", "ZeroDivisionError", None),
+ ("input('hello')", "error", "EOFError", None),
+ ],
+)
+async def test_scratch_outcomes_from_the_kernel(
+ live_host: tuple[Starlette, str, Response],
+ code: str,
+ kind: str,
+ name: str | None,
+ value: str | None,
+) -> None:
+ app, notebook_id, events = live_host
+ accepted = await finished(
+ app,
+ "POST",
+ f"/notebooks/{notebook_id}/runtime/runs",
+ headers=key("run"),
+ body=json.dumps({"code": code}).encode(),
+ )
+ assert accepted.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("status") == "completed"
+ for r in response.records
+ ),
+ )
+ [execution] = [
+ r["data"]["execution"]
+ for r in events.records
+ if r.get("data", {}).get("execution", {}).get("status") == "completed"
+ ]
+ outcome = execution["outcome"]
+ assert execution["code"] == code
+ assert execution["code_hash"]
+ assert execution["runtime_id"] is not None
+ assert execution["caused_by"] is None
+ if kind == "value":
+ assert outcome == {
+ "kind": "value",
+ "display": None
+ if value is None
+ else {"mimetype": "text/html", "data": value},
+ }
+ if value is not None:
+ assert "hello\n" == "".join(
+ r["data"]["console"]["text"]
+ for r in events.records
+ if r.get("event") == "console"
+ )
+ else:
+ assert (
+ outcome["kind"],
+ outcome["error"]["kind"],
+ outcome["error"]["name"],
+ ) == ("error", "syntax" if name is None else "exception", name)
+ assert outcome["error"]["message"]
+
+
+async def test_background_output_stays_with_its_execution(
+ live_host: tuple[Starlette, str, Response],
+) -> None:
+ app, notebook_id, events = live_host
+ path = f"/notebooks/{notebook_id}/runtime/runs"
+ code = """import builtins
+import threading
+import marimo as mo
+builtins._host_test_gate = threading.Event()
+def worker():
+ builtins._host_test_gate.wait(5)
+ print("late output")
+mo.Thread(target=worker).start()
+"""
+ first = await finished(
+ app,
+ "POST",
+ path,
+ headers=key("first"),
+ body=json.dumps({"code": code}).encode(),
+ )
+ assert first.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("id") == "first"
+ and r["data"]["run"]["status"] == "completed"
+ for r in response.records
+ ),
+ )
+ second = await finished(
+ app,
+ "POST",
+ path,
+ headers=key("second"),
+ body=json.dumps(
+ {
+ "code": "import builtins\nimport time\nbuiltins._host_test_gate.set()\ntime.sleep(0.2)\ndel builtins._host_test_gate"
+ }
+ ).encode(),
+ )
+ assert second.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("id") == "second"
+ and r["data"]["run"]["status"] == "completed"
+ for r in response.records
+ ),
+ )
+ console = [
+ r["data"]["console"]
+ for r in events.records
+ if r.get("event") == "console"
+ ]
+ assert any("late output" in item["text"] for item in console)
+ first_execution = next(
+ record["data"]["execution"]
+ for record in events.records
+ if record.get("event") == "execution"
+ and record["data"]["execution"]["run_id"] == "first"
+ )
+ assert {item["execution_id"] for item in console} == {
+ first_execution["id"]
+ }
+
+
+async def test_queued_cancellation_never_executes_the_code(
+ live_host: tuple[Starlette, str, Response], tmp_path: Path
+) -> None:
+ app, notebook_id, events = live_host
+ session = next(iter(app.state.session_manager.sessions.values()))
+ marker = tmp_path / "executed"
+ runs = f"/notebooks/{notebook_id}/runtime/runs"
+ async with session.scratchpad_lock:
+ accepted = await finished(
+ app,
+ "POST",
+ runs,
+ headers=key("canceled"),
+ body=json.dumps(
+ {
+ "code": f"__import__('pathlib').Path({str(marker)!r}).touch()"
+ }
+ ).encode(),
+ )
+ assert accepted.status == 202
+ interrupted = await finished(
+ app, "DELETE", runs + "/canceled", headers=key("interrupt")
+ )
+ assert interrupted.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("status") == "completed"
+ for r in response.records
+ ),
+ )
+ [outcome] = [
+ r["data"]["execution"]["outcome"]
+ for r in events.records
+ if r.get("data", {}).get("execution", {}).get("status") == "completed"
+ ]
+ assert outcome == {"kind": "interrupted"}
+ following = await finished(
+ app, "POST", runs, headers=key("next"), body=b'{"code":"42"}'
+ )
+ assert following.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("id") == "next"
+ and r["data"]["run"]["status"] == "completed"
+ for r in response.records
+ ),
+ )
+ assert not marker.exists()
+
+
+async def test_run_retries_return_the_result_even_after_restart(
+ live_host: tuple[Starlette, str, Response], tmp_path: Path
+) -> None:
+ app, notebook_id, events = live_host
+ runtime = f"/notebooks/{notebook_id}/runtime"
+ runs = runtime + "/runs"
+ marker = tmp_path / "executions"
+ body = json.dumps(
+ {
+ "code": (
+ f"_marker = __import__('pathlib').Path({str(marker)!r})\n"
+ "_marker.write_text((_marker.read_text() if _marker.exists() else '') + 'x')"
+ )
+ }
+ ).encode()
+ accepted = await finished(
+ app, "POST", runs, headers=key("once"), body=body
+ )
+ assert accepted.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("status") == "completed"
+ for r in response.records
+ ),
+ )
+ [completed] = [
+ r["data"]["run"]
+ for r in events.records
+ if r.get("data", {}).get("run", {}).get("status") == "completed"
+ ]
+ replayed = await finished(
+ app, "POST", runs, headers=key("once"), body=body
+ )
+ assert replayed.status == 202
+ assert replayed.json() == completed
+
+ restarted = await finished(
+ app, "POST", runtime + "/restart", headers=key("restart")
+ )
+ assert restarted.status == 202
+ new_runtime_id = restarted.json()["id"]
+ assert restarted.json()["status"] == "starting"
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("event") == "runtime"
+ and r["data"]["runtime"]["id"] == new_runtime_id
+ and r["data"]["runtime"]["status"] == "running"
+ for r in response.records
+ ),
+ timeout=15,
+ )
+ replayed = await finished(
+ app, "POST", runs, headers=key("once"), body=body
+ )
+ assert replayed.status == 202
+ assert replayed.json() == completed
+ assert marker.read_text() == "x"
+
+
+CASCADE_NOTEBOOK = """import marimo
+app = marimo.App()
+
+def _():
+ import anywidget
+ import traitlets
+ import threading
+ import marimo as mo
+ class CounterWidget(anywidget.AnyWidget):
+ value = traitlets.Int(0).tag(sync=True)
+ counter = CounterWidget()
+ get_x, set_x = mo.state(counter.value)
+ counter.observe(lambda _: set_x(counter.value), names="value")
+ gate = threading.Event()
+ return counter, get_x, set_x, gate, mo
+
+def _(mo):
+ get_y, set_y = mo.state(0)
+ return get_y, set_y
+
+def _(get_x, set_y):
+ current = get_x()
+ if current == 99:
+ raise ValueError("downstream failed")
+ set_y(current)
+ return
+
+def _(get_y):
+ print(10 + get_y())
+ return
+"""
+
+
+async def initialize_cascade(app: Starlette, events: Response) -> None:
+ # Pytest can import the test directory as an empty namespace package.
+ if not hasattr(pytest.importorskip("anywidget"), "AnyWidget"):
+ pytest.skip("requires anywidget")
+ session = next(iter(app.state.session_manager.sessions.values()))
+ session.instantiate(
+ InstantiateNotebookRequest(object_ids=[], values=[], auto_run=True),
+ http_request=None,
+ )
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("status") == "completed"
+ for r in response.records
+ ),
+ )
+ runs = [
+ r["data"]["run"] for r in events.records if r.get("event") == "run"
+ ]
+ assert runs[-1]["outcome"] == "succeeded", [
+ r["data"]["execution"]["outcome"]
+ for r in events.records
+ if r.get("event") == "execution"
+ and r["data"]["execution"]["status"] == "completed"
+ ]
+
+
[email protected]("anywidget", "traitlets")
+ "notebook_source", [CASCADE_NOTEBOOK], indirect=True, ids=["widget"]
+)
+ ("value", "outcome", "children"), [(20, "succeeded", 2), (99, "failed", 1)]
+)
+async def test_scratch_run_includes_the_full_reactive_cycle(
+ live_host: tuple[Starlette, str, Response],
+ value: int,
+ outcome: str,
+ children: int,
+) -> None:
+ app, notebook_id, events = live_host
+ await initialize_cascade(app, events)
+ accepted = await finished(
+ app,
+ "POST",
+ f"/notebooks/{notebook_id}/runtime/runs",
+ headers=key("cascade"),
+ body=json.dumps({"code": f"counter.value = {value}"}).encode(),
+ )
+ assert accepted.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("id") == "cascade"
+ and r["data"]["run"]["status"] == "completed"
+ for r in response.records
+ ),
+ )
+ records = [
+ r
+ for r in events.records
+ if r.get("data", {}).get("request_id") == "cascade"
+ ]
+ assert records[-1]["event"] == "run"
+ assert records[-1]["data"]["run"]["outcome"] == outcome
+ executions = [
+ r["data"]["execution"]
+ for r in records
+ if r["event"] == "execution"
+ and r["data"]["execution"]["status"] == "completed"
+ ]
+ assert len(executions) == children + 1
+ root, *downstream = executions
+ assert root["cell_id"] is None
+ assert root["outcome"]["kind"] == "value"
+ assert all(
+ e["run_id"] == "cascade"
+ and e["cell_id"] is not None
+ and e["caused_by"] == root["id"]
+ for e in downstream
+ )
+ assert downstream[-1]["outcome"]["kind"] == (
+ "error" if outcome == "failed" else "value"
+ )
+ if outcome == "succeeded":
+ consoles = [
+ r["data"]["console"] for r in records if r["event"] == "console"
+ ]
+ assert "".join(c["text"] for c in consoles) == "30\n"
+ assert {c["execution_id"] for c in consoles} == {downstream[-1]["id"]}
+
+
[email protected]("anywidget", "traitlets")
+ "notebook_source", [CASCADE_NOTEBOOK], indirect=True, ids=["widget"]
+)
[email protected]("command", [False, True])
+async def test_detached_reactivity_starts_a_new_run(
+ live_host: tuple[Starlette, str, Response],
+ command: bool,
+) -> None:
+ app, notebook_id, events = live_host
+ await initialize_cascade(app, events)
+ origin = (
+ "import asyncio\n"
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteCellsCommand\n"
+ "ctx = cm.get_context()\n"
+ "async def later():\n"
+ " await asyncio.to_thread(gate.wait)\n"
+ " await ctx.execute_command(ExecuteCellsCommand(cell_ids=['later'], codes=['print(30)']))\n"
+ "asyncio.create_task(later())"
+ if command
+ else "mo.Thread(target=lambda: (gate.wait(), set_x(20))).start()"
+ )
+ for run_id, code in [
+ ("origin", origin),
+ ("release", "gate.set()"),
+ ]:
+ accepted = await finished(
+ app,
+ "POST",
+ f"/notebooks/{notebook_id}/runtime/runs",
+ headers=key(run_id),
+ body=json.dumps({"code": code}).encode(),
+ )
+ assert accepted.status == 202
+ await wait_for(
+ events,
+ lambda response, run_id=run_id: any(
+ r.get("data", {}).get("run", {}).get("id") == run_id
+ and r["data"]["run"]["status"] == "completed"
+ for r in response.records
+ ),
+ )
+ await wait_for(
+ events,
+ lambda response: any(
+ "30\n" in r.get("data", {}).get("console", {}).get("text", "")
+ for r in response.records
+ ),
+ )
+ printed = next(
+ r["data"]["console"]
+ for r in events.records
+ if "30\n" in r.get("data", {}).get("console", {}).get("text", "")
+ )
+ execution = next(
+ r["data"]["execution"]
+ for r in events.records
+ if r.get("data", {}).get("execution", {}).get("id")
+ == printed["execution_id"]
+ )
+ assert execution["run_id"] not in ("origin", "release")
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("id") == execution["run_id"]
+ and r["data"]["run"]["status"] == "completed"
+ for r in response.records
+ ),
+ )
+ origin = [
+ r["data"]["run"]
+ for r in events.records
+ if r.get("data", {}).get("run", {}).get("id") == "origin"
+ ]
+ assert [r["status"] for r in origin] == ["queued", "running", "completed"]
+ assert origin[-1]["outcome"] == "succeeded"
+
+
+async def test_nested_evaluations_keep_the_scratch_result_and_skipped_child(
+ live_host: tuple[Starlette, str, Response],
+) -> None:
+ app, notebook_id, events = live_host
+ code = (
+ "import marimo._code_mode as cm\n"
+ "async with cm.get_context() as ctx:\n"
+ " a = ctx.create_cell('x = 1/0')\n"
+ " b = ctx.create_cell('y = x + 1')\n"
+ " ctx.run_cell(a)\n"
+ " ctx.run_cell(b)\n"
+ "42"
+ )
+ accepted = await finished(
+ app,
+ "POST",
+ f"/notebooks/{notebook_id}/runtime/runs",
+ headers=key("nested"),
+ body=json.dumps({"code": code}).encode(),
+ )
+ assert accepted.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("id") == "nested"
+ and r["data"]["run"]["status"] == "completed"
+ for r in response.records
+ ),
+ )
+ records = [
+ r
+ for r in events.records
+ if r.get("data", {}).get("request_id") == "nested"
+ ]
+ assert records[-1]["data"]["run"]["outcome"] == "failed"
+ executions = [
+ r["data"]["execution"]
+ for r in records
+ if r["event"] == "execution"
+ and r["data"]["execution"]["status"] == "completed"
+ ]
+ assert len(executions) == 3
+ [root] = [e for e in executions if e["cell_id"] is None]
+ assert root["outcome"]["kind"] == "value"
+ assert "42" in root["outcome"]["display"]["data"]
+ assert all(
+ e["outcome"]["kind"] == "error"
+ for e in executions
+ if e["cell_id"] is not None
+ )
+
+
+async def test_a_fixed_cell_replaces_its_failed_compilation(
+ live_host: tuple[Starlette, str, Response],
+) -> None:
+ app, notebook_id, events = live_host
+ code = (
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteCellsCommand\n"
+ "await cm.get_context().execute_command(ExecuteCellsCommand(cell_ids=['child'], codes=['if !!!']))\n"
+ "await cm.get_context().execute_command(ExecuteCellsCommand(cell_ids=['child'], codes=['x = 42']))\n"
+ "42"
+ )
+ accepted = await finished(
+ app,
+ "POST",
+ f"/notebooks/{notebook_id}/runtime/runs",
+ headers=key("retry"),
+ body=json.dumps({"code": code}).encode(),
+ )
+ assert accepted.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("id") == "retry"
+ and r["data"]["run"]["status"] == "completed"
+ for r in response.records
+ ),
+ )
+ executions = [
+ r["data"]["execution"]
+ for r in events.records
+ if r.get("data", {}).get("execution", {}).get("cell_id") == "child"
+ and r["data"]["execution"]["status"] == "completed"
+ ]
+ assert [(e["code_hash"], e["outcome"]["kind"]) for e in executions] == [
+ (hashlib.sha256(b"if !!!").hexdigest(), "error"),
+ (hashlib.sha256(b"x = 42").hexdigest(), "value"),
+ ]
+ assert len({e["id"] for e in executions}) == 2
+ runs = [
+ r["data"]["run"]
+ for r in events.records
+ if r.get("data", {}).get("run", {}).get("id") == "retry"
+ ]
+ assert runs[-1]["outcome"] == "failed"
+
+
+async def test_nested_commands_can_run_a_cell_queued_by_the_outer_command(
+ live_host: tuple[Starlette, str, Response],
+) -> None:
+ app, notebook_id, events = live_host
+ inner = (
+ "x = 42\n"
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteCellsCommand\n"
+ "await cm.get_context().execute_command(ExecuteCellsCommand("
+ "cell_ids=['b'], codes=['print(x)']))"
+ )
+ code = (
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteCellsCommand\n"
+ "await cm.get_context().execute_command(ExecuteCellsCommand("
+ f"cell_ids=['a', 'b'], codes=[{inner!r}, 'print(x)']))"
+ )
+ accepted = await finished(
+ app,
+ "POST",
+ f"/notebooks/{notebook_id}/runtime/runs",
+ headers=key("nested-queue"),
+ body=json.dumps({"code": code}).encode(),
+ )
+ assert accepted.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("id") == "nested-queue"
+ and r["data"]["run"]["status"] == "completed"
+ for r in response.records
+ ),
+ )
+ executions = [
+ r["data"]["execution"]
+ for r in events.records
+ if r.get("data", {}).get("execution", {}).get("cell_id") == "b"
+ and r["data"]["execution"]["status"] == "completed"
+ ]
+ assert [e["outcome"]["kind"] for e in executions] == ["value", "value"]
+ assert len({e["id"] for e in executions}) == 2
+ runs = [
+ r["data"]["run"]
+ for r in events.records
+ if r.get("data", {}).get("run", {}).get("id") == "nested-queue"
+ ]
+ assert runs[-1]["outcome"] == "succeeded"
+
+
[email protected]("nested_scratch", [False, True])
[email protected]("child_code", ["1/0", "if !!!"])
+async def test_awaited_commands_join_the_enclosing_run(
+ live_host: tuple[Starlette, str, Response],
+ nested_scratch: bool,
+ child_code: str,
+) -> None:
+ app, notebook_id, events = live_host
+ command = (
+ f"ExecuteScratchpadCommand(code={child_code!r}, request=None)"
+ if nested_scratch
+ else f"ExecuteCellsCommand(cell_ids=['child'], codes=[{child_code!r}])"
+ )
+ sibling = (
+ "await cm.get_context().execute_command(ExecuteScratchpadCommand(code='3 * 3', request=None))\n"
+ if nested_scratch
+ else ""
+ )
+ code = (
+ "import marimo._code_mode as cm\n"
+ "from marimo._runtime.commands import ExecuteCellsCommand, ExecuteScratchpadCommand\n"
+ f"await cm.get_context().execute_command({command})\n{sibling}42"
+ )
+ before = len(events.records)
+ accepted = await finished(
+ app,
+ "POST",
+ f"/notebooks/{notebook_id}/runtime/runs",
+ headers=key("awaited"),
+ body=json.dumps({"code": code}).encode(),
+ )
+ assert accepted.status == 202
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("id") == "awaited"
+ and r["data"]["run"]["status"] == "completed"
+ for r in response.records
+ ),
+ )
+ records = events.records[before:]
+ runs = [r["data"]["run"] for r in records if r.get("event") == "run"]
+ assert {r["id"] for r in runs} == {"awaited"}
+ assert runs[-1]["outcome"] == "failed"
+ executions = [
+ r["data"]["execution"]
+ for r in records
+ if r.get("event") == "execution"
+ and r["data"]["execution"]["status"] == "completed"
+ ]
+ assert len(executions) == (3 if nested_scratch else 2)
+ [root] = [e for e in executions if e["caused_by"] is None]
+ children = [e for e in executions if e["caused_by"] == root["id"]]
+ assert len(children) == len(executions) - 1
+ child = children[0]
+ assert root["outcome"]["kind"] == "value"
+ assert "42" in root["outcome"]["display"]["data"]
+ assert child["outcome"]["kind"] == "error"
+ assert (
+ child["code_hash"] == hashlib.sha256(child_code.encode()).hexdigest()
+ )
+ assert all(e["run_id"] == "awaited" for e in executions)
+
+
+ "notebook_source",
+ [
+ "import marimo\napp = marimo.App()\[email protected]\ndef _():\n x = __file__\n return (x,)\n"
+ ],
+ indirect=True,
+)
+async def test_rename_reactivity_completes_its_run(
+ live_host: tuple[Starlette, str, Response],
+) -> None:
+ app, notebook_id, events = live_host
+ session = next(iter(app.state.session_manager.sessions.values()))
+ session.instantiate(
+ InstantiateNotebookRequest(object_ids=[], values=[], auto_run=True),
+ http_request=None,
+ )
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("status") == "completed"
+ for r in response.records
+ ),
+ )
+ before = len(events.records)
+ moved = await finished(
+ app,
+ "PATCH",
+ f"/notebooks/{notebook_id}",
+ headers=key("rename"),
+ body=b'{"path":"renamed.py"}',
+ )
+ assert moved.status == 200
+ await wait_for(
+ events,
+ lambda response: any(
+ r.get("data", {}).get("run", {}).get("status") == "completed"
+ for r in response.records[before:]
+ ),
+ )
+ runs = [
+ r["data"]["run"]
+ for r in events.records[before:]
+ if r.get("event") == "run"
+ ]
+ assert runs[-1]["outcome"] == "succeeded"
+ accepted = await finished(
+ app,
+ "POST",
+ f"/notebooks/{notebook_id}/runtime/runs",
+ headers=key("after-rename"),
+ body=b'{"code":"42"}',
+ )
+ assert accepted.status == 202
diff --git a/tests/_server/host/test_host_index.py b/tests/_server/host/test_host_index.py
new file mode 100644
index 0000000000..86c6fdef28
--- /dev/null
+++ b/tests/_server/host/test_host_index.py
@@ -0,0 +1,159 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Workspace indexing and notebook catalog updates."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from msgspec.structs import replace
+
+from marimo._core import backend as be
+from marimo._core.errors import NotFound
+from marimo._core.host import Host
+from marimo._core.protocol import ProjectMessage
+from marimo._core.stream import Event
+from marimo._server.host.index import WorkspaceIndex
+from marimo._server.models.home import MarimoFile
+from marimo._server.workspace import FixedFilesWorkspace
+from tests._core.conftest import ScriptedBackend, names
+
+
+def workspace(root: Path, *names: str) -> FixedFilesWorkspace:
+ files = []
+ for name in names:
+ path = root / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ if not path.exists():
+ path.write_text("import marimo\n")
+ files.append(MarimoFile(name=name, path=str(path), last_modified=1.0))
+ return FixedFilesWorkspace(files, directory=str(root))
+
+
+def test_refresh_publishes_the_project_and_its_notebooks(
+ tmp_path: Path,
+) -> None:
+ host = Host(operations=[])
+ index = WorkspaceIndex(
+ host,
+ workspace(tmp_path, "a.py", "sub/b.py"),
+ lambda _: ScriptedBackend(),
+ )
+ index.refresh()
+
+ assert names(host.events()) == [
+ "host",
+ "project",
+ "notebook",
+ "notebook",
+ "ready",
+ ]
+ [project] = [
+ e.data.project
+ for e in host.events()
+ if isinstance(e.data, ProjectMessage)
+ ]
+ assert project.root == str(tmp_path)
+ assert project.status == "indexed"
+ records = sorted(n.path or "" for n in host.notebooks.values())
+ assert records == ["a.py", str(Path("sub") / "b.py")]
+
+
+def test_ids_survive_a_rescan_and_a_move(tmp_path: Path) -> None:
+ host = Host(operations=[])
+ index = WorkspaceIndex(
+ host, workspace(tmp_path, "a.py"), lambda _: ScriptedBackend()
+ )
+ index.refresh()
+ (notebook,) = host.notebooks.values()
+ log: list[Event] = []
+ host.subscribe(log.append)
+
+ index.refresh()
+ assert log == []
+
+ (tmp_path / "a.py").rename(tmp_path / "b.py")
+ moved = index.moved(notebook.id, str(tmp_path / "b.py"), request_id="req")
+ assert moved is not None
+ assert moved.id == notebook.id
+ assert moved.path == "b.py"
+ assert moved.name == "b"
+ assert names(log) == ["notebook"]
+ assert index.notebook_for(str(tmp_path / "b.py")) == moved
+ assert index.notebook_for(str(tmp_path / "a.py")) is None
+ assert index.file_of(notebook.id) == tmp_path / "b.py"
+
+
+def test_a_deleted_file_leaves_the_catalog(tmp_path: Path) -> None:
+ host = Host(operations=[])
+ ws = workspace(tmp_path, "a.py", "b.py")
+ index = WorkspaceIndex(host, ws, lambda _: ScriptedBackend())
+ index.refresh()
+ removed = index.notebook_for(str(tmp_path / "b.py"))
+ assert removed is not None
+ index.rename(removed.id, "Old name")
+ (tmp_path / "b.py").unlink()
+ ws._files = [f for f in ws._files if f.name == "a.py"]
+
+ index.refresh()
+
+ assert [n.path for n in host.notebooks.values()] == ["a.py"]
+ with pytest.raises(NotFound):
+ host.notebook(removed.id)
+
+ (tmp_path / "b.py").write_text("import marimo\n")
+ recreated = index.ensure(str(tmp_path / "b.py"))
+ assert recreated is not None
+ assert recreated.id != removed.id
+ assert recreated.name == "b"
+
+
+def test_ensure_admits_a_file_the_listing_missed(tmp_path: Path) -> None:
+ host = Host(operations=[])
+ index = WorkspaceIndex(
+ host, workspace(tmp_path, "a.py"), lambda _: ScriptedBackend()
+ )
+ index.refresh()
+ (tmp_path / "c.py").write_text("")
+
+ admitted = index.ensure(str(tmp_path / "c.py"))
+ assert admitted is not None
+ assert admitted.path == "c.py"
+ assert index.ensure(str(tmp_path / "missing.py")) is None
+ outside = tmp_path.parent / f"{tmp_path.name}-outside.py"
+ outside.write_text("import marimo\n")
+ assert index.ensure(str(outside)) is None
+ index.refresh()
+ assert admitted.id in host.notebooks
+
+
+def test_deleted_file_keeps_its_runtime_until_stopped(tmp_path: Path) -> None:
+ host = Host(operations=[])
+ ws = workspace(tmp_path, "a.py")
+ backend = ScriptedBackend()
+ index = WorkspaceIndex(host, ws, lambda _: backend)
+ index.refresh()
+ (record,) = host.notebooks.values()
+ notebook = host.notebook(record.id)
+ notebook.start()
+ notebook.observe(be.Running())
+ runtime = notebook.runtime
+ backend.calls.clear()
+ (tmp_path / "a.py").unlink()
+ ws._files = []
+
+ index.refresh()
+ index.refresh()
+
+ assert host.notebooks[record.id] == replace(
+ record, path=None, updated_at=None
+ )
+ assert notebook.runtime == runtime
+ assert backend.calls == []
+
+ notebook.stop()
+ notebook.observe(be.Exited())
+ index.refresh()
+
+ assert dict(host.notebooks) == {}
+ assert backend.calls == [("stop",)]
diff --git a/tests/_server/host/test_host_record.py b/tests/_server/host/test_host_record.py
new file mode 100644
index 0000000000..62960f75d4
--- /dev/null
+++ b/tests/_server/host/test_host_record.py
@@ -0,0 +1,82 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Host discovery records and server lifecycle."""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from typing import TYPE_CHECKING
+
+import msgspec
+import pytest
+import uvicorn
+
+from marimo._core import protocol
+from marimo._server.host import HOST_API_PATH, record as record_module
+from marimo._server.host.lifespan import host as host_lifespan
+from marimo._server.host.record import host_url
+from marimo._server.main import create_starlette_app
+from marimo._utils.lifespans import Lifespans
+from tests._server.host.drive import finished
+from tests._server.mocks import get_starlette_server_state_init
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+
+def test_the_url_always_names_a_loopback_address() -> None:
+ assert (
+ host_url("0.0.0.0", 2718, "")
+ == f"http://127.0.0.1:2718{HOST_API_PATH}"
+ )
+ assert host_url("::1", 2718, "/marimo") == (
+ f"http://[::1]:2718/marimo{HOST_API_PATH}"
+ )
+ assert host_url("[::1]", 2718, "") == f"http://[::1]:2718{HOST_API_PATH}"
+
+
[email protected]("external_port", [1234, 8443])
+async def test_the_lifespan_serves_the_host_while_the_server_runs(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, external_port: int
+) -> None:
+ monkeypatch.setattr(record_module, "marimo_state_dir", lambda: tmp_path)
+ app = create_starlette_app(
+ base_url="", enable_auth=True, lifespan=Lifespans([host_lifespan])
+ )
+ state = get_starlette_server_state_init()
+ state.apply(app.state)
+ app.state.port = external_port
+ app.state.host = "proxy.example" if external_port != 1234 else "localhost"
+ app.state.server = uvicorn.Server(
+ uvicorn.Config(app, host="127.0.0.1", port=1234)
+ )
+
+ async with app.router.lifespan_context(app):
+ [path] = list((tmp_path / "hosts-v1").glob("*.json"))
+ record = msgspec.json.decode(
+ path.read_bytes(), type=protocol.HostRecord
+ )
+ assert record.url == f"http://127.0.0.1:1234{HOST_API_PATH}"
+ assert record.process.pid == os.getpid()
+ if sys.platform != "win32":
+ assert stat.S_IMODE(path.stat().st_mode) == 0o600
+ assert stat.S_IMODE(path.parent.stat().st_mode) == 0o700
+
+ probe = "/notebooks/x/runtime"
+ refused = await finished(
+ app, "DELETE", probe, headers={"Idempotency-Key": "k"}
+ )
+ assert refused.status == 401
+ admitted = await finished(
+ app,
+ "DELETE",
+ probe,
+ headers={
+ "Authorization": f"Bearer {record.token}",
+ "Idempotency-Key": "k",
+ },
+ )
+ assert admitted.status == 404
+
+ assert list((tmp_path / "hosts-v1").glob("*.json")) == []
diff --git a/tests/_server/host/test_host_translate.py b/tests/_server/host/test_host_translate.py
new file mode 100644
index 0000000000..30405d1556
--- /dev/null
+++ b/tests/_server/host/test_host_translate.py
@@ -0,0 +1,334 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Translation of kernel notifications into backend messages."""
+
+from __future__ import annotations
+
+import hashlib
+
+import pytest
+from dirty_equals import IsStr
+from inline_snapshot import snapshot
+
+from marimo._core.backend import (
+ Concluded,
+ Done,
+ Planned,
+ PlannedExecution,
+ Produced,
+ Status,
+)
+from marimo._core.protocol import (
+ Console,
+ DisplayData,
+ Error,
+ ErrorOutcome,
+ ExecutionId,
+ InterruptedOutcome,
+ RunId,
+ ValueOutcome,
+)
+from marimo._messaging.cell_output import CellChannel, CellOutput
+from marimo._messaging.errors import (
+ MarimoExceptionRaisedError,
+ MarimoInterruptionError,
+)
+from marimo._messaging.notification import (
+ CellNotification,
+ CompletedRunNotification,
+ ExecutionNotification,
+)
+from marimo._runtime.scratch import SCRATCH_CELL_ID
+from marimo._server.host.translate import RunTranslator
+from marimo._types.ids import CellId_t
+
+
+def scratch(**fields: object) -> CellNotification:
+ return CellNotification(
+ cell_id=SCRATCH_CELL_ID, run_id="r1", execution_id="scratch", **fields
+ ) # type: ignore[arg-type]
+
+
+def attempt(phase: str, **fields: object) -> ExecutionNotification:
+ return ExecutionNotification(
+ cell_id=SCRATCH_CELL_ID,
+ run_id="r1",
+ execution_id="scratch",
+ phase=phase,
+ code="3 * 3" if phase == "planned" else None,
+ **fields,
+ ) # type: ignore[arg-type]
+
+
+def test_a_run_that_prints_and_shows_a_value() -> None:
+ t = RunTranslator(RunId("r1"), "3 * 3")
+
+ messages = t.feed(attempt("planned"))
+ messages.extend(t.feed(attempt("running")))
+ messages.extend(t.feed(scratch(console=CellOutput.stdout("2\n"))))
+ messages.extend(
+ t.feed(
+ scratch(
+ output=CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="text/html",
+ data="<pre>9</pre>",
+ ) # type: ignore[arg-type]
+ )
+ )
+ )
+ assert t.feed(CompletedRunNotification(run_id="other")) == []
+ assert not t.completed
+ messages.extend(t.feed(attempt("completed")))
+ messages.extend(t.feed(CompletedRunNotification(run_id="r1")))
+ assert t.completed
+ messages.extend(t.finish())
+
+ assert messages == snapshot(
+ [
+ Planned(
+ run_id=RunId("r1"),
+ executions=(
+ PlannedExecution(
+ id=ExecutionId("r1-1"),
+ cell_id=None,
+ code_hash=hashlib.sha256(b"3 * 3").hexdigest(),
+ code="3 * 3",
+ caused_by=None,
+ ),
+ ),
+ ),
+ Status(execution_id=ExecutionId("r1-1"), status="running"),
+ Produced(
+ item=Console(
+ execution_id=ExecutionId("r1-1"),
+ id=IsStr(),
+ name="stdout",
+ seq=0,
+ text="2\n",
+ )
+ ),
+ Concluded(
+ execution_id=ExecutionId("r1-1"),
+ outcome=ValueOutcome(
+ display=DisplayData(
+ data="<pre>9</pre>", mimetype="text/html"
+ )
+ ),
+ ),
+ Status(execution_id=ExecutionId("r1-1"), status="completed"),
+ Done(run_id=RunId("r1"), outcome="succeeded"),
+ ]
+ )
+
+
+def test_unrelated_output_does_not_belong_to_the_scratch_execution() -> None:
+ t = RunTranslator(RunId("r1"), "3 * 3")
+ other = CellNotification(
+ cell_id=CellId_t("c1"), console=CellOutput.stdout("x")
+ )
+ assert t.feed(other) == []
+ t.feed(attempt("planned"))
+ t.feed(attempt("running"))
+ assert t.feed(other) == []
+ assert (
+ t.feed(
+ CellNotification(
+ cell_id=SCRATCH_CELL_ID,
+ run_id="other",
+ console=CellOutput.stdout("x"),
+ )
+ )
+ == []
+ )
+
+
+def test_an_exception_ends_the_run_in_error() -> None:
+ t = RunTranslator(RunId("r1"), "3 * 3")
+ t.feed(attempt("planned"))
+ t.feed(attempt("running"))
+ error = MarimoExceptionRaisedError(
+ msg="division by zero",
+ exception_type="ZeroDivisionError",
+ raising_cell=None,
+ traceback="Traceback...\nZeroDivisionError: division by zero\n",
+ )
+ assert t.feed(scratch(output=CellOutput.errors([error]))) == []
+
+ assert t.finish() == snapshot(
+ [
+ Concluded(
+ execution_id=ExecutionId("r1-1"),
+ outcome=ErrorOutcome(
+ error=Error(
+ source="marimo",
+ severity="error",
+ range=None,
+ related=[],
+ kind="exception",
+ message="division by zero",
+ name="ZeroDivisionError",
+ traceback=DisplayData(
+ data="""\
+Traceback...
+ZeroDivisionError: division by zero
+""",
+ mimetype="text/plain",
+ ),
+ )
+ ),
+ ),
+ Status(execution_id=ExecutionId("r1-1"), status="completed"),
+ Done(run_id=RunId("r1"), outcome="failed"),
+ ]
+ )
+
+
[email protected]("interrupted_by", ["kernel", "client"])
+def test_an_interruption_ends_the_run_interrupted(
+ interrupted_by: str,
+) -> None:
+ t = RunTranslator(RunId("r1"), "3 * 3")
+ t.feed(attempt("planned"))
+ t.feed(attempt("running"))
+ if interrupted_by == "kernel":
+ t.feed(scratch(output=CellOutput.errors([MarimoInterruptionError()])))
+ else:
+ t.interrupted = True
+
+ assert t.finish() == snapshot(
+ [
+ Concluded(
+ execution_id=ExecutionId("r1-1"),
+ outcome=InterruptedOutcome(),
+ ),
+ Status(execution_id=ExecutionId("r1-1"), status="completed"),
+ Done(run_id=RunId("r1"), outcome="interrupted"),
+ ]
+ )
+
+
+def test_console_items_number_in_order_and_lose_highlighting() -> None:
+ t = RunTranslator(RunId("r1"), "3 * 3")
+ t.feed(attempt("planned"))
+ t.feed(attempt("running"))
+ out = t.feed(
+ scratch(
+ console=[
+ CellOutput.stdout("a"),
+ CellOutput.stderr('<span class="codehilite">&lt;b&gt;</span>'),
+ ]
+ )
+ )
+ items = [m.item for m in out if isinstance(m, Produced)]
+ assert len({i.id for i in items}) == 2
+ assert out == snapshot(
+ [
+ Produced(
+ item=Console(
+ execution_id=ExecutionId("r1-1"),
+ id=IsStr(),
+ name="stdout",
+ seq=0,
+ text="a",
+ )
+ ),
+ Produced(
+ item=Console(
+ execution_id=ExecutionId("r1-1"),
+ id=IsStr(),
+ name="stderr",
+ seq=1,
+ text="<b>",
+ )
+ ),
+ ]
+ )
+
+
+def test_late_output_keeps_its_evaluation_when_a_cell_runs_again() -> None:
+ translator = RunTranslator(RunId("r1"), None)
+ ids = []
+ for identity in ("first", "second"):
+ planned = translator.feed(
+ ExecutionNotification(
+ cell_id=CellId_t("cell"),
+ run_id="r1",
+ phase="planned",
+ execution_id=identity,
+ code="pass",
+ )
+ )[0]
+ assert isinstance(planned, Planned)
+ ids.append(planned.executions[0].id)
+ translator.feed(
+ ExecutionNotification(
+ cell_id=CellId_t("cell"),
+ run_id="r1",
+ phase="completed",
+ execution_id=identity,
+ )
+ )
+ assert ids[0] != ids[1]
+ assert translator.finish() == [Done(RunId("r1"), "succeeded")]
+ [output] = translator.feed(
+ CellNotification(
+ cell_id=CellId_t("cell"),
+ run_id="r1",
+ execution_id="first",
+ console=CellOutput.stdout("late"),
+ )
+ )
+ assert isinstance(output, Produced)
+ assert output.item.execution_id == ids[0]
+
+
+ ("error", "outcome_type", "run_outcome"),
+ [
+ (MarimoInterruptionError(), InterruptedOutcome, "interrupted"),
+ (
+ MarimoExceptionRaisedError(
+ "ancestor failed", "RuntimeError", None
+ ),
+ ErrorOutcome,
+ "failed",
+ ),
+ ],
+)
+def test_skipped_cells_report_their_error_after_becoming_idle(
+ error: object, outcome_type: type, run_outcome: str
+) -> None:
+ translator = RunTranslator(RunId("r1"), None)
+
+ def cell(**fields: object) -> CellNotification:
+ return CellNotification(
+ cell_id=CellId_t("cell"),
+ run_id="r1",
+ execution_id="skipped",
+ **fields,
+ ) # type: ignore[arg-type]
+
+ translator.feed(
+ ExecutionNotification(
+ cell_id=CellId_t("cell"),
+ run_id="r1",
+ execution_id="skipped",
+ phase="planned",
+ code="pass",
+ )
+ )
+ assert translator.feed(cell(status="idle")) == []
+ translator.feed(cell(output=CellOutput.errors([error]))) # type: ignore[list-item]
+ messages = translator.feed(
+ ExecutionNotification(
+ cell_id=CellId_t("cell"),
+ run_id="r1",
+ execution_id="skipped",
+ phase="completed",
+ )
+ )
+ messages.extend(translator.finish())
+ assert isinstance(messages[0], Concluded)
+ assert isinstance(messages[0].outcome, outcome_type)
+ assert messages[1] == Status(ExecutionId("r1-1"), "completed")
+ assert messages[2] == Done(RunId("r1"), run_outcome) # type: ignore[arg-type]
diff --git a/tests/_session/notebook/test_filesystem_storage.py b/tests/_session/notebook/test_filesystem_storage.py
index 80c74a862e..0210f59719 100644
--- a/tests/_session/notebook/test_filesystem_storage.py
+++ b/tests/_session/notebook/test_filesystem_storage.py
@@ -80,6 +80,21 @@ class TestFilesystemStorage:
assert new_file.exists()
assert new_file.read_text(encoding="utf-8") == "content"
+ def test_rename_preserves_an_existing_destination(
+ self, tmp_path: Path
+ ) -> None:
+ source, target = tmp_path / "source.py", tmp_path / "target.py"
+ source.write_text("source notebook")
+ target.write_text("destination notebook")
+
+ with pytest.raises(HTTPException):
+ FilesystemStorage().rename(source, target)
+
+ assert (source.read_text(), target.read_text()) == (
+ "source notebook",
+ "destination notebook",
+ )
+
def test_rename_creates_parent_dirs(self, tmp_path: Path) -> None:
storage = FilesystemStorage()
old_file = tmp_path / "old.txt"