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
improvement: run auto-instaniate on the backend for run mode (#7603)
Myles Scolnickb41bc5e766dc
diff --git a/frontend/src/core/dom/uiregistry.ts b/frontend/src/core/dom/uiregistry.tsindex c09ec42902..94a42ba615 100644--- a/frontend/src/core/dom/uiregistry.ts+++ b/frontend/src/core/dom/uiregistry.ts@@ -28,7 +28,7 @@ interface UIElementEntry {*/export class UIElementRegistry {// maps UIElement objectIds to entries.- entries: Map<string, UIElementEntry>;+ entries: Map<UIElementId, UIElementEntry>;/*** Shared instance of UIElementRegistry since this must be a singleton.@@ -125,7 +125,7 @@ export class UIElementRegistry {* @param objectId - id of the UIElement* @returns the value for `objectId`, or `undefined` if the object was not found.*/- lookupValue(objectId: string): ValueType {+ lookupValue(objectId: UIElementId): ValueType {const entry = this.entries.get(objectId);return entry === undefined ? undefined : entry.value;}diff --git a/frontend/src/core/kernel/__tests__/handlers.test.ts b/frontend/src/core/kernel/__tests__/handlers.test.tsindex 467f1d4df5..2cb7634e6a 100644--- a/frontend/src/core/kernel/__tests__/handlers.test.ts+++ b/frontend/src/core/kernel/__tests__/handlers.test.ts@@ -1,5 +1,7 @@/* Copyright 2026 Marimo. All rights reserved. */import { describe, expect, it, vi } from "vitest";+import { buildCellData, buildLayoutState } from "../handlers";+import type { NotificationMessageData } from "../messages";import { queryParamHandlers } from "../queryParamHandlers";// Helper to set up URL and searchParams@@ -59,3 +61,229 @@ describe("queryParamHandlers", () => {expect(window.history.pushState).toHaveBeenCalled();});});++describe("buildCellData", () => {+ it("should build cell data from kernel-ready data", () => {+ const kernelReadyData: NotificationMessageData<"kernel-ready"> = {+ cell_ids: ["cell1", "cell2"],+ codes: ["x = 1", "y = 2"],+ names: ["__", "__"],+ configs: [+ { disabled: false, hide_code: false },+ { disabled: false, hide_code: false },+ ],+ layout: null,+ resumed: false,+ ui_values: {},+ last_executed_code: {},+ last_execution_time: {},+ app_config: {+ width: "normal",+ app_title: null,+ layout_file: null,+ css_file: null,+ auto_download: [],+ },+ kiosk: false,+ capabilities: {+ terminal: false,+ },+ auto_instantiated: false,+ };++ const cells = buildCellData(kernelReadyData);++ expect(cells).toMatchInlineSnapshot(`+ [+ {+ "code": "x = 1",+ "config": {+ "disabled": false,+ "hide_code": false,+ },+ "edited": false,+ "id": "cell1",+ "lastCodeRun": null,+ "lastExecutionTime": null,+ "name": "__",+ "serializedEditorState": null,+ },+ {+ "code": "y = 2",+ "config": {+ "disabled": false,+ "hide_code": false,+ },+ "edited": false,+ "id": "cell2",+ "lastCodeRun": null,+ "lastExecutionTime": null,+ "name": "__",+ "serializedEditorState": null,+ },+ ]+ `);+ });++ it("should mark cells as edited when code differs from last executed code", () => {+ const kernelReadyData: NotificationMessageData<"kernel-ready"> = {+ cell_ids: ["cell1", "cell2"],+ codes: ["x = 1", "y = 3"],+ names: ["__", "__"],+ configs: [+ { disabled: false, hide_code: false },+ { disabled: false, hide_code: false },+ ],+ layout: null,+ resumed: false,+ ui_values: {},+ last_executed_code: {+ cell1: "x = 1",+ cell2: "y = 2",+ },+ last_execution_time: {+ cell1: 1234567890,+ cell2: 1234567891,+ },+ app_config: {+ width: "normal",+ app_title: null,+ layout_file: null,+ css_file: null,+ auto_download: [],+ },+ kiosk: false,+ capabilities: {+ terminal: false,+ },+ auto_instantiated: false,+ };++ const cells = buildCellData(kernelReadyData);++ expect(cells[0].edited).toBe(false);+ expect(cells[1].edited).toBe(true);+ expect(cells[0].lastCodeRun).toBe("x = 1");+ expect(cells[1].lastCodeRun).toBe("y = 2");+ });++ it("should handle empty cell data", () => {+ const kernelReadyData: NotificationMessageData<"kernel-ready"> = {+ cell_ids: [],+ codes: [],+ names: [],+ configs: [],+ layout: null,+ resumed: false,+ ui_values: {},+ last_executed_code: {},+ last_execution_time: {},+ app_config: {+ width: "normal",+ app_title: null,+ layout_file: null,+ css_file: null,+ auto_download: [],+ },+ kiosk: false,+ capabilities: {+ terminal: false,+ },+ auto_instantiated: false,+ };++ const cells = buildCellData(kernelReadyData);++ expect(cells).toMatchInlineSnapshot("[]");+ });+});++describe("buildLayoutState", () => {+ it("should build default layout state when no layout is provided", () => {+ const kernelReadyData: NotificationMessageData<"kernel-ready"> = {+ cell_ids: ["cell1"],+ codes: ["x = 1"],+ names: ["__"],+ configs: [{ disabled: false, hide_code: false }],+ layout: null,+ resumed: false,+ ui_values: {},+ last_executed_code: {},+ last_execution_time: {},+ app_config: {+ width: "normal",+ app_title: null,+ layout_file: null,+ css_file: null,+ auto_download: [],+ },+ kiosk: false,+ capabilities: {+ terminal: false,+ },+ auto_instantiated: false,+ };++ const cells = buildCellData(kernelReadyData);+ const mockSetLayoutData = vi.fn();+ const layoutState = buildLayoutState(+ kernelReadyData,+ cells,+ mockSetLayoutData,+ );++ expect(layoutState).toMatchInlineSnapshot(`+ {+ "layoutData": {},+ "selectedLayout": "vertical",+ }+ `);+ expect(mockSetLayoutData).not.toHaveBeenCalled();+ });++ it("should build layout state with vertical layout", () => {+ const kernelReadyData: NotificationMessageData<"kernel-ready"> = {+ cell_ids: ["cell1", "cell2"],+ codes: ["x = 1", "y = 2"],+ names: ["__", "__"],+ configs: [+ { disabled: false, hide_code: false },+ { disabled: false, hide_code: false },+ ],+ layout: {+ type: "vertical",+ data: [],+ },+ resumed: false,+ ui_values: {},+ last_executed_code: {},+ last_execution_time: {},+ app_config: {+ width: "normal",+ app_title: null,+ layout_file: null,+ css_file: null,+ auto_download: [],+ },+ kiosk: false,+ capabilities: {+ terminal: false,+ },+ auto_instantiated: false,+ };++ const cells = buildCellData(kernelReadyData);+ const mockSetLayoutData = vi.fn();+ const layoutState = buildLayoutState(+ kernelReadyData,+ cells,+ mockSetLayoutData,+ );++ expect(layoutState.selectedLayout).toBe("vertical");+ expect(mockSetLayoutData).toHaveBeenCalledWith({+ layoutView: "vertical",+ data: expect.any(Array),+ });+ });+});diff --git a/frontend/src/core/kernel/handlers.ts b/frontend/src/core/kernel/handlers.tsindex 189655115d..548c74e2a9 100644--- a/frontend/src/core/kernel/handlers.ts+++ b/frontend/src/core/kernel/handlers.ts@@ -19,69 +19,57 @@ import type {NotificationMessageData,} from "./messages";-export function handleKernelReady(- data: NotificationMessageData<"kernel-ready">,- opts: {- autoInstantiate: boolean;- setCells: (cells: CellData[], layout: LayoutState) => void;- setLayoutData: (payload: {- layoutView: LayoutType;- data: LayoutData;- }) => void;- setCapabilities: (capabilities: Capabilities) => void;- setAppConfig: (config: AppConfig) => void;- onError: (error: Error) => void;- },-) {- const {- autoInstantiate,- setCells,- setLayoutData,- onError,- setAppConfig,- setCapabilities,- } = opts;+type KernelReadyData = NotificationMessageData<"kernel-ready">;+/**+ * Build cells from kernel-ready data.+ */+export function buildCellData(data: KernelReadyData): CellData[] {const {codes,names,- layout,configs,- resumed,- ui_values,cell_ids,last_executed_code,- last_execution_time = {},- app_config,- capabilities,+ last_execution_time,} = data;+const lastExecutedCode = last_executed_code || {};const lastExecutionTime = last_execution_time || {};- // Set the layout, initial codes, cells- const cells = codes.map((code, i) => {+ return codes.map((code, i) => {const cellId = cell_ids[i];-- // A cell is stale if we did not auto-instantiate (i.e. nothing has run yet)- // or if the code has changed since the last time it was run.- let edited = false;const lastCodeRun = lastExecutedCode[cellId];- if (lastCodeRun) {- edited = lastCodeRun !== code;- }++ // A cell is edited if the code has changed since the last time it was run+ const edited = lastCodeRun ? lastCodeRun !== code : false;return createCell({id: cellId as CellId,code,- edited: edited,+ edited,name: names[i],lastCodeRun: lastExecutedCode[cellId] ?? null,lastExecutionTime: lastExecutionTime[cellId] ?? null,config: configs[i],});});+}+/**+ * Build layout state from kernel-ready data.+ */+export function buildLayoutState(+ data: KernelReadyData,+ cells: CellData[],+ setLayoutData: (payload: {+ layoutView: LayoutType;+ data: LayoutData;+ }) => void,+): LayoutState {const layoutState = initialLayoutState();+ const { layout } = data;+if (layout) {const layoutType = layout.type as LayoutType;const layoutData = deserializeLayout({@@ -93,15 +81,75 @@ export function handleKernelReady(layoutState.layoutData[layoutType] = layoutData;setLayoutData({ layoutView: layoutType, data: layoutData });}++ return layoutState;+}++/**+ * Collect current UI element values from the registry.+ */+function collectUIElementValues() {+ const objectIds: UIElementId[] = [];+ const values: unknown[] = [];+ UI_ELEMENT_REGISTRY.entries.forEach((entry, objectId) => {+ objectIds.push(objectId);+ values.push(entry.value);+ });+ return { objectIds, values };+}++export function handleKernelReady(+ data: KernelReadyData,+ opts: {+ autoInstantiate: boolean;+ setCells: (cells: CellData[], layout: LayoutState) => void;+ setLayoutData: (payload: {+ layoutView: LayoutType;+ data: LayoutData;+ }) => void;+ setCapabilities: (capabilities: Capabilities) => void;+ setAppConfig: (config: AppConfig) => void;+ onError: (error: Error) => void;+ /**+ * If provided, these cells will be used instead of the cells from+ * kernel-ready. This allows preserving local edits made before connecting.+ */+ existingCells?: CellData[];+ },+) {+ const {+ existingCells,+ autoInstantiate,+ setCells,+ setLayoutData,+ setAppConfig,+ setCapabilities,+ onError,+ } = opts;+ const { resumed, ui_values, app_config, capabilities, auto_instantiated } =+ data;++ // Use existing cells if provided (local pre-connect edits), otherwise build from kernel-ready+ const hasExistingCells = existingCells && existingCells.length > 0;+ const cells = hasExistingCells ? existingCells : buildCellData(data);++ // Set up layout and cells+ const layoutState = buildLayoutState(data, cells, setLayoutData);setCells(cells, layoutState);++ // Set app config and capabilitiesconst parsedAppConfig = AppConfigSchema.safeParse(app_config);if (parsedAppConfig.success) {setAppConfig(parsedAppConfig.data);}setCapabilities(capabilities);- // If resumed, we don't need to instantiate the UI elements,- // and we should read in th existing values from the kernel.+ // If the kernel was already instantiated server-side (e.g. run mode), we're done+ if (auto_instantiated) {+ return;+ }++ // If resumed, restore UI element values from kernel and we're doneif (resumed) {for (const [objectId, value] of Objects.entries(ui_values || {})) {UI_ELEMENT_REGISTRY.set(objectId as UIElementId, value);@@ -109,23 +157,22 @@ export function handleKernelReady(return;}- // Auto-instantiate, in future this can be configurable- // or include initial values- const objectIds: string[] = [];- const values: unknown[] = [];+ // Send instantiate request to kernel+// If we already have values for some objects, we should// send them to the kernel. This may happen after re-connecting// to the kernel after the computer wakes from sleep.- UI_ELEMENT_REGISTRY.entries.forEach((entry, objectId) => {- objectIds.push(objectId);- values.push(entry.value);- });+ const { objectIds, values } = collectUIElementValues();+ const codesToSend = hasExistingCells+ ? Object.fromEntries(existingCells.map((c) => [c.id, c.code]))+ : undefined;- getRequestClient()+ void getRequestClient().sendInstantiate({- objectIds: objectIds,+ objectIds,values,autoRun: autoInstantiate,+ codes: codesToSend,}).catch((error) => {onError(new Error("Failed to instantiate", { cause: error }));diff --git a/frontend/src/core/websocket/useMarimoKernelConnection.tsx b/frontend/src/core/websocket/useMarimoKernelConnection.tsxindex 0e36a4a462..c2fb10fea6 100644--- a/frontend/src/core/websocket/useMarimoKernelConnection.tsx+++ b/frontend/src/core/websocket/useMarimoKernelConnection.tsx@@ -25,7 +25,7 @@ import { Logger } from "@/utils/Logger";import { reloadSafe } from "@/utils/reload-safe";import { useAlertActions } from "../alerts/state";import { cacheInfoAtom } from "../cache/requests";-import type { CellId, UIElementId } from "../cells/ids";+import { type CellId, SCRATCH_CELL_ID, type UIElementId } from "../cells/ids";import { useRunsActions } from "../cells/runs";import { focusAndScrollCellOutputIntoView } from "../cells/scrollCellIntoView";import type { CellData } from "../cells/types";@@ -61,6 +61,19 @@ import type { VariableName } from "../variables/types";import { isWasm } from "../wasm/utils";import { WebSocketClosedReason, WebSocketState } from "./types";+const SUPPORTS_LAZY_KERNELS = false;++function getExistingCells(): CellData[] | undefined {+ if (!SUPPORTS_LAZY_KERNELS) {+ return undefined;+ }++ // Remove scratch pad+ return Object.values(getNotebook().cellData).filter(+ (cell) => cell.id !== SCRATCH_CELL_ID,+ );+}+/*** Creates a connection to the Marimo kernel and handles incoming messages.*/@@ -97,7 +110,11 @@ export function useMarimoKernelConnection(opts: {case "reload":reloadSafe();return;- case "kernel-ready":+ case "kernel-ready": {+ // TODO(mscolnick): For lazy kernels, we should grab existing cells from the page+ // in case they have been edited locally.+ const existingCells = getExistingCells();+handleKernelReady(msg.data, {autoInstantiate,setCells,@@ -105,9 +122,11 @@ export function useMarimoKernelConnection(opts: {setAppConfig,setCapabilities,onError: showBoundary,+ existingCells,});setKioskMode(msg.data.kiosk);return;+ }case "completed-run":return;diff --git a/frontend/src/plugins/impl/FormPlugin.tsx b/frontend/src/plugins/impl/FormPlugin.tsxindex 53bfcf1d75..fe242f3716 100644--- a/frontend/src/plugins/impl/FormPlugin.tsx+++ b/frontend/src/plugins/impl/FormPlugin.tsx@@ -4,6 +4,7 @@ import { Loader2Icon } from "lucide-react";import { type JSX, useEffect, useRef, useState } from "react";import { z } from "zod";import { Tooltip, TooltipProvider } from "@/components/ui/tooltip";+import type { UIElementId } from "@/core/cells/ids";import {MarimoValueInputEvent,type MarimoValueInputEventType,@@ -22,7 +23,7 @@ type T = unknown;interface Data {label: string | null;- elementId: string;+ elementId: UIElementId;bordered: boolean;loading: boolean;submitButtonLabel: string;@@ -52,7 +53,7 @@ export const FormPlugin = createPlugin("marimo-form").withData<Data>(z.object({label: z.string().nullable(),- elementId: z.string(),+ elementId: z.string().transform((v) => v as UIElementId),bordered: z.boolean().default(true),loading: z.boolean().default(false),submitButtonLabel: z.string().default("Submit"),diff --git a/marimo/_ast/cell_manager.py b/marimo/_ast/cell_manager.pyindex 1e0b75994c..152b6b897a 100644--- a/marimo/_ast/cell_manager.py+++ b/marimo/_ast/cell_manager.py@@ -411,6 +411,14 @@ class CellManager:"""return self._cell_data.values()+ def code_map(self) -> dict[CellId_t, str]:+ """Get a mapping of cell IDs to their codes.++ Returns:+ dict[CellId_t, str]: Dictionary mapping cell IDs to their codes+ """+ return {cid: cd.code for cid, cd in self._cell_data.items()}+def cell_data_at(self, cell_id: CellId_t) -> CellData:"""Get the cell data for a specific cell ID.diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.pyindex d551ac46bf..d8a203cedf 100644--- a/marimo/_messaging/notification.py+++ b/marimo/_messaging/notification.py@@ -181,6 +181,9 @@ class KernelReadyNotification(Notification, tag="kernel-ready"):kiosk: bool# Kernel capabilitiescapabilities: KernelCapabilitiesNotification+ # Whether the kernel has already been instantiated server-side (e.g. run mode)+ # If True, the frontend does not need to instantiate the app.+ auto_instantiated: bool = Falseclass CompletionResultNotification(Notification, tag="completion-result"):diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.pyindex acf0bd2051..a46bf087e8 100644--- a/marimo/_server/api/endpoints/execution.py+++ b/marimo/_server/api/endpoints/execution.py@@ -100,6 +100,7 @@ async def set_model_values(@router.post("/instantiate")+@requires("edit")async def instantiate(*,request: Request,@@ -112,7 +113,8 @@ async def instantiate($ref: "#/components/schemas/InstantiateNotebookRequest"responses:200:- description: Instantiate a component+ description: Instantiate a component. Only allowed in edit mode;+ in run mode, instantiation happens server-side automatically.content:application/json:schema:diff --git a/marimo/_server/api/endpoints/ws/ws_kernel_ready.py b/marimo/_server/api/endpoints/ws/ws_kernel_ready.pyindex a9564dbe80..fc4c216612 100644--- a/marimo/_server/api/endpoints/ws/ws_kernel_ready.py+++ b/marimo/_server/api/endpoints/ws/ws_kernel_ready.py@@ -38,6 +38,7 @@ def build_kernel_ready(file_key: MarimoFileKey,mode: SessionMode,doc_manager: LoroDocManager,+ auto_instantiated: bool = False,) -> KernelReadyNotification:"""Build a KernelReady message.@@ -53,6 +54,9 @@ def build_kernel_ready(file_key: File key for the sessionmode: Session mode (edit/run)doc_manager: LoroDoc manager for RTC+ auto_instantiated: Whether the kernel has already been instantiated+ server-side (run mode). If True, the frontend does not need+ to instantiate the app.Returns:KernelReady message operation.@@ -76,6 +80,7 @@ def build_kernel_ready(app_config=session.app_file_manager.app.config,kiosk=kiosk,capabilities=KernelCapabilitiesNotification(),+ auto_instantiated=auto_instantiated,)diff --git a/marimo/_server/api/endpoints/ws/ws_session_connector.py b/marimo/_server/api/endpoints/ws/ws_session_connector.pyindex bb43203cf9..1de5ad2b80 100644--- a/marimo/_server/api/endpoints/ws/ws_session_connector.py+++ b/marimo/_server/api/endpoints/ws/ws_session_connector.py@@ -19,7 +19,8 @@ from marimo import _loggersfrom marimo._messaging.types import NoopStreamfrom marimo._runtime.params import QueryParamsfrom marimo._server.codes import WebSocketCodes-from marimo._server.model import SessionMode+from marimo._server.model import ConnectionState, SessionMode+from marimo._server.models.models import InstantiateNotebookRequestLOGGER = _loggers.marimo_logger()@@ -159,21 +160,22 @@ class SessionConnector:self.handler._reconnect_session(session, replay=True)return session, ConnectionType.RESUME+ @property+ def _is_run_mode(self) -> bool:+ """Check if we're in run mode (read-only app mode)."""+ return self.manager.mode == SessionMode.RUN+def _create_new_session(self) -> tuple[Session, ConnectionType]:"""Create a new session.Grabs query params from the websocket and creates a new sessionwith the session manager."""- # Grab the query params from the websocket+# Note: if we resume a session, we don't pick up the new query# params, and instead use the query params from when the# session was created.- query_params = QueryParams({}, NoopStream())- for key, value in self.websocket.query_params.multi_items():- if key in QueryParams.IGNORED_KEYS:- continue- query_params.append(key, value)+ query_params = self._extract_query_params()new_session = self.manager.create_session(query_params=query_params.to_dict(),@@ -183,19 +185,44 @@ class SessionConnector:auto_instantiate=self.params.auto_instantiate,)- # Notify frontend that kernel is ready- from marimo._server.model import ConnectionState+ self._notify_kernel_ready(new_session)++ # In run mode, auto-instantiate server-side (frontend won't call it)+ if self._is_run_mode:+ self._auto_instantiate(new_session)++ return new_session, ConnectionType.NEW+ def _extract_query_params(self) -> QueryParams:+ """Extract query params from the websocket, filtering ignored keys."""+ query_params = QueryParams({}, NoopStream())+ for key, value in self.websocket.query_params.multi_items():+ if key not in QueryParams.IGNORED_KEYS:+ query_params.append(key, value)+ return query_params++ def _notify_kernel_ready(self, session: Session) -> None:+ """Send kernel-ready notification to the frontend."""self.handler.status = ConnectionState.CONNECTINGself.handler._write_kernel_ready(- new_session,+ session,resumed=False,ui_values={},last_executed_code={},last_execution_time={},kiosk=False,+ auto_instantiated=self._is_run_mode,)self.handler.status = ConnectionState.OPEN- self.handler._replay_previous_session(new_session)-- return new_session, ConnectionType.NEW+ self.handler._replay_previous_session(session)++ def _auto_instantiate(self, session: Session) -> None:+ """Auto-instantiate the session (used in run mode)."""+ session.instantiate(+ InstantiateNotebookRequest(+ object_ids=[],+ values=[],+ auto_run=True,+ ),+ http_request=None,+ )diff --git a/marimo/_server/api/endpoints/ws_endpoint.py b/marimo/_server/api/endpoints/ws_endpoint.pyindex 7c61e2801c..8e311569fe 100644--- a/marimo/_server/api/endpoints/ws_endpoint.py+++ b/marimo/_server/api/endpoints/ws_endpoint.py@@ -183,6 +183,7 @@ class WebSocketHandler(SessionConsumer):last_executed_code=session.session_view.last_executed_code,last_execution_time=session.session_view.last_execution_time,kiosk=kiosk,+ auto_instantiated=False,)def _write_kernel_ready(@@ -193,10 +194,22 @@ class WebSocketHandler(SessionConsumer):last_executed_code: dict[CellId_t, str],last_execution_time: dict[CellId_t, float],kiosk: bool,+ auto_instantiated: bool,) -> None:"""Communicates to the client that the kernel is ready.Sends cell code and other metadata to client.++ Args:+ session: Current session+ resumed: Whether this is a resumed session+ ui_values: UI element values+ last_executed_code: Last executed code for each cell+ last_execution_time: Last execution time for each cell+ kiosk: Whether this is kiosk mode+ auto_instantiated: Whether the kernel has already been instantiated+ server-side (run mode). If True, the frontend does not need+ to instantiate the app."""# Only send execution data if sending code to frontendshould_send = self.manager.should_send_code_to_frontend()@@ -217,6 +230,7 @@ class WebSocketHandler(SessionConsumer):file_key=self.params.file_key,mode=self.mode,doc_manager=DOC_MANAGER,+ auto_instantiated=auto_instantiated,)self._serialize_and_notify(kernel_ready_msg)diff --git a/marimo/_server/models/models.py b/marimo/_server/models/models.pyindex 0a4e3f8bb4..067c820c38 100644--- a/marimo/_server/models/models.py+++ b/marimo/_server/models/models.py@@ -186,6 +186,11 @@ class UpdateUIElementValuesRequest(msgspec.Struct, rename="camel"):class InstantiateNotebookRequest(UpdateUIElementValuesRequest):auto_run: bool = True+ # Optional: cell codes to use instead of the codes from the file.+ # This is used when the frontend has local edits that should be+ # used instead of the file codes (e.g., pre-connect editing).+ # Maps cell_id -> code.+ codes: Optional[dict[CellId_t, str]] = Noneclass BaseResponse(msgspec.Struct, rename="camel"):diff --git a/marimo/_server/sessions/extensions/extensions.py b/marimo/_server/sessions/extensions/extensions.pyindex cc84576dcc..8a59de8b09 100644--- a/marimo/_server/sessions/extensions/extensions.py+++ b/marimo/_server/sessions/extensions/extensions.py@@ -8,7 +8,7 @@ Extensions provide a way to add cross-cutting concerns to sessionsfrom __future__ import annotationsimport asyncio-from typing import TYPE_CHECKING, Optional, Union+from typing import TYPE_CHECKING, Optionalfrom marimo import _loggersfrom marimo._cli.print import red@@ -287,9 +287,7 @@ class SessionViewExtension(SessionExtension, SessionEventListener):def on_received_command(self,session: Session,- request: Union[- commands.CommandMessage, commands.CodeCompletionCommand- ],+ request: commands.CommandMessage,from_consumer_id: Optional[ConsumerId],) -> None:"""Called when a command is received."""@@ -331,9 +329,7 @@ class QueueExtension(SessionExtension, SessionEventListener):def on_received_command(self,session: Session,- request: Union[- commands.CommandMessage, commands.CodeCompletionCommand- ],+ request: commands.CommandMessage,from_consumer_id: Optional[ConsumerId],) -> None:"""Called when a command is received."""@@ -368,9 +364,7 @@ class ReplayExtension(SessionExtension, SessionEventListener):def on_received_command(self,session: Session,- request: Union[- commands.CommandMessage, commands.CodeCompletionCommand- ],+ request: commands.CommandMessage,from_consumer_id: Optional[ConsumerId],) -> None:"""Called when a command is received."""diff --git a/marimo/_server/sessions/session.py b/marimo/_server/sessions/session.pyindex 06925bedf9..6e2d163268 100644--- a/marimo/_server/sessions/session.py+++ b/marimo/_server/sessions/session.py@@ -328,13 +328,21 @@ class SessionImpl(Session):http_request: Optional[HTTPRequest],) -> None:"""Instantiate the app."""++ # If codes are provided, use them instead of the file codes+ # This is used when the frontend has local edits that should be+ # used instead of the stored file (e.g. local editing before connecting).+ codes = (+ request.codes or self.app_file_manager.app.cell_manager.code_map()+ )+execution_requests = tuple(ExecuteCellCommand(- cell_id=cell_data.cell_id,- code=cell_data.code,+ cell_id=cell_id,+ code=code,request=http_request,)- for cell_data in self.app_file_manager.app.cell_manager.cell_data()+ for cell_id, code in codes.items())self.put_control_request(diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yamlindex bca3b6c10b..6f70da5f87 100644--- a/packages/openapi/api.yaml+++ b/packages/openapi/api.yaml@@ -1993,6 +1993,13 @@ components:autoRun:default: truetype: boolean+ codes:+ anyOf:+ - additionalProperties:+ type: string+ type: object+ - type: 'null'+ default: nullobjectIds:items:type: string@@ -2108,6 +2115,9 @@ components:properties:app_config:$ref: '#/components/schemas/_AppConfig'+ auto_instantiated:+ default: false+ type: booleancapabilities:$ref: '#/components/schemas/KernelCapabilitiesNotification'cell_ids:@@ -4928,7 +4938,8 @@ paths:application/json:schema:$ref: '#/components/schemas/SuccessResponse'- description: Instantiate a component+ description: Instantiate a component. Only allowed in edit mode; in run+ mode, instantiation happens server-side automatically./api/kernel/interrupt:post:responses:diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.tsindex a9e32ab128..2eefb8e110 100644--- a/packages/openapi/src/api.ts+++ b/packages/openapi/src/api.ts@@ -1571,7 +1571,7 @@ export interface paths {};};responses: {- /** @description Instantiate a component */+ /** @description Instantiate a component. Only allowed in edit mode; in run mode, instantiation happens server-side automatically. */200: {headers: {[name: string]: unknown;@@ -3943,6 +3943,10 @@ export interface components {InstantiateNotebookRequest: {/** @default true */autoRun?: boolean;+ /** @default null */+ codes?: {+ [key: string]: string;+ } | null;objectIds: string[];values: unknown[];};@@ -4011,6 +4015,8 @@ export interface components {*/KernelReadyNotification: {app_config: components["schemas"]["_AppConfig"];+ /** @default false */+ auto_instantiated?: boolean;capabilities: components["schemas"]["KernelCapabilitiesNotification"];cell_ids: string[];codes: string[];diff --git a/tests/_ast/test_cell_manager.py b/tests/_ast/test_cell_manager.pyindex 7442c0fe2e..f3e400d1b1 100644--- a/tests/_ast/test_cell_manager.py+++ b/tests/_ast/test_cell_manager.py@@ -564,3 +564,23 @@ class TestSortCellIdsBySimilarity:assert list(curr_manager.cell_ids()) == [CELL_A]assert curr_manager.seen_ids == {CELL_A}assert curr_manager.cell_data_at(CELL_A).code == "y = 2 + 1"++ def test_code_map(self) -> None:+ """Test that code_map returns a dictionary of cell IDs to codes."""+ manager = CellManager()+ manager.register_cell(CELL_A, "x = 1", CellConfig())+ manager.register_cell(CELL_B, "y = 2", CellConfig())+ manager.register_cell(CELL_C, "z = 3", CellConfig())++ code_map = manager.code_map()+ assert code_map == {+ CELL_A: "x = 1",+ CELL_B: "y = 2",+ CELL_C: "z = 3",+ }++ def test_code_map_empty(self) -> None:+ """Test that code_map returns an empty dict for empty manager."""+ manager = CellManager()+ code_map = manager.code_map()+ assert code_map == {}diff --git a/tests/_server/api/endpoints/test_auto_instantiate.py b/tests/_server/api/endpoints/test_auto_instantiate.pynew file mode 100644index 0000000000..f03aab2d87--- /dev/null+++ b/tests/_server/api/endpoints/test_auto_instantiate.py@@ -0,0 +1,208 @@+# Copyright 2024 Marimo. All rights reserved.+"""Tests for auto-instantiate behavior in run mode vs edit mode."""++from __future__ import annotations++from typing import TYPE_CHECKING++from marimo._messaging.notification import KernelReadyNotification+from marimo._server.model import SessionMode+from marimo._utils.parse_dataclass import parse_raw+from tests._server.mocks import token_header++if TYPE_CHECKING:+ from starlette.testclient import TestClient+++def _create_headers(session_id: str) -> dict[str, str]:+ """Create headers with both token and session ID."""+ return {+ **token_header("fake-token"),+ "Marimo-Session-Id": session_id,+ }+++def _create_ws_url(session_id: str) -> str:+ return f"/ws?session_id={session_id}&access_token=fake-token"+++class TestAutoInstantiateEditMode:+ """Tests for auto-instantiate in edit mode."""++ def test_kernel_ready_auto_instantiated_false_in_edit_mode(+ self, client: TestClient+ ) -> None:+ """In edit mode, auto_instantiated should be False."""+ session_id = "test-edit-mode"+ ws_url = _create_ws_url(session_id)+ headers = _create_headers(session_id)++ with client.websocket_connect(ws_url) as websocket:+ data = websocket.receive_json()+ assert data["op"] == "kernel-ready"++ kernel_ready = parse_raw(data["data"], KernelReadyNotification)+ # In edit mode, auto_instantiated should be False+ assert kernel_ready.auto_instantiated is False++ client.post("/api/kernel/shutdown", headers=headers)++ def test_instantiate_endpoint_allowed_in_edit_mode(+ self, client: TestClient+ ) -> None:+ """In edit mode, /instantiate endpoint should be allowed."""+ session_id = "test-instantiate-edit"+ ws_url = _create_ws_url(session_id)+ headers = _create_headers(session_id)++ with client.websocket_connect(ws_url):+ # The /instantiate endpoint should work in edit mode+ response = client.post(+ "/api/kernel/instantiate",+ headers=headers,+ json={"objectIds": [], "values": [], "autoRun": False},+ )+ assert response.status_code == 200++ client.post("/api/kernel/shutdown", headers=headers)+++class TestAutoInstantiateRunMode:+ """Tests for auto-instantiate in run mode."""++ def test_kernel_ready_auto_instantiated_true_in_run_mode(+ self, client: TestClient+ ) -> None:+ """In run mode, auto_instantiated should be True."""+ from tests._server.conftest import get_session_manager++ session_manager = get_session_manager(client)+ original_mode = session_manager.mode+ session_id = "test-run-mode"+ headers = _create_headers(session_id)++ try:+ # Switch to run mode+ session_manager.mode = SessionMode.RUN+ ws_url = _create_ws_url(session_id)++ with client.websocket_connect(ws_url) as websocket:+ data = websocket.receive_json()+ assert data["op"] == "kernel-ready"++ kernel_ready = parse_raw(data["data"], KernelReadyNotification)+ # In run mode, auto_instantiated should be True+ assert kernel_ready.auto_instantiated is True+ finally:+ session_manager.mode = original_mode+ client.post("/api/kernel/shutdown", headers=headers)++ def test_instantiate_endpoint_blocked_in_run_mode(+ self, client: TestClient+ ) -> None:+ """In run mode, /instantiate endpoint should return 401 (Unauthorized).++ The @requires("edit") decorator checks for edit permissions, and in run mode+ users only have "read" permissions, so they get 401 Unauthorized.+ """+ from tests._server.conftest import get_session_manager++ session_manager = get_session_manager(client)+ original_mode = session_manager.mode+ session_id = "test-instantiate-run"+ headers = _create_headers(session_id)++ try:+ # Switch to run mode+ session_manager.mode = SessionMode.RUN+ ws_url = _create_ws_url(session_id)++ with client.websocket_connect(ws_url):+ # The /instantiate endpoint should be blocked in run mode+ # Returns 401 because @requires("edit") checks permissions+ response = client.post(+ "/api/kernel/instantiate",+ headers=headers,+ json={"objectIds": [], "values": [], "autoRun": False},+ )+ assert response.status_code == 401+ finally:+ session_manager.mode = original_mode+ client.post("/api/kernel/shutdown", headers=headers)+++class TestInstantiateNotebookRequest:+ """Tests for InstantiateNotebookRequest with codes field."""++ def test_instantiate_request_with_codes(self) -> None:+ """InstantiateNotebookRequest should accept optional codes field."""+ from marimo._server.models.models import InstantiateNotebookRequest++ # Without codes+ request = InstantiateNotebookRequest(+ object_ids=[],+ values=[],+ auto_run=True,+ )+ assert request.codes is None++ # With codes+ request_with_codes = InstantiateNotebookRequest(+ object_ids=[],+ values=[],+ auto_run=True,+ codes={"cell1": "print('hello')"},+ )+ assert request_with_codes.codes == {"cell1": "print('hello')"}++ def test_instantiate_with_codes_field(self, client: TestClient) -> None:+ """Test that instantiate endpoint accepts codes field.++ This test verifies the API accepts the codes parameter without+ creating a new session (which would fail due to multiprocessing issues+ in the test environment).+ """+ del client+ from marimo._server.models.models import InstantiateNotebookRequest++ # Test that the model accepts codes+ request_with_codes = InstantiateNotebookRequest(+ object_ids=[],+ values=[],+ auto_run=True,+ codes={"cell1": "print('test')", "cell2": "x = 1"},+ )+ assert request_with_codes.codes == {+ "cell1": "print('test')",+ "cell2": "x = 1",+ }+ assert request_with_codes.auto_run is True++ def test_instantiate_endpoint_without_codes_uses_file_codes(+ self, client: TestClient+ ) -> None:+ """Test that instantiate without codes uses file codes."""+ session_id = "test-file-codes"+ ws_url = _create_ws_url(session_id)+ headers = _create_headers(session_id)++ try:+ with client.websocket_connect(ws_url) as websocket:+ # Get the kernel-ready message+ data = websocket.receive_json()+ assert data["op"] == "kernel-ready"++ # Send instantiate without codes (should use file codes)+ response = client.post(+ "/api/kernel/instantiate",+ headers=headers,+ json={+ "objectIds": [],+ "values": [],+ "autoRun": True,+ # No codes field+ },+ )+ assert response.status_code == 200+ finally:+ client.post("/api/kernel/shutdown", headers=headers)diff --git a/tests/_server/api/endpoints/test_execution.py b/tests/_server/api/endpoints/test_execution.pyindex 0140f63c06..48f3a20bd8 100644--- a/tests/_server/api/endpoints/test_execution.py+++ b/tests/_server/api/endpoints/test_execution.py@@ -259,9 +259,7 @@ class TestExecutionRoutes_RunMode:"autoRun": True,},)- assert response.status_code == 200, response.text- assert response.headers["content-type"] == "application/json"- assert "success" in response.json()+ assert response.status_code == 401, response.text@staticmethod@with_read_session(SESSION_ID)@@ -275,9 +273,7 @@ class TestExecutionRoutes_RunMode:"autoRun": False,},)- assert response.status_code == 200, response.text- assert response.headers["content-type"] == "application/json"- assert "success" in response.json()+ assert response.status_code == 401, response.text@staticmethod@with_read_session(SESSION_ID)