A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
sidebar code-mode: add run_scratchpad utility functions (#9637)
Shahmir Varqha068f14093f33
diff --git a/marimo/_code_mode/_context.py b/marimo/_code_mode/_context.pyindex 52853eadcc..4c4b3a2a0e 100644--- a/marimo/_code_mode/_context.py+++ b/marimo/_code_mode/_context.py@@ -54,6 +54,10 @@ from marimo._code_mode._plan import (_UpdateOp,_validate_ops,)+from marimo._code_mode.screenshot_meta import (+ SCREENSHOT_AUTH_TOKEN_KEY,+ SCREENSHOT_SERVER_URL_KEY,+)from marimo._messaging.cell_output import CellOutputfrom marimo._messaging.errors import Errorfrom marimo._messaging.notebook.changes import (@@ -1405,19 +1409,20 @@ class AsyncCodeModeContext:"available. screenshot() must be called during cell ""execution (e.g. from code-mode).")- # Read trusted server URL and auth token injected by the- # /execute endpoint (from server config, not request headers).++ # Trusted server URL + auth token injected by the /execute+ # endpoint (from server config, not request headers).server_url = cast(- "str | None", request.meta.get("screenshot_server_url")+ "str | None", request.meta.get(SCREENSHOT_SERVER_URL_KEY))if server_url is None:raise ScreenshotError(- "Cannot take screenshots: screenshot_server_url not "+ "Cannot take screenshots: screenshot credentials not ""found in request.meta. This endpoint may not ""support screenshots.")screenshot_auth_token = cast(- "str | None", request.meta.get("screenshot_auth_token")+ "str | None", request.meta.get(SCREENSHOT_AUTH_TOKEN_KEY))# Lazy-init the screenshot session (browser reuse).diff --git a/marimo/_code_mode/screenshot_meta.py b/marimo/_code_mode/screenshot_meta.pynew file mode 100644index 0000000000..bb3f94e1c4--- /dev/null+++ b/marimo/_code_mode/screenshot_meta.py@@ -0,0 +1,14 @@+# Copyright 2026 Marimo. All rights reserved.+"""Meta keys for wiring screenshot credentials through `HTTPRequest.meta`.++Code-mode tools running in the kernel need to call back into the marimo+server (e.g. `ctx.screenshot()` driving Playwright against the+kiosk page). The server stamps a trusted `server_url` and+`auth_token` onto each control request's `meta` dict; the runtime+side reads them when building the screenshot session.+"""++from __future__ import annotations++SCREENSHOT_SERVER_URL_KEY = "screenshot_server_url"+SCREENSHOT_AUTH_TOKEN_KEY = "screenshot_auth_token"diff --git a/marimo/_server/ai/tools/code_mode.py b/marimo/_server/ai/tools/code_mode.pynew file mode 100644index 0000000000..1609ba8e94--- /dev/null+++ b/marimo/_server/ai/tools/code_mode.py@@ -0,0 +1,55 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++from typing import TYPE_CHECKING++from marimo._ai._tools.types import CodeExecutionResult+from marimo._server.api.deps import AppState+from marimo._server.api.utils import get_code_mode_credentials+from marimo._server.scratchpad import run_scratchpad_code++if TYPE_CHECKING:+ from pydantic_ai import FunctionToolset+ from starlette.requests import Request++ from marimo._session.session import Session+++def build_execute_code_toolset(+ session: Session,+ request: Request,+) -> FunctionToolset[None]:+ """Build a `FunctionToolset` exposing one tool: `execute_code`.++ The tool is bound to the caller's *session* and *request*; the model+ never sees or passes a session id. Screenshot credentials are derived+ per tool call from the request so `ctx.screenshot()` can call back+ into this server (see `marimo/_code_mode/_context.py`).+ """++ from pydantic_ai import FunctionToolset++ toolset: FunctionToolset[None] = FunctionToolset()++ async def execute_code(code: str) -> CodeExecutionResult:+ """Run Python inside the running notebook's kernel scratchpad.++ Use this for all notebook mutations via `marimo._code_mode`.+ """+ server_url, auth_token = get_code_mode_credentials(+ AppState(request), request+ )+ return await run_scratchpad_code(+ session,+ request,+ code=code,+ server_url=server_url,+ auth_token=auth_token,+ )++ toolset.add_function(+ execute_code,+ name="execute_code",+ description=execute_code.__doc__,+ )+ return toolsetdiff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.pyindex d5e4e19439..40d2d68ceb 100644--- a/marimo/_server/api/endpoints/execution.py+++ b/marimo/_server/api/endpoints/execution.py@@ -9,13 +9,21 @@ from starlette.authentication import requiresfrom starlette.responses import JSONResponse, StreamingResponsefrom marimo import _loggers+from marimo._code_mode.screenshot_meta import (+ SCREENSHOT_AUTH_TOKEN_KEY,+ SCREENSHOT_SERVER_URL_KEY,+)from marimo._runtime.commands import HTTPRequest, UpdateUIElementCommandfrom marimo._server.api.deps import AppStatefrom marimo._server.api.endpoints.ws.ws_connection_validator import (FILE_QUERY_PARAM_KEY,)from marimo._server.api.endpoints.ws_endpoint import DOC_MANAGER-from marimo._server.api.utils import dispatch_control_request, parse_request+from marimo._server.api.utils import (+ dispatch_control_request,+ get_code_mode_credentials,+ parse_request,+)from marimo._server.models.models import (BaseResponse,DebugCellRequest,@@ -354,19 +362,11 @@ async def execute_code(with session.scoped(listener):async with session.scratchpad_lock:http_req = HTTPRequest.from_request(request)- # Inject trusted server URL and auth token for- # code-mode screenshot support. We use the- # server's own host/port (from config) rather- # than the request's Host header to prevent- # header-spoofing attacks.- http_req.meta["screenshot_auth_token"] = str(- app_state.session_manager.auth_token- )- base_url = app_state.base_url.rstrip("/")- scheme = request.url.scheme or "http"- http_req.meta["screenshot_server_url"] = (- f"{scheme}://{app_state.host}:{app_state.port}{base_url}"+ server_url, auth_token = get_code_mode_credentials(+ app_state, request)+ http_req.meta[SCREENSHOT_SERVER_URL_KEY] = server_url+ http_req.meta[SCREENSHOT_AUTH_TOKEN_KEY] = auth_tokennotebook_cells, cell_outputs = snapshot_for_scratchpad(session)diff --git a/marimo/_server/api/lifespans.py b/marimo/_server/api/lifespans.pyindex dfe057b84d..fc1bb302be 100644--- a/marimo/_server/api/lifespans.py+++ b/marimo/_server/api/lifespans.py@@ -3,8 +3,6 @@ from __future__ import annotationsimport asyncioimport contextlib-import ipaddress-import socketfrom typing import TYPE_CHECKING, Anyfrom marimo import _loggers@@ -12,7 +10,10 @@ from marimo._server.ai.mcp.config import is_mcp_config_emptyfrom marimo._server.ai.tools.tool_manager import setup_tool_managerfrom marimo._server.api.deps import AppState, AppStateBasefrom marimo._server.api.interrupt import InterruptHandler-from marimo._server.api.utils import open_url_in_browser+from marimo._server.api.utils import (+ format_url_host,+ open_url_in_browser,+)from marimo._server.lsp import any_lsp_server_runningfrom marimo._server.print import (print_experimental_features,@@ -271,48 +272,10 @@ async def reap_subprocesses(app: Starlette) -> AsyncIterator[None]:await cancel_pending_reaps()-def _pretty_host(host: str, port: int) -> str:- """Replace loopback addresses with 'localhost' for display.-- Uses ipaddress for a reliable cross-platform loopback check (covers- 127.0.0.1, ::1, and the full 127.0.0.0/8 range). Falls back to- socket.getnameinfo only for non-IP hosts. getnameinfo is skipped for- raw IP addresses because it can hang on Windows/CI for link-local IPv6.- """- try:- if ipaddress.ip_address(host).is_loopback:- return "localhost"- except ValueError:- # Not a valid IP literal — might be a hostname; try getnameinfo- try:- if (- socket.getnameinfo((host, port), socket.NI_NOFQDN)[0]- == "localhost"- ):- return "localhost"- except Exception:- pass- return host--def _startup_url(state: AppStateBase) -> str:- host = state.host.strip(- "[]"- ) # normalize: remove brackets if user passed [addr]+ url_host = format_url_host(state.host, state.port)port = state.port- # Strip IPv6 zone ID (e.g. fe80::1%eth0 -> fe80::1); zone IDs are- # interface-specific and not valid in URLs.- # Must happen before _pretty_host — zone IDs can cause getnameinfo- # to hang on Windows/CI.- host = host.split("%")[0]-- # pretty printing: show "localhost" for loopback addresses- host = _pretty_host(host, port)-- url_host_bare = host- # IPv6 addresses must be wrapped in brackets in URLs (RFC 3986)- url_host = f"[{url_host_bare}]" if ":" in url_host_bare else url_host_bareurl = f"http://{url_host}:{port}{state.base_url}"if port == 80:url = f"http://{url_host}{state.base_url}"@@ -325,18 +288,10 @@ def _startup_url(state: AppStateBase) -> str:def _mcp_startup_url(state: AppStateBase) -> str:- host = state.host.strip(- "[]"- ) # normalize: remove brackets if user passed [addr]+ url_host = format_url_host(state.host, state.port)port = state.portbase_url = state.base_url- # Strip zone ID, then pretty-print loopback (same logic as _startup_url)- host = host.split("%")[0]- host = _pretty_host(host, port)-- url_host_bare = host- url_host = f"[{url_host_bare}]" if ":" in url_host_bare else url_host_bare# Construct MCP endpoint URLmcp_prefix = "/mcp"mcp_name = "server"diff --git a/marimo/_server/api/utils.py b/marimo/_server/api/utils.pyindex 08a10fdda9..ce8c36a427 100644--- a/marimo/_server/api/utils.py+++ b/marimo/_server/api/utils.py@@ -31,6 +31,7 @@ if TYPE_CHECKING:from starlette.datastructures import UploadFilefrom starlette.requests import Request+ from marimo._server.api.deps import AppStateBasefrom marimo._session.session import Session@@ -113,6 +114,89 @@ async def dispatch_control_request(return SuccessResponse()+def pretty_host(host: str, port: int) -> str:+ """Replace loopback addresses with 'localhost' for display.++ Uses ipaddress for a reliable cross-platform loopback check (covers+ 127.0.0.1, ::1, and the full 127.0.0.0/8 range). Falls back to+ socket.getnameinfo only for non-IP hosts. getnameinfo is skipped+ for raw IP addresses because it can hang on Windows/CI for+ link-local IPv6.+ """+ import ipaddress+ import socket++ try:+ if ipaddress.ip_address(host).is_loopback:+ return "localhost"+ except ValueError:+ # Not a valid IP literal — might be a hostname; try getnameinfo+ try:+ if (+ socket.getnameinfo((host, port), socket.NI_NOFQDN)[0]+ == "localhost"+ ):+ return "localhost"+ except Exception:+ pass+ return host+++def format_url_host(+ host: str,+ port: int,+ *,+ route_bind_all_to_loopback: bool = False,+) -> str:+ """Normalize `host` for use in a URL authority.++ Transforms (in order):++ 1. Strip user-supplied brackets (`[::1]` -> `::1`).+ 2. Drop IPv6 zone IDs (`fe80::1%eth0` -> `fe80::1`); zone IDs+ are interface-specific and not valid in URLs. (Must happen+ before :func:`pretty_host` — zone IDs can cause getnameinfo+ to hang on Windows/CI.)+ 3. Replace loopback addresses with `"localhost"`.+ 4. If `route_bind_all_to_loopback`, replace the bind-all+ sentinels `0.0.0.0` / `::` with `"localhost"` so internal+ callback URLs reach a routable target (the bind-all addresses+ are not valid destinations for an HTTP client / Playwright).+ Display URLs leave them alone — the user knows what they+ configured.+ 5. Wrap bare IPv6 literals in brackets per RFC 3986.+ """+ host = host.strip("[]").split("%")[0]+ host = pretty_host(host, port)+ if route_bind_all_to_loopback and host in {"0.0.0.0", "::"}:+ host = "localhost"+ return f"[{host}]" if ":" in host else host+++def get_code_mode_credentials(+ app_state: AppStateBase, request: Request+) -> tuple[str, str]:+ """Return `(server_url, auth_token)` for code-mode tools that+ call back into this marimo server (e.g. `ctx.screenshot()`+ driving Playwright against the running notebook UI).++ The URL is built from the server's configured `host`/`port`+ rather than the request's `Host` header so a spoofed header+ can't redirect the auth token to an attacker-controlled URL.+ `host` is also normalized for URL safety (IPv6 bracketing, zone-ID+ stripping) and for routability (bind-all addresses mapped to+ `localhost`) so the callback actually reaches the server.+ """+ auth_token = str(app_state.session_manager.auth_token)+ base_url = app_state.base_url.rstrip("/")+ scheme = request.url.scheme or "http"+ url_host = format_url_host(+ app_state.host, app_state.port, route_bind_all_to_loopback=True+ )+ server_url = f"{scheme}://{url_host}:{app_state.port}{base_url}"+ return server_url, auth_token++def parse_title(filepath: str | None) -> str:"""Create a title from a filename.diff --git a/marimo/_server/scratchpad.py b/marimo/_server/scratchpad.pyindex 5d0bedd569..56ca93dc07 100644--- a/marimo/_server/scratchpad.py+++ b/marimo/_server/scratchpad.py@@ -6,8 +6,13 @@ from __future__ import annotationsimport asyncioimport jsonfrom typing import TYPE_CHECKING, Any, TypedDict+from uuid import uuid4from marimo._ai._tools.types import CodeExecutionResult+from marimo._code_mode.screenshot_meta import (+ SCREENSHOT_AUTH_TOKEN_KEY,+ SCREENSHOT_SERVER_URL_KEY,+)from marimo._messaging.cell_output import CellChannelfrom marimo._messaging.notebook.outputs import CellOutputsfrom marimo._messaging.notification import (@@ -15,12 +20,16 @@ from marimo._messaging.notification import (CompletedRunNotification,)from marimo._messaging.serde import deserialize_kernel_message+from marimo._runtime.commands import ExecuteScratchpadCommand, HTTPRequestfrom marimo._runtime.scratch import SCRATCH_CELL_ID+from marimo._server.models.models import InstantiateNotebookRequestfrom marimo._session.extensions.types import EventAwareExtensionif TYPE_CHECKING:from collections.abc import AsyncGenerator+ from starlette.requests import Request+from marimo._messaging.notebook.document import NotebookCellfrom marimo._messaging.types import KernelMessagefrom marimo._session.session import Session@@ -308,3 +317,54 @@ def extract_result(stderr=stderr,errors=errors,)+++async def run_scratchpad_code(+ session: Session,+ request: Request,+ *,+ code: str,+ server_url: str,+ auth_token: str,+ timeout: float = EXECUTION_TIMEOUT,+) -> CodeExecutionResult:+ """Drive the kernel scratchpad on behalf of code-mode"""+ http_req = HTTPRequest.from_request(request)+ http_req.meta[SCREENSHOT_SERVER_URL_KEY] = server_url+ http_req.meta[SCREENSHOT_AUTH_TOKEN_KEY] = auth_token++ session.instantiate(+ InstantiateNotebookRequest(object_ids=[], values=[], auto_run=False),+ http_request=http_req,+ )++ run_id = str(uuid4())+ listener = ScratchCellListener(run_id=run_id)++ with session.scoped(listener):+ async with session.scratchpad_lock:+ notebook_cells, cell_outputs = snapshot_for_scratchpad(session)+ session.put_control_request(+ ExecuteScratchpadCommand(+ code=code,+ request=http_req,+ notebook_cells=notebook_cells,+ cell_outputs=cell_outputs,+ run_id=run_id,+ ),+ from_consumer_id=None,+ )+ settled = False+ try:+ await listener.wait(timeout=timeout)+ settled = not listener.timed_out+ finally:+ if not settled:+ session.try_interrupt()+ if listener.timed_out:+ return CodeExecutionResult(+ success=False,+ errors=[f"Execution timed out after {timeout}s"],+ )++ return extract_result(session, listener)diff --git a/tests/_server/api/endpoints/test_execution.py b/tests/_server/api/endpoints/test_execution.pyindex 8a6f7f8308..685bb3bd0c 100644--- a/tests/_server/api/endpoints/test_execution.py+++ b/tests/_server/api/endpoints/test_execution.py@@ -8,6 +8,10 @@ from typing import TYPE_CHECKINGimport pytest+from marimo._code_mode.screenshot_meta import (+ SCREENSHOT_AUTH_TOKEN_KEY,+ SCREENSHOT_SERVER_URL_KEY,+)from marimo._types.ids import CellId_t, SessionIdfrom marimo._utils.lists import firstfrom tests._server.api.endpoints.ws_helpers import (@@ -247,10 +251,13 @@ class TestExecutionRoutes_EditMode:assert len(scratchpad_cmds) == 1, (f"expected one ExecuteScratchpadCommand, got {captured!r}")- meta = scratchpad_cmds[0].request.meta- assert meta["screenshot_auth_token"] == "fake-token"+ http_req = scratchpad_cmds[0].request+ assert http_req is not None# Mock server uses host="localhost", port=1234, base_url=""- assert meta["screenshot_server_url"] == "http://localhost:1234"+ assert http_req.meta[SCREENSHOT_SERVER_URL_KEY] == (+ "http://localhost:1234"+ )+ assert http_req.meta[SCREENSHOT_AUTH_TOKEN_KEY] == "fake-token"@staticmethod@with_session(SESSION_ID)diff --git a/tests/_server/api/test_api_utils.py b/tests/_server/api/test_api_utils.pyindex 56e009e543..5a2f39bb01 100644--- a/tests/_server/api/test_api_utils.py+++ b/tests/_server/api/test_api_utils.py@@ -1,19 +1,26 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from typing import TYPE_CHECKING+from types import SimpleNamespace+from typing import TYPE_CHECKING, castimport msgspecimport pytestfrom starlette.applications import Starlette+from starlette.requests import Requestfrom starlette.responses import JSONResponsefrom starlette.routing import Routefrom starlette.testclient import TestClient-from marimo._server.api.utils import parse_multipart_request+from marimo._server.api.utils import (+ get_code_mode_credentials,+ parse_multipart_request,+)if TYPE_CHECKING:- from starlette.requests import Request+ from starlette.types import Scope++ from marimo._server.api.deps import AppStateBaseclass _SampleForm(msgspec.Struct):@@ -70,3 +77,128 @@ def test_parse_multipart_request_raises_on_missing_field() -> None:client = _build_app(captured)with pytest.raises(msgspec.ValidationError):client.post("/test", data={"name": "marimo"})+++def _fake_app_state(+ *,+ host: str = "localhost",+ port: int = 2718,+ base_url: str = "",+ auth_token: str = "tok",+) -> AppStateBase:+ """Minimal duck-typed stand-in for AppStateBase exposing only the+ attributes that get_code_mode_credentials reads."""+ state = SimpleNamespace(+ host=host,+ port=port,+ base_url=base_url,+ session_manager=SimpleNamespace(auth_token=auth_token),+ )+ return cast("AppStateBase", cast(object, state))+++def _fake_request(+ *,+ scheme: str = "http",+ host_header: str = "evil.example.com:80",+) -> Request:+ """Build a Starlette Request with a chosen scheme and Host header+ without spinning up an app."""+ scope: Scope = {+ "type": "http",+ "method": "POST",+ "scheme": scheme,+ "server": ("localhost", 2718),+ "path": "/",+ "raw_path": b"/",+ "query_string": b"",+ "headers": [(b"host", host_header.encode())],+ }+ return Request(scope)+++def test_get_code_mode_credentials_uses_configured_host_not_request_host_header() -> (+ None+):+ """Regression guard for the security property documented on+ get_code_mode_credentials: the server URL must come from the server's+ configured host/port, not from the (spoofable) Host header.+ Loopback addresses are pretty-printed to `localhost`."""+ url, token = get_code_mode_credentials(+ _fake_app_state(host="127.0.0.1", port=2718, auth_token="secret"),+ _fake_request(host_header="evil.example.com:80"),+ )+ assert url == "http://localhost:2718"+ assert token == "secret"+++def test_get_code_mode_credentials_strips_trailing_slash_from_base_url() -> (+ None+):+ url, _ = get_code_mode_credentials(+ _fake_app_state(base_url="/notebook/"),+ _fake_request(),+ )+ assert url == "http://localhost:2718/notebook"+++def test_get_code_mode_credentials_includes_non_empty_base_url() -> None:+ url, _ = get_code_mode_credentials(+ _fake_app_state(base_url="/notebook"),+ _fake_request(),+ )+ assert url == "http://localhost:2718/notebook"+++def test_get_code_mode_credentials_empty_base_url() -> None:+ url, _ = get_code_mode_credentials(+ _fake_app_state(base_url=""),+ _fake_request(),+ )+ assert url == "http://localhost:2718"+++def test_get_code_mode_credentials_propagates_https_scheme() -> None:+ url, _ = get_code_mode_credentials(+ _fake_app_state(),+ _fake_request(scheme="https"),+ )+ assert url == "https://localhost:2718"+++ ("host", "expected_url"),+ [+ # Loopback addresses get pretty-printed to "localhost".+ ("127.0.0.1", "http://localhost:2718"),+ ("::1", "http://localhost:2718"),+ # Bracket-wrapped loopback (user passed [::1]) — strip + map.+ ("[::1]", "http://localhost:2718"),+ # Bind-all sentinels are NOT routable for an internal callback;+ # they must be mapped to localhost so Playwright can connect.+ ("0.0.0.0", "http://localhost:2718"),+ ("::", "http://localhost:2718"),+ # Real IPv6 literals must be bracketed per RFC 3986.+ ("fd00::cafe", "http://[fd00::cafe]:2718"),+ ("2001:db8::1", "http://[2001:db8::1]:2718"),+ # User-supplied brackets on a real address — strip and re-add.+ ("[fd00::cafe]", "http://[fd00::cafe]:2718"),+ # Zone IDs are interface-specific and not valid in URLs.+ ("fe80::1%eth0", "http://[fe80::1]:2718"),+ ("[fe80::1%lo0]", "http://[fe80::1]:2718"),+ # Regular hostnames pass through unchanged.+ ("example.com", "http://example.com:2718"),+ ],+)+def test_get_code_mode_credentials_normalizes_host(+ host: str, expected_url: str+) -> None:+ """The server URL must be a routable, URL-safe destination — bind-all+ addresses mapped to loopback, IPv6 bracketed, zone IDs stripped —+ so code-mode callbacks (e.g. Playwright screenshots) actually reach+ the server."""+ url, _ = get_code_mode_credentials(+ _fake_app_state(host=host),+ _fake_request(),+ )+ assert url == expected_urldiff --git a/tests/_server/test_scratchpad.py b/tests/_server/test_scratchpad.pyindex 2231143b03..058bb58081 100644--- a/tests/_server/test_scratchpad.py+++ b/tests/_server/test_scratchpad.py@@ -1,29 +1,54 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations+import asyncioimport json+from contextlib import contextmanager+from types import SimpleNamespace+from typing import TYPE_CHECKING, castfrom unittest.mock import MagicMockimport pytestfrom inline_snapshot import snapshotfrom marimo._ai._tools.types import CodeExecutionResult+from marimo._code_mode.screenshot_meta import (+ SCREENSHOT_AUTH_TOKEN_KEY,+ SCREENSHOT_SERVER_URL_KEY,+)from marimo._messaging.cell_output import CellChannel, CellOutputfrom marimo._messaging.errors import MarimoExceptionRaisedErrorfrom marimo._messaging.notification import (CellNotification,CompletedRunNotification,+ NotificationMessage,+)+from marimo._messaging.serde import serialize_kernel_message+from marimo._runtime.commands import (+ CommandMessage,+ ExecuteScratchpadCommand,+ HTTPRequest,)from marimo._runtime.scratch import SCRATCH_CELL_ID+from marimo._server.models.models import InstantiateNotebookRequestfrom marimo._server.scratchpad import (ScratchCellListener,_format_console,_format_sse,build_done_event,extract_result,+ run_scratchpad_code,snapshot_for_scratchpad,)+if TYPE_CHECKING:+ from collections.abc import Iterator++ from starlette.types import Scope++ from marimo._session.session import Session+ from marimo._types.ids import CellId_t+_TEST_RUN_ID = "test-run-id"@@ -88,6 +113,130 @@ class TestSnapshotForScratchpad:assert cell_outputs.console_outputs == snapshot({"a": console})+def _build_request(+ *,+ scheme: str = "http",+ host: str = "localhost",+ port: int = 1234,+):+ """Build a real Starlette Request so `HTTPRequest.from_request`+ can read it without an exhaustive MagicMock setup."""+ from starlette.requests import Request++ scope: Scope = {+ "type": "http",+ "method": "POST",+ "scheme": scheme,+ "server": (host, port),+ "path": "/",+ "raw_path": b"/",+ "query_string": b"",+ "headers": [(b"host", f"{host}:{port}".encode())],+ }+ return Request(scope)+++class _FakeSession:+ """Minimal duck-typed Session for `run_scratchpad_code` tests.++ Behaves like a real Session in the ways the runner cares about:++ * `scoped` registers a listener for the duration of the context.+ * `put_control_request` routes a `CompletedRunNotification` to+ the active listener so `listener.wait()` returns naturally —+ no need to monkey-patch listener internals.++ Set `auto_complete=False` to drive the timeout path (the listener+ will never see a completion event).+ """++ cell_outputs: dict[CellId_t, CellOutput]+ console_outputs: dict[CellId_t, list[CellOutput]]+ document: SimpleNamespace+ session_view: SimpleNamespace+ scratchpad_lock: asyncio.Lock+ control_requests: list[CommandMessage]+ instantiate_calls: list[+ tuple[InstantiateNotebookRequest, HTTPRequest | None]+ ]+ interrupt_count: int+ _auto_complete: bool+ _active_listener: ScratchCellListener | None+ _pre_complete_notifs: list[NotificationMessage]++ def __init__(self, *, auto_complete: bool = True) -> None:+ self.cell_outputs = {}+ self.console_outputs = {}+ self.document = SimpleNamespace(cells=(), cell_ids=())+ self.session_view = SimpleNamespace(+ cell_notifications={},+ get_cell_outputs=lambda _ids: self.cell_outputs,+ get_cell_console_outputs=lambda _ids: self.console_outputs,+ )+ self.scratchpad_lock = asyncio.Lock()+ self.control_requests = []+ self.instantiate_calls = []+ self.interrupt_count = 0+ self._auto_complete = auto_complete+ self._active_listener = None+ self._pre_complete_notifs = []++ def as_session(self) -> Session:+ """Type-only cast to `Session` for the runner's signature."""+ return cast("Session", cast(object, self))++ def emit(self, notification: NotificationMessage) -> None:+ """Schedule a notification to be delivered to the active+ listener just before the auto-generated completion event."""+ self._pre_complete_notifs.append(notification)++ @contextmanager+ def scoped(+ self, listener: ScratchCellListener+ ) -> Iterator[ScratchCellListener]:+ self._active_listener = listener+ try:+ yield listener+ finally:+ self._active_listener = None++ def instantiate(+ self,+ request: InstantiateNotebookRequest,+ *,+ http_request: HTTPRequest | None,+ ) -> None:+ self.instantiate_calls.append((request, http_request))++ def put_control_request(+ self,+ req: CommandMessage,+ from_consumer_id: object = None,+ ) -> None:+ del from_consumer_id+ self.control_requests.append(req)+ if not (+ self._auto_complete+ and isinstance(req, ExecuteScratchpadCommand)+ and self._active_listener is not None+ ):+ return+ session = self.as_session()+ for notif in self._pre_complete_notifs:+ self._active_listener.on_notification_sent(+ session, serialize_kernel_message(notif)+ )+ self._active_listener.on_notification_sent(+ session,+ serialize_kernel_message(+ CompletedRunNotification(run_id=req.run_id)+ ),+ )++ def try_interrupt(self) -> None:+ self.interrupt_count += 1++class TestExtractResult:def test_no_notification(self) -> None:result = extract_result(_make_session())@@ -298,9 +447,9 @@ class TestFormatConsole:class TestBuildDoneEvent:- # ``done`` shape is uniform ``{success, output}``. Failures always+ # `done` shape is uniform `{success, output}`. Failures always# carry an empty output — the actual error detail was streamed via- # preceding ``stderr`` events.+ # preceding `stderr` events._EMPTY = {"mimetype": "text/plain", "data": ""}def test_no_notification(self) -> None:@@ -557,3 +706,262 @@ class TestScratchCellListener:name, payload = _parse_sse(events[0])assert name == "stdout"assert payload["data"] == "partial\n"+++class TestRunScratchpadCode:+ """Regression guards for `run_scratchpad_code` — the runner that+ backs the AI `execute_code` tool."""++ @staticmethod+ def _execute_command(session: _FakeSession) -> ExecuteScratchpadCommand:+ cmds = [+ c+ for c in session.control_requests+ if isinstance(c, ExecuteScratchpadCommand)+ ]+ assert len(cmds) == 1, (+ f"expected one ExecuteScratchpadCommand, got {session.control_requests!r}"+ )+ return cmds[0]++ @pytest.mark.asyncio+ async def test_stamps_screenshot_meta_and_run_id_on_command(+ self,+ ) -> None:+ """Regression guard: `run_id` and screenshot meta must reach+ the `ExecuteScratchpadCommand` unchanged. Without `run_id`,+ `ScratchCellListener` filters out the completion event and+ every code-mode tool call hangs ~30s before timing out."""+ session = _FakeSession()++ result = await run_scratchpad_code(+ session.as_session(),+ _build_request(),+ code="x = 1",+ server_url="http://localhost:1234",+ auth_token="fake-token",+ )++ assert result.success is True+ cmd = self._execute_command(session)+ assert cmd.run_id is not None+ assert cmd.request is not None+ assert cmd.request.meta[SCREENSHOT_SERVER_URL_KEY] == (+ "http://localhost:1234"+ )+ assert cmd.request.meta[SCREENSHOT_AUTH_TOKEN_KEY] == "fake-token"++ @pytest.mark.asyncio+ async def test_snapshots_cell_outputs_onto_command(self) -> None:+ """`run_scratchpad_code` must snapshot existing cell outputs+ onto the command (via `snapshot_for_scratchpad`), same as the+ `/execute` endpoint and MCP code server. Without this, code-mode+ invoked by the AI `execute_code` tool sees every `cell.output`+ as `None` while the other entry points expose them."""+ from marimo._types.ids import CellId_t++ session = _FakeSession()+ output = CellOutput(+ channel=CellChannel.OUTPUT, mimetype="text/plain", data="42"+ )+ console = CellOutput.stdout("hi\n")+ session.cell_outputs = {CellId_t("a"): output}+ session.console_outputs = {CellId_t("a"): [console]}++ await run_scratchpad_code(+ session.as_session(),+ _build_request(),+ code="x = 1",+ server_url="u",+ auth_token="t",+ )++ cmd = self._execute_command(session)+ assert cmd.cell_outputs is not None+ assert cmd.cell_outputs.output == snapshot({"a": output})+ assert cmd.cell_outputs.console_outputs == snapshot({"a": [console]})++ @pytest.mark.asyncio+ async def test_instantiates_session_without_auto_run(self) -> None:+ """The runner must seed the dependency graph before executing+ (so `_code_mode.run_cell` can resolve cell IDs) but it must+ NOT auto-run the notebook's cells."""+ session = _FakeSession()++ await run_scratchpad_code(+ session.as_session(),+ _build_request(),+ code="x = 1",+ server_url="u",+ auth_token="t",+ )++ assert len(session.instantiate_calls) == 1+ instantiate_req, _ = session.instantiate_calls[0]+ assert instantiate_req.auto_run is False++ @pytest.mark.asyncio+ async def test_holds_scratchpad_lock_while_putting_execute_command(+ self,+ ) -> None:+ """`scratchpad_lock` must be held while putting the execute+ command so two concurrent code-mode calls can't interleave."""+ session = _FakeSession()+ lock_held: list[bool] = []+ original_put = session.put_control_request++ def spy(req: CommandMessage, from_consumer_id: object = None) -> None:+ if isinstance(req, ExecuteScratchpadCommand):+ lock_held.append(session.scratchpad_lock.locked())+ original_put(req, from_consumer_id)++ session.put_control_request = spy # type: ignore[method-assign]++ await run_scratchpad_code(+ session.as_session(),+ _build_request(),+ code="x = 1",+ server_url="u",+ auth_token="t",+ )++ assert lock_held == [True]++ @pytest.mark.asyncio+ async def test_timeout_interrupts_kernel_and_surfaces_in_errors(+ self,+ ) -> None:+ """On timeout the kernel is still running the (likely hung)+ scratchpad code; `run_scratchpad_code` must interrupt it so the+ next code-mode call doesn't block on `scratchpad_lock` — and+ the timeout must be reported in `errors` (plural), matching+ the success path's shape."""+ session = _FakeSession(auto_complete=False)++ result = await run_scratchpad_code(+ session.as_session(),+ _build_request(),+ code="while True: pass",+ server_url="u",+ auth_token="t",+ timeout=0.05,+ )++ assert result == snapshot(+ CodeExecutionResult(+ success=False,+ errors=["Execution timed out after 0.05s"],+ )+ )+ assert session.interrupt_count == 1++ @pytest.mark.asyncio+ async def test_cancelled_wait_interrupts_kernel(self) -> None:+ """If the caller cancels mid-tool-call (e.g. the chat session+ ends or pydantic_ai aborts the run), the kernel is still+ processing our `ExecuteScratchpadCommand`. We must interrupt+ before releasing `scratchpad_lock` so the next code-mode+ call isn't blocked behind the abandoned code, and we must+ re-raise the cancellation so the caller still observes it."""+ session = _FakeSession(auto_complete=False)++ async def run() -> None:+ await run_scratchpad_code(+ session.as_session(),+ _build_request(),+ code="while True: pass",+ server_url="u",+ auth_token="t",+ )++ task = asyncio.create_task(run())+ # Yield enough for the runner to reach `await listener.wait(...)`.+ for _ in range(10):+ await asyncio.sleep(0)+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await task++ assert session.interrupt_count == 1++ @pytest.mark.asyncio+ async def test_timeout_interrupt_happens_while_holding_lock(+ self,+ ) -> None:+ """Regression guard: `try_interrupt()` must run BEFORE releasing+ `scratchpad_lock`. Otherwise a concurrent code-mode call could+ acquire the lock and start running between timeout detection and+ the interrupt — and get its brand-new execution killed by us."""+ session = _FakeSession(auto_complete=False)+ lock_held_during_interrupt: list[bool] = []+ original_interrupt = session.try_interrupt++ def spy() -> None:+ lock_held_during_interrupt.append(session.scratchpad_lock.locked())+ original_interrupt()++ session.try_interrupt = spy # type: ignore[method-assign]++ await run_scratchpad_code(+ session.as_session(),+ _build_request(),+ code="while True: pass",+ server_url="u",+ auth_token="t",+ timeout=0.05,+ )++ assert lock_held_during_interrupt == [True]++ @pytest.mark.asyncio+ async def test_child_cell_errors_flow_into_result_errors(self) -> None:+ """End-to-end: child-cell errors captured by the listener during+ execution must surface in `result.errors` — otherwise the AI+ never learns its `run_cell` calls failed. This pins down the+ `extract_result(session, listener)` plumbing as well; dropping+ the `listener` arg silently loses every child-cell error."""+ from marimo._types.ids import CellId_t++ session = _FakeSession()+ # Real scratch cell runs emit an idle notification even when+ # their own output is empty; without one, extract_result+ # short-circuits before consulting the listener.+ session.session_view.cell_notifications[SCRATCH_CELL_ID] = (+ CellNotification(+ cell_id=SCRATCH_CELL_ID,+ output=CellOutput(+ channel=CellChannel.OUTPUT,+ mimetype="text/plain",+ data="",+ ),+ console=None,+ status="idle",+ )+ )+ session.emit(+ CellNotification(+ cell_id=CellId_t("child-cell"),+ output=CellOutput.errors(+ [+ MarimoExceptionRaisedError(+ msg="division by zero",+ exception_type="ZeroDivisionError",+ raising_cell=None,+ )+ ]+ ),+ console=None,+ status="idle",+ )+ )++ result = await run_scratchpad_code(+ session.as_session(),+ _build_request(),+ code="run_cell('child-cell')",+ server_url="u",+ auth_token="t",+ )++ assert result.success is False+ assert result.errors == ["cell 'child-cell' raised ZeroDivisionError"]