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.

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.ts
index 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.ts
index 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.ts
index 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 capabilities
const 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 done
if (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.tsx
index 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.tsx
index 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.py
index 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.py
index 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 capabilities
capabilities: 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 = False
class CompletionResultNotification(Notification, tag="completion-result"):
diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.py
index 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.py
index 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 session
mode: 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.py
index 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 _loggers
from marimo._messaging.types import NoopStream
from marimo._runtime.params import QueryParams
from marimo._server.codes import WebSocketCodes
-from marimo._server.model import SessionMode
+from marimo._server.model import ConnectionState, SessionMode
+from marimo._server.models.models import InstantiateNotebookRequest
LOGGER = _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 session
with 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.CONNECTING
self.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.py
index 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 frontend
should_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.py
index 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]] = None
class BaseResponse(msgspec.Struct, rename="camel"):
diff --git a/marimo/_server/sessions/extensions/extensions.py b/marimo/_server/sessions/extensions/extensions.py
index 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 sessions
from __future__ import annotations
import asyncio
-from typing import TYPE_CHECKING, Optional, Union
+from typing import TYPE_CHECKING, Optional
from marimo import _loggers
from 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.py
index 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.yaml
index bca3b6c10b..6f70da5f87 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -1993,6 +1993,13 @@ components:
autoRun:
default: true
type: boolean
+ codes:
+ anyOf:
+ - additionalProperties:
+ type: string
+ type: object
+ - type: 'null'
+ default: null
objectIds:
items:
type: string
@@ -2108,6 +2115,9 @@ components:
properties:
app_config:
$ref: '#/components/schemas/_AppConfig'
+ auto_instantiated:
+ default: false
+ type: boolean
capabilities:
$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.ts
index 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.py
index 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.py
new file mode 100644
index 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.py
index 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)