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
/* Copyright 2026 Marimo. All rights reserved. */
import { invalidatePackageData } from "@/core/packages/package-data";
import { useAtom, useAtomValue, useSetAtom, useStore } from "jotai";
import { useEffect, useLayoutEffect, useMemo } from "react";
import { useErrorBoundary } from "react-error-boundary";
import { toast } from "@/components/ui/use-toast";
import {
getNotebook,
notebookAtom,
useReducerActions,
} from "@/core/cells/cells";
import { followDocument } from "@/core/cells/document";
import { AUTOCOMPLETER } from "@/core/codemirror/completion/Autocompleter";
import { createDocumentModel } from "@/core/notebook/document";
import type { NotificationPayload } from "@/core/kernel/messages";
import { useNotebookReplica } from "@/core/session/useNotebookReplica";
import { renderHTML } from "@/plugins/core/RenderHTML";
import {
handleWidgetMessage,
WIDGET_REGISTRY,
} from "@/plugins/impl/anywidget/registry";
import { logNever } from "@/utils/assertNever";
import { prettyError } from "@/utils/errors";
import { safeExtractSetUIElementMessageBuffers } from "@/utils/json/base64";
import { Logger } from "@/utils/Logger";
import { reloadSafe } from "@/utils/reload-safe";
import { useAlertActions } from "../alerts/state";
import { cacheInfoAtom } from "../cache/requests";
import { useRunsActions } from "../cells/runs";
import { focusAndScrollCellOutputIntoView } from "../cells/scrollCellIntoView";
import {
resyncBreakpoints,
setActiveLine,
} from "../codemirror/cells/debugger-state";
import { notebookCells } from "../cells/utils";
import { capabilitiesAtom } from "../config/capabilities";
import { connectionTransportTypeAtom } from "../config/config";
import { useDataSourceActions } from "../datasets/data-source-connections";
import { invalidateDataSourceDiscovery } from "../datasets/data-source-discovery";
import type { ConnectionName } from "../datasets/engines";
import {
DiscoverDataSources,
PreviewSQLSchemaList,
PreviewSQLTable,
PreviewSQLTableList,
ValidateSQL,
} from "../datasets/request-registry";
import { useDatasetsActions } from "../datasets/state";
import { UI_ELEMENT_REGISTRY } from "../dom/uiregistry";
import { kernelStartupErrorAtom, useBannersActions } from "../errors/state";
import { FUNCTIONS_REGISTRY } from "../functions/FunctionRegistry";
import {
handleCellNotificationeration,
handleKernelReady,
handleRemoveUIElements,
} from "../kernel/handlers";
import { queryParamHandlers } from "../kernel/queryParamHandlers";
import {
type SessionId,
type StableSessionId,
stableSessionIdAtom,
} from "../kernel/session";
import { initialRunCompletedAtom, kernelStateAtom } from "../kernel/state";
import { useLayoutActions } from "../layout/state";
import { kioskModeAtom } from "../mode";
import { connectionAtom, startupProgressAtom } from "../network/connection";
import { savedLayoutAtom } from "../saving/state";
import type { RequestId } from "../network/DeferredRequestRegistry";
import { useRuntimeManager } from "../runtime/config";
import { SECRETS_REGISTRY } from "../secrets/request-registry";
import { isStaticNotebook } from "../static/static-state";
import {
DownloadStorage,
ListStorageEntries,
} from "../storage/request-registry";
import { useStorageActions } from "../storage/state";
import { useVariablesActions } from "../variables/state";
import type { VariableName } from "../variables/types";
import { activeDocumentModelAtom } from "./active-notebook";
import { embeddedSnapshotAtom } from "./embedded";
import { WebSocketClosedReason, ConnectionState } from "./types";
/** Coordinate session startup and apply notifications to the editor. */
export function useNotebookSession(opts: {
sessionId: SessionId;
autoInstantiate: boolean;
}) {
const { autoInstantiate, sessionId } = opts;
const { showBoundary } = useErrorBoundary();
const store = useStore();
const {
handleCellMessage,
reconcileDocument,
setLastRun,
resetCellRuntimes,
} = useReducerActions();
const { addCellNotification } = useRunsActions();
const setKernelState = useSetAtom(kernelStateAtom);
const setInitialRunCompleted = useSetAtom(initialRunCompletedAtom);
const { setVariables, setMetadata } = useVariablesActions();
const { addColumnPreview } = useDatasetsActions();
const { addDatasets, filterDatasetsFromVariables } = useDatasetsActions();
const { addDataSourceConnection, filterDataSourcesFromVariables } =
useDataSourceActions();
const { setLayoutData } = useLayoutActions();
const [connection, setConnection] = useAtom(connectionAtom);
const updateStartupProgress = useSetAtom(startupProgressAtom);
const { addBanner } = useBannersActions();
const {
addMissingPackageAlert,
updateEnvironment,
setEnvironment,
addStartupLog,
} = useAlertActions();
const setKioskMode = useSetAtom(kioskModeAtom);
const setStableSessionId = useSetAtom(stableSessionIdAtom);
const setCapabilities = useSetAtom(capabilitiesAtom);
const runtimeManager = useRuntimeManager();
const transportType = useAtomValue(connectionTransportTypeAtom);
const setCacheInfo = useSetAtom(cacheInfoAtom);
const setKernelStartupError = useSetAtom(kernelStartupErrorAtom);
const {
setNamespaces: setStorageNamespaces,
filterFromVariables: filterStorageFromVariables,
} = useStorageActions();
const handleNotification = (msg: NotificationPayload) => {
switch (msg.data.op) {
case "reload":
reloadSafe();
return;
case "startup-progress": {
const { phase } = msg.data;
updateStartupProgress(msg.data);
setConnection((previous) =>
previous.state === ConnectionState.OPEN ||
(previous.state === ConnectionState.CONNECTING &&
previous.phase === phase)
? previous
: { state: ConnectionState.CONNECTING, phase },
);
return;
}
case "kernel-ready": {
setKernelStartupError(null);
setConnection({ state: ConnectionState.OPEN });
setInitialRunCompleted(
Boolean(msg.data.resumed || msg.data.auto_instantiated),
);
const layout = handleKernelReady(msg.data, {
autoInstantiate,
cells: notebookCells(store.get(notebookAtom)),
setLastRun,
resetCellRuntimes,
setLayoutData,
setCapabilities,
setKernelState,
onError: showBoundary,
});
store.set(savedLayoutAtom, layout);
if (!msg.data.resumed) {
// A freshly started kernel may expose a different environment
// (e.g. new env vars); re-run discovery instead of reusing stale
// suggestions from the previous kernel instance.
invalidateDataSourceDiscovery();
}
setKioskMode(msg.data.kiosk);
setStableSessionId(
(msg.data.stable_session_id as StableSessionId | null | undefined) ??
null,
);
// A freshly started kernel has no breakpoints of its own; re-push
// the client's set so they still apply, and clear the stale
// highlighted line from the previous kernel instance.
setActiveLine(null);
resyncBreakpoints();
return;
}
case "completed-run":
setInitialRunCompleted(true);
return;
case "execution":
return;
case "interrupted":
return;
case "kernel-startup-error":
// Full error received via message before websocket close
setKernelStartupError(msg.data.error);
return;
case "send-ui-element-message": {
const uiElement = msg.data.ui_element;
if (uiElement) {
const buffers = safeExtractSetUIElementMessageBuffers(msg.data);
UI_ELEMENT_REGISTRY.broadcastMessage(
uiElement,
msg.data.message,
buffers,
);
}
return;
}
case "model-lifecycle":
handleWidgetMessage(WIDGET_REGISTRY, msg.data);
return;
case "remove-ui-elements":
handleRemoveUIElements(msg.data);
return;
case "completion-result":
AUTOCOMPLETER.resolve(msg.data.completion_id, msg.data);
return;
case "function-call-result":
FUNCTIONS_REGISTRY.resolve(msg.data.function_call_id, msg.data);
return;
case "cell-op": {
handleCellNotificationeration(msg.data, handleCellMessage);
const cellData = getNotebook().cellData[msg.data.cell_id];
if (!cellData) {
return;
}
addCellNotification({
cellNotification: msg.data,
code: cellData.code,
});
return;
}
case "variables":
const variableNames = msg.data.variables.map((v) => v.name);
setVariables(
msg.data.variables.map((v) => ({
name: v.name,
declaredBy: v.declared_by,
usedBy: v.used_by,
})),
);
filterDatasetsFromVariables(variableNames);
filterDataSourcesFromVariables(variableNames);
filterStorageFromVariables(variableNames);
return;
case "variable-values":
setMetadata([
...(msg.data.removed ?? []).map((v) => ({
name: v.name as VariableName,
dataType: undefined,
value: undefined,
})),
...msg.data.variables.map((v) => ({
name: v.name as VariableName,
dataType: v.datatype,
value: v.value,
})),
]);
return;
case "alert":
toast({
title: msg.data.title,
description: renderHTML({
html: msg.data.description,
}),
variant: msg.data.variant,
});
return;
case "banner":
addBanner(msg.data);
return;
case "missing-package-alert":
addMissingPackageAlert({
...msg.data,
kind: "missing",
});
return;
case "environment-operation":
if (
msg.data.source === "kernel" &&
msg.data.status.kind !== "running"
) {
invalidatePackageData();
}
updateEnvironment(msg.data);
return;
case "environment-state":
setEnvironment(msg.data);
if (msg.data.source === "kernel") {
invalidatePackageData();
}
return;
case "startup-logs":
addStartupLog({
content: msg.data.content,
status: msg.data.status,
});
return;
case "query-params-append":
queryParamHandlers.append(msg.data);
return;
case "query-params-set":
queryParamHandlers.set(msg.data);
return;
case "query-params-delete":
queryParamHandlers.delete(msg.data);
return;
case "query-params-clear":
queryParamHandlers.clear();
return;
case "datasets":
addDatasets(msg.data);
return;
case "data-column-preview":
addColumnPreview(msg.data);
return;
case "sql-table-preview":
PreviewSQLTable.resolve(msg.data.request_id, msg.data);
return;
case "sql-table-list-preview":
PreviewSQLTableList.resolve(msg.data.request_id, msg.data);
return;
case "sql-schema-list-preview":
PreviewSQLSchemaList.resolve(msg.data.request_id, msg.data);
return;
case "validate-sql-result":
ValidateSQL.resolve(msg.data.request_id as RequestId, msg.data);
return;
case "data-source-discovery-result":
DiscoverDataSources.resolve(msg.data.request_id as RequestId, msg.data);
return;
case "secret-keys-result":
SECRETS_REGISTRY.resolve(msg.data.request_id, msg.data);
return;
case "cache-info":
setCacheInfo(msg.data);
return;
case "cache-cleared":
// Cache cleared, could refresh cache info if needed
return;
case "data-source-connections":
addDataSourceConnection({
connections: msg.data.connections.map((conn) => ({
...conn,
name: conn.name as ConnectionName,
})),
});
return;
case "storage-namespaces":
setStorageNamespaces(msg.data);
return;
case "storage-entries":
ListStorageEntries.resolve(msg.data.request_id as RequestId, msg.data);
return;
case "storage-download-ready":
DownloadStorage.resolve(msg.data.request_id as RequestId, msg.data);
return;
case "reconnected":
setKernelStartupError(null);
setConnection({ state: ConnectionState.OPEN });
return;
case "focus-cell":
focusAndScrollCellOutputIntoView(msg.data.cell_id);
return;
case "active-line":
setActiveLine(
msg.data.line == null
? null
: { cellId: msg.data.cell_id, line: msg.data.line },
);
return;
case "notebook-document-transaction":
// Edits reach the notebook through the host document.
return;
case "consumer-capabilities":
setKioskMode(!msg.data.consumer_capabilities.edit);
return;
default:
logNever(msg.data);
}
};
const onMessageError = (error: unknown) => {
toast({
title: "Failed to handle message",
description: prettyError(error),
variant: "danger",
});
};
const replica = useNotebookReplica({
static: isStaticNotebook(),
snapshot: useAtomValue(embeddedSnapshotAtom),
transportType,
url: () =>
transportType === "sse"
? runtimeManager.getSseURL(sessionId).toString()
: runtimeManager.getWsURL(sessionId).toString(),
// SSE uses headers for auth. WebSockets carry the token in the URL.
headers: () => runtimeManager.headers(),
notebookUrl: (notebookId) => runtimeManager.getNotebookURL(notebookId),
// Only the host's transports read the URL, so static and WASM never wait.
waitUntilReady: async () => {
if (!runtimeManager.isSameOrigin) {
await runtimeManager.waitForHealthy();
}
},
checkHealth: () => runtimeManager.reconcileFromHealth(),
onNotification: (notification) => {
try {
handleNotification(notification);
} catch (error) {
Logger.error("Failed to handle notification", notification, error);
onMessageError(error);
}
},
});
const documentModel = useMemo(
() =>
createDocumentModel({
store,
documentAtom: replica.documentAtom,
backendAtom: replica.backendAtom,
}),
[store, replica],
);
// Edits outlive reconnects and end with the session. The notebook's cells
// follow the document for as long as the session is mounted.
useEffect(() => {
const controller = new AbortController();
documentModel.start({ signal: controller.signal });
store.set(activeDocumentModelAtom, documentModel);
followDocument({
store,
model: documentModel,
reconcile: reconcileDocument,
signal: controller.signal,
});
return () => {
controller.abort();
if (store.get(activeDocumentModelAtom) === documentModel) {
store.set(activeDocumentModelAtom, null);
}
};
}, [documentModel, store, reconcileDocument]);
// Subscribe before passive connection setup: static/WASM transports can emit synchronously.
useLayoutEffect(() => {
const updateConnection = () => {
const status = store.get(replica.connectionAtom);
if (status.state === ConnectionState.NOT_STARTED) {
return;
}
if (status.state === ConnectionState.OPEN) {
updateStartupProgress(null);
return; // kernel-ready, not the socket, establishes session readiness.
}
if (status.state === ConnectionState.CONNECTING) {
setKernelStartupError(null);
}
setConnection((previous) => {
if (
status.state === ConnectionState.CLOSED &&
status.code === WebSocketClosedReason.KERNEL_STARTUP_ERROR &&
(previous.state === ConnectionState.CONNECTING ||
previous.state === ConnectionState.CLOSED)
) {
return { ...status, phase: previous.phase };
}
if (
status.state === ConnectionState.CONNECTING &&
(previous.state === ConnectionState.OPEN ||
(previous.state === ConnectionState.CONNECTING &&
previous.phase === "reconnecting"))
) {
return { ...status, phase: "reconnecting" };
}
return status;
});
};
const unsubscribe = store.sub(replica.connectionAtom, updateConnection);
updateConnection();
return unsubscribe;
}, [
replica,
store,
setConnection,
setKernelStartupError,
updateStartupProgress,
]);
return { replica, documentModel, connection, reconnect: replica.reconnect };
}