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.

Correlate scratchpad completion with `run_id` (#9350)

Trevor Manz0aabb241a4b2
diff --git a/marimo/_mcp/code_server/main.py b/marimo/_mcp/code_server/main.py
index 4a3f5dc310..f2e0ed7b69 100644
--- a/marimo/_mcp/code_server/main.py
+++ b/marimo/_mcp/code_server/main.py
@@ -10,6 +10,7 @@ from __future__ import annotations
import os
from typing import TYPE_CHECKING
+from uuid import uuid4
from marimo._ai._tools.types import (
CodeExecutionResult,
@@ -125,11 +126,13 @@ def setup_code_mcp_server(
"Use list_sessions to find valid session IDs.",
)
- listener = ScratchCellListener()
+ # Correlation ID: see /api/kernel/execute for rationale.
+ run_id = str(uuid4())
+ listener = ScratchCellListener(run_id=run_id)
with session.scoped(listener):
async with session.scratchpad_lock:
session.put_control_request(
- ExecuteScratchpadCommand(code=code),
+ ExecuteScratchpadCommand(code=code, run_id=run_id),
from_consumer_id=None,
)
await listener.wait(timeout=EXECUTION_TIMEOUT)
diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.py
index 213a94d00e..6fc7f111ee 100644
--- a/marimo/_messaging/notification.py
+++ b/marimo/_messaging/notification.py
@@ -238,9 +238,18 @@ class InterruptedNotification(Notification, tag="interrupted"):
class CompletedRunNotification(Notification, tag="completed-run"):
- """Run of submitted cells and descendants completed."""
+ """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.
+ """
name: ClassVar[str] = "completed-run"
+ run_id: str | None = None
class KernelCapabilitiesNotification(msgspec.Struct):
diff --git a/marimo/_runtime/commands.py b/marimo/_runtime/commands.py
index 556a7e9411..6134dec0af 100644
--- a/marimo/_runtime/commands.py
+++ b/marimo/_runtime/commands.py
@@ -360,6 +360,12 @@ class ExecuteScratchpadCommand(Command):
notebook_cells: Snapshot of notebook cells from the session document.
Used to populate the document ContextVar so code_mode can read
cell ordering, code, names, and configs.
+ run_id: Optional correlation ID. When set, the
+ ``CompletedRunNotification`` emitted at the end of this command
+ carries the same ``run_id`` so a caller holding a
+ ``ScratchCellListener`` can filter for *its* completion and
+ ignore ``CompletedRun`` events from unrelated commands on the
+ same session.
"""
code: str
@@ -367,6 +373,7 @@ class ExecuteScratchpadCommand(Command):
request: HTTPRequest | None = None
# Document snapshot — set by the execution endpoint from session.document.
notebook_cells: tuple[NotebookCell, ...] | None = None
+ run_id: str | None = None
class RenameNotebookCommand(Command):
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index d7dcb9d873..f42a8bdcaa 100644
--- a/marimo/_runtime/runtime.py
+++ b/marimo/_runtime/runtime.py
@@ -1768,9 +1768,21 @@ class Kernel:
# If cannot compile, don't run
cell, error = self._try_compiling_cell(SCRATCH_CELL_ID, code, [])
if error:
+ # Surface the diagnostic on stderr so SSE clients (e.g. the
+ # /api/kernel/execute CLI path) see it — compile errors
+ # never hit ``write_traceback``, so without this the error
+ # only reaches the ``CellNotification`` side channel and
+ # the SSE ``done`` event drops it.
+ CellNotificationUtils.broadcast_console_output(
+ channel=CellChannel.STDERR,
+ mimetype="text/plain",
+ data=error.describe(),
+ cell_id=SCRATCH_CELL_ID,
+ status=None,
+ )
CellNotificationUtils.broadcast_error(
data=[error],
- clear_console=True,
+ clear_console=False,
cell_id=SCRATCH_CELL_ID,
)
CellNotificationUtils.broadcast_status(
@@ -2361,12 +2373,18 @@ class Kernel:
if request.notebook_cells is not None
else None
)
- with (
- notebook_document_context(doc),
- http_request_context(request.request),
- ):
- await self.run_scratchpad(request.code)
- broadcast_notification(CompletedRunNotification())
+ try:
+ with (
+ notebook_document_context(doc),
+ http_request_context(request.request),
+ ):
+ await self.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)
+ )
async def handle_execute_stale(
request: ExecuteStaleCellsCommand,
diff --git a/marimo/_schemas/generated/notifications.yaml b/marimo/_schemas/generated/notifications.yaml
index 9fe9d7ede0..ed1d67798c 100644
--- a/marimo/_schemas/generated/notifications.yaml
+++ b/marimo/_schemas/generated/notifications.yaml
@@ -340,11 +340,21 @@ components:
title: ColumnStats
type: object
CompletedRunNotification:
- description: Run of submitted cells and descendants completed.
+ 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."
properties:
op:
enum:
- completed-run
+ run_id:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
required:
- op
title: CompletedRunNotification
@@ -957,6 +967,11 @@ components:
anyOf:
- type: string
- type: 'null'
+ traceback:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
type:
enum:
- exception
diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.py
index 1b94f81fa3..1b3f2508ec 100644
--- a/marimo/_server/api/endpoints/execution.py
+++ b/marimo/_server/api/endpoints/execution.py
@@ -297,8 +297,14 @@ async def execute_code(
async def sse_generator() -> AsyncGenerator[str, None]:
disconnect_task = asyncio.create_task(_watch_disconnect())
+ # Correlation ID: tags both the scratchpad command and the
+ # listener so we wait for *our* completion and ignore
+ # ``CompletedRun`` events from other commands on this session
+ # (e.g. the ``session.instantiate`` call above, or concurrent
+ # browser activity).
+ run_id = str(uuid4())
try:
- listener = ScratchCellListener()
+ listener = ScratchCellListener(run_id=run_id)
with session.scoped(listener):
async with session.scratchpad_lock:
http_req = HTTPRequest.from_request(request)
@@ -320,6 +326,7 @@ async def execute_code(
code=body.code,
request=http_req,
notebook_cells=tuple(session.document.cells),
+ run_id=run_id,
),
from_consumer_id=None,
)
diff --git a/marimo/_server/scratchpad.py b/marimo/_server/scratchpad.py
index f395f0df28..e5ddb98993 100644
--- a/marimo/_server/scratchpad.py
+++ b/marimo/_server/scratchpad.py
@@ -5,17 +5,14 @@ from __future__ import annotations
import asyncio
import json
-import sys
from typing import TYPE_CHECKING, Any, TypedDict
-if sys.version_info < (3, 11):
- from typing_extensions import NotRequired
-else:
- from typing import NotRequired
-
from marimo._ai._tools.types import CodeExecutionResult
from marimo._messaging.cell_output import CellChannel
-from marimo._messaging.notification import CellNotification
+from marimo._messaging.notification import (
+ CellNotification,
+ CompletedRunNotification,
+)
from marimo._messaging.serde import deserialize_kernel_message
from marimo._runtime.scratch import SCRATCH_CELL_ID
from marimo._session.extensions.types import EventAwareExtension
@@ -45,24 +42,21 @@ class OutputData(TypedDict):
data: str
-class ErrorData(TypedDict):
- type: str
- msg: str
- exception_type: NotRequired[str]
-
-
class ConsoleEvent(TypedDict):
data: str
-class DoneSuccess(TypedDict):
- success: bool
- output: NotRequired[OutputData]
+class Done(TypedDict):
+ """Terminal SSE event for ``/api/kernel/execute``.
+ ``success`` drives the CLI exit code. ``output`` is the scratch
+ cell's rendered value on success, or ``{mimetype: "text/plain",
+ data: ""}`` on failure — the actual error detail (traceback, etc.)
+ was already streamed via preceding ``stderr`` events.
+ """
-class DoneError(TypedDict):
success: bool
- error: ErrorData
+ output: OutputData
def _format_sse(event: str, data: Any) -> str:
@@ -83,14 +77,18 @@ class ScratchCellListener(EventAwareExtension):
In addition to the scratch cell's own output, the listener captures
console output (stdout/stderr) from *other* cells that execute while
the scratchpad is active — e.g. cells created and run by
- ``_code_mode``. Only the scratch cell's ``idle`` status triggers
- the done sentinel; non-scratch notifications are streamed but never
- signal completion.
+ ``_code_mode``. The done sentinel fires on the
+ ``CompletedRunNotification`` whose ``run_id`` matches this
+ listener's ``run_id`` — other completion events (e.g. from the
+ ``session.instantiate`` that happens before the scratchpad runs, or
+ from concurrent browser activity) are ignored, so we can't
+ misidentify someone else's completion as ours.
"""
- def __init__(self) -> None:
+ def __init__(self, *, run_id: str) -> None:
super().__init__()
self._queue: asyncio.Queue[CellNotification | None] = asyncio.Queue()
+ self._run_id = run_id
self.timed_out = False
self.child_error_summaries: list[str] = []
@@ -99,13 +97,22 @@ class ScratchCellListener(EventAwareExtension):
) -> None:
del session
msg = deserialize_kernel_message(notification)
+
+ # Completion sentinel: the ``CompletedRunNotification`` tagged
+ # with OUR run_id means the scratchpad's full cascade (including
+ # any ``state_updates`` flushed after the scratch cell goes
+ # idle) has settled. ``CompletedRun``s with other ids belong to
+ # unrelated commands — skip them.
+ if isinstance(msg, CompletedRunNotification):
+ if msg.run_id == self._run_id:
+ self._queue.put_nowait(None)
+ return
+
if not isinstance(msg, CellNotification):
return
if msg.cell_id == SCRATCH_CELL_ID:
self._queue.put_nowait(msg)
- if msg.status == "idle":
- self._queue.put_nowait(None) # sentinel
else:
if msg.console is not None:
# Stream console output from cells run by _code_mode
@@ -195,85 +202,39 @@ def _format_console(msg: CellNotification) -> list[str]:
]
+_EMPTY_OUTPUT = OutputData(mimetype="text/plain", data="")
+
+
def build_done_event(
session: Session,
listener: ScratchCellListener | None = None,
) -> str:
- """Build the ``done`` SSE event from the session's scratch cell state."""
+ """Build the terminal ``done`` SSE event.
+
+ ``success`` is false when the scratch cell itself errored OR any
+ downstream cell captured by the listener errored. The actual error
+ detail was already streamed via ``stderr`` events earlier in the
+ response — ``done`` carries only the success bit plus the scratch
+ cell's rendered output on success (empty on failure).
+ """
cell_notif = session.session_view.cell_notifications.get(SCRATCH_CELL_ID)
- if cell_notif is None:
- return _format_sse("done", DoneSuccess(success=True))
+ output = cell_notif.output if cell_notif is not None else None
- output = cell_notif.output
+ scratch_errored = (
+ output is not None and output.channel == CellChannel.MARIMO_ERROR
+ )
+ has_child_errors = bool(listener and listener.child_error_summaries)
+ success = not (scratch_errored or has_child_errors)
- # Error case — scratch cell itself errored
- if (
- output is not None
- and output.channel == CellChannel.MARIMO_ERROR
- and isinstance(output.data, list)
- and output.data
- ):
- err = output.data[0]
- error_data = ErrorData(
- type=type(err).__name__,
- msg=str(getattr(err, "msg", None) or err),
- )
- if hasattr(err, "exception_type"):
- error_data["exception_type"] = err.exception_type
- if err.exception_type in (
- "ModuleNotFoundError",
- "ImportError",
- ):
- error_data["msg"] += (
- "\n\nHint: Use ctx.install_packages(...)"
- " to install missing packages."
- )
- return _format_sse("done", DoneError(success=False, error=error_data))
-
- # Error case — child cells (created/run by code_mode) errored.
- # Full traceback was already streamed; msg is just a summary.
- if listener and listener.child_error_summaries:
- return _format_sse(
- "done",
- DoneError(
- success=False,
- error=ErrorData(
- type="CellExecutionError",
- msg="; ".join(listener.child_error_summaries),
- ),
- ),
- )
-
- # Success case
- if output is not None:
+ if success and output is not None and output.channel == CellChannel.OUTPUT:
data = output.data
if isinstance(data, dict):
data = data.get("text/plain", data.get("text/html", str(data)))
- return _format_sse(
- "done",
- DoneSuccess(
- success=True,
- output=OutputData(
- mimetype=str(output.mimetype), data=str(data)
- ),
- ),
- )
-
- return _format_sse("done", DoneSuccess(success=True))
-
-
-def build_timeout_event(timeout: float) -> str:
- """Build a ``done`` SSE event for a timeout."""
- return _format_sse(
- "done",
- DoneError(
- success=False,
- error=ErrorData(
- type="TimeoutError",
- msg=f"Execution timed out after {timeout}s",
- ),
- ),
- )
+ output_data = OutputData(mimetype=str(output.mimetype), data=str(data))
+ else:
+ output_data = _EMPTY_OUTPUT
+
+ return _format_sse("done", Done(success=success, output=output_data))
def extract_result(
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index e45073164d..66ba981d5c 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -731,11 +731,21 @@ components:
title: ColumnStats
type: object
CompletedRunNotification:
- description: Run of submitted cells and descendants completed.
+ 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."
properties:
op:
enum:
- completed-run
+ run_id:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
required:
- op
title: CompletedRunNotification
@@ -1501,7 +1511,12 @@ components:
\ request: HTTP request context if available.\n notebook_cells:\
\ Snapshot of notebook cells from the session document.\n Used\
\ to populate the document ContextVar so code_mode can read\n cell\
- \ ordering, code, names, and configs."
+ \ ordering, code, names, and configs.\n run_id: Optional correlation\
+ \ ID. When set, the\n ``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."
properties:
code:
type: string
@@ -1517,6 +1532,11 @@ components:
- $ref: '#/components/schemas/HTTPRequest'
- type: 'null'
default: null
+ runId:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
type:
enum:
- execute-scratchpad
@@ -1541,6 +1561,11 @@ components:
- $ref: '#/components/schemas/HTTPRequest'
- type: 'null'
default: null
+ runId:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
required:
- code
title: ExecuteScratchpadRequest
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 7fc0cabfa0..d7fbe124d9 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -3807,10 +3807,19 @@ 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.
*/
CompletedRunNotification: {
/** @enum {unknown} */
op: "completed-run";
+ /** @default null */
+ run_id?: string | null;
};
/**
* CompletionConfig
@@ -4269,6 +4278,12 @@ export interface components {
* notebook_cells: Snapshot of notebook cells from the session document.
* Used to populate the document ContextVar so code_mode can read
* cell ordering, code, names, and configs.
+ * run_id: Optional correlation ID. When set, the
+ * ``CompletedRunNotification`` emitted at the end of this command
+ * carries the same ``run_id`` so a caller holding a
+ * ``ScratchCellListener`` can filter for *its* completion and
+ * ignore ``CompletedRun`` events from unrelated commands on the
+ * same session.
*/
ExecuteScratchpadCommand: {
code: string;
@@ -4276,6 +4291,8 @@ export interface components {
notebookCells?: components["schemas"]["NotebookCell"][] | null;
/** @default null */
request?: components["schemas"]["HTTPRequest"] | null;
+ /** @default null */
+ runId?: string | null;
/** @enum {unknown} */
type: "execute-scratchpad";
};
@@ -4286,6 +4303,8 @@ export interface components {
notebookCells?: components["schemas"]["NotebookCell"][] | null;
/** @default null */
request?: components["schemas"]["HTTPRequest"] | null;
+ /** @default null */
+ runId?: string | null;
};
/**
* ExecuteStaleCellsCommand
diff --git a/tests/_server/test_scratchpad.py b/tests/_server/test_scratchpad.py
index 565eed36e6..4e1647b319 100644
--- a/tests/_server/test_scratchpad.py
+++ b/tests/_server/test_scratchpad.py
@@ -9,21 +9,26 @@ from inline_snapshot import snapshot
from marimo._ai._tools.types import CodeExecutionResult
from marimo._messaging.cell_output import CellChannel, CellOutput
-from marimo._messaging.errors import (
- MarimoExceptionRaisedError,
- MarimoSyntaxError,
+from marimo._messaging.errors import MarimoExceptionRaisedError
+from marimo._messaging.notification import (
+ CellNotification,
+ CompletedRunNotification,
)
-from marimo._messaging.notification import CellNotification
from marimo._runtime.scratch import SCRATCH_CELL_ID
from marimo._server.scratchpad import (
ScratchCellListener,
_format_console,
_format_sse,
build_done_event,
- build_timeout_event,
extract_result,
)
+_TEST_RUN_ID = "test-run-id"
+
+
+def _completed_run(run_id: str = _TEST_RUN_ID) -> CompletedRunNotification:
+ return CompletedRunNotification(run_id=run_id)
+
def _make_session(
notification: CellNotification | None = None,
@@ -152,7 +157,7 @@ class TestExtractResult:
console=None,
status="idle",
)
- listener = ScratchCellListener()
+ listener = ScratchCellListener(run_id=_TEST_RUN_ID)
listener.child_error_summaries.append(
"cell 'abc12345' raised ZeroDivisionError"
)
@@ -257,10 +262,15 @@ class TestFormatConsole:
class TestBuildDoneEvent:
+ # ``done`` shape is uniform ``{success, output}``. Failures always
+ # carry an empty output — the actual error detail was streamed via
+ # preceding ``stderr`` events.
+ _EMPTY = {"mimetype": "text/plain", "data": ""}
+
def test_no_notification(self) -> None:
event, data = _parse_sse(build_done_event(_make_session()))
assert event == "done"
- assert data == {"success": True}
+ assert data == snapshot({"success": True, "output": self._EMPTY})
def test_success_with_output(self) -> None:
notif = CellNotification(
@@ -273,9 +283,12 @@ class TestBuildDoneEvent:
status="idle",
)
_, data = _parse_sse(build_done_event(_make_session(notif)))
- assert data["success"] is True
- assert data["output"]["mimetype"] == "text/plain"
- assert data["output"]["data"] == "42"
+ assert data == snapshot(
+ {
+ "success": True,
+ "output": {"mimetype": "text/plain", "data": "42"},
+ }
+ )
def test_success_with_dict_output(self) -> None:
notif = CellNotification(
@@ -288,10 +301,16 @@ class TestBuildDoneEvent:
status="idle",
)
_, data = _parse_sse(build_done_event(_make_session(notif)))
- assert data["success"] is True
- assert data["output"]["data"] == "value"
+ assert data == snapshot(
+ {
+ "success": True,
+ "output": {"mimetype": "text/plain", "data": "value"},
+ }
+ )
- def test_error_with_exception(self) -> None:
+ def test_scratch_cell_error(self) -> None:
+ """Scratch cell's own MARIMO_ERROR marks the done event as failed;
+ the traceback itself is in preceding stderr events, not here."""
err = MarimoExceptionRaisedError(
msg="NameError: x is not defined",
exception_type="NameError",
@@ -303,43 +322,7 @@ class TestBuildDoneEvent:
status="idle",
)
_, data = _parse_sse(build_done_event(_make_session(notif)))
- assert data["success"] is False
- assert data["error"]["type"] == "MarimoExceptionRaisedError"
- assert data["error"]["exception_type"] == "NameError"
- assert "NameError" in data["error"]["msg"]
-
- def test_error_without_exception_type(self) -> None:
- err = MarimoSyntaxError(msg="invalid syntax", lineno=1)
- notif = CellNotification(
- cell_id=SCRATCH_CELL_ID,
- output=CellOutput.errors([err]),
- status="idle",
- )
- _, data = _parse_sse(build_done_event(_make_session(notif)))
- assert data["success"] is False
- assert data["error"]["type"] == "MarimoSyntaxError"
- assert "exception_type" not in data["error"]
-
- @pytest.mark.parametrize(
- "exception_type",
- ["ModuleNotFoundError", "ImportError"],
- )
- def test_import_error_includes_install_hint(
- self, exception_type: str
- ) -> None:
- err = MarimoExceptionRaisedError(
- msg=f"{exception_type}: No module named 'pandas'",
- exception_type=exception_type,
- raising_cell=None,
- )
- notif = CellNotification(
- cell_id=SCRATCH_CELL_ID,
- output=CellOutput.errors([err]),
- status="idle",
- )
- _, data = _parse_sse(build_done_event(_make_session(notif)))
- assert data["success"] is False
- assert "ctx.install_packages" in data["error"]["msg"]
+ assert data == snapshot({"success": False, "output": self._EMPTY})
def test_child_cell_error_reports_failure(self) -> None:
"""done event reports failure when listener saw child errors."""
@@ -352,24 +335,16 @@ class TestBuildDoneEvent:
),
status="idle",
)
- listener = ScratchCellListener()
+ listener = ScratchCellListener(run_id=_TEST_RUN_ID)
listener.child_error_summaries.append(
"cell 'abc12345' raised ZeroDivisionError"
)
_, data = _parse_sse(build_done_event(_make_session(notif), listener))
- assert data == snapshot(
- {
- "success": False,
- "error": {
- "type": "CellExecutionError",
- "msg": "cell 'abc12345' raised ZeroDivisionError",
- },
- }
- )
+ assert data == snapshot({"success": False, "output": self._EMPTY})
def test_no_child_errors_still_succeeds(self) -> None:
"""done event succeeds when listener has no child errors."""
- listener = ScratchCellListener()
+ listener = ScratchCellListener(run_id=_TEST_RUN_ID)
notif = CellNotification(
cell_id=SCRATCH_CELL_ID,
output=CellOutput(
@@ -387,19 +362,13 @@ class TestBuildDoneEvent:
}
)
- def test_timeout(self) -> None:
- _, data = _parse_sse(build_timeout_event(30.0))
- assert data["success"] is False
- assert data["error"]["type"] == "TimeoutError"
- assert "30.0s" in data["error"]["msg"]
-
class TestScratchCellListener:
@pytest.mark.asyncio
async def test_stream_basic(self) -> None:
from marimo._messaging.serde import serialize_kernel_message
- listener = ScratchCellListener()
+ listener = ScratchCellListener(run_id=_TEST_RUN_ID)
event_bus = MagicMock()
session = MagicMock()
listener.on_attach(session, event_bus)
@@ -411,7 +380,7 @@ class TestScratchCellListener:
)
idle = CellNotification(cell_id=SCRATCH_CELL_ID, status="idle")
- for notif in [running, console, idle]:
+ for notif in [running, console, idle, _completed_run()]:
listener.on_notification_sent(
session, serialize_kernel_message(notif)
)
@@ -426,12 +395,47 @@ class TestScratchCellListener:
assert name == "stdout"
assert payload["data"] == "hello\n"
+ @pytest.mark.asyncio
+ async def test_ignores_unrelated_completed_run(self) -> None:
+ """CompletedRun with a different run_id must NOT fire the sentinel."""
+ import asyncio
+
+ from marimo._messaging.serde import serialize_kernel_message
+
+ listener = ScratchCellListener(run_id=_TEST_RUN_ID)
+ event_bus = MagicMock()
+ session = MagicMock()
+ listener.on_attach(session, event_bus)
+
+ # A CompletedRun from an unrelated command (e.g. session.instantiate)
+ listener.on_notification_sent(
+ session, serialize_kernel_message(_completed_run("other-run-id"))
+ )
+
+ # Consumer should still be blocked — no sentinel fired.
+ got_event = asyncio.Event()
+
+ async def consume() -> None:
+ async for _ in listener.stream():
+ got_event.set()
+
+ task = asyncio.create_task(consume())
+ try:
+ await asyncio.wait_for(got_event.wait(), timeout=0.1)
+ raise AssertionError("listener exited on wrong run_id")
+ except asyncio.TimeoutError:
+ pass
+ finally:
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+
@pytest.mark.asyncio
async def test_ignores_other_cell_status(self) -> None:
"""Status-only notifications from non-scratch cells are ignored."""
from marimo._messaging.serde import serialize_kernel_message
- listener = ScratchCellListener()
+ listener = ScratchCellListener(run_id=_TEST_RUN_ID)
event_bus = MagicMock()
session = MagicMock()
listener.on_attach(session, event_bus)
@@ -450,7 +454,7 @@ class TestScratchCellListener:
"""Console output from non-scratch cells is captured."""
from marimo._messaging.serde import serialize_kernel_message
- listener = ScratchCellListener()
+ listener = ScratchCellListener(run_id=_TEST_RUN_ID)
event_bus = MagicMock()
session = MagicMock()
listener.on_attach(session, event_bus)
@@ -464,8 +468,9 @@ class TestScratchCellListener:
)
assert not listener._queue.empty()
- idle = CellNotification(cell_id=SCRATCH_CELL_ID, status="idle")
- listener.on_notification_sent(session, serialize_kernel_message(idle))
+ listener.on_notification_sent(
+ session, serialize_kernel_message(_completed_run())
+ )
events: list[str] = []
async for event in listener.stream():
@@ -483,12 +488,12 @@ class TestScratchCellListener:
from marimo._messaging.serde import serialize_kernel_message
- listener = ScratchCellListener()
+ listener = ScratchCellListener(run_id=_TEST_RUN_ID)
event_bus = MagicMock()
session = MagicMock()
listener.on_attach(session, event_bus)
- # Send one stdout event but no idle sentinel — stream would block forever
+ # Send one stdout event but no sentinel — stream would block forever
console = CellNotification(
cell_id=SCRATCH_CELL_ID,
console=CellOutput.stdout("partial\n"),
diff --git a/tests/_server/test_scratchpad_integration.py b/tests/_server/test_scratchpad_integration.py
index a6f12d1ebc..b948223856 100644
--- a/tests/_server/test_scratchpad_integration.py
+++ b/tests/_server/test_scratchpad_integration.py
@@ -22,10 +22,10 @@ fresh session via a per-test ``session`` fixture that calls
snapshotted as SSE lines with volatile paths and version-specific
traceback noise scrubbed.
-Each test's snapshot encodes the **correct** expected output.
-Scenarios currently broken (see issue #9255) are marked
-``xfail(strict=True)`` so a fix turns them into ``XPASS`` failures
-and the fix PR must remove the markers.
+Each test's snapshot encodes the expected SSE output for that
+scenario — failure cases land in ``done`` with
+``{success: false, output: {mimetype: "text/plain", data: ""}}``;
+error detail arrives earlier in the stream as ``stderr`` SSE events.
"""
from __future__ import annotations
@@ -275,9 +275,41 @@ _PATH_RE = re.compile(
# Windows: C:\\\\... up to the closing \\"
r"|[A-Z]:(?:\\\\[^\"\\]+)+"
)
-# Error-pointer line (Python 3.11+): indented `~~^~~` + trailing \n.
-# Absent on 3.10, so we strip it to make snapshots cross-version stable.
-_POINTER_RE = re.compile(r" +~+\^+~*\\n")
+# Absolute paths into the running marimo source tree — present in
+# tracebacks that traverse library frames (e.g. code_mode RuntimeError).
+# Match both Unix (``/…/marimo/…py``) and Windows (``C:\\…\\marimo\\…py``)
+# forms, reduce the repo-prefix portion to a stable ``<marimo>`` marker, and
+# slash-normalize the captured tail so the snapshot compares equal across
+# platforms. Run before ``_PATH_RE`` so Windows source paths are claimed
+# here rather than scrubbed to ``<tmp>``.
+_MARIMO_SRC_RE = re.compile(
+ r'\\"'
+ r"(?:"
+ r"/(?:[^\"\\]|\\\\)*/" # Unix prefix: /…/
+ r"|[A-Z]:\\\\(?:(?:[^\"\\]|\\\\)*\\\\)?" # Windows prefix: C:\\(…\\)?
+ r")"
+ r"(marimo(?:/|\\\\)(?:[^\"\\]|\\\\)*?\.py)" # marimo<sep>…<file>.py
+ r'\\"'
+)
+
+
+def _marimo_src_repl(m: re.Match[str]) -> str:
+ return '\\"<marimo>/' + m.group(1).replace("\\\\", "/") + '\\"'
+
+
+# Error-pointer line (Python 3.11+): indented PEP 657 location underline.
+# Python emits this in two flavors: ``~~~^~~~`` (call-site, with tildes
+# flanking the carets) and ``^^^^`` (pure multi-caret spans, e.g. an
+# expression range). Absent on 3.10, so we strip both for cross-version
+# parity. Single-caret pointers (` ^`) come from the classic
+# SyntaxError source-position marker, which is present on all versions,
+# so we don't strip them.
+_POINTER_RE = re.compile(r" +(?:~+\^+~*|\^{2,})\\n")
+# Python 3.13's collapsed-frames view keeps the closing ``)`` on its own
+# line for multi-line ``raise Foo(...)`` after ``_COLLAPSED_FRAMES_RE``
+# elides the middle; 3.10–3.12 don't show it at all. Strip the lone
+# closer for cross-version parity.
+_RAISE_CLOSING_PAREN_RE = re.compile(r"(raise \w+\(\\n) +\)\\n")
# Internal marimo frames (e.g. ``File "<tmp>", line 138, in execute_cell``)
# that Py 3.10 shows but 3.11+ hides. Strip them so tests only match the
# user-facing ``<module>`` frame.
@@ -285,12 +317,32 @@ _INTERNAL_FRAME_RE = re.compile(
r' File \\"<tmp>\\", line \d+, in (?!<module>)[^\\]+\\n'
r" +[^\\]*\\n"
)
+# Python 3.13 collapsed traceback marker (``...<N lines>...``) that older
+# Python versions don't emit. Strip together with the indent and newline.
+_COLLAPSED_FRAMES_RE = re.compile(r" +\.\.\.<\d+ lines>\.\.\.\\n")
+# Line numbers inside internal marimo frames (``File \"<marimo>/..., line N``)
+# drift when library source edits shift offsets. Zero them out so the test
+# stays stable under unrelated edits to code_mode, runtime, etc. User-facing
+# ``<tmp>`` frames keep their linenos so scratch-cell line positions remain
+# assertable.
+_MARIMO_FRAME_LINENO_RE = re.compile(r'(File \\"<marimo>/[^\\]*\\"), line \d+')
+# Auto-generated cell IDs from ``CellIdGenerator``: 4 random ascii
+# letters, appearing in code_mode summaries as ``cell 'AbCd'``. Replace
+# with ``cell '<cid>'``. Scoped to the ``cell '...'`` phrase so
+# unrelated 4-letter tokens (e.g. ``'boom'`` inside a test payload) are
+# untouched.
+_AUTO_CELL_ID_RE = re.compile(r"(cell )'[A-Za-z]{4}'")
def _normalize(body: str) -> list[str]:
+ body = _MARIMO_SRC_RE.sub(_marimo_src_repl, body)
body = _PATH_RE.sub("<tmp>", body)
body = _POINTER_RE.sub("", body)
body = _INTERNAL_FRAME_RE.sub("", body)
+ body = _COLLAPSED_FRAMES_RE.sub("", body)
+ body = _RAISE_CLOSING_PAREN_RE.sub(r"\1", body)
+ body = _MARIMO_FRAME_LINENO_RE.sub(r"\1, line N", body)
+ body = _AUTO_CELL_ID_RE.sub(r"\1'<cid>'", body)
return body.splitlines()
@@ -323,6 +375,33 @@ def test_scratchpad_success(session: _Session) -> None:
)
+def test_scratchpad_compile_error(session: _Session) -> None:
+ """Scratchpad code that fails to compile (SyntaxError).
+
+ Guards that compile-time errors reach the client with actionable
+ detail. Compile failures never go through ``redirect_streams`` /
+ ``write_traceback`` (the cell never runs), so the diagnostic has
+ to be emitted explicitly as a ``stderr`` SSE event before ``done``.
+ """
+ lines = session.execute("def :")
+
+ assert lines == snapshot(
+ [
+ "event: stderr",
+ (
+ 'data: {"data": "line 1\\n def :\\n ^\\nSyntaxError: invalid syntax\\n"}'
+ ),
+ "",
+ "event: done",
+ (
+ 'data: {"success": false, "output": '
+ '{"mimetype": "text/plain", "data": ""}}'
+ ),
+ "",
+ ]
+ )
+
+
def test_scratchpad_itself_errors(session: _Session) -> None:
"""Scratchpad code raises — scratch cell's own error surfaces.
@@ -342,19 +421,14 @@ def test_scratchpad_itself_errors(session: _Session) -> None:
"",
"event: done",
(
- 'data: {"success": false, "error": '
- '{"type": "MarimoExceptionRaisedError", '
- '"msg": "boom", "exception_type": "ValueError"}}'
+ 'data: {"success": false, "output": '
+ '{"mimetype": "text/plain", "data": ""}}'
),
"",
]
)
- reason="issue #9255: state_updates cascade error is silent",
- strict=True,
-)
def test_state_setter_cascade_error(session: _Session) -> None:
"""Scratchpad calls ``set_x(0)`` → downstream cell_b divides by zero.
@@ -388,19 +462,14 @@ def test_state_setter_cascade_error(session: _Session) -> None:
"",
"event: done",
(
- 'data: {"success": false, "error": '
- '{"type": "CellExecutionError", '
- '"msg": "cell \'cell_b\' raised ZeroDivisionError"}}'
+ 'data: {"success": false, "output": '
+ '{"mimetype": "text/plain", "data": ""}}'
),
"",
]
)
- reason="issue #9255: multi-hop state cascade error is silent",
- strict=True,
-)
def test_state_chain_cascade_error(session: _Session) -> None:
"""Nested state chain: ``set_x(0)`` → cell_b calls ``set_y`` →
slow cell_d divides by zero. Listener must capture cell_d's error
@@ -423,21 +492,24 @@ def test_state_chain_cascade_error(session: _Session) -> None:
assert lines == snapshot(
[
+ "event: stderr",
+ (
+ 'data: {"data": "Traceback (most recent call last):\\n'
+ ' File \\"<tmp>\\", line 3, in <module>\\n'
+ " z = 1 / get_y()\\n"
+ 'ZeroDivisionError: division by zero\\n"}'
+ ),
+ "",
"event: done",
(
- 'data: {"success": false, "error": '
- '{"type": "CellExecutionError", '
- '"msg": "cell \'cell_d\' raised ZeroDivisionError"}}'
+ 'data: {"success": false, "output": '
+ '{"mimetype": "text/plain", "data": ""}}'
),
"",
]
)
- reason="issue #9255: slow downstream errors missed in partial reports",
- strict=True,
-)
def test_multiple_downstream_cells_all_error(session: _Session) -> None:
"""Two downstream cells both error (fast + slow). Both must be
reported — partial reporting misleads the agent into thinking
@@ -477,20 +549,14 @@ def test_multiple_downstream_cells_all_error(session: _Session) -> None:
"",
"event: done",
(
- 'data: {"success": false, "error": '
- '{"type": "CellExecutionError", '
- '"msg": "cell \'cell_b\' raised ZeroDivisionError;'
- " cell 'cell_c' raised ZeroDivisionError\"}}"
+ 'data: {"success": false, "output": '
+ '{"mimetype": "text/plain", "data": ""}}'
),
"",
]
)
- reason="issue #9255: cascade error hidden when scratchpad also raises",
- strict=True,
-)
def test_scratchpad_raises_after_triggering_cascade(
session: _Session,
) -> None:
@@ -522,12 +588,18 @@ def test_scratchpad_raises_after_triggering_cascade(
'RuntimeError: scratch explosion\\n"}'
),
"",
+ "event: stderr",
+ (
+ 'data: {"data": "Traceback (most recent call last):\\n'
+ ' File \\"<tmp>\\", line 3, in <module>\\n'
+ " result = 1 / get_x()\\n"
+ 'ZeroDivisionError: division by zero\\n"}'
+ ),
+ "",
"event: done",
(
- 'data: {"success": false, "error": '
- '{"type": "CellExecutionError", '
- '"msg": "RuntimeError: scratch explosion;'
- " cell 'cell_b' raised ZeroDivisionError\"}}"
+ 'data: {"success": false, "output": '
+ '{"mimetype": "text/plain", "data": ""}}'
),
"",
]
@@ -572,10 +644,68 @@ def test_ctx_run_cell_cascade_error(session: _Session) -> None:
"",
"event: done",
(
- 'data: {"success": false, "error": '
- '{"type": "CellExecutionError", '
- '"msg": "cell \'cell_b\' raised ZeroDivisionError"}}'
+ 'data: {"success": false, "output": '
+ '{"mimetype": "text/plain", "data": ""}}'
),
"",
]
)
+
+
+def test_ctx_create_cell_multiply_defined(session: _Session) -> None:
+ """``ctx.create_cell`` introducing a duplicate definition errors early.
+
+ The notebook already has ``x = 10`` in ``cell_a``. code_mode's
+ dry-run compile detects the new cell would multiply-define ``x``
+ and raises ``RuntimeError`` before any real mutation — the new
+ cell is never registered and ``x`` stays ``10``.
+ """
+ session.setup_cells(["cell_a"], ["x = 10"])
+
+ lines = session.execute(
+ "import marimo._code_mode as cm\n"
+ "async with cm.get_context() as ctx:\n"
+ ' ctx.create_cell("x = 20")',
+ )
+
+ assert lines == snapshot(
+ [
+ "event: stderr",
+ 'data: {"data": "Traceback (most recent call last):\\n File \\"<marimo>/marimo/_runtime/executor.py\\", line N, in execute_cell_async\\n await eval(cell.body, glbls)\\n File \\"<tmp>\\", line 2, in <module>\\n async with cm.get_context() as ctx:\\n File \\"<marimo>/marimo/_code_mode/_context.py\\", line N, in __aexit__\\n self._dry_run_compile(ops)\\n File \\"<marimo>/marimo/_code_mode/_context.py\\", line N, in _dry_run_compile\\n raise RuntimeError(\\nRuntimeError: Multiply-defined names:\\n - \'x\' is already defined in cell \'cell_a\' (cell_a)\\n\\nTo skip validation, use: async with cm.get_context(skip_validation=True) as ctx\\n"}',
+ "",
+ "event: done",
+ 'data: {"success": false, "output": {"mimetype": "text/plain", "data": ""}}',
+ "",
+ ]
+ )
+
+
+def test_ctx_create_cell_skip_validation(session: _Session) -> None:
+ """``skip_validation=True`` bypasses the dry-run compile check.
+
+ Same setup as above, but the caller opts out of validation — no
+ ``RuntimeError`` is raised and the new cell is registered, as
+ evidenced by the ``created cell`` stdout summary. The kernel's own
+ graph-validity pass still flags the resulting multiply-defined
+ state (visible to the listener as a child error, hence
+ ``success: false``), but no traceback reaches stderr because the
+ new cell never runs — the error is a pure graph-state marker.
+ """
+ session.setup_cells(["cell_a"], ["x = 10"])
+
+ lines = session.execute(
+ "import marimo._code_mode as cm\n"
+ "async with cm.get_context(skip_validation=True) as ctx:\n"
+ ' ctx.create_cell("x = 20")',
+ )
+
+ assert lines == snapshot(
+ [
+ "event: stdout",
+ 'data: {"data": "created cell \'<cid>\'\\n"}',
+ "",
+ "event: done",
+ 'data: {"success": false, "output": {"mimetype": "text/plain", "data": ""}}',
+ "",
+ ]
+ )