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.

Keep sandbox setup separate from installed packages (#10944)

Trevor Manz74792388835b
diff --git a/frontend/src/components/editor/alerts/__tests__/connection-notice.test.tsx b/frontend/src/components/editor/alerts/__tests__/connection-notice.test.tsx
new file mode 100644
index 0000000000..4a74ac817e
--- /dev/null
+++ b/frontend/src/components/editor/alerts/__tests__/connection-notice.test.tsx
@@ -0,0 +1,186 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, fireEvent, render, screen, within } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { MockNotebook } from "@/__mocks__/notebook";
+import type { EnvironmentOperation } from "@/core/alerts/environment";
+import { alertAtom, getPackageAlert } from "@/core/alerts/state";
+import { notebookAtom } from "@/core/cells/cells";
+import { CellId } from "@/core/cells/ids";
+import { AppConfigSchema } from "@/core/config/config-schema";
+import { connectionAtom } from "@/core/network/connection";
+import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";
+import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";
+import { chromeAtom } from "../../chrome/state";
+import { ConnectionNotice } from "../connection-notice";
+
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => vi.useRealTimers());
+
+function mount(existingCells = false) {
+ const store = createStore();
+ store.set(sandboxAtom, {
+ backend: "pixi",
+ manifest: "",
+ filename: "notebook.py",
+ });
+ store.set(connectionAtom, {
+ state: WebSocketState.CONNECTING,
+ phase: "preparing-environment",
+ });
+ if (existingCells) {
+ store.set(
+ notebookAtom,
+ MockNotebook.notebookState({
+ cellData: { [CellId.create()]: { code: "1 + 1" } },
+ }),
+ );
+ }
+ render(
+ <Provider store={store}>
+ <ConnectionNotice
+ appConfig={AppConfigSchema.parse({})}
+ onRetry={vi.fn()}
+ />
+ </Provider>,
+ );
+ return store;
+}
+
+it("shows both stages in an empty notebook, checks them off, then dismisses Ready", () => {
+ const store = mount();
+ act(() => vi.advanceTimersByTime(500));
+ const steps = within(
+ screen.getByRole("list", { name: "Notebook startup stages" }),
+ );
+ expect(steps.getByText("Preparing environment")).toBeInTheDocument();
+ expect(steps.getByText("Start kernel")).toBeInTheDocument();
+ act(() =>
+ store.set(connectionAtom, {
+ state: WebSocketState.CONNECTING,
+ phase: "starting-kernel",
+ }),
+ );
+ expect(steps.getByText("Environment prepared")).toBeInTheDocument();
+ expect(steps.getByText("Starting kernel")).toBeInTheDocument();
+ act(() => store.set(connectionAtom, { state: WebSocketState.OPEN }));
+ expect(
+ screen.getByRole("heading", { name: "Your notebook is ready" }),
+ ).toBeInTheDocument();
+ expect(steps.getByText("Kernel started")).toBeInTheDocument();
+ act(() => vi.advanceTimersByTime(1000));
+ expect(screen.getByRole("status")).toHaveTextContent(
+ "Your notebook is ready",
+ );
+ act(() => vi.advanceTimersByTime(1000));
+ expect(
+ screen.queryByRole("region", { name: "Notebook startup" }),
+ ).not.toBeInTheDocument();
+});
+
+it("opens Packages from the minimal inline status when cells exist", () => {
+ const store = mount(true);
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.queryByRole("list")).not.toBeInTheDocument();
+ fireEvent.click(screen.getByRole("button", { name: /Open Packages/ }));
+ expect(store.get(chromeAtom)).toMatchObject({
+ isSidebarOpen: true,
+ selectedPanel: "packages",
+ });
+ act(() => store.set(connectionAtom, { state: WebSocketState.OPEN }));
+ expect(screen.getByRole("status")).toHaveTextContent(/^Ready$/);
+});
+
+it("does not flash Ready for a startup that finished before the notice appeared", () => {
+ const store = mount(true);
+ act(() => vi.advanceTimersByTime(200));
+ act(() => store.set(connectionAtom, { state: WebSocketState.OPEN }));
+ expect(screen.queryByRole("status")).not.toBeInTheDocument();
+ act(() => vi.advanceTimersByTime(2000));
+ expect(screen.queryByRole("status")).not.toBeInTheDocument();
+});
+
+it("replaces Ready with a new attempt and never dismisses a failure", () => {
+ const store = mount();
+ act(() => vi.advanceTimersByTime(500));
+ act(() => store.set(connectionAtom, { state: WebSocketState.OPEN }));
+ act(() => vi.advanceTimersByTime(1000));
+ act(() =>
+ store.set(connectionAtom, {
+ state: WebSocketState.CONNECTING,
+ phase: "starting-kernel",
+ }),
+ );
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.getByText("Starting kernel")).toBeInTheDocument();
+ act(() =>
+ store.set(connectionAtom, {
+ state: WebSocketState.CLOSED,
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ phase: "starting-kernel",
+ reason: "Kernel startup failed",
+ }),
+ );
+ act(() => vi.advanceTimersByTime(10_000));
+ expect(screen.getByRole("status")).toHaveTextContent(
+ "Kernel failed to start",
+ );
+});
+
+it("shows a sync as a single operation, without pretending to restart the kernel", () => {
+ const store = mount(true);
+ act(() => {
+ store.set(connectionAtom, { state: WebSocketState.OPEN });
+ store.set(sandboxSyncAtom, { kind: "running" });
+ });
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.getByRole("status")).toHaveTextContent("Syncing sandbox");
+ expect(screen.queryByRole("list")).not.toBeInTheDocument();
+ act(() => store.set(sandboxSyncAtom, { kind: "succeeded" }));
+ expect(screen.getByRole("status")).toHaveTextContent("Environment synced");
+});
+
+it("restores syncing in the existing status and stays quiet for a completed snapshot", () => {
+ const store = mount(true);
+ const operation: EnvironmentOperation = {
+ operation_id: "sync",
+ action: "sync",
+ source: "kernel",
+ status: { kind: "succeeded" },
+ packages: {},
+ logs: { environment: "Sync complete\n" },
+ };
+ const restore = (status: EnvironmentOperation["status"]) =>
+ store.set(alertAtom, (value) => ({
+ ...value,
+ environments: {
+ ...value.environments,
+ kernel: {
+ restart_required: false,
+ operations: [{ ...operation, status }],
+ },
+ },
+ }));
+ act(() => {
+ store.set(connectionAtom, { state: WebSocketState.OPEN });
+ restore({ kind: "succeeded" });
+ });
+ act(() => vi.advanceTimersByTime(2000));
+ expect(screen.queryByRole("status")).not.toBeInTheDocument();
+
+ act(() => restore({ kind: "running" }));
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.getByRole("status")).toHaveTextContent("Syncing sandbox");
+ expect(getPackageAlert(store.get(alertAtom))).toBeNull();
+ for (const [status, title] of [
+ [{ kind: "failed", error: "Dependency conflict" }, "Sandbox sync failed"],
+ [
+ { kind: "restart-required", reason: "Restart the kernel" },
+ "Sandbox restart required",
+ ],
+ [{ kind: "cancelled" }, "Sandbox sync failed"],
+ ] as const) {
+ act(() => restore(status));
+ expect(screen.getByRole("status")).toHaveTextContent(title);
+ }
+});
diff --git a/frontend/src/components/editor/alerts/__tests__/startup-progress.test.tsx b/frontend/src/components/editor/alerts/__tests__/startup-progress.test.tsx
new file mode 100644
index 0000000000..e6ae0181f9
--- /dev/null
+++ b/frontend/src/components/editor/alerts/__tests__/startup-progress.test.tsx
@@ -0,0 +1,185 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { expect, it } from "vitest";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import type { EnvironmentOperation } from "@/core/alerts/environment";
+import { alertAtom } from "@/core/alerts/state";
+import { startupProgressAtom } from "@/core/network/connection";
+import type { DisplayConnectionNotice } from "@/core/network/useConnectionNotice";
+import { StartupOutput } from "../startup-output";
+import { StartupProgress } from "../startup-progress";
+
+const notice: DisplayConnectionNotice = {
+ kind: "startup",
+ phase: "starting-kernel",
+ sandbox: true,
+ title: "Starting kernel",
+ description: "Connecting to this notebook.",
+ pending: true,
+ ready: false,
+ error: null,
+};
+
+const preparation: EnvironmentOperation = {
+ operation_id: "prepare-1",
+ action: "prepare",
+ source: "kernel",
+ status: { kind: "succeeded" },
+ packages: {},
+ logs: {
+ environment:
+ "Using Python\nResolving dependencies\nDownloading numpy\nInstalled 24 packages\n",
+ },
+};
+
+function restorePreparation(
+ store: ReturnType<typeof createStore>,
+ operation: EnvironmentOperation,
+) {
+ store.set(alertAtom, (state) => ({
+ ...state,
+ environments: {
+ ...state.environments,
+ kernel: { restart_required: false, operations: [operation] },
+ },
+ }));
+}
+
+it("restores separate compact previews and keeps expanded output open through snapshots and live updates", () => {
+ const store = createStore();
+ restorePreparation(store, preparation);
+ store.set(startupProgressAtom, {
+ phase: "starting-kernel",
+ logs: "Using Python\nLoading runtime\nLaunching kernel\nConnecting\n",
+ log_mode: "replace",
+ });
+ render(
+ <Provider store={store}>
+ <StartupProgress notice={notice} surface="sidebar" />
+ </Provider>,
+ { wrapper: TooltipProvider },
+ );
+ const prepareButton = screen.getByRole("button", {
+ name: "Expand environment preparation output",
+ });
+ expect(prepareButton).toHaveTextContent("Installed 24 packages");
+ expect(prepareButton).toHaveTextContent("Resolving dependencies");
+ expect(prepareButton).toHaveTextContent("Downloading numpy");
+ expect(prepareButton).not.toHaveTextContent("Using Python");
+ const kernelButton = screen.getByRole("button", {
+ name: "Expand kernel startup output",
+ });
+ expect(kernelButton).toHaveAttribute("aria-expanded", "false");
+ expect(kernelButton).toHaveTextContent(
+ "Loading runtimeLaunching kernelConnecting",
+ );
+ expect(kernelButton).not.toHaveTextContent("Using Python");
+
+ fireEvent.click(prepareButton);
+ const prepareOutput = screen.getByLabelText("environment preparation output");
+ expect(prepareOutput).toBeVisible();
+ expect(prepareOutput.textContent).toBe(preparation.logs.environment);
+ act(() => restorePreparation(store, { ...preparation }));
+ expect(prepareOutput).toBeVisible();
+
+ fireEvent.click(kernelButton);
+ act(() =>
+ store.set(startupProgressAtom, {
+ phase: "starting-kernel",
+ logs: "Kernel connected\n",
+ log_mode: "append",
+ }),
+ );
+ const output = screen.getByLabelText("kernel startup output");
+ expect(output).toBeVisible();
+ expect(output.textContent).toBe(
+ "Using Python\nLoading runtime\nLaunching kernel\nConnecting\nKernel connected\n",
+ );
+ expect(prepareOutput.textContent).toBe(preparation.logs.environment);
+});
+
+it("starts a new preparation compact and offers no disclosure before output arrives", () => {
+ const store = createStore();
+ const { rerender } = render(
+ <Provider store={store}>
+ <StartupProgress
+ notice={{ ...notice, phase: "preparing-environment" }}
+ surface="sidebar"
+ />
+ </Provider>,
+ { wrapper: TooltipProvider },
+ );
+ expect(screen.queryByRole("button")).not.toBeInTheDocument();
+ act(() => restorePreparation(store, preparation));
+ fireEvent.click(screen.getByRole("button", { name: /Expand environment/ }));
+ act(() =>
+ restorePreparation(store, {
+ ...preparation,
+ operation_id: "prepare-2",
+ status: { kind: "running" },
+ logs: { environment: "Trying again\n" },
+ }),
+ );
+ expect(
+ screen.getByRole("button", { name: /Expand environment/ }),
+ ).toHaveTextContent("Trying again");
+ expect(
+ screen.getByLabelText("environment preparation output"),
+ ).not.toBeVisible();
+
+ rerender(
+ <Provider store={store}>
+ <StartupProgress notice={notice} surface="notebook" />
+ </Provider>,
+ );
+ expect(screen.queryByRole("button")).not.toBeInTheDocument();
+});
+
+it("preserves reading position and selected text while output streams, then resumes following", () => {
+ const logs = "Resolving dependencies\nDownloading numpy\n";
+ const { rerender } = render(
+ <StartupOutput logs={logs} label="preparation output" />,
+ { wrapper: TooltipProvider },
+ );
+ fireEvent.click(
+ screen.getByRole("button", { name: "Expand preparation output" }),
+ );
+ const output = screen.getByLabelText("preparation output");
+ Object.defineProperties(output, {
+ scrollHeight: { value: 1000 },
+ clientHeight: { value: 200 },
+ });
+ fireEvent.scroll(output, { target: { scrollTop: 100 } });
+ expect(screen.getByRole("button", { name: "Jump to latest" })).toBeVisible();
+
+ const selection = document.getSelection();
+ const range = document.createRange();
+ range.selectNodeContents(output);
+ act(() => {
+ selection?.removeAllRanges();
+ selection?.addRange(range);
+ document.dispatchEvent(new Event("selectionchange"));
+ });
+ rerender(
+ <StartupOutput
+ logs={`${logs}Downloaded numpy\n`}
+ label="preparation output"
+ />,
+ );
+ expect(selection?.toString()).toBe(logs);
+ expect(output.scrollTop).toBe(100);
+ expect(output.textContent).toBe(`${logs}Downloaded numpy\n`);
+
+ fireEvent.click(screen.getByRole("button", { name: "Jump to latest" }));
+ expect(selection?.isCollapsed).toBe(true);
+ expect(output.scrollTop).toBeGreaterThan(100);
+ expect(
+ screen.queryByRole("button", { name: "Jump to latest" }),
+ ).not.toBeInTheDocument();
+
+ fireEvent.click(
+ screen.getByRole("button", { name: "Collapse preparation output" }),
+ );
+ expect(output).not.toBeVisible();
+});
diff --git a/frontend/src/components/editor/alerts/connection-notice.tsx b/frontend/src/components/editor/alerts/connection-notice.tsx
index 32da3e1fcf..2fe0356037 100644
--- a/frontend/src/components/editor/alerts/connection-notice.tsx
+++ b/frontend/src/components/editor/alerts/connection-notice.tsx
@@ -1,20 +1,20 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { useAtomValue } from "jotai";
-import { AlertCircleIcon, ArrowRightIcon } from "lucide-react";
+import { ArrowRightIcon, ChevronRightIcon } from "lucide-react";
import { useState } from "react";
-import { Spinner } from "@/components/icons/spinner";
import { Button } from "@/components/ui/button";
import { hasCellsAtom } from "@/core/cells/cells";
import type { AppConfig } from "@/core/config/config-schema";
import { connectionAtom } from "@/core/network/connection";
-import { connectionNoticeAtom } from "@/core/network/connection-notice";
+import { useConnectionNotice } from "@/core/network/useConnectionNotice";
+import { sandboxAtom } from "@/core/packages/sandbox-state";
import { WebSocketState } from "@/core/websocket/types";
-import { useDelayElapsed } from "@/hooks/useDelayElapsed";
import { useInterval } from "@/hooks/useInterval";
import { cn } from "@/utils/cn";
import { SandboxErrorOutput } from "../chrome/panels/sandbox-panel";
import { chromeAtom, useChromeActions } from "../chrome/state";
import { VerticalLayoutWrapper } from "../renderers/vertical-layout/vertical-layout-wrapper";
+import { ConnectionStatusIcon, StartupProgress } from "./startup-progress";
export const ConnectionNotice = ({
appConfig,
@@ -23,28 +23,61 @@ export const ConnectionNotice = ({
appConfig: AppConfig;
onRetry: () => void;
}) => {
- const notice = useAtomValue(connectionNoticeAtom);
+ const notice = useConnectionNotice();
const connection = useAtomValue(connectionAtom);
const hasCells = useAtomValue(hasCellsAtom);
+ const sandbox = useAtomValue(sandboxAtom);
const chrome = useAtomValue(chromeAtom);
const packagesOpen =
(chrome.isSidebarOpen && chrome.selectedPanel === "packages") ||
(chrome.isDeveloperPanelOpen &&
chrome.selectedDeveloperPanelTab === "packages");
- const elapsed = useDelayElapsed(notice?.pending ? 500 : 0);
const { openApplication } = useChromeActions();
// Reconnection uses the footer indicator while existing cells stay visible.
- if (
- !notice ||
- !elapsed ||
- (hasCells &&
- connection.state === WebSocketState.CONNECTING &&
- connection.phase === "reconnecting")
- ) {
+ const reconnecting =
+ connection.state === WebSocketState.CONNECTING &&
+ connection.phase === "reconnecting";
+
+ if (sandbox?.backend && hasCells) {
+ const title =
+ notice?.ready && notice.kind === "startup" ? "Ready" : notice?.title;
+ return (
+ <VerticalLayoutWrapper
+ appConfig={appConfig}
+ // Reserve the status row and gutter so completion never shifts cells.
+ className="shrink-0 h-12 pb-0 sm:pb-0 print:hidden"
+ innerClassName="pb-0 sm:pb-0 pr-4"
+ >
+ {notice && !reconnecting && (
+ <section aria-label="Notebook startup">
+ <button
+ type="button"
+ onClick={() => openApplication("packages")}
+ aria-label={`${title} Open Packages`}
+ aria-expanded={packagesOpen}
+ className="flex h-6 items-center gap-2 whitespace-nowrap text-xs text-muted-foreground hover:text-foreground rounded focus-visible:outline-2 focus-visible:outline-ring"
+ >
+ <ConnectionStatusIcon notice={notice} />
+ <output>{title}</output>
+ <ChevronRightIcon className="size-3" aria-hidden={true} />
+ </button>
+ </section>
+ )}
+ </VerticalLayoutWrapper>
+ );
+ }
+
+ if (!notice || (hasCells && reconnecting)) {
return null;
}
+ const showSteps =
+ notice.sandbox &&
+ notice.kind === "startup" &&
+ (notice.ready ||
+ notice.phase === "preparing-environment" ||
+ notice.phase === "starting-kernel");
return (
<VerticalLayoutWrapper
appConfig={appConfig}
@@ -57,60 +90,73 @@ export const ConnectionNotice = ({
"text-muted-foreground",
hasCells
? "mt-4 mb-8 border rounded-lg px-5 py-5"
- : "max-w-sm mx-auto mt-16 sm:mt-24 px-4",
+ : "max-w-md mx-auto mt-16 sm:mt-24 px-4",
hasCells && !notice.pending && "border-(--red-7)",
)}
>
- <div role="status" className="flex items-center gap-2.5">
- {notice.pending ? (
- <Spinner className="size-4 shrink-0" aria-hidden={true} />
- ) : (
- <AlertCircleIcon
- className="size-4 shrink-0 text-(--red-11)"
- aria-hidden={true}
- />
+ {showSteps ? (
+ <StartupProgress notice={notice} surface="notebook" />
+ ) : (
+ <div role="status" className="flex items-center gap-2.5">
+ <ConnectionStatusIcon notice={notice} />
+ <h2
+ className={cn(
+ "text-base",
+ notice.pending || notice.ready
+ ? "font-normal text-foreground"
+ : "font-medium text-(--red-11)",
+ )}
+ >
+ {notice.title}
+ </h2>
+ </div>
+ )}
+ <div className={showSteps ? "mt-8" : "ml-6.5"}>
+ {!showSteps && (
+ <p
+ className={cn(
+ "mt-3 text-sm leading-7",
+ !notice.pending && "text-foreground",
+ )}
+ >
+ {notice.description}
+ </p>
)}
- <h2
- className={cn(
- "text-base",
- notice.pending
- ? "font-normal text-foreground"
- : "font-medium text-(--red-11)",
- )}
- >
- {notice.title}
- </h2>
- </div>
- <div className="ml-6.5">
- <p
- className={cn(
- "mt-3 text-sm leading-7",
- !notice.pending && "text-foreground",
- )}
- >
- {notice.description}
- </p>
{!notice.sandbox && notice.error && (
<SandboxErrorOutput error={notice.error} />
)}
- <div className="mt-5 flex flex-wrap items-center gap-x-6 gap-y-3">
- {!packagesOpen && (notice.sandbox || notice.pending) && (
- <Button
- variant="text"
- size="xs"
- className="h-auto p-0 text-xs gap-1.5"
- onClick={() => openApplication("packages")}
- >
- {notice.pending ? "View setup details" : "Open Packages"}
- <ArrowRightIcon className="size-3" aria-hidden={true} />
- </Button>
+ <div
+ className={cn(
+ "flex flex-wrap items-center gap-x-6 gap-y-3",
+ showSteps ? "border-t border-border/60 pt-4" : "mt-5",
)}
+ >
+ {!notice.ready &&
+ !packagesOpen &&
+ (notice.sandbox || notice.pending) && (
+ <Button
+ variant="text"
+ size="xs"
+ className={cn(
+ "p-0 text-xs gap-1.5",
+ showSteps ? "h-6" : "h-auto",
+ )}
+ onClick={() => openApplication("packages")}
+ >
+ {notice.pending ? "View setup details" : "Open Packages"}
+ <ArrowRightIcon className="size-3" aria-hidden={true} />
+ </Button>
+ )}
{!notice.pending && !notice.sandbox && (
<Button variant="outline" size="xs" onClick={onRetry}>
Try again
</Button>
)}
- {notice.pending && <StartupElapsedTime />}
+ {notice.pending && (
+ <div className={showSteps ? "ml-auto" : undefined}>
+ <StartupElapsedTime />
+ </div>
+ )}
</div>
</div>
</section>
diff --git a/frontend/src/components/editor/alerts/startup-output.tsx b/frontend/src/components/editor/alerts/startup-output.tsx
new file mode 100644
index 0000000000..d83c861521
--- /dev/null
+++ b/frontend/src/components/editor/alerts/startup-output.tsx
@@ -0,0 +1,173 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { ArrowDownIcon, ChevronUpIcon } from "lucide-react";
+import { useId, useLayoutEffect, useRef, useState } from "react";
+import { CopyClipboardIcon } from "@/components/icons/copy-icon";
+import { useEventListener } from "@/hooks/useEventListener";
+import { cn } from "@/utils/cn";
+
+function hasSelection(element: HTMLElement) {
+ const selection = element.ownerDocument.getSelection();
+ return (
+ selection && !selection.isCollapsed && selection.containsNode(element, true)
+ );
+}
+
+export type StartupOutputState = "running" | "succeeded" | "failed";
+
+export function StartupOutput({
+ logs,
+ label,
+ state = "running",
+}: {
+ logs: string;
+ label: string;
+ /** Running keeps the newest line bright; failed keeps all of it bright. */
+ state?: StartupOutputState;
+}) {
+ const [expanded, setExpanded] = useState(false);
+ const [following, setFollowing] = useState(true);
+ const outputRef = useRef<HTMLPreElement>(null);
+ const toggleRef = useRef<HTMLButtonElement>(null);
+ const outputId = useId();
+ const lines = logs.trimEnd().split(/\r?\n/);
+ const emphasis =
+ state === "failed"
+ ? "text-foreground"
+ : state === "running"
+ ? "last:text-foreground"
+ : undefined;
+
+ useEventListener(outputRef, "keydown", (event) => {
+ if (event.key === "Escape") {
+ event.preventDefault();
+ setExpanded(false);
+ toggleRef.current?.focus();
+ }
+ });
+
+ useEventListener(document, "selectionchange", () => {
+ if (outputRef.current && hasSelection(outputRef.current)) {
+ setFollowing(false);
+ }
+ });
+
+ useLayoutEffect(() => {
+ const output = outputRef.current;
+ if (!output) {
+ return;
+ }
+ const previous = output.textContent ?? "";
+ // Append without replacing selected text nodes as more output arrives.
+ if (logs.startsWith(previous)) {
+ if (logs.length > previous.length) {
+ output.append(document.createTextNode(logs.slice(previous.length)));
+ }
+ } else {
+ output.textContent = logs;
+ }
+ if (expanded && following && !hasSelection(output)) {
+ output.scrollTop = output.scrollHeight;
+ }
+ }, [logs, expanded, following]);
+
+ if (!logs.trim()) {
+ return null;
+ }
+
+ return (
+ <div
+ className={cn(
+ "relative mt-2.5 min-w-0 contain-inline-size rounded text-muted-foreground",
+ // One surface: it washes on hover and the wash stays while open.
+ expanded ? "bg-muted/40" : "hover:bg-muted/40",
+ )}
+ >
+ <div className={cn(expanded && "flex items-center pr-1")}>
+ <button
+ ref={toggleRef}
+ type="button"
+ aria-label={`${expanded ? "Collapse" : "Expand"} ${label}`}
+ aria-expanded={expanded}
+ aria-controls={outputId}
+ title={expanded ? "Collapse output" : "Expand output"}
+ className={cn(
+ "flex w-full min-w-0 rounded px-2.5 py-1 text-left focus-visible:outline-2 focus-visible:outline-ring",
+ expanded &&
+ "items-center justify-between gap-2 text-xs hover:text-foreground",
+ )}
+ onClick={() => {
+ setExpanded(!expanded);
+ setFollowing(true);
+ }}
+ >
+ {expanded ? (
+ <>
+ <span className="leading-5">Logs</span>
+ <ChevronUpIcon className="size-3.5 shrink-0" aria-hidden={true} />
+ </>
+ ) : (
+ <span
+ className={cn(
+ "min-w-0 flex-1 font-mono text-[11px] leading-5",
+ // Fade the top of the tail so it reads as a stream, not as
+ // greyed-out prose.
+ lines.length > 1 &&
+ "[mask-image:linear-gradient(to_bottom,transparent,#000_70%)]",
+ )}
+ aria-hidden={true}
+ >
+ {lines.slice(-3).map((line, index) => (
+ <span key={index} className={cn("block truncate", emphasis)}>
+ {line || "\u00A0"}
+ </span>
+ ))}
+ </span>
+ )}
+ </button>
+ {expanded && (
+ <CopyClipboardIcon
+ value={logs}
+ ariaLabel={`Copy ${label}`}
+ tooltip="Copy output"
+ className="size-3.5"
+ buttonClassName="size-6 shrink-0 flex items-center justify-center rounded hover:bg-accent focus-visible:outline-2 focus-visible:outline-ring"
+ />
+ )}
+ </div>
+ <pre
+ id={outputId}
+ ref={outputRef}
+ hidden={!expanded}
+ tabIndex={0}
+ aria-label={label}
+ className="max-h-48 overflow-auto overscroll-contain whitespace-pre px-2.5 pb-2.5 font-mono text-[11px] leading-5 scrollbar-thin focus-visible:outline-2 focus-visible:outline-ring"
+ onScroll={(event) => {
+ const output = event.currentTarget;
+ setFollowing(
+ !hasSelection(output) &&
+ output.scrollHeight - output.scrollTop - output.clientHeight < 12,
+ );
+ }}
+ />
+ {expanded && !following && (
+ <button
+ type="button"
+ className="absolute bottom-2 left-1/2 -translate-x-1/2 flex items-center gap-1 whitespace-nowrap rounded-full border bg-background px-2 py-1 text-xs shadow-xs hover:text-foreground focus-visible:outline-2 focus-visible:outline-ring"
+ onClick={() => {
+ const output = outputRef.current;
+ if (output) {
+ if (hasSelection(output)) {
+ output.ownerDocument.getSelection()?.removeAllRanges();
+ }
+ output.focus({ preventScroll: true });
+ }
+ setFollowing(true);
+ }}
+ >
+ <ArrowDownIcon className="size-3" aria-hidden={true} />
+ Jump to latest
+ </button>
+ )}
+ </div>
+ );
+}
diff --git a/frontend/src/components/editor/alerts/startup-progress.tsx b/frontend/src/components/editor/alerts/startup-progress.tsx
new file mode 100644
index 0000000000..7683d42307
--- /dev/null
+++ b/frontend/src/components/editor/alerts/startup-progress.tsx
@@ -0,0 +1,204 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtomValue } from "jotai";
+import { AlertCircleIcon, CheckIcon, CircleIcon } from "lucide-react";
+import { Spinner } from "@/components/icons/spinner";
+import { preparationAtom } from "@/core/packages/sandbox-state";
+import { startupProgressAtom } from "@/core/network/connection";
+import type { DisplayConnectionNotice } from "@/core/network/useConnectionNotice";
+import { cn } from "@/utils/cn";
+import { StartupOutput, type StartupOutputState } from "./startup-output";
+
+const STEPS = [
+ {
+ phase: "preparing-environment",
+ titles: {
+ complete: "Environment prepared",
+ failed: "Environment setup failed",
+ pending: "Preparing environment",
+ waiting: "Prepare environment",
+ },
+ descriptions: {
+ complete: "Python and dependencies are available.",
+ failed: "Setup could not finish.",
+ pending: "Set up Python and dependencies.",
+ waiting: "Set up Python and dependencies.",
+ },
+ },
+ {
+ phase: "starting-kernel",
+ titles: {
+ complete: "Kernel started",
+ failed: "Kernel failed to start",
+ pending: "Starting kernel",
+ waiting: "Start kernel",
+ },
+ descriptions: {
+ complete: "The notebook is ready to run.",
+ failed: "The kernel could not connect.",
+ pending: "Connecting to this notebook.",
+ waiting: "After the environment is ready.",
+ },
+ },
+] as const;
+
+interface StartupProgressProps {
+ notice: DisplayConnectionNotice;
+ surface: "notebook" | "sidebar";
+}
+
+function StartupStepOutput({
+ phase,
+ state,
+}: {
+ phase: (typeof STEPS)[number]["phase"];
+ state: StartupOutputState;
+}) {
+ const preparation = useAtomValue(preparationAtom);
+ const progress = useAtomValue(startupProgressAtom);
+ const preparing = phase === "preparing-environment";
+ const logs = preparing
+ ? (preparation?.logs.environment ?? "")
+ : progress?.phase === phase
+ ? progress.logs
+ : "";
+
+ return (
+ <StartupOutput
+ key={preparation?.operation_id}
+ logs={logs}
+ state={state}
+ label={
+ preparing ? "environment preparation output" : "kernel startup output"
+ }
+ />
+ );
+}
+
+function StartupSummary({ notice }: { notice: DisplayConnectionNotice }) {
+ return (
+ <header>
+ <output className="sr-only">{notice.title}</output>
+ <h2 className="text-foreground font-heading text-2xl leading-8 tracking-tight font-normal">
+ {notice.ready
+ ? "Your notebook is ready"
+ : "Getting your notebook ready"}
+ </h2>
+ <p className="text-muted-foreground mt-3 text-sm leading-6">
+ {notice.ready
+ ? "Your environment and kernel are ready."
+ : notice.pending
+ ? "Preparing Python and dependencies for this notebook."
+ : "Review the setup details below to continue."}
+ </p>
+ </header>
+ );
+}
+
+export function ConnectionStatusIcon({
+ notice,
+}: {
+ notice: DisplayConnectionNotice;
+}) {
+ if (notice.ready) {
+ return (
+ <CheckIcon
+ className="size-4 shrink-0 text-(--grass-11)"
+ aria-hidden={true}
+ />
+ );
+ }
+ if (notice.pending) {
+ return (
+ <Spinner
+ className="size-4 shrink-0 motion-reduce:animate-none"
+ aria-hidden={true}
+ />
+ );
+ }
+ return (
+ <AlertCircleIcon
+ className="size-4 shrink-0 text-(--red-11)"
+ aria-hidden={true}
+ />
+ );
+}
+
+export function StartupProgress({ notice, surface }: StartupProgressProps) {
+ return (
+ <>
+ {surface === "notebook" && <StartupSummary notice={notice} />}
+ <ol
+ className={cn("space-y-6", surface === "notebook" && "mt-8")}
+ aria-label="Notebook startup stages"
+ >
+ {STEPS.map(({ phase, titles, descriptions }, index) => {
+ const complete =
+ notice.ready || (index === 0 && notice.phase === "starting-kernel");
+ const active = !notice.ready && notice.phase === phase;
+ const failed = active && !notice.pending;
+ const state = complete
+ ? "complete"
+ : failed
+ ? "failed"
+ : active
+ ? "pending"
+ : "waiting";
+ return (
+ <li
+ key={phase}
+ aria-current={active ? "step" : undefined}
+ className="relative flex items-start gap-3"
+ >
+ {index === 0 && (
+ <span
+ aria-hidden={true}
+ className="absolute left-2 top-6 -bottom-4 border-l border-border"
+ />
+ )}
+ <span
+ className={cn(
+ "mt-0.5",
+ complete ? "text-(--grass-11)" : "text-muted-foreground",
+ )}
+ >
+ {complete ? (
+ <CheckIcon className="size-4" aria-hidden={true} />
+ ) : active ? (
+ <ConnectionStatusIcon notice={notice} />
+ ) : (
+ <CircleIcon
+ className="size-4 text-muted-foreground/50"
+ aria-hidden={true}
+ />
+ )}
+ </span>
+ <div className="min-w-0 flex-1">
+ <div
+ className={cn(
+ "text-sm",
+ failed
+ ? "text-(--red-11)"
+ : complete || active
+ ? "text-foreground"
+ : "text-muted-foreground",
+ )}
+ >
+ {titles[state]}
+ </div>
+ <p className="mt-1 text-xs text-muted-foreground">
+ {descriptions[state]}
+ </p>
+ {surface === "sidebar" && (
+ <StartupStepOutput
+ phase={phase}
+ state={failed ? "failed" : active ? "running" : "succeeded"}
+ />
+ )}
+ </div>
+ </li>
+ );
+ })}
+ </ol>
+ </>
+ );
+}
diff --git a/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx
index a258d8d1b7..a1a853009e 100644
--- a/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx
+++ b/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx
@@ -12,6 +12,7 @@ import { Provider } from "jotai";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { MockRequestClient } from "@/__mocks__/requests";
import { TooltipProvider } from "@/components/ui/tooltip";
+import { connectionAtom } from "@/core/network/connection";
import { requestClientAtom } from "@/core/network/requests";
import type {
DependencyTreeNode,
@@ -21,7 +22,10 @@ import { withPackageInvalidation } from "@/core/packages/package-data";
import { useInstallPackages } from "@/core/packages/useInstallPackage";
import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";
import { store } from "@/core/state/jotai";
+import { WebSocketState } from "@/core/websocket/types";
import PackagesPanel from "../packages-panel";
+import { PanelSectionProvider } from "../panel-context";
+import { SandboxToggle } from "../sandbox-toggle";
const { openSettings } = vi.hoisted(() => ({
openSettings: vi.fn(),
@@ -67,7 +71,8 @@ function renderPanel(
? { backend: context.backend, manifest: "", filename: "notebook.py" }
: null,
);
- store.set(sandboxSyncAtom, { pending: false, error: null });
+ store.set(connectionAtom, { state: WebSocketState.OPEN });
+ store.set(sandboxSyncAtom, { kind: "succeeded" });
const getPackageList = vi.fn().mockResolvedValue({ packages: [] });
const client = MockRequestClient.create({
getPackageList,
@@ -81,7 +86,10 @@ function renderPanel(
...render(
<Provider store={store}>
<TooltipProvider>
- <PackagesPanel />
+ <PanelSectionProvider value="sidebar">
+ <SandboxToggle section="sidebar" />
+ <PackagesPanel />
+ </PanelSectionProvider>
</TooltipProvider>
</Provider>,
),
@@ -178,7 +186,8 @@ it("refreshes an open panel when a package is installed elsewhere, after install
manifest: "",
filename: "notebook.py",
});
- store.set(sandboxSyncAtom, { pending: false, error: null });
+ store.set(connectionAtom, { state: WebSocketState.OPEN });
+ store.set(sandboxSyncAtom, { kind: "succeeded" });
store.set(requestClientAtom, withPackageInvalidation(client));
function InstallElsewhere() {
const { handleInstallPackages } = useInstallPackages();
@@ -191,7 +200,10 @@ it("refreshes an open panel when a package is installed elsewhere, after install
render(
<Provider store={store}>
<TooltipProvider>
- <PackagesPanel />
+ <PanelSectionProvider value="sidebar">
+ <SandboxToggle section="sidebar" />
+ <PackagesPanel />
+ </PanelSectionProvider>
<InstallElsewhere />
</TooltipProvider>
</Provider>,
@@ -208,6 +220,43 @@ it("refreshes an open panel when a package is installed elsewhere, after install
expect(await screen.findByText("polars")).toBeInTheDocument();
});
+it("keeps packages and the install draft visible while blocking mutations during sync", async () => {
+ store.set(connectionAtom, { state: WebSocketState.OPEN });
+ renderPanel({ kind: "sandbox", backend: "pixi" }, populatedTree);
+ await screen.findByRole("treeitem", { name: /polars/ });
+ const input = screen.getByPlaceholderText("Add packages to pixi sandbox...");
+ fireEvent.change(input, { target: { value: "altair" } });
+ act(() => store.set(sandboxSyncAtom, { kind: "running" }));
+ const row = screen.getByRole("treeitem", { name: /polars/ });
+ expect(
+ screen.getByPlaceholderText("Add packages to pixi sandbox..."),
+ ).toBeDisabled();
+ expect(within(row).getByRole("button", { name: "Remove" })).toBeDisabled();
+ expect(
+ screen.queryByRole("list", { name: "Notebook startup stages" }),
+ ).not.toBeInTheDocument();
+ const toggle = screen.getByRole("button", { name: "pixi sandbox" });
+ fireEvent.click(toggle);
+ expect(toggle).toHaveAttribute("aria-expanded", "false");
+ act(() =>
+ store.set(sandboxSyncAtom, {
+ kind: "failed",
+ error: "Could not resolve dependencies",
+ }),
+ );
+ expect(screen.getByRole("treeitem", { name: /polars/ })).toBeInTheDocument();
+ expect(screen.getByLabelText("Error details")).toHaveTextContent(
+ "Could not resolve dependencies",
+ );
+ expect(toggle).toHaveAttribute("aria-expanded", "true");
+ expect(screen.getByRole("button", { name: "Retry sync" })).toBeVisible();
+ const restoredInput = screen.getByPlaceholderText(
+ "Add packages to pixi sandbox...",
+ );
+ expect(restoredInput).toHaveValue("altair");
+ expect(restoredInput).toBeEnabled();
+});
+
it.each(["uv", "pixi", "list"] as const)(
"allows upgrading marimo but not removing it in the %s view",
async (view) => {
diff --git a/frontend/src/components/editor/chrome/panels/__tests__/sandbox-details.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/sandbox-details.test.tsx
new file mode 100644
index 0000000000..86b6ae1ae8
--- /dev/null
+++ b/frontend/src/components/editor/chrome/panels/__tests__/sandbox-details.test.tsx
@@ -0,0 +1,358 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, fireEvent, render, screen, within } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { expect, it, vi } from "vitest";
+import { MockRequestClient } from "@/__mocks__/requests";
+import { ModalProvider } from "@/components/modal/ImperativeModal";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { alertAtom } from "@/core/alerts/state";
+import type { EnvironmentOperation } from "@/core/alerts/environment";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import { connectionAtom, startupProgressAtom } from "@/core/network/connection";
+import { requestClientAtom } from "@/core/network/requests";
+import { sandboxAtom } from "@/core/packages/sandbox-state";
+import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";
+import PackagesPanel from "../packages-panel";
+import { PanelSectionProvider } from "../panel-context";
+import { SandboxToggle } from "../sandbox-toggle";
+
+vi.mock("@/utils/reload-safe", () => ({ reloadSafe: vi.fn() }));
+
+const preparation: EnvironmentOperation = {
+ operation_id: "prepare-1",
+ action: "prepare",
+ source: "kernel",
+ status: { kind: "succeeded" },
+ packages: {},
+ logs: {
+ environment:
+ "Using Python\nResolved dependencies\nDownloaded numpy\nInstalled numpy\n",
+ },
+};
+
+function mount({
+ preparing = false,
+ backend = "uv",
+}: { preparing?: boolean; backend?: "uv" | "pixi" | null } = {}) {
+ const store = createStore();
+ store.set(sandboxAtom, {
+ backend,
+ manifest: "dependencies = []",
+ filename: "notebook.py",
+ });
+ store.set(
+ connectionAtom,
+ preparing
+ ? { state: WebSocketState.CONNECTING, phase: "preparing-environment" }
+ : { state: WebSocketState.OPEN },
+ );
+ store.set(alertAtom, (state) => ({
+ ...state,
+ environments: {
+ ...state.environments,
+ kernel: {
+ restart_required: false,
+ operations: backend ? [preparation] : [],
+ },
+ },
+ }));
+ if (backend) {
+ store.set(startupProgressAtom, {
+ phase: preparing ? "preparing-environment" : "starting-kernel",
+ logs: preparing
+ ? ""
+ : "Loading runtime\nLaunching kernel\nKernel connected\n",
+ log_mode: "replace",
+ });
+ }
+ const client = MockRequestClient.create({
+ sendRestart: vi.fn(async () => null),
+ getDependencyTree: vi.fn(async () => ({
+ context: backend
+ ? { kind: "sandbox" as const, backend }
+ : { kind: "package-manager" as const, name: "pip" },
+ tree: {
+ name: "<root>",
+ version: null,
+ tags: [],
+ dependencies: [
+ { name: "numpy", version: "2.0.0", tags: [], dependencies: [] },
+ ],
+ },
+ })),
+ getPackageList: vi.fn(async () => ({
+ packages: [{ name: "numpy", version: "2.0.0" }],
+ })),
+ });
+ store.set(requestClientAtom, client);
+ const { unmount } = render(
+ <Provider store={store}>
+ <TooltipProvider>
+ <ModalProvider>
+ <SandboxToggle section="sidebar" />
+ <PanelSectionProvider value="sidebar">
+ <PackagesPanel />
+ </PanelSectionProvider>
+ </ModalProvider>
+ </TooltipProvider>
+ </Provider>,
+ );
+ return { store, client, unmount };
+}
+
+it("opens restored preparation and kernel logs without reopening completed startup on refresh", async () => {
+ mount();
+ await screen.findByText("numpy");
+ const toggle = screen.getByRole("button", { name: "uv sandbox" });
+ expect(toggle).toHaveAttribute("aria-expanded", "false");
+ expect(
+ screen.queryByRole("region", { name: "Sandbox details" }),
+ ).not.toBeInTheDocument();
+ fireEvent.click(toggle);
+ const details = within(
+ screen.getByRole("region", { name: "Sandbox details" }),
+ );
+ expect(details.getByText("Environment prepared")).toBeVisible();
+ expect(details.getByText("Kernel started")).toBeVisible();
+ fireEvent.click(
+ details.getByRole("button", {
+ name: "Expand environment preparation output",
+ }),
+ );
+ fireEvent.click(
+ details.getByRole("button", { name: "Expand kernel startup output" }),
+ );
+ expect(
+ details.getByLabelText("environment preparation output").textContent,
+ ).toBe(preparation.logs.environment);
+ expect(details.getByLabelText("kernel startup output")).toHaveTextContent(
+ "Loading runtime",
+ );
+ fireEvent.click(toggle);
+ fireEvent.click(toggle);
+ expect(
+ details.getByLabelText("environment preparation output"),
+ ).toBeVisible();
+ expect(details.getByLabelText("kernel startup output")).toBeVisible();
+});
+
+it("restores a restart-required sync with the kernel restart action", async () => {
+ const { store, client } = mount();
+ act(() =>
+ store.set(alertAtom, (state) => ({
+ ...state,
+ environments: {
+ ...state.environments,
+ kernel: {
+ restart_required: true,
+ operations: [
+ preparation,
+ {
+ operation_id: "sync-python",
+ action: "sync",
+ source: "kernel",
+ status: {
+ kind: "restart-required",
+ reason: "Python version changed",
+ },
+ packages: {},
+ logs: { environment: "Resolved Python 3.14\n" },
+ },
+ ],
+ },
+ },
+ })),
+ );
+ await screen.findByText("numpy");
+ expect(screen.getByText("Sandbox restart required")).toBeVisible();
+ expect(
+ screen.queryByRole("button", { name: "Retry sync" }),
+ ).not.toBeInTheDocument();
+ expect(screen.getByLabelText("Error details")).toHaveTextContent(
+ "Python version changed",
+ );
+ // A later package operation can displace the sync, but not its restart.
+ act(() =>
+ store.set(alertAtom, (state) => ({
+ ...state,
+ environments: {
+ ...state.environments,
+ kernel: {
+ restart_required: true,
+ operations: [
+ preparation,
+ {
+ operation_id: "install-1",
+ action: "install",
+ source: "kernel",
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: {},
+ },
+ ],
+ },
+ },
+ })),
+ );
+ expect(screen.getByText("Sandbox restart required")).toBeVisible();
+ fireEvent.click(screen.getByRole("button", { name: "Restart Kernel" }));
+ expect(screen.getByRole("alertdialog")).toHaveTextContent("Restart Kernel");
+ expect(client.sendRestart).not.toHaveBeenCalled();
+ fireEvent.click(screen.getByRole("button", { name: "Confirm Restart" }));
+ expect(client.sendRestart).toHaveBeenCalledTimes(1);
+});
+
+it("keeps sync output open through completion and restores it quietly after refresh", () => {
+ const { store, unmount } = mount();
+ const restore = (status: EnvironmentOperation["status"], logs: string) =>
+ store.set(alertAtom, (state) => ({
+ ...state,
+ environments: {
+ ...state.environments,
+ kernel: {
+ restart_required: false,
+ operations: [
+ preparation,
+ {
+ operation_id: "sync-1",
+ action: "sync",
+ source: "kernel",
+ status,
+ packages: {},
+ logs: { environment: logs },
+ },
+ ],
+ },
+ },
+ }));
+ act(() => restore({ kind: "running" }, "Resolving dependencies\n"));
+ const preview = screen.getByRole("button", {
+ name: "Expand sandbox sync output",
+ });
+ fireEvent.pointerDown(preview);
+ fireEvent.click(preview);
+ const output = screen.getByLabelText("sandbox sync output");
+ act(() =>
+ restore({ kind: "running" }, "Resolving dependencies\nDownloading numpy\n"),
+ );
+ expect(output).toHaveTextContent("Downloading numpy");
+ act(() =>
+ restore(
+ { kind: "succeeded" },
+ "Resolving dependencies\nDownloading numpy\nDone\n",
+ ),
+ );
+ expect(output).toBeVisible();
+ expect(output).toHaveTextContent("Done");
+ expect(screen.getByText("Environment prepared")).toBeVisible();
+ expect(screen.getByText("Kernel started")).toBeVisible();
+
+ const snapshot = store.get(alertAtom);
+ unmount();
+ const refreshed = mount();
+ act(() => refreshed.store.set(alertAtom, snapshot));
+ const toggle = screen.getByRole("button", { name: "uv sandbox" });
+ expect(toggle).toHaveAttribute("aria-expanded", "false");
+ fireEvent.click(toggle);
+ fireEvent.click(
+ screen.getByRole("button", { name: "Expand sandbox sync output" }),
+ );
+ expect(screen.getByLabelText("sandbox sync output").textContent).toBe(
+ "Resolving dependencies\nDownloading numpy\nDone\n",
+ );
+});
+
+it.each([false, true])(
+ "retains the progression after completion with inspecting=%s",
+ async (inspecting) => {
+ const { store, client } = mount({ preparing: true });
+ const toggle = screen.getByRole("button", { name: "uv sandbox" });
+ expect(toggle).toHaveAttribute("aria-expanded", "true");
+ expect(client.getDependencyTree).not.toHaveBeenCalled();
+ if (inspecting) {
+ const preview = screen.getByRole("button", {
+ name: "Expand environment preparation output",
+ });
+ fireEvent.pointerDown(preview);
+ fireEvent.click(preview);
+ }
+ act(() => {
+ store.set(startupProgressAtom, {
+ phase: "starting-kernel",
+ logs: "Launching kernel\n",
+ log_mode: "replace",
+ });
+ store.set(connectionAtom, {
+ state: WebSocketState.CONNECTING,
+ phase: "starting-kernel",
+ });
+ });
+ act(() => store.set(connectionAtom, { state: WebSocketState.OPEN }));
+ await screen.findByText("numpy");
+ expect(toggle).toHaveAttribute("aria-expanded", String(inspecting));
+ if (!inspecting) {
+ fireEvent.click(toggle);
+ }
+ expect(screen.getByText("Environment prepared")).toBeVisible();
+ expect(screen.getByText("Kernel started")).toBeVisible();
+ expect(
+ screen.getByRole("button", {
+ name: `${inspecting ? "Collapse" : "Expand"} environment preparation output`,
+ }),
+ ).toBeVisible();
+ expect(
+ screen.getByRole("button", { name: "Expand kernel startup output" }),
+ ).toHaveTextContent("Launching kernel");
+ },
+);
+
+it("opens a startup error even after collapsing preparation and keeps both step outputs available", () => {
+ const { store } = mount({ preparing: true, backend: "pixi" });
+ const toggle = screen.getByRole("button", { name: "pixi sandbox" });
+ fireEvent.click(toggle);
+ act(() => {
+ store.set(startupProgressAtom, {
+ phase: "starting-kernel",
+ logs: "Loading runtime\nImport failed\n",
+ log_mode: "replace",
+ });
+ store.set(kernelStartupErrorAtom, "Could not import the runtime");
+ store.set(connectionAtom, {
+ state: WebSocketState.CLOSED,
+ phase: "starting-kernel",
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ reason: "Kernel startup failed",
+ });
+ });
+ expect(toggle).toHaveAttribute("aria-expanded", "true");
+ expect(within(toggle).getByRole("status")).toHaveAccessibleName(
+ "Kernel failed to start",
+ );
+ expect(screen.getByLabelText("Error details")).toHaveTextContent(
+ "Could not import the runtime",
+ );
+ expect(screen.getByText("Environment prepared")).toBeVisible();
+ expect(
+ screen.getByRole("button", {
+ name: "Expand environment preparation output",
+ }),
+ ).toHaveTextContent("Installed numpy");
+ expect(
+ screen.getByRole("button", { name: "Expand kernel startup output" }),
+ ).toHaveTextContent("Import failed");
+ fireEvent.click(toggle);
+ expect(toggle).toHaveAttribute("aria-expanded", "false");
+ fireEvent.click(toggle);
+ expect(screen.getByLabelText("Error details")).toBeVisible();
+});
+
+it("does not add a toggle or startup details to an existing environment", async () => {
+ mount({ backend: null });
+ await screen.findByText("numpy");
+ expect(
+ screen.queryByRole("button", { name: /sandbox/ }),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole("region", { name: "Sandbox details" }),
+ ).not.toBeInTheDocument();
+});
diff --git a/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx
index 1b8592bb59..5be243a7e3 100644
--- a/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx
+++ b/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx
@@ -27,6 +27,7 @@ import { store } from "@/core/state/jotai";
import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";
import { chromeAtom } from "../../state";
import PackagesPanel from "../packages-panel";
+import { PanelSectionProvider } from "../panel-context";
import { SandboxController } from "../sandbox-controller";
vi.mock("@/plugins/impl/code/LazyAnyLanguageCodeMirror", () => ({
@@ -58,7 +59,7 @@ const failed = {
} as const;
beforeEach(() => {
store.set(sandboxAtom, { backend: "uv", manifest, filename: "notebook.py" });
- store.set(sandboxSyncAtom, { pending: false, error: null });
+ store.set(sandboxSyncAtom, { kind: "succeeded" });
store.set(sandboxActionsAtom, null);
store.set(connectionAtom, failed);
store.set(kernelStartupErrorAtom, "resolver output\n no solution");
@@ -83,7 +84,9 @@ function mount(
appConfig={AppConfigSchema.parse({})}
onRetry={reconnect}
/>
- <PackagesPanel />
+ <PanelSectionProvider value="sidebar">
+ <PackagesPanel />
+ </PanelSectionProvider>
</TooltipProvider>
</Provider>,
);
diff --git a/frontend/src/components/editor/chrome/panels/packages-panel.tsx b/frontend/src/components/editor/chrome/panels/packages-panel.tsx
index 15a1b14e0b..ec2e932c97 100644
--- a/frontend/src/components/editor/chrome/panels/packages-panel.tsx
+++ b/frontend/src/components/editor/chrome/panels/packages-panel.tsx
@@ -7,7 +7,7 @@ import {
HelpCircleIcon,
} from "lucide-react";
import React from "react";
-import { connectionNoticeAtom } from "@/core/network/connection-notice";
+import { useConnectionNotice } from "@/core/network/useConnectionNotice";
import { useOpenSettingsToTab } from "@/components/app-config/state";
import { Spinner } from "@/components/icons/spinner";
import { SearchInput } from "@/components/ui/input";
@@ -36,7 +36,7 @@ import { ErrorBanner } from "@/plugins/impl/common/error-banner";
import { cn } from "@/utils/cn";
import { copyToClipboard } from "@/utils/copy";
import { Events } from "@/utils/events";
-import { SandboxFooter, SandboxStartupPanel } from "./sandbox-panel";
+import { SandboxDetails } from "./sandbox-panel";
import { PanelEmptyState } from "./empty-state";
import { PACKAGES_INPUT_ID, packagesToInstallAtom } from "./packages-utils";
@@ -71,17 +71,12 @@ const PackageActionButton: React.FC<{
const PackagesPanel: React.FC = () => {
const sandbox = useAtomValue(sandboxAtom);
const connected = useAtomValue(isConnectedAtom);
- const notice = useAtomValue(connectionNoticeAtom);
- const operation = useAtomValue(sandboxSyncAtom);
+ const notice = useConnectionNotice(0);
if (sandbox?.backend) {
return (
<div className="flex flex-col flex-1 min-h-0 overflow-hidden">
- {notice && (!operation.pending || !connected) ? (
- <SandboxStartupPanel />
- ) : (
- <PackageContents />
- )}
- <SandboxFooter />
+ <SandboxDetails />
+ {connected && <PackageContents />}
</div>
);
}
@@ -104,13 +99,18 @@ const PackagesPanel: React.FC = () => {
};
const PackageContents: React.FC = () => {
- const { pending: syncing } = useAtomValue(sandboxSyncAtom);
+ const syncing = useAtomValue(sandboxSyncAtom).kind === "running";
const [userViewMode, setUserViewMode] = React.useState<ViewMode | null>(null);
const { data: dependencies, error, isPending } = usePackageDependencies();
// Only show on the first load
if (isPending) {
- return <Spinner size="medium" centered={true} />;
+ return (
+ <output className="flex flex-1 items-center justify-center gap-2 text-xs text-muted-foreground">
+ <Spinner className="size-4" />
+ Loading installed packages…
+ </output>
+ );
}
if (error) {
@@ -179,15 +179,26 @@ const PackageContents: React.FC = () => {
</div>
</div>
)}
- {viewMode === "list" ? (
- <PackagesList packages={dependencies.list} />
- ) : (
- <DependencyTree
- tree={dependencies.tree}
- error={error}
- sandboxBackend={sandboxBackend}
- />
- )}
+ <fieldset
+ disabled={syncing}
+ className="flex flex-col flex-1 min-h-0"
+ aria-busy={syncing}
+ >
+ {syncing && (
+ <p className="px-3 py-2 text-xs text-muted-foreground">
+ Showing packages from the last sync.
+ </p>
+ )}
+ {viewMode === "list" ? (
+ <PackagesList packages={dependencies.list} />
+ ) : (
+ <DependencyTree
+ tree={dependencies.tree}
+ error={error}
+ sandboxBackend={sandboxBackend}
+ />
+ )}
+ </fieldset>
</div>
);
};
diff --git a/frontend/src/components/editor/chrome/panels/sandbox-details-state.ts b/frontend/src/components/editor/chrome/panels/sandbox-details-state.ts
new file mode 100644
index 0000000000..94be867893
--- /dev/null
+++ b/frontend/src/components/editor/chrome/panels/sandbox-details-state.ts
@@ -0,0 +1,38 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { atom } from "jotai";
+import { connectionNoticeAtom } from "@/core/network/connection-notice";
+import { preparationAtom } from "@/core/packages/sandbox-state";
+
+const preferenceAtom = atom<{
+ preparationId: string | undefined;
+ error: string | null;
+ expanded: boolean;
+} | null>(null);
+
+const disclosureContextAtom = atom((get) => {
+ const notice = get(connectionNoticeAtom);
+ return {
+ preparationId: get(preparationAtom)?.operation_id,
+ error: notice && !notice.pending ? (notice.error ?? notice.title) : null,
+ };
+});
+
+export const sandboxDetailsExpandedAtom = atom(
+ (get) => {
+ const context = get(disclosureContextAtom);
+ const preference = get(preferenceAtom);
+ if (
+ preference &&
+ preference.preparationId === context.preparationId &&
+ preference.error === context.error
+ ) {
+ return preference.expanded;
+ }
+ // New work and failures open automatically. Completed startup stays quiet
+ // unless the user chose to inspect it.
+ return get(connectionNoticeAtom) !== null;
+ },
+ (get, set, expanded: boolean) => {
+ set(preferenceAtom, { ...get(disclosureContextAtom), expanded });
+ },
+);
diff --git a/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx b/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx
index 07e14f5e2c..f2e5f3f05c 100644
--- a/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx
+++ b/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx
@@ -1,28 +1,29 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import { useAtomValue } from "jotai";
-import {
- AlertCircleIcon,
- ChevronUpIcon,
- FileCodeIcon,
- RefreshCwIcon,
-} from "lucide-react";
+import { useAtom, useAtomValue } from "jotai";
+import { RefreshCwIcon } from "lucide-react";
import { connectionNoticeAtom } from "@/core/network/connection-notice";
-import { Spinner } from "@/components/icons/spinner";
import { Button } from "@/components/ui/button";
+import { useRestartKernel } from "@/components/editor/actions/useRestartKernel";
import {
- DropdownMenu,
- DropdownMenuContent,
- DropdownMenuItem,
- DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
-import { Tooltip } from "@/components/ui/tooltip";
-import { isConnectedAtom } from "@/core/network/connection";
+ isConnectedAtom,
+ startupProgressAtom,
+} from "@/core/network/connection";
+import type { DisplayConnectionNotice } from "@/core/network/useConnectionNotice";
import {
+ preparationAtom,
sandboxActionsAtom,
sandboxAtom,
sandboxSyncAtom,
+ sandboxSyncOperationAtom,
} from "@/core/packages/sandbox-state";
import { cn } from "@/utils/cn";
+import { usePanelSection } from "./panel-context";
+import { sandboxDetailsExpandedAtom } from "./sandbox-details-state";
+import { StartupOutput } from "../../alerts/startup-output";
+import {
+ ConnectionStatusIcon,
+ StartupProgress,
+} from "../../alerts/startup-progress";
export function SandboxErrorOutput({ error }: { error: string }) {
return (
@@ -36,138 +37,194 @@ export function SandboxErrorOutput({ error }: { error: string }) {
);
}
-export function SandboxStartupPanel() {
- const notice = useAtomValue(connectionNoticeAtom);
+function SandboxRecovery({ notice }: { notice: DisplayConnectionNotice }) {
const sandbox = useAtomValue(sandboxAtom);
const actions = useAtomValue(sandboxActionsAtom);
- if (!notice) {
+ const sync = useAtomValue(sandboxSyncAtom);
+ if (notice.pending || notice.ready) {
return null;
}
return (
- <div className="flex-1 min-h-0 overflow-auto p-4 text-sm">
- <div
- className={cn(
- "flex items-center gap-2",
- notice.pending
- ? "text-muted-foreground"
- : "font-medium text-(--red-11)",
- )}
- >
- {notice.pending ? (
- <Spinner className="size-4 shrink-0" aria-hidden={true} />
+ <>
+ <p className="mt-2 text-foreground">{notice.description}</p>
+ {notice.error && <SandboxErrorOutput error={notice.error} />}
+ <div className="flex items-center gap-2 mt-3">
+ <Button
+ variant="outline"
+ size="xs"
+ disabled={!actions || sandbox?.manifest == null}
+ onClick={() => actions?.editManifest()}
+ >
+ Edit manifest…
+ </Button>
+ {notice.kind === "sync" && sync.kind === "restart-required" ? (
+ <SandboxRestart />
) : (
- <AlertCircleIcon className="size-4 shrink-0" aria-hidden={true} />
+ <Button
+ variant="text"
+ size="xs"
+ disabled={!actions}
+ onClick={() => actions?.sync()}
+ >
+ Retry sync
+ </Button>
)}
- <h2>{notice.title}</h2>
</div>
- {!notice.pending && (
- <>
- <p className="mt-2 text-foreground">{notice.description}</p>
- {notice.error && <SandboxErrorOutput error={notice.error} />}
- <div className="flex items-center gap-2 mt-3">
- <Button
- variant="outline"
- size="xs"
- disabled={!actions || sandbox?.manifest == null}
- onClick={() => actions?.editManifest()}
- >
- Edit manifest…
- </Button>
- <Button
- variant="text"
- size="xs"
- disabled={!actions}
- onClick={() => actions?.sync()}
- >
- Retry sync
- </Button>
- </div>
- {sandbox?.manifest == null && (
- <p className="mt-3 text-xs text-muted-foreground">
- A manifest will be available once this new notebook starts.
- </p>
- )}
- </>
+ {sandbox?.manifest == null && (
+ <p className="mt-3 text-xs text-muted-foreground">
+ A manifest will be available once this new notebook starts.
+ </p>
+ )}
+ </>
+ );
+}
+
+function SandboxRestart() {
+ const restartKernel = useRestartKernel();
+ return (
+ <Button variant="text" size="xs" onClick={restartKernel}>
+ Restart Kernel
+ </Button>
+ );
+}
+
+function SandboxStartupPanel({ notice }: { notice: DisplayConnectionNotice }) {
+ const showSteps =
+ notice.kind === "startup" &&
+ (notice.ready ||
+ notice.phase === "preparing-environment" ||
+ notice.phase === "starting-kernel");
+ return (
+ <div className="min-w-0 text-sm">
+ {showSteps ? (
+ <StartupProgress notice={notice} surface="sidebar" />
+ ) : (
+ <div className="flex items-center gap-2" role="status">
+ <ConnectionStatusIcon notice={notice} />
+ <h2>{notice.title}</h2>
+ </div>
)}
+ <SandboxRecovery notice={notice} />
</div>
);
}
-export function SandboxFooter() {
- const sandbox = useAtomValue(sandboxAtom);
- const connected = useAtomValue(isConnectedAtom);
- const actions = useAtomValue(sandboxActionsAtom);
- const operation = useAtomValue(sandboxSyncAtom);
- const notice = useAtomValue(connectionNoticeAtom);
- if (!sandbox?.backend) {
+function SandboxSyncStatus({ notice }: { notice: DisplayConnectionNotice }) {
+ return (
+ <div className="mb-5 text-sm">
+ <output className="flex items-center gap-2 text-xs">
+ <ConnectionStatusIcon notice={notice} />
+ <span>{notice.title}</span>
+ </output>
+ <SandboxRecovery notice={notice} />
+ </div>
+ );
+}
+
+function SandboxSyncDetails({
+ notice,
+}: {
+ notice: DisplayConnectionNotice | null;
+}) {
+ const operation = useAtomValue(sandboxSyncOperationAtom);
+ if (!operation && !notice) {
return null;
}
- const pending = operation.pending || notice?.pending;
- const status = operation.pending
- ? "Syncing sandbox…"
- : (notice?.title ?? (connected ? "Sandbox ready" : "Sandbox not started"));
return (
- <div className="border-t p-1.5 shrink-0">
- <DropdownMenu>
- <Tooltip content={status}>
- <DropdownMenuTrigger asChild={true}>
- <button
- type="button"
- className="flex items-center gap-2 w-full px-2 py-1.5 rounded text-xs text-muted-foreground hover:bg-accent data-[state=open]:bg-accent"
- aria-label={`${sandbox.backend} sandbox actions`}
- >
- <span
- role="status"
- aria-label={status}
- className={cn(
- "size-1.5 shrink-0 rounded-full",
- pending
- ? "bg-amber-500 motion-safe:animate-pulse"
- : notice
- ? "bg-(--red-9)"
- : connected
- ? "bg-emerald-500"
- : "bg-muted-foreground",
- )}
- />
- <span>{sandbox.backend} sandbox</span>
- <span className="ml-auto">
- {pending
- ? operation.pending
- ? "Syncing…"
- : notice?.title
- : ""}
- </span>
- <ChevronUpIcon className="size-3" />
- </button>
- </DropdownMenuTrigger>
- </Tooltip>
- <DropdownMenuContent
- side="top"
- align="start"
- className="w-52"
- sideOffset={8}
- >
- <DropdownMenuItem
- disabled={pending || !actions}
- onSelect={() => {
- void actions?.sync();
- }}
- >
- <RefreshCwIcon className="size-3.5 mr-2" />
- Sync
- </DropdownMenuItem>
- <DropdownMenuItem
- disabled={!actions || sandbox.manifest === null}
- onSelect={() => {
- void actions?.editManifest();
- }}
- >
- <FileCodeIcon className="size-3.5 mr-2" />
- Edit manifest…
- </DropdownMenuItem>
- </DropdownMenuContent>
- </DropdownMenu>
+ <div className="mt-5 min-w-0">
+ {notice ? (
+ <SandboxSyncStatus notice={notice} />
+ ) : (
+ <p className="text-sm">Environment synced</p>
+ )}
+ <StartupOutput
+ key={operation?.operation_id}
+ logs={operation?.logs.environment ?? ""}
+ state={
+ operation?.status.kind === "running"
+ ? "running"
+ : operation?.status.kind === "succeeded"
+ ? "succeeded"
+ : "failed"
+ }
+ label="sandbox sync output"
+ />
+ </div>
+ );
+}
+
+export function SandboxDetails() {
+ const section = usePanelSection();
+ const connected = useAtomValue(isConnectedAtom);
+ const notice = useAtomValue(connectionNoticeAtom);
+ const preparation = useAtomValue(preparationAtom);
+ const progress = useAtomValue(startupProgressAtom);
+ const [expanded, setExpanded] = useAtom(sandboxDetailsExpandedAtom);
+ const startup: DisplayConnectionNotice | null =
+ notice?.kind === "startup"
+ ? { ...notice, ready: false }
+ : preparation || progress
+ ? {
+ kind: "startup",
+ sandbox: true,
+ title: "Notebook started",
+ description: "The notebook is ready to run.",
+ pending: false,
+ ready: true,
+ error: null,
+ }
+ : null;
+ return (
+ <section
+ id={`sandbox-details-${section}`}
+ aria-label="Sandbox details"
+ hidden={!expanded}
+ className={cn(
+ "min-w-0 overflow-auto p-4",
+ connected ? "shrink-0 max-h-[65%] border-b" : "flex-1",
+ )}
+ onPointerDownCapture={() => setExpanded(true)}
+ onFocusCapture={() => setExpanded(true)}
+ >
+ {notice?.kind === "connection" && (
+ <SandboxSyncStatus notice={{ ...notice, ready: false }} />
+ )}
+ {startup && <SandboxStartupPanel notice={startup} />}
+ {connected && (
+ <SandboxSyncDetails
+ notice={notice?.kind === "sync" ? { ...notice, ready: false } : null}
+ />
+ )}
+ {connected && (!notice || notice.pending) && <SandboxActions />}
+ </section>
+ );
+}
+
+function SandboxActions() {
+ const sandbox = useAtomValue(sandboxAtom);
+ const actions = useAtomValue(sandboxActionsAtom);
+ const pending = useAtomValue(sandboxSyncAtom).kind === "running";
+ return (
+ <div className="flex items-center gap-4 mt-5 border-t pt-3">
+ <Button
+ variant="text"
+ size="xs"
+ className="text-muted-foreground gap-1.5 p-0"
+ disabled={pending || !actions}
+ onClick={() => actions?.sync()}
+ >
+ <RefreshCwIcon className="size-3" aria-hidden={true} />
+ Sync
+ </Button>
+ <Button
+ variant="text"
+ size="xs"
+ className="text-muted-foreground p-0"
+ disabled={!actions || sandbox?.manifest == null}
+ onClick={() => actions?.editManifest()}
+ >
+ Edit manifest…
+ </Button>
</div>
);
}
diff --git a/frontend/src/components/editor/chrome/panels/sandbox-toggle.tsx b/frontend/src/components/editor/chrome/panels/sandbox-toggle.tsx
new file mode 100644
index 0000000000..a393ab8003
--- /dev/null
+++ b/frontend/src/components/editor/chrome/panels/sandbox-toggle.tsx
@@ -0,0 +1,52 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtom, useAtomValue } from "jotai";
+import { ChevronDownIcon } from "lucide-react";
+import { connectionNoticeAtom } from "@/core/network/connection-notice";
+import { sandboxAtom } from "@/core/packages/sandbox-state";
+import { cn } from "@/utils/cn";
+import type { PanelSection } from "./panel-context";
+import { sandboxDetailsExpandedAtom } from "./sandbox-details-state";
+
+export function SandboxToggle({ section }: { section: PanelSection }) {
+ const sandbox = useAtomValue(sandboxAtom);
+ const notice = useAtomValue(connectionNoticeAtom);
+ const [expanded, setExpanded] = useAtom(sandboxDetailsExpandedAtom);
+ if (!sandbox?.backend) {
+ return null;
+ }
+ const status = notice ? (notice.pending ? "pending" : "error") : "healthy";
+ return (
+ <button
+ type="button"
+ aria-label={`${sandbox.backend} sandbox`}
+ aria-expanded={expanded}
+ aria-controls={`sandbox-details-${section}`}
+ title={notice?.title ?? "Sandbox details"}
+ className={cn(
+ "flex items-center gap-1.5 rounded px-1.5 py-1 text-xs whitespace-nowrap hover:bg-accent focus-visible:outline-2 focus-visible:outline-ring",
+ status === "error" ? "text-(--red-11)" : "text-foreground",
+ )}
+ onClick={() => setExpanded(!expanded)}
+ >
+ <output
+ aria-label={notice?.title ?? "Sandbox healthy"}
+ className={cn(
+ "size-1.5 shrink-0 rounded-full",
+ status === "error"
+ ? "bg-(--red-9)"
+ : status === "pending"
+ ? "bg-muted-foreground motion-safe:animate-pulse"
+ : "bg-(--grass-9)",
+ )}
+ />
+ {sandbox.backend} sandbox
+ <ChevronDownIcon
+ aria-hidden={true}
+ className={cn(
+ "size-3 shrink-0 text-muted-foreground",
+ expanded && "rotate-180",
+ )}
+ />
+ </button>
+ );
+}
diff --git a/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx b/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx
index f12052c3eb..ab46cdce53 100644
--- a/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx
+++ b/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx
@@ -34,6 +34,7 @@ import { ErrorBoundary } from "../../boundary/ErrorBoundary";
import { raf2 } from "../../navigation/focus-utils";
import { ContextAwarePanel } from "../panels/context-aware-panel/context-aware-panel";
import { PanelSectionProvider } from "../panels/panel-context";
+import { SandboxToggle } from "../panels/sandbox-toggle";
import { useTheme } from "@/theme/useTheme";
import {
LazyAgentPanel,
@@ -389,6 +390,9 @@ export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
{selectedPanel}
</span>
)}
+ {selectedPanel === "packages" && (
+ <SandboxToggle section="sidebar" />
+ )}
<Button
data-testid="close-helper-pane"
className="m-0"
@@ -544,6 +548,9 @@ export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
<BackendConnectionStatus />
<LspStatus />
<div className="flex-1" />
+ {selectedDeveloperPanelTab === "packages" && (
+ <SandboxToggle section="developer-panel" />
+ )}
<Button
size="xs"
variant="text"
diff --git a/frontend/src/components/editor/package-alert.tsx b/frontend/src/components/editor/package-alert.tsx
index ebc945480c..ed34c531fa 100644
--- a/frontend/src/components/editor/package-alert.tsx
+++ b/frontend/src/components/editor/package-alert.tsx
@@ -14,7 +14,7 @@ import {
XIcon,
} from "lucide-react";
import type React from "react";
-import { useState } from "react";
+import { useEffect, useState } from "react";
import { useForm } from "react-hook-form";
import type { z } from "zod";
import {
@@ -25,19 +25,20 @@ import {
FormMessage,
} from "@/components/ui/form";
import {
- isInstallingPackageAlert,
+ type EnvironmentOperationAlert,
+ isEnvironmentOperationAlert,
isMissingPackageAlert,
useAlertActions,
useAlerts,
} from "@/core/alerts/state";
import { useResolvedMarimoConfig } from "@/core/config/config";
-import type { PackageInstallationStatus } from "@/core/kernel/messages";
+import type { PackageOperationStatus } from "@/core/kernel/messages";
import { useRequestClient } from "@/core/network/requests";
import { RESTART_REQUIRED_DESCRIPTION } from "@/core/packages/toast-components";
import { isWasm } from "@/core/wasm/utils";
import { usePackageMetadata } from "@/hooks/usePackageMetadata";
import { Banner } from "@/plugins/impl/common/error-banner";
-import { logNever } from "@/utils/assertNever";
+import { assertNever, logNever } from "@/utils/assertNever";
import { cn } from "@/utils/cn";
import { Logger } from "@/utils/Logger";
import {
@@ -100,7 +101,7 @@ const SourceBadge: React.FC<{ source?: "kernel" | "server" }> = ({
};
export const PackageAlert: React.FC = () => {
- const { packageAlert, packageLogs } = useAlerts();
+ const { packageAlert } = useAlerts();
const { clearPackageAlert } = useAlertActions();
const [userConfig] = useResolvedMarimoConfig();
const [desiredPackageVersions, setDesiredPackageVersions] = useState<
@@ -110,6 +111,23 @@ export const PackageAlert: React.FC = () => {
Record<string, string[]>
>({});
+ const completedAlertId =
+ packageAlert?.kind === "environment" &&
+ packageAlert.status.kind === "succeeded" &&
+ !packageAlert.restartRequired
+ ? packageAlert.id
+ : null;
+ useEffect(() => {
+ if (completedAlertId === null) {
+ return;
+ }
+ const timeout = setTimeout(
+ () => clearPackageAlert(completedAlertId),
+ 10_000,
+ );
+ return () => clearTimeout(timeout);
+ }, [completedAlertId, clearPackageAlert]);
+
if (packageAlert === null) {
return null;
}
@@ -224,12 +242,9 @@ export const PackageAlert: React.FC = () => {
);
}
- if (isInstallingPackageAlert(packageAlert)) {
+ if (isEnvironmentOperationAlert(packageAlert)) {
const { status, title, titleIcon, description } =
- getInstallationStatusElements(packageAlert.packages);
- if (status === "installed") {
- setTimeout(() => clearPackageAlert(packageAlert.id), 10_000);
- }
+ getOperationStatusElements(packageAlert);
return (
<div className="flex flex-col gap-4 mb-5 fixed top-5 left-12 min-w-[400px] z-200 opacity-95 max-w-[600px] pointer-events-none">
@@ -255,23 +270,27 @@ export const PackageAlert: React.FC = () => {
<div
className={cn(
"flex flex-col gap-4 justify-between items-start text-muted-foreground text-base",
- status === "installed" && "text-accent-foreground",
+ status === "succeeded" && "text-accent-foreground",
)}
>
<p>{description}</p>
- {status !== "installing" &&
- Object.values(packageAlert.packages).includes(
- "restart-required",
- ) && <RestartKernelButton />}
+ {status !== "running" && packageAlert.restartRequired && (
+ <>
+ {status !== "restart-required" && (
+ <p>{RESTART_REQUIRED_DESCRIPTION}</p>
+ )}
+ <RestartKernelButton />
+ </>
+ )}
<ul className="list-disc ml-2 mt-1">
{Object.entries(packageAlert.packages).map(([pkg, st], index) => (
<li
className={cn(
"flex items-center gap-1 font-mono text-sm",
- st === "installing" && "font-semibold",
+ st === "running" && "font-semibold",
st === "failed" && "text-destructive",
- st === "installed" && "text-accent-foreground",
- st === "installed" &&
+ st === "succeeded" && "text-accent-foreground",
+ st === "succeeded" &&
status === "failed" &&
"text-muted-foreground",
)}
@@ -282,8 +301,11 @@ export const PackageAlert: React.FC = () => {
</li>
))}
</ul>
- {Object.keys(packageLogs).length > 0 && (
- <StreamingLogsViewer packageLogs={packageLogs} />
+ {Object.keys(packageAlert.logs).length > 0 && (
+ <StreamingLogsViewer
+ key={packageAlert.id}
+ packageLogs={packageAlert.logs}
+ />
)}
</div>
</Banner>
@@ -295,60 +317,84 @@ export const PackageAlert: React.FC = () => {
return null;
};
-function getInstallationStatusElements(packages: PackageInstallationStatus) {
- const statuses = new Set(Object.values(packages));
- const status =
- statuses.has("queued") || statuses.has("installing")
- ? "installing"
- : statuses.has("failed")
- ? "failed"
- : statuses.has("restart-required")
- ? "restart-required"
- : "installed";
-
- if (status === "installing") {
- return {
- status: "installing",
- title: "Installing packages",
- titleIcon: <DownloadCloudIcon className="w-5 h-5 inline-block mr-2" />,
- description: "Installing packages:",
- };
- }
- if (status === "restart-required") {
- return {
- status,
- title: "Changes saved — restart required",
- titleIcon: <RotateCwIcon className="w-5 h-5 inline-block mr-2" />,
- description: RESTART_REQUIRED_DESCRIPTION,
- };
- }
- if (status === "installed") {
- return {
- status: "installed",
- title: "All packages installed!",
- titleIcon: <PackageCheckIcon className="w-5 h-5 inline-block mr-2" />,
- description: "Installed packages:",
- };
+function getOperationStatusElements({
+ action,
+ status: outcome,
+ restartRequired,
+}: EnvironmentOperationAlert) {
+ const status: EnvironmentOperationAlert["status"] =
+ outcome.kind === "succeeded" && restartRequired
+ ? { kind: "restart-required", reason: RESTART_REQUIRED_DESCRIPTION }
+ : outcome;
+ const titles = {
+ install: {
+ running: "Installing packages",
+ succeeded: "All packages installed!",
+ failed: "Some packages failed to install",
+ cancelled: "Package installation cancelled",
+ },
+ remove: {
+ running: "Removing packages",
+ succeeded: "Packages removed",
+ failed: "Some packages failed to remove",
+ cancelled: "Package removal cancelled",
+ },
+ }[action];
+ switch (status.kind) {
+ case "running":
+ return {
+ status: "running",
+ title: titles.running,
+ titleIcon: <DownloadCloudIcon className="w-5 h-5 inline-block mr-2" />,
+ description:
+ action === "install" ? "Installing packages:" : "Removing packages:",
+ };
+ case "restart-required":
+ return {
+ status: "restart-required",
+ title: "Changes saved — restart required",
+ titleIcon: <RotateCwIcon className="w-5 h-5 inline-block mr-2" />,
+ description: status.reason,
+ };
+ case "succeeded":
+ return {
+ status: "succeeded",
+ title: titles.succeeded,
+ titleIcon: <PackageCheckIcon className="w-5 h-5 inline-block mr-2" />,
+ description:
+ action === "install" ? "Installed packages:" : "Removed packages:",
+ };
+ case "failed":
+ return {
+ status: "failed",
+ title: titles.failed,
+ titleIcon: <PackageXIcon className="w-5 h-5 inline-block mr-2" />,
+ description: status.error,
+ };
+ case "cancelled":
+ return {
+ status: "cancelled",
+ title: titles.cancelled,
+ titleIcon: <XIcon className="w-5 h-5 inline-block mr-2" />,
+ description:
+ "The operation was interrupted. Some packages may have changed.",
+ };
+ default:
+ return assertNever(status);
}
- return {
- status: "failed",
- title: "Some packages failed to install",
- titleIcon: <PackageXIcon className="w-5 h-5 inline-block mr-2" />,
- description: "See error logs.",
- };
}
const ProgressIcon = ({
status,
}: {
- status: PackageInstallationStatus[string];
+ status: PackageOperationStatus[string];
}) => {
switch (status) {
case "queued":
return <BoxIcon size="1rem" />;
- case "installing":
+ case "running":
return <DownloadCloudIcon size="1rem" />;
- case "installed":
+ case "succeeded":
return <CheckIcon size="1rem" />;
case "failed":
return <XIcon size="1rem" />;
@@ -672,7 +718,7 @@ const StreamingLogsViewer: React.FC<StreamingLogsViewerProps> = ({
}
return (
- <div className="mt-4 border-t border-border pt-4 w-full">
+ <div className="mt-4 border-t border-border pt-4 w-full contain-inline-size">
<button
onClick={() => setIsExpanded(!isExpanded)}
className="flex items-center gap-2 text-sm font-medium text-muted-foreground hover:text-foreground transition-colors"
@@ -683,7 +729,7 @@ const StreamingLogsViewer: React.FC<StreamingLogsViewerProps> = ({
) : (
<ChevronRightIcon className="w-4 h-4" />
)}
- Installation logs
+ Logs
</button>
{isExpanded && (
@@ -694,7 +740,7 @@ const StreamingLogsViewer: React.FC<StreamingLogsViewerProps> = ({
{packageName}
</h4>
<div className="border border-border rounded w-full">
- <pre className="p-3 text-xs font-mono bg-background max-h-64 overflow-y-auto text-muted-foreground whitespace-pre-wrap scrollbar-thin">
+ <pre className="p-3 text-xs font-mono bg-background max-h-64 overflow-auto text-muted-foreground whitespace-pre scrollbar-thin">
{logs || "No logs available"}
</pre>
</div>
diff --git a/frontend/src/core/alerts/__tests__/environment.test.ts b/frontend/src/core/alerts/__tests__/environment.test.ts
new file mode 100644
index 0000000000..38307f253b
--- /dev/null
+++ b/frontend/src/core/alerts/__tests__/environment.test.ts
@@ -0,0 +1,183 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import type { NotificationMessageData } from "@/core/kernel/messages";
+import { emptyEnvironmentState, reduceEnvironmentState } from "../environment";
+
+function progress(
+ operation_id: string,
+ update: Partial<NotificationMessageData<"environment-operation">> = {},
+): NotificationMessageData<"environment-operation"> {
+ return {
+ operation_id,
+ action: "install",
+ source: "kernel",
+ status: { kind: "running" },
+ packages: { numpy: "running" },
+ logs: { numpy: "Downloading\n" },
+ log_mode: "append",
+ ...update,
+ };
+}
+
+describe("environment progress", () => {
+ it("continues snapshot logs without mutating or duplicating them", () => {
+ const snapshot = reduceEnvironmentState(
+ emptyEnvironmentState(),
+ progress("one"),
+ );
+ const result = reduceEnvironmentState(
+ snapshot,
+ progress("one", {
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: { numpy: "Installed\n" },
+ log_mode: "append",
+ }),
+ );
+ expect(result).toEqual({
+ restart_required: false,
+ operations: [
+ {
+ operation_id: "one",
+ action: "install",
+ source: "kernel",
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: { numpy: "Downloading\nInstalled\n" },
+ },
+ ],
+ });
+ expect(snapshot.operations[0].logs).toEqual({ numpy: "Downloading\n" });
+ });
+
+ it("isolates overlapping operations and starts retries with fresh logs", () => {
+ let state = reduceEnvironmentState(
+ emptyEnvironmentState(),
+ progress("one"),
+ );
+ state = reduceEnvironmentState(
+ state,
+ progress("two", { logs: { numpy: "Other\n" } }),
+ );
+ state = reduceEnvironmentState(
+ state,
+ progress("one", {
+ status: { kind: "failed", error: "Network unavailable" },
+ logs: {},
+ }),
+ );
+ expect(state.operations.map((op) => [op.operation_id, op.logs])).toEqual([
+ ["one", { numpy: "Downloading\n" }],
+ ["two", { numpy: "Other\n" }],
+ ]);
+ state = reduceEnvironmentState(state, progress("retry", { logs: {} }));
+ expect(state.operations.map((op) => [op.operation_id, op.logs])).toEqual([
+ ["two", { numpy: "Other\n" }],
+ ["retry", {}],
+ ]);
+ });
+
+ it("replaces named logs independently of the package map", () => {
+ const state = reduceEnvironmentState(
+ emptyEnvironmentState(),
+ progress("one", {
+ packages: { numpy: "succeeded", pandas: "running" },
+ logs: { numpy: "Old\n", pandas: "Old\n" },
+ }),
+ );
+ const result = reduceEnvironmentState(
+ state,
+ progress("one", {
+ log_mode: "replace",
+ logs: { numpy: "", pandas: "Ignored\n" },
+ }),
+ );
+ expect(result.operations[0].logs).toEqual({
+ numpy: "",
+ pandas: "Ignored\n",
+ });
+ });
+
+ it("keeps a restart requirement after a later operation succeeds", () => {
+ let state = reduceEnvironmentState(
+ emptyEnvironmentState(),
+ progress("one", {
+ status: { kind: "restart-required", reason: "Python changed" },
+ }),
+ );
+ state = reduceEnvironmentState(
+ state,
+ progress("two", {
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: {},
+ }),
+ );
+ expect(state).toEqual({
+ restart_required: true,
+ operations: [
+ {
+ operation_id: "two",
+ action: "install",
+ source: "kernel",
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: {},
+ },
+ ],
+ });
+ });
+});
+
+it("retains preparation through later package changes and replaces it on a new attempt", () => {
+ const preparation = progress("prepare", {
+ action: "prepare",
+ status: { kind: "succeeded" },
+ packages: {},
+ logs: { environment: "Prepared environment\n" },
+ });
+ let state = reduceEnvironmentState(emptyEnvironmentState(), preparation);
+ const retained = state.operations[0];
+ for (const action of ["install", "sync", "remove"] as const) {
+ state = reduceEnvironmentState(state, progress(action, { action }));
+ state = reduceEnvironmentState(
+ state,
+ progress(action, {
+ action,
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: {},
+ }),
+ );
+ expect(state.operations).toEqual([
+ retained,
+ {
+ operation_id: action,
+ action,
+ source: "kernel",
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: { numpy: "Downloading\n" },
+ },
+ ]);
+ }
+ state = reduceEnvironmentState(
+ state,
+ progress("prepare-again", {
+ action: "prepare",
+ packages: {},
+ logs: {},
+ }),
+ );
+ expect(state.operations).toEqual([
+ {
+ operation_id: "prepare-again",
+ action: "prepare",
+ source: "kernel",
+ status: { kind: "running" },
+ packages: {},
+ logs: {},
+ },
+ ]);
+});
diff --git a/frontend/src/core/alerts/__tests__/state.test.tsx b/frontend/src/core/alerts/__tests__/state.test.tsx
new file mode 100644
index 0000000000..3e74f21623
--- /dev/null
+++ b/frontend/src/core/alerts/__tests__/state.test.tsx
@@ -0,0 +1,240 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+// @vitest-environment jsdom
+
+import { act, renderHook } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { expect, it } from "vitest";
+import type { EnvironmentOperation } from "../environment";
+import { alertAtom, getPackageAlert, useAlertActions } from "../state";
+
+it.each(["install", "remove"] as const)(
+ "restores active %s progress without announcing old successes",
+ (action) => {
+ const store = createStore();
+ const { result } = renderHook(() => useAlertActions(), {
+ wrapper: ({ children }) => <Provider store={store}>{children}</Provider>,
+ });
+ const operation: EnvironmentOperation = {
+ operation_id: "package",
+ action,
+ source: "kernel",
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: { numpy: "Done\n" },
+ };
+ const snapshot = (value: EnvironmentOperation) =>
+ result.current.setEnvironment({
+ source: value.source,
+ state: { restart_required: false, operations: [value] },
+ });
+ act(() => snapshot(operation));
+ expect(getPackageAlert(store.get(alertAtom))).toBeNull();
+ expect(store.get(alertAtom).environments.kernel.operations).toEqual([
+ operation,
+ ]);
+
+ const active: EnvironmentOperation = {
+ ...operation,
+ status: { kind: "running" },
+ packages: { numpy: "running" },
+ logs: { numpy: "Working\n" },
+ };
+ act(() => snapshot(active));
+ expect(getPackageAlert(store.get(alertAtom))).toEqual({
+ ...active,
+ id: active.operation_id,
+ kind: "environment",
+ restartRequired: false,
+ });
+
+ // Reconnecting can complete work that was already visible on this page.
+ act(() => snapshot(operation));
+ expect(getPackageAlert(store.get(alertAtom))).toEqual({
+ ...operation,
+ id: operation.operation_id,
+ kind: "environment",
+ restartRequired: false,
+ });
+ act(() => result.current.clearPackageAlert(operation.operation_id));
+ act(() => snapshot(operation));
+ expect(getPackageAlert(store.get(alertAtom))).toBeNull();
+
+ // A live result still gives feedback for a new package action.
+ act(() =>
+ result.current.updateEnvironment({
+ ...operation,
+ operation_id: "new",
+ log_mode: "replace",
+ }),
+ );
+ expect(getPackageAlert(store.get(alertAtom))?.id).toBe("new");
+
+ // Earlier changes can still require a restart after a later action succeeds.
+ act(() => result.current.clearPackageAlert("new"));
+ act(() =>
+ result.current.setEnvironment({
+ source: operation.source,
+ state: { restart_required: true, operations: [operation] },
+ }),
+ );
+ expect(getPackageAlert(store.get(alertAtom))).toEqual({
+ ...operation,
+ id: operation.operation_id,
+ kind: "environment",
+ restartRequired: true,
+ });
+ },
+);
+
+it.each(["prepare", "sync"] as const)(
+ "retains %s progress without turning it into a package alert",
+ (action) => {
+ const store = createStore();
+ const { result } = renderHook(() => useAlertActions(), {
+ wrapper: ({ children }) => <Provider store={store}>{children}</Provider>,
+ });
+ const operation: EnvironmentOperation = {
+ operation_id: "sandbox",
+ action,
+ source: "kernel",
+ status: { kind: "succeeded" },
+ packages: {},
+ logs: { environment: "Environment ready\n" },
+ };
+ const environment = { restart_required: false, operations: [operation] };
+
+ // A refreshed browser restores the result without announcing it again.
+ act(() =>
+ result.current.setEnvironment({ source: "kernel", state: environment }),
+ );
+ expect(getPackageAlert(store.get(alertAtom))).toBeNull();
+ expect(store.get(alertAtom).environments.kernel).toEqual(environment);
+
+ const install: EnvironmentOperation = {
+ ...operation,
+ operation_id: "install",
+ action: "install",
+ status: { kind: "running" },
+ packages: { numpy: "running" },
+ logs: { numpy: "Installing\n" },
+ };
+ act(() =>
+ result.current.updateEnvironment({ ...install, log_mode: "replace" }),
+ );
+ const packageAlert = getPackageAlert(store.get(alertAtom));
+ for (const status of [
+ { kind: "running" },
+ { kind: "failed", error: "Sync failed" },
+ ] as const) {
+ act(() =>
+ result.current.updateEnvironment({
+ ...operation,
+ status,
+ log_mode: "replace",
+ }),
+ );
+ expect(getPackageAlert(store.get(alertAtom))).toEqual(packageAlert);
+ }
+
+ act(() => result.current.clearPackageAlert(install.operation_id));
+ act(() =>
+ result.current.updateEnvironment({ ...operation, log_mode: "replace" }),
+ );
+ expect(getPackageAlert(store.get(alertAtom))).toBeNull();
+ },
+);
+
+it.each(["kernel", "server"] as const)(
+ "preserves the selected %s result across snapshots and follows new work",
+ (source) => {
+ const store = createStore();
+ const { result } = renderHook(() => useAlertActions(), {
+ wrapper: ({ children }) => <Provider store={store}>{children}</Provider>,
+ });
+ const selected: EnvironmentOperation = {
+ operation_id: "selected",
+ action: "install",
+ source,
+ status: { kind: "failed", error: "Network unavailable" },
+ packages: { numpy: "failed" },
+ logs: { numpy: "Selected logs\n" },
+ };
+ const other: EnvironmentOperation = {
+ ...selected,
+ operation_id: "other",
+ source: source === "kernel" ? "server" : "kernel",
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: { numpy: "Other logs\n" },
+ };
+ const snapshot = (operation: EnvironmentOperation) =>
+ result.current.setEnvironment({
+ source: operation.source,
+ state: { restart_required: false, operations: [operation] },
+ });
+ act(() => snapshot(selected));
+ for (const operations of [
+ [selected, other],
+ [other, selected],
+ ]) {
+ act(() => operations.forEach(snapshot));
+ expect(getPackageAlert(store.get(alertAtom))).toEqual({
+ ...selected,
+ id: selected.operation_id,
+ kind: "environment",
+ restartRequired: false,
+ });
+ }
+
+ // Live work in the other environment should still take over the banner.
+ const active: EnvironmentOperation = {
+ ...other,
+ operation_id: "new-work",
+ status: { kind: "running" },
+ packages: { numpy: "running" },
+ logs: { numpy: "Installing\n" },
+ };
+ act(() =>
+ result.current.updateEnvironment({ ...active, log_mode: "replace" }),
+ );
+ act(() => snapshot(selected));
+ expect(getPackageAlert(store.get(alertAtom))?.id).toBe(active.operation_id);
+ act(() =>
+ result.current.updateEnvironment({
+ ...active,
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: {},
+ log_mode: "append",
+ }),
+ );
+ act(() => snapshot(selected));
+ expect(getPackageAlert(store.get(alertAtom))).toEqual({
+ ...active,
+ id: active.operation_id,
+ kind: "environment",
+ restartRequired: false,
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ });
+
+ // Replacing that environment with an empty snapshot removes its selection.
+ act(() =>
+ result.current.setEnvironment({
+ source: active.source,
+ state: { restart_required: false, operations: [] },
+ }),
+ );
+ expect(getPackageAlert(store.get(alertAtom))?.id).toBe(
+ selected.operation_id,
+ );
+ act(() =>
+ result.current.updateEnvironment({
+ ...other,
+ operation_id: "latest-result",
+ log_mode: "replace",
+ }),
+ );
+ expect(getPackageAlert(store.get(alertAtom))?.id).toBe("latest-result");
+ },
+);
diff --git a/frontend/src/core/alerts/environment.ts b/frontend/src/core/alerts/environment.ts
new file mode 100644
index 0000000000..1673d2fca9
--- /dev/null
+++ b/frontend/src/core/alerts/environment.ts
@@ -0,0 +1,57 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { NotificationMessageData, schemas } from "@/core/kernel/messages";
+
+export type EnvironmentState = schemas["EnvironmentState"];
+export type EnvironmentOperation = schemas["EnvironmentOperation"];
+export type EnvironmentSource = EnvironmentOperation["source"];
+
+export function emptyEnvironmentState(): EnvironmentState {
+ return { restart_required: false, operations: [] };
+}
+
+/** Apply a live delta after the connection's authoritative snapshot. */
+export function reduceEnvironmentState(
+ state: EnvironmentState,
+ update: NotificationMessageData<"environment-operation">,
+): EnvironmentState {
+ const previous = state.operations.find(
+ (operation) => operation.operation_id === update.operation_id,
+ );
+ const logs = { ...previous?.logs };
+ for (const [name, content] of Object.entries(update.logs)) {
+ logs[name] =
+ update.log_mode === "replace" ? content : (logs[name] ?? "") + content;
+ }
+
+ const operation: EnvironmentOperation = {
+ operation_id: update.operation_id,
+ action: update.action,
+ status: update.status,
+ packages: update.packages,
+ logs,
+ source: update.source,
+ };
+ const operations = state.operations.filter(
+ (item) =>
+ (previous && update.status.kind === "running") ||
+ item.status.kind === "running" ||
+ (item.action === "prepare" && update.action !== "prepare"),
+ );
+ const index = operations.findIndex(
+ (item) => item.operation_id === update.operation_id,
+ );
+ if (index === -1) {
+ operations.push(operation);
+ } else {
+ operations[index] = operation;
+ }
+
+ return {
+ restart_required:
+ state.restart_required ||
+ update.status.kind === "restart-required" ||
+ Object.values(update.packages).includes("restart-required"),
+ operations,
+ };
+}
diff --git a/frontend/src/core/alerts/state.ts b/frontend/src/core/alerts/state.ts
index 349403d955..260a70869a 100644
--- a/frontend/src/core/alerts/state.ts
+++ b/frontend/src/core/alerts/state.ts
@@ -1,9 +1,16 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { useAtomValue } from "jotai";
-import type { PackageInstallationStatus } from "@/core/kernel/messages";
+import type { NotificationMessageData } from "@/core/kernel/messages";
import { createReducerAndAtoms } from "@/utils/createReducer";
import { generateUUID } from "@/utils/uuid";
+import {
+ emptyEnvironmentState,
+ type EnvironmentOperation,
+ type EnvironmentSource,
+ type EnvironmentState,
+ reduceEnvironmentState,
+} from "./environment";
type Identified<T> = { id: string } & T;
@@ -14,12 +21,18 @@ export interface MissingPackageAlert {
source?: "kernel" | "server";
}
-export interface InstallingPackageAlert {
- kind: "installing";
- packages: PackageInstallationStatus;
- logs?: { [key: string]: string } | null;
- log_status?: "append" | "start" | "done" | null;
- source?: "kernel" | "server";
+export interface EnvironmentOperationAlert extends EnvironmentOperation {
+ action: "install" | "remove";
+ kind: "environment";
+ restartRequired: boolean;
+}
+
+function isPackageOperation(
+ operation: EnvironmentOperation,
+): operation is EnvironmentOperation & {
+ action: EnvironmentOperationAlert["action"];
+} {
+ return operation.action === "install" || operation.action === "remove";
}
export interface StartupLogsAlert {
@@ -28,118 +41,161 @@ export interface StartupLogsAlert {
}
export function isMissingPackageAlert(
- alert: MissingPackageAlert | InstallingPackageAlert,
+ alert: MissingPackageAlert | EnvironmentOperationAlert,
): alert is MissingPackageAlert {
return alert.kind === "missing";
}
-export function isInstallingPackageAlert(
- alert: MissingPackageAlert | InstallingPackageAlert,
-): alert is InstallingPackageAlert {
- return alert.kind === "installing";
+export function isEnvironmentOperationAlert(
+ alert: MissingPackageAlert | EnvironmentOperationAlert,
+): alert is EnvironmentOperationAlert {
+ return alert.kind === "environment";
}
-/** Prominent alerts.
- *
- * Right now we only have one type of alert.
- */
interface AlertState {
packageAlert:
| Identified<MissingPackageAlert>
- | Identified<InstallingPackageAlert>
+ | { kind: "environment"; id: string; source: EnvironmentSource }
| null;
+ environments: Record<EnvironmentSource, EnvironmentState>;
startupLogsAlert: StartupLogsAlert | null;
- packageLogs: { [packageName: string]: string };
}
-const { valueAtom: alertAtom, useActions } = createReducerAndAtoms(
- () =>
- ({
- packageAlert: null,
- startupLogsAlert: null,
- packageLogs: {},
- }) as AlertState,
- {
- addPackageAlert: (
- state,
- alert: MissingPackageAlert | InstallingPackageAlert,
- ) => {
- const newPackageLogs = { ...state.packageLogs };
-
- // Handle streaming logs for installing package alerts
- if (isInstallingPackageAlert(alert) && alert.logs && alert.log_status) {
- for (const [packageName, newContent] of Object.entries(alert.logs)) {
- switch (alert.log_status) {
- case "start":
- // Start new log for this package
- newPackageLogs[packageName] = newContent;
-
- break;
-
- case "append": {
- // Append to existing log
- const prevContent = newPackageLogs[packageName] || "";
- newPackageLogs[packageName] = prevContent + newContent;
-
- break;
- }
- case "done": {
- // Append final content and mark as done
- const prevContent = newPackageLogs[packageName] || "";
- newPackageLogs[packageName] = prevContent + newContent;
-
- break;
- }
- // No default
- }
+function setEnvironment(
+ state: AlertState,
+ source: EnvironmentSource,
+ environment: EnvironmentState,
+): AlertState {
+ // Sandbox preparation and sync use the existing sandbox UI.
+ const environments = { ...state.environments, [source]: environment };
+ const operations = Object.values(environments)
+ .flatMap((item) => item.operations)
+ .filter(isPackageOperation);
+ const incoming = environment.operations.filter(isPackageOperation);
+ const alert = state.packageAlert;
+ const selected =
+ alert?.kind === "environment"
+ ? operations.find(
+ (item) =>
+ item.operation_id === alert.id && item.source === alert.source,
+ )
+ : undefined;
+ // A snapshot restores work and unresolved issues, not old success banners.
+ const needsAttention = (operation: EnvironmentOperation) =>
+ operation.status.kind !== "succeeded" ||
+ environments[operation.source].restart_required;
+ const operation =
+ (selected?.status.kind === "running" ? selected : undefined) ??
+ incoming.findLast((item) => item.status.kind === "running") ??
+ operations.findLast((item) => item.status.kind === "running") ??
+ selected ??
+ incoming.findLast(needsAttention) ??
+ operations.findLast(needsAttention);
+ return {
+ ...state,
+ environments,
+ packageAlert: operation
+ ? {
+ kind: "environment",
+ id: operation.operation_id,
+ source: operation.source,
}
- }
-
- const existingAlert = state.packageAlert;
- const alertId = existingAlert?.id || generateUUID();
+ : state.packageAlert?.kind === "missing"
+ ? state.packageAlert
+ : null,
+ };
+}
- return {
+export const { valueAtom: alertAtom, useActions: useAlertActions } =
+ createReducerAndAtoms(
+ (): AlertState => ({
+ packageAlert: null,
+ startupLogsAlert: null,
+ environments: {
+ kernel: emptyEnvironmentState(),
+ server: emptyEnvironmentState(),
+ },
+ }),
+ {
+ addMissingPackageAlert: (state, alert: MissingPackageAlert) => ({
...state,
- packageAlert: { id: alertId, ...alert },
- packageLogs: newPackageLogs,
- };
- },
-
- clearPackageAlert: (state, id: string) => {
- return state.packageAlert !== null && state.packageAlert.id === id
- ? { ...state, packageAlert: null, packageLogs: {} }
- : state;
- },
-
- addStartupLog: (
- state,
- logData: { content: string; status: "append" | "start" | "done" },
- ) => {
- const prevContent = state.startupLogsAlert?.content || "";
- return {
+ packageAlert: { id: generateUUID(), ...alert },
+ }),
+
+ updateEnvironment: (
+ state,
+ update: NotificationMessageData<"environment-operation">,
+ ) => {
+ const source = update.source;
+ const environment = reduceEnvironmentState(
+ state.environments[source],
+ update,
+ );
+ if (!isPackageOperation(update)) {
+ return {
+ ...state,
+ environments: { ...state.environments, [source]: environment },
+ };
+ }
+ return setEnvironment(
+ {
+ ...state,
+ packageAlert: {
+ kind: "environment",
+ id: update.operation_id,
+ source,
+ },
+ },
+ source,
+ environment,
+ );
+ },
+
+ setEnvironment: (
+ state,
+ snapshot: NotificationMessageData<"environment-state">,
+ ) => setEnvironment(state, snapshot.source, snapshot.state),
+
+ clearPackageAlert: (state, id: string) =>
+ state.packageAlert?.id === id
+ ? { ...state, packageAlert: null }
+ : state,
+
+ addStartupLog: (
+ state,
+ logData: { content: string; status: "append" | "start" | "done" },
+ ) => ({
...state,
startupLogsAlert: {
- ...state.startupLogsAlert,
- content: prevContent + logData.content,
+ content: (state.startupLogsAlert?.content ?? "") + logData.content,
status: logData.status,
},
- };
- },
+ }),
- clearStartupLogsAlert: (state) => {
- return { ...state, startupLogsAlert: null };
+ clearStartupLogsAlert: (state) => ({ ...state, startupLogsAlert: null }),
},
- },
-);
-
-/**
- * React hook to get the Alert state.
- */
-export const useAlerts = () => useAtomValue(alertAtom);
-
-/**
- * React hook to get the Alerts actions.
- */
-export function useAlertActions() {
- return useActions();
+ );
+
+export function getPackageAlert(
+ state: AlertState,
+): Identified<MissingPackageAlert | EnvironmentOperationAlert> | null {
+ const alert = state.packageAlert;
+ if (alert?.kind !== "environment") {
+ return alert;
+ }
+ const environment = state.environments[alert.source];
+ const operation = environment.operations.find(
+ (item) => item.operation_id === alert.id,
+ );
+ return operation && isPackageOperation(operation)
+ ? { ...operation, ...alert, restartRequired: environment.restart_required }
+ : null;
+}
+
+export function useAlerts() {
+ const state = useAtomValue(alertAtom);
+ return {
+ packageAlert: getPackageAlert(state),
+ startupLogsAlert: state.startupLogsAlert,
+ };
}
diff --git a/frontend/src/core/islands/bootstrap.ts b/frontend/src/core/islands/bootstrap.ts
index 70c07d30d5..0292cd0682 100644
--- a/frontend/src/core/islands/bootstrap.ts
+++ b/frontend/src/core/islands/bootstrap.ts
@@ -181,7 +181,8 @@ function handleMessage(
// Unsupported operations in islands mode
case "banner":
case "missing-package-alert":
- case "installing-package-alert":
+ case "environment-operation":
+ case "environment-state":
case "completion-result":
case "reload":
case "focus-cell":
diff --git a/frontend/src/core/kernel/messages.ts b/frontend/src/core/kernel/messages.ts
index e0a1c1e903..6d074bfe99 100644
--- a/frontend/src/core/kernel/messages.ts
+++ b/frontend/src/core/kernel/messages.ts
@@ -36,8 +36,8 @@ export type CompletionResultMessage =
export type HumanReadableStatus = schemas["HumanReadableStatus"];
export type FunctionCallResultMessage =
NotificationMessageData<"function-call-result">;
-export type PackageInstallationStatus =
- schemas["InstallingPackageAlertNotification"]["packages"];
+export type PackageOperationStatus =
+ schemas["EnvironmentOperationNotification"]["packages"];
export type DataColumnPreview = NotificationMessageData<"data-column-preview">;
export type SQLTablePreview = NotificationMessageData<"sql-table-preview">;
export type SQLTableListPreview =
diff --git a/frontend/src/core/network/connection-notice.ts b/frontend/src/core/network/connection-notice.ts
index 7061ef398a..f25f4602f5 100644
--- a/frontend/src/core/network/connection-notice.ts
+++ b/frontend/src/core/network/connection-notice.ts
@@ -2,40 +2,69 @@
import { atom } from "jotai";
import { kernelStartupErrorAtom } from "@/core/errors/state";
import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";
-import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";
+import {
+ type ConnectionPhase,
+ WebSocketClosedReason,
+ WebSocketState,
+} from "@/core/websocket/types";
import { connectionAtom } from "./connection";
-export const connectionNoticeAtom = atom((get) => {
+export interface ConnectionNotice {
+ kind: "startup" | "sync" | "connection";
+ phase?: ConnectionPhase;
+ sandbox: boolean;
+ title: string;
+ description: string;
+ pending: boolean;
+ error: string | null;
+}
+
+export const connectionNoticeAtom = atom<ConnectionNotice | null>((get) => {
const connection = get(connectionAtom);
const backend = get(sandboxAtom)?.backend;
const sandbox = Boolean(backend);
const sync = get(sandboxSyncAtom);
+ const syncing = sync.kind === "running";
+ const restartRequired = sync.kind === "restart-required";
+ const syncError =
+ sync.kind === "failed"
+ ? sync.error
+ : sync.kind === "cancelled"
+ ? "Sandbox sync was interrupted."
+ : restartRequired
+ ? sync.reason
+ : null;
if (
sandbox &&
- (sync.pending || sync.error) &&
+ (syncing || syncError !== null) &&
connection.state === WebSocketState.OPEN
) {
return {
+ kind: "sync",
sandbox,
- title: sync.pending ? "Syncing sandbox…" : "Sandbox sync failed",
- description: sync.pending
+ title: syncing
+ ? "Syncing sandbox…"
+ : restartRequired
+ ? "Sandbox restart required"
+ : "Sandbox sync failed",
+ description: syncing
? "Applying the saved manifest to this notebook’s environment."
- : "Review the error details, then try again.",
- pending: sync.pending,
- error: sync.error,
+ : restartRequired
+ ? "Restart the kernel to use the updated environment."
+ : "Review the error details, then try again.",
+ pending: syncing,
+ error: syncError,
};
}
if (connection.state === WebSocketState.CONNECTING) {
const messages = {
"preparing-environment": {
- title: backend
- ? `Preparing ${backend} sandbox…`
- : "Preparing environment…",
+ title: "Preparing environment…",
description:
"Getting this notebook’s Python environment ready. The first start can take a few minutes.",
},
"starting-kernel": {
- title: "Starting notebook…",
+ title: "Starting kernel…",
description:
"The environment is prepared. Waiting for the Python kernel to connect to this notebook.",
},
@@ -46,6 +75,8 @@ export const connectionNoticeAtom = atom((get) => {
},
};
return {
+ kind: connection.phase === "reconnecting" ? "connection" : "startup",
+ phase: connection.phase,
sandbox,
...(connection.phase
? messages[connection.phase]
@@ -63,6 +94,8 @@ export const connectionNoticeAtom = atom((get) => {
const environmentFailed =
startupFailed && connection.phase === "preparing-environment";
return {
+ kind: startupFailed ? "startup" : "connection",
+ phase: connection.phase,
sandbox,
title: environmentFailed
? "Sandbox setup failed"
diff --git a/frontend/src/core/network/connection.ts b/frontend/src/core/network/connection.ts
index df234c4981..27c8c79e9b 100644
--- a/frontend/src/core/network/connection.ts
+++ b/frontend/src/core/network/connection.ts
@@ -1,5 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { atom } from "jotai";
+import { atomWithReducer } from "jotai/utils";
+import type { NotificationMessageData } from "../kernel/messages";
import { isNotebookPage } from "../mode";
import { waitFor } from "../state/jotai";
import { type ConnectionStatus, WebSocketState } from "../websocket/types";
@@ -12,6 +14,23 @@ export const connectionAtom = atom<ConnectionStatus>({
state: WebSocketState.NOT_STARTED,
});
+type StartupProgress = NotificationMessageData<"startup-progress">;
+
+export const startupProgressAtom = atomWithReducer<
+ Pick<StartupProgress, "phase" | "logs"> | null,
+ StartupProgress | null
+>(null, (previous, update: StartupProgress | null) =>
+ update === null
+ ? null
+ : {
+ phase: update.phase,
+ logs:
+ update.log_mode === "append" && previous?.phase === update.phase
+ ? previous.logs + update.logs
+ : update.logs,
+ },
+);
+
export function waitForConnectionOpen() {
return waitFor(connectionAtom, (value) => {
return value.state === WebSocketState.OPEN;
diff --git a/frontend/src/core/network/useConnectionNotice.ts b/frontend/src/core/network/useConnectionNotice.ts
new file mode 100644
index 0000000000..c41dbcd175
--- /dev/null
+++ b/frontend/src/core/network/useConnectionNotice.ts
@@ -0,0 +1,53 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtomValue } from "jotai";
+import { useEffect, useState } from "react";
+import { useDelayElapsed } from "@/hooks/useDelayElapsed";
+import { isConnectedAtom } from "./connection";
+import {
+ type ConnectionNotice,
+ connectionNoticeAtom,
+} from "./connection-notice";
+
+export type DisplayConnectionNotice = ConnectionNotice & { ready: boolean };
+
+/** Briefly acknowledge completion, but only for setup the user actually saw. */
+export function useConnectionNotice(
+ delayMs = 500,
+): DisplayConnectionNotice | null {
+ const notice = useAtomValue(connectionNoticeAtom);
+ const connected = useAtomValue(isConnectedAtom);
+ const elapsed = useDelayElapsed(notice?.pending ? delayMs : 0);
+ const [previous, setPrevious] = useState<ConnectionNotice | null>(null);
+
+ useEffect(() => {
+ if (notice || !connected) {
+ setPrevious(elapsed ? notice : null);
+ return;
+ }
+ const timeout = setTimeout(() => setPrevious(null), 1500);
+ return () => clearTimeout(timeout);
+ }, [notice, connected, elapsed]);
+
+ if (notice) {
+ return elapsed ? { ...notice, ready: false } : null;
+ }
+ if (
+ connected &&
+ previous?.pending &&
+ previous.sandbox &&
+ previous.kind !== "connection"
+ ) {
+ return {
+ ...previous,
+ pending: false,
+ ready: true,
+ title:
+ previous.kind === "sync"
+ ? "Environment synced"
+ : "Your notebook is ready",
+ description: "The notebook is ready to run.",
+ error: null,
+ };
+ }
+ return null;
+}
diff --git a/frontend/src/core/packages/__tests__/useSandboxController.test.tsx b/frontend/src/core/packages/__tests__/useSandboxController.test.tsx
index 7343e85119..4681520f75 100644
--- a/frontend/src/core/packages/__tests__/useSandboxController.test.tsx
+++ b/frontend/src/core/packages/__tests__/useSandboxController.test.tsx
@@ -3,6 +3,11 @@ import { act, renderHook, waitFor } from "@testing-library/react";
import { Provider } from "jotai";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { MockRequestClient } from "@/__mocks__/requests";
+import {
+ emptyEnvironmentState,
+ type EnvironmentOperation,
+} from "@/core/alerts/environment";
+import { alertAtom } from "@/core/alerts/state";
import { kernelStartupErrorAtom } from "@/core/errors/state";
import { connectionAtom } from "@/core/network/connection";
import { requestClientAtom } from "@/core/network/requests";
@@ -25,6 +30,8 @@ import { useSandboxController } from "../useSandboxController";
vi.mock("../toast-components", () => ({
showPackageRestartToast: vi.fn(),
showSandboxSyncToast: vi.fn(),
+ RESTART_REQUIRED_DESCRIPTION:
+ "Restart the kernel to use the updated environment.",
}));
const manifest = 'dependencies = ["numpy"]';
@@ -35,8 +42,15 @@ const sandbox: SandboxResponse = {
};
beforeEach(() => {
+ store.set(alertAtom, (value) => ({
+ ...value,
+ environments: {
+ kernel: emptyEnvironmentState(),
+ server: emptyEnvironmentState(),
+ },
+ }));
store.set(sandboxAtom, null);
- store.set(sandboxSyncAtom, { pending: false, error: null });
+ store.set(sandboxSyncAtom, { kind: "succeeded" });
store.set(sandboxActionsAtom, null);
store.set(connectionAtom, { state: WebSocketState.OPEN });
store.set(kernelStartupErrorAtom, null);
@@ -65,6 +79,73 @@ function setup() {
}
describe("useSandboxController", () => {
+ it("preserves a restart-required response instead of reporting a failed sync", async () => {
+ const { client, result } = setup();
+ vi.mocked(client.syncSandbox).mockResolvedValue({
+ success: false,
+ restartRequired: true,
+ error: "Python version changed",
+ });
+ await act(async () => {
+ expect(await store.get(sandboxActionsAtom)?.sync()).toBe(false);
+ });
+ expect(store.get(sandboxSyncAtom)).toEqual({
+ kind: "restart-required",
+ reason: "Python version changed",
+ });
+ expect(result.current.pending).toBe(false);
+ expect(result.current.diagnostic).toBe("Python version changed");
+ });
+
+ it("restores sync progress and lets a retry replace the restored failure", async () => {
+ const operation: EnvironmentOperation = {
+ operation_id: "sync",
+ action: "sync",
+ source: "kernel",
+ status: { kind: "running" },
+ packages: {},
+ logs: {},
+ };
+ const restore = (status: EnvironmentOperation["status"]) =>
+ store.set(alertAtom, (value) => ({
+ ...value,
+ environments: {
+ ...value.environments,
+ kernel: {
+ restart_required: false,
+ operations: [{ ...operation, status }],
+ },
+ },
+ }));
+ restore({ kind: "running" });
+ const { client, result } = setup();
+ const actions = store.get(sandboxActionsAtom)!;
+ expect(result.current.pending).toBe(true);
+ await act(async () => {
+ expect(await actions.sync()).toBe(false);
+ });
+ expect(client.syncSandbox).not.toHaveBeenCalled();
+ act(() => restore({ kind: "failed", error: "Dependency conflict" }));
+ expect(result.current.diagnostic).toBe("Dependency conflict");
+
+ const { promise, resolve } = Promise.withResolvers<SyncSandboxResponse>();
+ vi.mocked(client.syncSandbox).mockReturnValue(promise);
+ let pending: Promise<boolean>;
+ act(() => {
+ pending = actions.sync();
+ });
+ expect(store.get(sandboxSyncAtom)).toEqual({ kind: "running" });
+ act(() => restore({ kind: "running" }));
+ await act(async () => {
+ resolve({ success: true, reconnect: false });
+ expect(await pending).toBe(true);
+ });
+ // The response can arrive before the final websocket notification.
+ expect(store.get(sandboxSyncAtom)).toEqual({ kind: "running" });
+ act(() => restore({ kind: "succeeded" }));
+ expect(store.get(sandboxSyncAtom)).toEqual({ kind: "succeeded" });
+ });
+
it("keeps a conflicting draft across closing and only discards it on explicit reload", async () => {
const { result, client } = setup();
vi.mocked(client.updateManifest).mockRejectedValue(
@@ -116,7 +197,7 @@ describe("useSandboxController", () => {
act(() => {
pending = actions.sync();
});
- expect(store.get(sandboxSyncAtom)).toEqual({ pending: true, error: null });
+ expect(store.get(sandboxSyncAtom)).toEqual({ kind: "running" });
await act(async () => {
expect(await actions.sync()).toBe(false);
});
@@ -125,7 +206,7 @@ describe("useSandboxController", () => {
resolve({ success: true, reconnect: false });
expect(await pending).toBe(true);
});
- expect(store.get(sandboxSyncAtom)).toEqual({ pending: false, error: null });
+ expect(store.get(sandboxSyncAtom)).toEqual({ kind: "succeeded" });
expect(store.get(packageDataVersionAtom)).toBe(1);
expect(reconnect).not.toHaveBeenCalled();
});
@@ -138,13 +219,13 @@ describe("useSandboxController", () => {
expect(await actions.sync()).toBe(false);
});
expect(store.get(sandboxSyncAtom)).toEqual({
- pending: false,
+ kind: "failed",
error: "offline",
});
await act(async () => {
expect(await actions.sync()).toBe(true);
});
- expect(store.get(sandboxSyncAtom)).toEqual({ pending: false, error: null });
+ expect(store.get(sandboxSyncAtom)).toEqual({ kind: "succeeded" });
});
it("ignores stale metadata after a filename change and unregisters actions on unmount", async () => {
diff --git a/frontend/src/core/packages/sandbox-state.ts b/frontend/src/core/packages/sandbox-state.ts
index dbf66d26e5..fb78f3caa9 100644
--- a/frontend/src/core/packages/sandbox-state.ts
+++ b/frontend/src/core/packages/sandbox-state.ts
@@ -1,12 +1,64 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { atom } from "jotai";
+import type { EnvironmentOperation } from "@/core/alerts/environment";
+import { alertAtom } from "@/core/alerts/state";
import type { SandboxResponse } from "@/core/network/types";
export const sandboxAtom = atom<SandboxResponse | null>(null);
-export const sandboxSyncAtom = atom<{ pending: boolean; error: string | null }>(
- {
- pending: false,
- error: null,
+
+export const preparationAtom = atom((get) =>
+ get(alertAtom).environments.kernel.operations.findLast(
+ (operation) => operation.action === "prepare",
+ ),
+);
+
+type SandboxSyncState = EnvironmentOperation["status"] | { kind: "idle" };
+
+export const sandboxSyncOperationAtom = atom((get) => {
+ const operations = get(alertAtom).environments.kernel.operations;
+ return (
+ operations.findLast(
+ (operation) =>
+ operation.action === "sync" && operation.status.kind === "running",
+ ) ?? operations.findLast((operation) => operation.action === "sync")
+ );
+});
+
+const sandboxSyncRequestAtom = atom<{
+ state: SandboxSyncState;
+ operation: EnvironmentOperation | undefined;
+} | null>(null);
+
+export const sandboxSyncAtom = atom(
+ (get): SandboxSyncState => {
+ const operation = get(sandboxSyncOperationAtom);
+ const request = get(sandboxSyncRequestAtom);
+ // Local request status lasts until newer progress arrives from the server.
+ const state: SandboxSyncState =
+ request &&
+ request.operation === operation &&
+ operation?.status.kind !== "running"
+ ? request.state
+ : (operation?.status ?? { kind: "idle" });
+ // Later package operations can replace the sync result, but only a new
+ // environment snapshot can clear an outstanding restart.
+ if (
+ get(alertAtom).environments.kernel.restart_required &&
+ (state.kind === "idle" || state.kind === "succeeded")
+ ) {
+ return {
+ kind: "restart-required",
+ reason:
+ "Dependency changes are saved; restart the kernel to apply them.",
+ };
+ }
+ return state;
+ },
+ (get, set, state: SandboxSyncState) => {
+ set(sandboxSyncRequestAtom, {
+ state,
+ operation: get(sandboxSyncOperationAtom),
+ });
},
);
export const sandboxActionsAtom = atom<{
diff --git a/frontend/src/core/packages/useSandboxController.ts b/frontend/src/core/packages/useSandboxController.ts
index 059cbc8e1d..4195359838 100644
--- a/frontend/src/core/packages/useSandboxController.ts
+++ b/frontend/src/core/packages/useSandboxController.ts
@@ -17,6 +17,7 @@ import {
sandboxSyncAtom,
} from "./sandbox-state";
import {
+ RESTART_REQUIRED_DESCRIPTION,
showPackageRestartToast,
showSandboxSyncToast,
} from "./toast-components";
@@ -63,15 +64,24 @@ export function useSandboxController(onReconnect: () => Promise<void>) {
}, [requests, filename, connection.state, setSandbox]);
const sync = useEvent(async () => {
- if (inFlight.current || connection.state === WebSocketState.CONNECTING) {
+ if (
+ inFlight.current ||
+ operation.kind === "running" ||
+ connection.state === WebSocketState.CONNECTING
+ ) {
return false;
}
inFlight.current = true;
- setOperation((value) => ({ ...value, pending: true, error: null }));
+ setOperation({ kind: "running" });
try {
const result = await requests.syncSandbox({ fileKey: filename });
if (result.restartRequired) {
+ setOperation({
+ kind: "restart-required",
+ reason: result.error ?? RESTART_REQUIRED_DESCRIPTION,
+ });
showPackageRestartToast();
+ return false;
}
if (!result.success) {
throw new Error(result.error ?? "Sandbox sync failed.");
@@ -85,6 +95,7 @@ export function useSandboxController(onReconnect: () => Promise<void>) {
value.state === WebSocketState.CLOSED,
);
if (status.state === WebSocketState.CLOSED) {
+ setOperation({ kind: "idle" });
return false;
}
}
@@ -92,13 +103,13 @@ export function useSandboxController(onReconnect: () => Promise<void>) {
invalidatePackageData();
}
showSandboxSyncToast();
+ setOperation({ kind: "succeeded" });
return true;
} catch (cause) {
- setOperation((value) => ({ ...value, error: prettyError(cause) }));
+ setOperation({ kind: "failed", error: prettyError(cause) });
return false;
} finally {
inFlight.current = false;
- setOperation((value) => ({ ...value, pending: false }));
}
});
@@ -135,7 +146,7 @@ export function useSandboxController(onReconnect: () => Promise<void>) {
}, [sync, editManifest, setActions]);
const saveAndSync = async () => {
- if (!document || loading || saving || operation.pending) {
+ if (!document || loading || saving || operation.kind === "running") {
return;
}
setSaving(true);
@@ -165,9 +176,18 @@ export function useSandboxController(onReconnect: () => Promise<void>) {
const pending =
saving ||
loading ||
- operation.pending ||
+ operation.kind === "running" ||
connection.state === WebSocketState.CONNECTING;
- const diagnostic = error ?? operation.error ?? startupError;
+ const diagnostic =
+ error ??
+ (operation.kind === "failed"
+ ? operation.error
+ : operation.kind === "restart-required"
+ ? operation.reason
+ : operation.kind === "cancelled"
+ ? "Sandbox sync was interrupted."
+ : null) ??
+ startupError;
return {
filename,
open,
diff --git a/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx b/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx
index 523deb3f90..550211f036 100644
--- a/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx
+++ b/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx
@@ -42,6 +42,7 @@ vi.mock("@/core/runtime/config", async () => {
import { MockNotebook } from "@/__mocks__/notebook";
import { cellId } from "@/__tests__/branded";
+import { alertAtom, getPackageAlert } from "@/core/alerts/state";
import { notebookAtom } from "@/core/cells/cells";
import { AppConfigSchema } from "@/core/config/config-schema";
import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
@@ -49,7 +50,7 @@ import { kernelStartupErrorAtom } from "@/core/errors/state";
import type { NotificationPayload } from "@/core/kernel/messages";
import { useRuntimeManager } from "@/core/runtime/config";
import { initialRunCompletedAtom } from "../../kernel/state";
-import { connectionAtom } from "../../network/connection";
+import { connectionAtom, startupProgressAtom } from "../../network/connection";
import type { SessionId } from "../../kernel/session";
import { WebSocketClosedReason, WebSocketState } from "../types";
import type { IConnectionTransport } from "../transports/transport";
@@ -306,7 +307,12 @@ describe("connection notice", () => {
it("keeps elapsed time across startup phases and leaves reconnection to the footer once cells are available", () => {
const { store, options, send } = renderNotice();
- send({ op: "startup-progress", phase: "preparing-environment" });
+ send({
+ op: "startup-progress",
+ phase: "preparing-environment",
+ logs: "",
+ log_mode: "replace",
+ });
expect(
screen.queryByRole("region", { name: "Notebook startup" }),
).not.toBeInTheDocument();
@@ -324,8 +330,13 @@ describe("connection notice", () => {
}),
),
);
- send({ op: "startup-progress", phase: "starting-kernel" });
- expect(screen.getByRole("status")).toHaveTextContent("Starting notebook");
+ send({
+ op: "startup-progress",
+ phase: "starting-kernel",
+ logs: "",
+ log_mode: "replace",
+ });
+ expect(screen.getByRole("status")).toHaveTextContent("Starting kernel");
expect(screen.getByText("Elapsed 35s")).toBeInTheDocument();
send({ op: "reconnected" });
expect(
@@ -342,11 +353,71 @@ describe("connection notice", () => {
).not.toBeInTheDocument();
});
+ it("restores startup output before appending live chunks and resets it for a new attempt", () => {
+ const { store, send } = renderNotice();
+ const snapshot = {
+ op: "startup-progress",
+ phase: "starting-kernel",
+ logs: "Downloading runtime\n",
+ log_mode: "replace",
+ } as const;
+ send(snapshot);
+ send(snapshot);
+ const connection = store.get(connectionAtom);
+ send({ ...snapshot, logs: "Loading kernel\n", log_mode: "append" });
+ expect(store.get(startupProgressAtom)).toEqual({
+ phase: "starting-kernel",
+ logs: "Downloading runtime\nLoading kernel\n",
+ });
+ expect(store.get(connectionAtom)).toBe(connection);
+ expect(getPackageAlert(store.get(alertAtom))).toBeNull();
+
+ send({ ...snapshot, phase: "preparing-environment", logs: "" });
+ expect(store.get(startupProgressAtom)).toEqual({
+ phase: "preparing-environment",
+ logs: "",
+ });
+ });
+
+ it("restores completed startup output without putting a connected kernel back into startup", async () => {
+ const { store, options, send } = renderNotice();
+ send({ op: "reconnected" });
+ send({
+ op: "startup-progress",
+ phase: "starting-kernel",
+ logs: "Kernel startup output\n",
+ log_mode: "replace",
+ });
+ expect(store.get(connectionAtom)).toEqual({ state: WebSocketState.OPEN });
+ expect(store.get(startupProgressAtom)).toEqual({
+ phase: "starting-kernel",
+ logs: "Kernel startup output\n",
+ });
+ act(() => vi.advanceTimersByTime(500));
+ expect(
+ screen.queryByRole("region", { name: "Notebook startup" }),
+ ).not.toBeInTheDocument();
+
+ // A new transport starts from the next session's authoritative snapshot.
+ await act(async () => options.onOpen(new Event("open")));
+ expect(store.get(startupProgressAtom)).toBeNull();
+ });
+
it("does not flash a notice when startup finishes within the delay", () => {
const { send } = renderNotice();
- send({ op: "startup-progress", phase: "preparing-environment" });
+ send({
+ op: "startup-progress",
+ phase: "preparing-environment",
+ logs: "",
+ log_mode: "replace",
+ });
act(() => vi.advanceTimersByTime(200));
- send({ op: "startup-progress", phase: "starting-kernel" });
+ send({
+ op: "startup-progress",
+ phase: "starting-kernel",
+ logs: "",
+ log_mode: "replace",
+ });
act(() => vi.advanceTimersByTime(200));
expect(
screen.queryByRole("region", { name: "Notebook startup" }),
@@ -365,7 +436,7 @@ describe("connection notice", () => {
"keeps a %s failure available until the user retries",
async (phase, title) => {
const { store, transport, options, send } = renderNotice();
- send({ op: "startup-progress", phase });
+ send({ op: "startup-progress", phase, logs: "", log_mode: "replace" });
const error = "A full diagnostic\nwith <stderr> details";
send({ op: "kernel-startup-error", error });
transport.readyState = WebSocket.CLOSED;
@@ -389,7 +460,12 @@ describe("connection notice", () => {
expect(
screen.queryByRole("button", { name: "Try again" }),
).not.toBeInTheDocument();
- send({ op: "startup-progress", phase: "preparing-environment" });
+ send({
+ op: "startup-progress",
+ phase: "preparing-environment",
+ logs: "",
+ log_mode: "replace",
+ });
act(() => vi.advanceTimersByTime(500));
expect(screen.getByRole("status")).toHaveTextContent(
"Preparing environment",
@@ -398,3 +474,118 @@ describe("connection notice", () => {
},
);
});
+
+it("replaces environment state from snapshots, then continues live progress", () => {
+ const store = createStore();
+ vi.mocked(useConnectionTransport).mockClear();
+ vi.mocked(useConnectionTransport).mockReturnValue(
+ makeTransport(WebSocket.OPEN),
+ );
+ vi.mocked(useRuntimeManager).mockReturnValue(
+ makeRuntimeManager() as unknown as ReturnType<typeof useRuntimeManager>,
+ );
+ renderConnectionHook(store);
+ const options = vi.mocked(useConnectionTransport).mock.calls.at(-1)?.[0];
+ function receive(data: NotificationPayload["data"]) {
+ act(() =>
+ options?.onMessage(
+ new MessageEvent("message", {
+ data: JSON.stringify({ op: data.op, data }),
+ }),
+ ),
+ );
+ }
+ receive({
+ op: "environment-operation",
+ source: "kernel",
+ operation_id: "old",
+ action: "install",
+ status: { kind: "running" },
+ packages: { pandas: "running" },
+ logs: { pandas: "stale" },
+ log_mode: "append",
+ });
+ const operation = {
+ operation_id: "new",
+ action: "install",
+ source: "kernel",
+ status: { kind: "running" },
+ packages: { numpy: "running" },
+ logs: { numpy: "Downloading\n" },
+ } as const;
+ const serverOperation = {
+ ...operation,
+ operation_id: "server",
+ action: "install",
+ source: "server",
+ status: { kind: "succeeded" },
+ packages: { numpy: "succeeded" },
+ logs: { numpy: "Server logs\n" },
+ } as const;
+ receive({
+ op: "environment-state",
+ source: "server",
+ state: {
+ restart_required: false,
+ operations: [serverOperation],
+ },
+ });
+ const snapshot = {
+ op: "environment-state",
+ source: "kernel",
+ state: { restart_required: false, operations: [operation] },
+ } as const;
+ // Receiving a snapshot twice must not duplicate logs.
+ receive({
+ ...snapshot,
+ state: { ...snapshot.state, operations: [operation] },
+ });
+ receive({
+ ...snapshot,
+ state: { ...snapshot.state, operations: [operation] },
+ });
+ receive({
+ op: "environment-operation",
+ operation_id: "new",
+ action: "install",
+ source: "kernel",
+ status: { kind: "failed", error: "Network unavailable" },
+ packages: { numpy: "running" },
+ logs: { numpy: "Failed\n" },
+ log_mode: "append",
+ });
+ expect(getPackageAlert(store.get(alertAtom))).toEqual({
+ ...operation,
+ id: "new",
+ kind: "environment",
+ restartRequired: false,
+ status: { kind: "failed", error: "Network unavailable" },
+ logs: { numpy: "Downloading\nFailed\n" },
+ });
+ receive({
+ op: "environment-state",
+ source: "kernel",
+ state: {
+ restart_required: false,
+ operations: [],
+ },
+ });
+ // Clearing the active environment must not promote an old server success.
+ expect(getPackageAlert(store.get(alertAtom))).toBeNull();
+ expect(store.get(alertAtom).environments.server.operations).toEqual([
+ serverOperation,
+ ]);
+ receive({
+ op: "environment-state",
+ source: "server",
+ state: {
+ restart_required: false,
+ operations: [],
+ },
+ });
+ expect(getPackageAlert(store.get(alertAtom))).toBeNull();
+ expect(store.get(alertAtom).environments).toEqual({
+ kernel: { restart_required: false, operations: [] },
+ server: { restart_required: false, operations: [] },
+ });
+});
diff --git a/frontend/src/core/websocket/types.ts b/frontend/src/core/websocket/types.ts
index 5cd37223e2..09a67d6e90 100644
--- a/frontend/src/core/websocket/types.ts
+++ b/frontend/src/core/websocket/types.ts
@@ -2,7 +2,7 @@
import type { NotificationMessageData } from "../kernel/messages";
-type ConnectionPhase =
+export type ConnectionPhase =
| NotificationMessageData<"startup-progress">["phase"]
| "reconnecting";
diff --git a/frontend/src/core/websocket/useMarimoKernelConnection.tsx b/frontend/src/core/websocket/useMarimoKernelConnection.tsx
index 8f4e8a3f5c..0548beeb61 100644
--- a/frontend/src/core/websocket/useMarimoKernelConnection.tsx
+++ b/frontend/src/core/websocket/useMarimoKernelConnection.tsx
@@ -64,7 +64,7 @@ import type { SessionId } from "../kernel/session";
import { initialRunCompletedAtom, kernelStateAtom } from "../kernel/state";
import { type LayoutState, useLayoutActions } from "../layout/state";
import { kioskModeAtom } from "../mode";
-import { connectionAtom } from "../network/connection";
+import { connectionAtom, startupProgressAtom } from "../network/connection";
import type { RequestId } from "../network/DeferredRequestRegistry";
import { useRuntimeManager } from "../runtime/config";
import { SECRETS_REGISTRY } from "../secrets/request-registry";
@@ -222,8 +222,14 @@ export function useMarimoKernelConnection(opts: {
useDataSourceActions();
const { setLayoutData } = useLayoutActions();
const [connection, setConnection] = useAtom(connectionAtom);
+ const updateStartupProgress = useSetAtom(startupProgressAtom);
const { addBanner } = useBannersActions();
- const { addPackageAlert, addStartupLog } = useAlertActions();
+ const {
+ addMissingPackageAlert,
+ updateEnvironment,
+ setEnvironment,
+ addStartupLog,
+ } = useAlertActions();
const setKioskMode = useSetAtom(kioskModeAtom);
const setCapabilities = useSetAtom(capabilitiesAtom);
const runtimeManager = useRuntimeManager();
@@ -241,12 +247,18 @@ export function useMarimoKernelConnection(opts: {
case "reload":
reloadSafe();
return;
- case "startup-progress":
- setConnection({
- state: WebSocketState.CONNECTING,
- phase: msg.data.phase,
- });
+ case "startup-progress": {
+ const { phase } = msg.data;
+ updateStartupProgress(msg.data);
+ setConnection((previous) =>
+ previous.state === WebSocketState.OPEN ||
+ (previous.state === WebSocketState.CONNECTING &&
+ previous.phase === phase)
+ ? previous
+ : { state: WebSocketState.CONNECTING, phase },
+ );
return;
+ }
case "kernel-ready": {
setKernelStartupError(null);
setConnection({ state: WebSocketState.OPEN });
@@ -366,26 +378,25 @@ export function useMarimoKernelConnection(opts: {
addBanner(msg.data);
return;
case "missing-package-alert":
- addPackageAlert({
+ addMissingPackageAlert({
...msg.data,
kind: "missing",
});
return;
- case "installing-package-alert":
+ case "environment-operation":
if (
- msg.data.source !== "server" &&
- msg.data.log_status !== "append" &&
- msg.data.log_status !== "start" &&
- Object.values(msg.data.packages).some(
- (status) => status === "installed" || status === "restart-required",
- )
+ msg.data.source === "kernel" &&
+ msg.data.status.kind !== "running"
) {
invalidatePackageData();
}
- addPackageAlert({
- ...msg.data,
- kind: "installing",
- });
+ updateEnvironment(msg.data);
+ return;
+ case "environment-state":
+ setEnvironment(msg.data);
+ if (msg.data.source === "kernel") {
+ invalidatePackageData();
+ }
return;
case "startup-logs":
addStartupLog({
@@ -538,6 +549,7 @@ export function useMarimoKernelConnection(opts: {
* The transport is open; kernel-ready establishes session readiness.
*/
onOpen: async () => {
+ updateStartupProgress(null);
// If we are open, we can reset our reconnecting flag.
shouldTryReconnecting.current = true;
},
diff --git a/frontend/src/stories/sandbox.stories.tsx b/frontend/src/stories/sandbox.stories.tsx
index d13f596837..d84bc2ab3d 100644
--- a/frontend/src/stories/sandbox.stories.tsx
+++ b/frontend/src/stories/sandbox.stories.tsx
@@ -3,14 +3,15 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
import { createStore, Provider, useAtomValue } from "jotai";
import { useEffect, useRef, useState } from "react";
import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
-import {
- SandboxFooter,
- SandboxStartupPanel,
-} from "@/components/editor/chrome/panels/sandbox-panel";
+import PackagesPanel from "@/components/editor/chrome/panels/packages-panel";
+import { PanelSectionProvider } from "@/components/editor/chrome/panels/panel-context";
+import { SandboxToggle } from "@/components/editor/chrome/panels/sandbox-toggle";
import { SandboxController } from "@/components/editor/chrome/panels/sandbox-controller";
import { chromeAtom } from "@/components/editor/chrome/state";
import { Cell } from "@/components/editor/notebook-cell";
import { VerticalLayoutWrapper } from "@/components/editor/renderers/vertical-layout/vertical-layout-wrapper";
+import { alertAtom } from "@/core/alerts/state";
+import type { EnvironmentOperation } from "@/core/alerts/environment";
import {
createNotebookActions,
notebookAtom,
@@ -18,18 +19,15 @@ import {
} from "@/core/cells/cells";
import { userConfigAtom } from "@/core/config/config";
import {
+ type AppConfig,
AppConfigSchema,
defaultUserConfig,
} from "@/core/config/config-schema";
import { kernelStartupErrorAtom } from "@/core/errors/state";
-import { connectionAtom } from "@/core/network/connection";
+import { connectionAtom, startupProgressAtom } from "@/core/network/connection";
import { requestClientAtom } from "@/core/network/requests";
import { createStaticRequests } from "@/core/network/requests-static";
-import {
- sandboxActionsAtom,
- sandboxAtom,
- sandboxSyncAtom,
-} from "@/core/packages/sandbox-state";
+import { sandboxActionsAtom, sandboxAtom } from "@/core/packages/sandbox-state";
import { filenameAtom } from "@/core/saving/file-state";
import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";
import { HTTPError } from "@/utils/errors";
@@ -46,6 +44,19 @@ description = "Explore bike trips"
const resolutionError = `No solution found when resolving dependencies:
Because there is no version of rich==999.0.0 and your script depends
on rich==999.0.0, your script's requirements are unsatisfiable.`;
+const preparationOutput = `Using Python 3.13
+Resolving notebook dependencies
+Resolved 24 packages
+Downloading polars
+Downloading rich
+Downloading marimo
+Downloading pyzmq
+Downloaded rich
+Downloaded polars
+Downloaded marimo
+Preparing packages
+Installing packages
+`;
interface Props {
surface: "notebook" | "packages" | "manifest";
@@ -55,11 +66,68 @@ interface Props {
| "failed"
| "ready"
| "syncing"
- | "sync-failed";
+ | "sync-failed"
+ | "synced"
+ | "restart-required";
existingCells: boolean;
backend: "uv" | "pixi";
saveResult: "success" | "failure" | "stale";
theme: "light" | "dark";
+ interactive: boolean;
+}
+
+function SandboxPreview({
+ props,
+ appConfig,
+ reconnect,
+}: {
+ props: Props;
+ appConfig: AppConfig;
+ reconnect: () => Promise<void>;
+}) {
+ const chrome = useAtomValue(chromeAtom);
+ const notebook = useAtomValue(notebookAtom);
+ const userConfig = useAtomValue(userConfigAtom);
+ const showPackages = props.surface === "packages" || chrome.isSidebarOpen;
+ return (
+ <div
+ className="flex bg-background text-foreground border rounded min-h-[460px]"
+ style={{ width: props.surface === "notebook" ? 1000 : 300 }}
+ data-testid="sandbox-story"
+ >
+ {showPackages && props.surface !== "manifest" && (
+ <aside className="flex flex-col w-[300px] shrink-0 border-r h-[520px]">
+ <div className="flex items-center justify-between px-3 py-2 border-b text-sm">
+ Packages
+ <SandboxToggle section="sidebar" />
+ </div>
+ <PanelSectionProvider value="sidebar">
+ <PackagesPanel />
+ </PanelSectionProvider>
+ </aside>
+ )}
+ {props.surface === "notebook" && (
+ <div className="flex-1 min-w-0 pt-12">
+ <ConnectionNotice appConfig={appConfig} onRetry={reconnect} />
+ {notebook.cellIds.inOrderIds.map((cellId) => (
+ <VerticalLayoutWrapper key={cellId} appConfig={appConfig}>
+ <Cell
+ cellId={cellId}
+ theme={props.theme}
+ mode="edit"
+ showPlaceholder={false}
+ canDelete={true}
+ isCollapsed={false}
+ collapseCount={0}
+ canMoveX={false}
+ userConfig={userConfig}
+ />
+ </VerticalLayoutWrapper>
+ ))}
+ </div>
+ )}
+ </div>
+ );
}
function OpenManifest() {
@@ -121,9 +189,74 @@ function SandboxStory(props: Props) {
kernelStartupErrorAtom,
props.phase === "failed" ? resolutionError : null,
);
- state.set(sandboxSyncAtom, {
- pending: props.phase === "syncing",
- error: props.phase === "sync-failed" ? resolutionError : null,
+ const syncStatus: EnvironmentOperation["status"] | null =
+ props.phase === "syncing"
+ ? { kind: "running" }
+ : props.phase === "sync-failed"
+ ? { kind: "failed", error: resolutionError }
+ : props.phase === "restart-required"
+ ? {
+ kind: "restart-required",
+ reason:
+ "The manifest requires Python 3.14. This kernel uses Python 3.13.",
+ }
+ : props.phase === "synced"
+ ? { kind: "succeeded" }
+ : null;
+ state.set(alertAtom, (value) => ({
+ ...value,
+ environments: {
+ ...value.environments,
+ kernel: {
+ restart_required: props.phase === "restart-required",
+ operations: [
+ {
+ operation_id: "story-preparation",
+ action: "prepare",
+ source: "kernel",
+ status:
+ props.phase === "failed"
+ ? { kind: "failed", error: resolutionError }
+ : props.phase === "preparing"
+ ? { kind: "running" }
+ : { kind: "succeeded" },
+ packages: {},
+ logs: {
+ environment:
+ props.phase === "failed"
+ ? resolutionError
+ : preparationOutput,
+ },
+ },
+ ...(syncStatus
+ ? [
+ {
+ operation_id: "story-sync",
+ action: "sync" as const,
+ source: "kernel" as const,
+ status: syncStatus,
+ packages: {},
+ logs: {
+ environment:
+ "Reading notebook manifest\nResolving dependencies\nChecking Python version\n",
+ },
+ },
+ ]
+ : []),
+ ],
+ },
+ },
+ }));
+ state.set(startupProgressAtom, {
+ phase:
+ props.phase !== "preparing" && props.phase !== "failed"
+ ? "starting-kernel"
+ : "preparing-environment",
+ logs:
+ props.phase !== "preparing" && props.phase !== "failed"
+ ? "Launching kernel process\nUsing /home/user/.cache/uv/environments-v2/bike-trips-a274bddc/bin/python\nWaiting for kernel connection\n"
+ : "",
+ log_mode: "replace",
});
if (props.existingCells) {
const actions = createNotebookActions((action) =>
@@ -143,6 +276,18 @@ function SandboxStory(props: Props) {
manifest: currentManifest,
filename: "bike_trips.py",
}),
+ getDependencyTree: async () => ({
+ context: { kind: "sandbox", backend: props.backend },
+ tree: {
+ name: "<root>",
+ version: null,
+ tags: [],
+ dependencies: [
+ { name: "marimo", version: "0.24.2", tags: [], dependencies: [] },
+ { name: "polars", version: "1.34.0", tags: [], dependencies: [] },
+ ],
+ },
+ }),
updateManifest: async ({ contents }) => {
if (props.saveResult === "stale") {
throw new HTTPError(
@@ -184,46 +329,56 @@ function SandboxStory(props: Props) {
const reconnect = async () => {
store.set(connectionAtom, { state: WebSocketState.OPEN });
};
+ useEffect(() => {
+ if (!props.interactive) {
+ return;
+ }
+ const appendPreparation = (line: string) =>
+ store.set(alertAtom, (value) => ({
+ ...value,
+ environments: {
+ ...value.environments,
+ kernel: {
+ ...value.environments.kernel,
+ operations: value.environments.kernel.operations.map(
+ (operation) => ({
+ ...operation,
+ logs: { environment: operation.logs.environment + line },
+ }),
+ ),
+ },
+ },
+ }));
+ const timers = [
+ setTimeout(() => appendPreparation("Installed 24 packages\n"), 1500),
+ setTimeout(() => appendPreparation("Environment prepared\n"), 2500),
+ setTimeout(() => {
+ store.set(startupProgressAtom, {
+ phase: "starting-kernel",
+ logs: "Launching kernel process\nWaiting for kernel connection\n",
+ log_mode: "replace",
+ });
+ store.set(connectionAtom, {
+ state: WebSocketState.CONNECTING,
+ phase: "starting-kernel",
+ });
+ }, 3500),
+ setTimeout(
+ () => store.set(connectionAtom, { state: WebSocketState.OPEN }),
+ 5500,
+ ),
+ ];
+ return () => timers.forEach(clearTimeout);
+ }, [props.interactive, store]);
return (
<Provider store={store}>
<SandboxController onReconnect={reconnect} />
{props.surface === "manifest" && <OpenManifest />}
- <div
- data-testid="sandbox-story"
- className="bg-background text-foreground"
- style={{
- width: props.surface === "notebook" ? 820 : 400,
- }}
- >
- {props.surface === "notebook" && (
- <>
- <ConnectionNotice appConfig={appConfig} onRetry={reconnect} />
- {store.get(notebookAtom).cellIds.inOrderIds.map((cellId) => (
- <VerticalLayoutWrapper key={cellId} appConfig={appConfig}>
- <Cell
- cellId={cellId}
- theme={props.theme}
- mode="edit"
- showPlaceholder={false}
- canDelete={true}
- isCollapsed={false}
- collapseCount={0}
- canMoveX={false}
- userConfig={store.get(userConfigAtom)}
- />
- </VerticalLayoutWrapper>
- ))}
- </>
- )}
- {props.surface === "packages" &&
- (props.phase === "failed" ||
- props.phase === "sync-failed" ||
- props.phase === "preparing" ? (
- <SandboxStartupPanel />
- ) : (
- <SandboxFooter />
- ))}
- </div>
+ <SandboxPreview
+ props={props}
+ appConfig={appConfig}
+ reconnect={reconnect}
+ />
</Provider>
);
}
@@ -239,6 +394,7 @@ const meta = {
backend: "uv",
saveResult: "success",
theme: "light",
+ interactive: false,
},
render: (args, context) => (
<SandboxStory
@@ -262,6 +418,14 @@ export const StartingKernel: Story = {
name: "Startup notice / starting kernel",
args: { phase: "starting" },
};
+export const StartupTransition: Story = {
+ name: "Startup / completion transition",
+ args: { interactive: true, backend: "pixi" },
+};
+export const EmptyStartupTransition: Story = {
+ name: "Empty notebook / completion transition",
+ args: { interactive: true, existingCells: false, backend: "pixi" },
+};
export const ExistingNotebookFailed: Story = {
name: "Startup notice / failed",
args: { phase: "failed" },
@@ -274,6 +438,14 @@ export const PackagesPreparing: Story = {
name: "Setup details / preparing",
args: { surface: "packages" },
};
+export const PackagesStarting: Story = {
+ name: "Setup details / starting kernel",
+ args: { surface: "packages", phase: "starting" },
+};
+export const PackagesStartupTransition: Story = {
+ name: "Setup details / live output",
+ args: { surface: "packages", interactive: true },
+};
export const PackagesFailed: Story = {
name: "Setup details / failed",
args: { surface: "packages", phase: "failed" },
@@ -290,6 +462,14 @@ export const PackagesSyncFailed: Story = {
name: "Setup details / sync failed",
args: { surface: "packages", phase: "sync-failed" },
};
+export const PackagesSynced: Story = {
+ name: "Setup details / sync completed",
+ args: { surface: "packages", phase: "synced" },
+};
+export const PackagesRestartRequired: Story = {
+ name: "Setup details / restart required",
+ args: { surface: "packages", phase: "restart-required" },
+};
export const PixiPackagesReady: Story = {
name: "Status row / pixi",
args: { surface: "packages", phase: "ready", backend: "pixi" },
diff --git a/marimo/_cli/development/commands.py b/marimo/_cli/development/commands.py
index adab26d3d8..a97c5cc345 100644
--- a/marimo/_cli/development/commands.py
+++ b/marimo/_cli/development/commands.py
@@ -307,7 +307,7 @@ def _generate_server_api_schema() -> dict[str, Any]:
notifications.CompletionResultNotification,
notifications.AlertNotification,
notifications.MissingPackageAlertNotification,
- notifications.InstallingPackageAlertNotification,
+ notifications.EnvironmentOperationNotification,
notifications.ReconnectedNotification,
notifications.BannerNotification,
notifications.ReloadNotification,
diff --git a/marimo/_code_mode/_packages.py b/marimo/_code_mode/_packages.py
index f5e5764079..6b423fe57c 100644
--- a/marimo/_code_mode/_packages.py
+++ b/marimo/_code_mode/_packages.py
@@ -10,14 +10,20 @@ from __future__ import annotations
import asyncio
from dataclasses import dataclass
+from functools import partial
+from itertools import groupby
from typing import TYPE_CHECKING, Literal, Union
from marimo._config.settings import GLOBAL_SETTINGS
from marimo._messaging.notification import (
- InstallingPackageAlertNotification,
+ EnvironmentAction,
PackageStatusType,
)
from marimo._messaging.notification_utils import broadcast_notification
+from marimo._runtime.packages.operations import (
+ EnvironmentOperationReporter,
+ environment_operation,
+)
from marimo._runtime.packages.package_manager import (
PackageDescription,
PackageManager,
@@ -187,125 +193,87 @@ class Packages:
pm.alert_not_installed()
return [PackageResult.failed(op) for op in ops]
- source: Literal["kernel", "server"] = "kernel"
- statuses: PackageStatusType = {}
- for op in ops:
- if isinstance(op, _AddPackage):
- statuses[op.package] = "queued"
-
- if statuses:
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=statuses, source=source
- ),
- stream=self._ctx._kernel.stream,
- )
-
filename = self._ctx._kernel.app_metadata.filename
manage_metadata = (
GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA is True
and filename is not None
)
-
results: PackageResultList = []
- for op in ops:
- if isinstance(op, _AddPackage):
- success = await self._run_add(
- op, pm, statuses, source, manage_metadata
- )
- else:
- success = await self._run_remove(op, pm, manage_metadata)
- if success:
- results.append(PackageResult.succeeded(op))
- elif pm.restart_required:
- results.append(PackageResult.restart_required(op))
- else:
- results.append(PackageResult.failed(op))
+ # Group adjacent actions so progress stays in package alerts without
+ # reordering an add/remove/add sequence.
+ for installing, group in groupby(
+ ops, key=lambda op: isinstance(op, _AddPackage)
+ ):
+ batch = list(group)
+ statuses: PackageStatusType = {
+ op.package: "queued" for op in batch
+ }
+ action: EnvironmentAction = "install" if installing else "remove"
+ with environment_operation(
+ action,
+ statuses,
+ "kernel",
+ partial(
+ broadcast_notification, stream=self._ctx._kernel.stream
+ ),
+ ) as operation:
+ for op in batch:
+ success = await self._run_operation(
+ op, pm, operation, manage_metadata
+ )
+ if success:
+ results.append(PackageResult.succeeded(op))
+ elif pm.restart_required:
+ results.append(PackageResult.restart_required(op))
+ else:
+ results.append(PackageResult.failed(op))
return results
- async def _run_add(
+ async def _run_operation(
self,
- op: _AddPackage,
+ op: PackageOp,
pm: PackageManager,
- statuses: PackageStatusType,
- source: Literal["kernel", "server"],
+ operation: EnvironmentOperationReporter,
manage_metadata: bool,
) -> bool:
pkg = op.package
- statuses[pkg] = "installing"
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=statuses, source=source
- ),
- stream=self._ctx._kernel.stream,
- )
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=statuses,
- logs={pkg: f"Installing {pkg}...\n"},
- log_status="start",
- source=source,
- ),
- stream=self._ctx._kernel.stream,
+ installing = isinstance(op, _AddPackage)
+ operation.packages[pkg] = "running"
+ operation.update(
+ {pkg: f"{'Installing' if installing else 'Removing'} {pkg}...\n"},
+ replace=True,
)
-
- def log_callback(log_line: str) -> None:
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=statuses,
- logs={pkg: log_line},
- log_status="append",
- source=source,
- ),
- stream=self._ctx._kernel.stream,
+ if installing:
+ success = await pm.install(
+ pkg,
+ version=None,
+ log_callback=lambda line: operation.update({pkg: line}),
)
-
- success = await pm.install(
- pkg, version=None, log_callback=log_callback
- )
+ else:
+ success = await pm.uninstall(pkg)
if success:
- statuses[pkg] = "installed"
- final_log = f"Successfully installed {pkg}\n"
+ operation.packages[pkg] = "succeeded"
filename = self._ctx._kernel.app_metadata.filename
if manage_metadata and filename is not None:
await asyncio.to_thread(
pm.update_notebook_script_metadata,
filepath=filename,
- packages_to_add=split_packages(pkg),
+ **(
+ {"packages_to_add": split_packages(pkg)}
+ if installing
+ else {"packages_to_remove": split_packages(pkg)}
+ ),
upgrade=False,
)
+ message = f"Successfully {'installed' if installing else 'removed'} {pkg}\n"
elif pm.restart_required:
- statuses[pkg] = "restart-required"
- final_log = f"Dependency changes saved for {pkg}; restart the kernel to use them.\n"
+ operation.packages[pkg] = "restart-required"
+ message = f"Dependency changes saved for {pkg}; restart the kernel to use them.\n"
else:
- statuses[pkg] = "failed"
- final_log = f"Failed to install {pkg}\n"
-
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=statuses,
- logs={pkg: final_log},
- log_status="done",
- source=source,
- ),
- stream=self._ctx._kernel.stream,
- )
- return success
-
- async def _run_remove(
- self,
- op: _RemovePackage,
- pm: PackageManager,
- manage_metadata: bool,
- ) -> bool:
- success = await pm.uninstall(op.package)
- filename = self._ctx._kernel.app_metadata.filename
- if success and manage_metadata and filename is not None:
- await asyncio.to_thread(
- pm.update_notebook_script_metadata,
- filepath=filename,
- packages_to_remove=split_packages(op.package),
- upgrade=False,
+ operation.packages[pkg] = "failed"
+ message = (
+ f"Failed to {'install' if installing else 'remove'} {pkg}\n"
)
+ operation.update({pkg: message})
return success
diff --git a/marimo/_environments/sandbox.py b/marimo/_environments/sandbox.py
index d9fc74eeb4..b34be0f35b 100644
--- a/marimo/_environments/sandbox.py
+++ b/marimo/_environments/sandbox.py
@@ -337,7 +337,9 @@ class NotebookSandbox:
self._environment_source = self._source
return self._launch_plan(environment, args, overlay, base_env)
- async def sync_async(self) -> None:
+ async def sync_async(
+ self, *, on_output: Callable[[str], None] | None = None
+ ) -> None:
"""Apply the saved manifest to the environment used by this kernel."""
await self._adapter.ensure_available_async()
async with script_metadata.materialized_for_environment_async(
@@ -353,7 +355,7 @@ class NotebookSandbox:
environment = await self._adapter.sync_async(
target,
python_override=None,
- on_output=None,
+ on_output=on_output,
active_environment=self._environment,
)
self._environment = environment
diff --git a/marimo/_export/file.py b/marimo/_export/file.py
index 4300da02df..36d82c167e 100644
--- a/marimo/_export/file.py
+++ b/marimo/_export/file.py
@@ -69,6 +69,7 @@ from marimo._schemas.serialization import NotebookSerialization
from marimo._session.model import ConnectionState, SessionMode
from marimo._session.notebook import load_notebook
from marimo._session.requests import InstantiateNotebookRequest
+from marimo._session.startup import SessionStartup
from marimo._types.ids import ConsumerId
from marimo._utils.inline_script_metadata import (
pin_pep723_dependencies_for_wasm,
@@ -679,6 +680,7 @@ async def run_notebook(
# Create a session
session_consumer = RunUntilCompletionSessionConsumer()
session = await SessionImpl.create(
+ startup=SessionStartup(),
# Any initialization ID will do
initialization_id="_any_",
session_consumer=session_consumer,
diff --git a/marimo/_internal/notifications.py b/marimo/_internal/notifications.py
index 7935b1b9cf..8770015917 100644
--- a/marimo/_internal/notifications.py
+++ b/marimo/_internal/notifications.py
@@ -13,10 +13,11 @@ from marimo._messaging.notification import (
DataColumnPreviewNotification,
DatasetsNotification,
DataSourceConnectionsNotification,
+ EnvironmentOperationNotification,
+ EnvironmentStateNotification,
FocusCellNotification,
FunctionCallResultNotification,
HumanReadableStatus,
- InstallingPackageAlertNotification,
InterruptedNotification,
KernelCapabilitiesNotification,
KernelReadyNotification,
@@ -58,10 +59,11 @@ __all__ = [
"DataColumnPreviewNotification",
"DataSourceConnectionsNotification",
"DatasetsNotification",
+ "EnvironmentOperationNotification",
+ "EnvironmentStateNotification",
"FocusCellNotification",
"FunctionCallResultNotification",
"HumanReadableStatus",
- "InstallingPackageAlertNotification",
"InterruptedNotification",
"KernelCapabilitiesNotification",
"KernelReadyNotification",
diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.py
index 72f66c066c..3315584f79 100644
--- a/marimo/_messaging/notification.py
+++ b/marimo/_messaging/notification.py
@@ -502,32 +502,106 @@ class MissingPackageAlertNotification(
source: Literal["kernel", "server"] = "kernel"
-# package name => installation status
+# Package name => progress within the current operation
PackageStatusType = dict[
str,
- Literal["queued", "installing", "installed", "failed", "restart-required"],
+ Literal["queued", "running", "succeeded", "failed", "restart-required"],
]
-class InstallingPackageAlertNotification(
- Notification, tag="installing-package-alert"
+class _EnvironmentOperationStatus(
+ msgspec.Struct,
+ tag_field="kind",
+ frozen=True,
+ forbid_unknown_fields=True,
):
- """Package installation progress with streaming logs.
+ pass
- Attributes:
- packages: Package name to status (queued/installing/installed/failed).
- logs: Optional streaming logs per package.
- log_status: Log stream status (append/start/done).
- source: Which Python environment packages are installed into.
- "kernel" (default) installs in the kernel's venv; "server"
- installs in the server's own Python env.
+
+class OperationRunning(
+ _EnvironmentOperationStatus, tag="running", frozen=True
+):
+ pass
+
+
+class OperationSucceeded(
+ _EnvironmentOperationStatus, tag="succeeded", frozen=True
+):
+ pass
+
+
+class OperationRestartRequired(
+ _EnvironmentOperationStatus, tag="restart-required", frozen=True
+):
+ reason: str
+
+
+class OperationFailed(_EnvironmentOperationStatus, tag="failed", frozen=True):
+ error: str
+
+
+class OperationCancelled(
+ _EnvironmentOperationStatus, tag="cancelled", frozen=True
+):
+ pass
+
+
+EnvironmentOperationStatus = (
+ OperationRunning
+ | OperationSucceeded
+ | OperationRestartRequired
+ | OperationFailed
+ | OperationCancelled
+)
+
+
+EnvironmentAction = Literal["prepare", "install", "remove", "sync"]
+
+
+class EnvironmentOperation(msgspec.Struct, frozen=True):
+ """Current progress and logs for one execution of environment work."""
+
+ operation_id: str
+ action: EnvironmentAction
+ status: EnvironmentOperationStatus
+ packages: PackageStatusType
+ logs: dict[str, str]
+ source: Literal["kernel", "server"]
+
+
+class EnvironmentState(msgspec.Struct, frozen=True):
+ """Preparation, active operations, the latest mutation, and restarts."""
+
+ restart_required: bool
+ operations: list[EnvironmentOperation]
+
+
+class EnvironmentStateNotification(Notification, tag="environment-state"):
+ """Replace the current state for one environment on connection."""
+
+ name: ClassVar[str] = "environment-state"
+ source: Literal["kernel", "server"]
+ state: EnvironmentState
+
+
+class EnvironmentOperationNotification(
+ Notification, tag="environment-operation"
+):
+ """Current operation progress and changes to its named log streams.
+
+ Package statuses replace the previous map. Log chunks append to a stream,
+ or replace it when `log_mode` is `replace`. The operation status determines
+ completion independently of its packages and output streams.
"""
- name: ClassVar[str] = "installing-package-alert"
+ name: ClassVar[str] = "environment-operation"
+ operation_id: str
+ action: EnvironmentAction
+ status: EnvironmentOperationStatus
+ source: Literal["kernel", "server"]
packages: PackageStatusType
- logs: dict[str, str] | None = None # package name -> log content
- log_status: Literal["append", "start", "done"] | None = None
- source: Literal["kernel", "server"] = "kernel"
+ logs: dict[str, str]
+ log_mode: Literal["append", "replace"]
class ReconnectedNotification(Notification, tag="reconnected"):
@@ -567,10 +641,16 @@ class BannerNotification(Notification, tag="banner"):
class StartupProgressNotification(Notification, tag="startup-progress"):
- """Progress reported before a session's kernel is ready."""
+ """Current startup phase and its output before the kernel is ready.
+
+ Output appends within a phase. Snapshots replace it, and changing phases
+ starts a new stream. Environment preparation logs belong to its operation.
+ """
name: ClassVar[str] = "startup-progress"
phase: StartupPhase
+ logs: str
+ log_mode: Literal["append", "replace"]
class KernelStartupErrorNotification(Notification, tag="kernel-startup-error"):
@@ -1024,7 +1104,8 @@ NotificationMessage = (
| AlertNotification
| BannerNotification
| MissingPackageAlertNotification
- | InstallingPackageAlertNotification
+ | EnvironmentOperationNotification
+ | EnvironmentStateNotification
| StartupLogsNotification
| StartupProgressNotification
| KernelStartupErrorNotification
diff --git a/marimo/_runtime/callbacks/packages.py b/marimo/_runtime/callbacks/packages.py
index d500dbcc01..c35cfb9cc7 100644
--- a/marimo/_runtime/callbacks/packages.py
+++ b/marimo/_runtime/callbacks/packages.py
@@ -1,6 +1,7 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+from functools import partial
from typing import TYPE_CHECKING
from marimo import _loggers
@@ -9,7 +10,6 @@ from marimo._dependencies.errors import ManyModulesNotFoundError
from marimo._messaging.context import is_code_mode_request
from marimo._messaging.notification import (
CompletedRunNotification,
- InstallingPackageAlertNotification,
MissingPackageAlertNotification,
PackageStatusType,
)
@@ -23,6 +23,7 @@ from marimo._runtime.packages.import_error_extractors import (
extract_missing_module_from_cause_chain,
try_extract_packages_from_import_error_message,
)
+from marimo._runtime.packages.operations import environment_operation
from marimo._runtime.packages.package_manager import (
LogCallback,
PackageManager,
@@ -291,117 +292,72 @@ class PackagesCallbacks:
missing_packages = [
str(pkg)
for pkg in sorted(resolved_packages.values(), key=lambda p: p.name)
+ if not self.package_manager.attempted_to_install(package=str(pkg))
]
+ if not missing_packages:
+ return
# Frontend shows package names, not module names
package_statuses: PackageStatusType = dict.fromkeys(
- missing_packages, "queued"
+ missing_packages, "running"
)
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=package_statuses, source=request.source
- )
- )
-
- def create_log_callback(pkg: str) -> LogCallback:
- # Bind the stream now, on the kernel thread: the callback
- # fires from worker threads, which do not carry the kernel's
- # thread-local context, so a bare broadcast would be dropped.
- try:
- stream = get_context().stream
- except ContextNotInitializedError:
- stream = None
-
- def log_callback(log_line: str) -> None:
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=package_statuses,
- logs={pkg: log_line},
- log_status="append",
- source=request.source,
- ),
- stream=stream,
- )
-
- return log_callback
-
- # Mark every still-installable package as "installing" up-front so the
- # UI can render the batch state before any wheel completes.
- for pkg in missing_packages:
- if not self.package_manager.attempted_to_install(package=pkg):
- package_statuses[pkg] = "installing"
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=package_statuses, source=request.source
- )
- )
- for pkg in missing_packages:
- if package_statuses.get(pkg) == "installing":
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=package_statuses,
- logs={pkg: f"Installing {pkg}...\n"},
- log_status="start",
- source=request.source,
+ # Worker log callbacks need the kernel's stream captured on this thread.
+ try:
+ stream = get_context().stream
+ except ContextNotInitializedError:
+ stream = None
+ with environment_operation(
+ "install",
+ package_statuses,
+ request.source,
+ partial(broadcast_notification, stream=stream),
+ ) as operation:
+
+ def create_log_callback(pkg: str) -> LogCallback:
+ return lambda line: operation.update({pkg: line})
+
+ for pkg in missing_packages:
+ operation.update({pkg: f"Installing {pkg}...\n"}, replace=True)
+
+ versions: dict[str, str | None] = {
+ pkg: request.versions.get(pkg) for pkg in missing_packages
+ }
+ async for pkg, success in self.package_manager.stream_install(
+ missing_packages,
+ versions=versions,
+ index_urls=request.index_urls or None,
+ log_callback_factory=create_log_callback,
+ ):
+ if success:
+ package_statuses[pkg] = "succeeded"
+ operation.update({pkg: f"Successfully installed {pkg}\n"})
+ else:
+ restart_required = self.package_manager.restart_required
+ package_statuses[pkg] = (
+ "restart-required" if restart_required else "failed"
)
- )
-
- installable = [
- pkg
- for pkg in missing_packages
- if not self.package_manager.attempted_to_install(package=pkg)
- ]
- versions: dict[str, str | None] = {
- pkg: request.versions.get(pkg) for pkg in installable
- }
- async for pkg, success in self.package_manager.stream_install(
- installable,
- versions=versions,
- index_urls=request.index_urls or None,
- log_callback_factory=create_log_callback,
- ):
- if success:
- package_statuses[pkg] = "installed"
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=package_statuses,
- logs={pkg: f"Successfully installed {pkg}\n"},
- log_status="done",
- source=request.source,
- ),
- )
- else:
- restart_required = self.package_manager.restart_required
- package_statuses[pkg] = (
- "restart-required" if restart_required else "failed"
- )
- mod = self.package_manager.package_to_module(pkg)
- self._kernel.module_registry.excluded_modules.add(mod)
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=package_statuses,
- logs={
+ mod = self.package_manager.package_to_module(pkg)
+ self._kernel.module_registry.excluded_modules.add(mod)
+ operation.update(
+ {
pkg: (
f"Dependency changes saved for {pkg}; restart the kernel to use them.\n"
if restart_required
else f"Failed to install {pkg}\n"
)
- },
- log_status="done",
- source=request.source,
- ),
- )
+ }
+ )
- installed_modules = [
- self.package_manager.package_to_module(pkg)
- for pkg in package_statuses
- if package_statuses[pkg] == "installed"
- ]
+ installed_modules = [
+ self.package_manager.package_to_module(pkg)
+ for pkg in package_statuses
+ if package_statuses[pkg] == "succeeded"
+ ]
- # If a package was not installed at cell registration time, it won't
- # yet be in the script metadata.
- if self.should_update_script_metadata():
- self.update_script_metadata(installed_modules)
+ # If a package was not installed at cell registration time, it won't
+ # yet be in the script metadata.
+ if self.should_update_script_metadata():
+ self.update_script_metadata(installed_modules)
# All cells that depend on successfully installed modules are re-run.
#
diff --git a/marimo/_runtime/packages/operations.py b/marimo/_runtime/packages/operations.py
new file mode 100644
index 0000000000..29a3b2e6ea
--- /dev/null
+++ b/marimo/_runtime/packages/operations.py
@@ -0,0 +1,114 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+from threading import Lock
+from typing import TYPE_CHECKING, Literal
+from uuid import uuid4
+
+from marimo._environments.errors import SandboxRestartRequired
+from marimo._messaging.notification import (
+ EnvironmentAction,
+ EnvironmentOperationNotification,
+ EnvironmentOperationStatus,
+ OperationCancelled,
+ OperationFailed,
+ OperationRestartRequired,
+ OperationRunning,
+ OperationSucceeded,
+ PackageStatusType,
+)
+
+if TYPE_CHECKING:
+ from collections.abc import Callable, Iterator
+
+
+class EnvironmentOperationReporter:
+ """Report one operation; callers update the package map as work proceeds."""
+
+ def __init__(
+ self,
+ action: EnvironmentAction,
+ packages: PackageStatusType,
+ source: Literal["kernel", "server"],
+ notify: Callable[[EnvironmentOperationNotification], None],
+ ) -> None:
+ self._operation_id = uuid4().hex
+ self._action = action
+ self.packages = packages
+ self._source = source
+ self._notify = notify
+ self._lock = Lock()
+ self._finished = False
+
+ def update(
+ self, logs: dict[str, str] | None = None, *, replace: bool = False
+ ) -> None:
+ self._send(OperationRunning(), logs or {}, replace=replace)
+
+ def _send(
+ self,
+ status: EnvironmentOperationStatus,
+ logs: dict[str, str],
+ *,
+ replace: bool = False,
+ ) -> None:
+ with self._lock:
+ # A cancelled worker may still deliver output after scope exit.
+ if self._finished:
+ return
+ self._notify(
+ EnvironmentOperationNotification(
+ operation_id=self._operation_id,
+ action=self._action,
+ status=status,
+ source=self._source,
+ packages=dict(self.packages),
+ logs=dict(logs),
+ log_mode="replace" if replace else "append",
+ )
+ )
+ # Only a delivered outcome closes the operation.
+ self._finished = not isinstance(status, OperationRunning)
+
+
+@contextmanager
+def environment_operation(
+ action: EnvironmentAction,
+ packages: PackageStatusType,
+ source: Literal["kernel", "server"],
+ notify: Callable[[EnvironmentOperationNotification], None],
+) -> Iterator[EnvironmentOperationReporter]:
+ """Publish an operation's start and its outcome, including empty syncs."""
+ operation = EnvironmentOperationReporter(action, packages, source, notify)
+ operation.update()
+ status: EnvironmentOperationStatus
+ try:
+ yield operation
+ except (asyncio.CancelledError, KeyboardInterrupt):
+ status = OperationCancelled()
+ raise
+ except SandboxRestartRequired as exc:
+ status = OperationRestartRequired(reason=str(exc))
+ raise
+ except BaseException as exc:
+ status = OperationFailed(error=str(exc) or type(exc).__name__)
+ raise
+ else:
+ if incomplete := [
+ package
+ for package, package_status in packages.items()
+ if package_status in ("queued", "running", "failed")
+ ]:
+ status = OperationFailed(
+ error=f"Could not apply changes to {', '.join(incomplete)}. See operation logs for details."
+ )
+ elif "restart-required" in packages.values():
+ status = OperationRestartRequired(
+ reason="Dependency changes are saved; restart the kernel to apply them."
+ )
+ else:
+ status = OperationSucceeded()
+ finally:
+ operation._send(status, {})
diff --git a/marimo/_schemas/generated/notifications.yaml b/marimo/_schemas/generated/notifications.yaml
index 742884a6b7..b0e4cb6f41 100644
--- a/marimo/_schemas/generated/notifications.yaml
+++ b/marimo/_schemas/generated/notifications.yaml
@@ -796,6 +796,90 @@ components:
- substrings
title: DialectHidesWhen
type: object
+ EnvironmentOperation:
+ description: Current progress and logs for one execution of environment work.
+ properties:
+ action:
+ enum:
+ - install
+ - prepare
+ - remove
+ - sync
+ logs:
+ additionalProperties:
+ type: string
+ type: object
+ operation_id:
+ type: string
+ packages:
+ additionalProperties:
+ enum:
+ - failed
+ - queued
+ - restart-required
+ - running
+ - succeeded
+ type: object
+ source:
+ enum:
+ - kernel
+ - server
+ status:
+ anyOf:
+ - $ref: '#/components/schemas/OperationRunning'
+ - $ref: '#/components/schemas/OperationSucceeded'
+ - $ref: '#/components/schemas/OperationRestartRequired'
+ - $ref: '#/components/schemas/OperationFailed'
+ - $ref: '#/components/schemas/OperationCancelled'
+ discriminator:
+ mapping:
+ cancelled: '#/components/schemas/OperationCancelled'
+ failed: '#/components/schemas/OperationFailed'
+ restart-required: '#/components/schemas/OperationRestartRequired'
+ running: '#/components/schemas/OperationRunning'
+ succeeded: '#/components/schemas/OperationSucceeded'
+ propertyName: kind
+ required:
+ - operation_id
+ - action
+ - status
+ - packages
+ - logs
+ - source
+ title: EnvironmentOperation
+ type: object
+ EnvironmentState:
+ description: Active operations, the latest result, and an outstanding restart.
+ properties:
+ operations:
+ items:
+ $ref: '#/components/schemas/EnvironmentOperation'
+ type: array
+ restart_required:
+ type: boolean
+ required:
+ - restart_required
+ - operations
+ title: EnvironmentState
+ type: object
+ EnvironmentStateNotification:
+ description: Replace the current state for one environment on connection.
+ properties:
+ op:
+ enum:
+ - environment-state
+ source:
+ enum:
+ - kernel
+ - server
+ state:
+ $ref: '#/components/schemas/EnvironmentState'
+ required:
+ - op
+ - source
+ - state
+ title: EnvironmentStateNotification
+ type: object
EnvironmentVariableDiscoveryValue:
description: A reference to an environment variable, never its value.
properties:
@@ -892,51 +976,69 @@ components:
- msg
title: ImportStarError
type: object
- InstallingPackageAlertNotification:
- description: "Package installation progress with streaming logs.\n\n Attributes:\n\
- \ packages: Package name to status (queued/installing/installed/failed).\n\
- \ logs: Optional streaming logs per package.\n log_status: Log\
- \ stream status (append/start/done).\n source: Which Python environment\
- \ packages are installed into.\n \"kernel\" (default) installs\
- \ in the kernel's venv; \"server\"\n installs in the server's\
- \ own Python env."
+ EnvironmentOperationNotification:
+ description: "Current operation progress and changes to its named log streams.\n\
+ \n Package statuses replace the previous map. Log chunks append to a stream,\n\
+ \ or replace it when `log_mode` is `replace`. The operation status determines\n\
+ \ completion independently of its packages and output streams."
properties:
- log_status:
- anyOf:
- - enum:
- - append
- - done
- - start
- - type: 'null'
- default: null
+ action:
+ enum:
+ - install
+ - prepare
+ - remove
+ - sync
+ log_mode:
+ enum:
+ - append
+ - replace
logs:
- anyOf:
- - additionalProperties:
- type: string
- type: object
- - type: 'null'
- default: null
+ additionalProperties:
+ type: string
+ type: object
op:
enum:
- - installing-package-alert
+ - environment-operation
+ operation_id:
+ type: string
packages:
additionalProperties:
enum:
- failed
- - installed
- - installing
- queued
- restart-required
+ - running
+ - succeeded
type: object
source:
- default: kernel
enum:
- kernel
- server
+ status:
+ anyOf:
+ - $ref: '#/components/schemas/OperationRunning'
+ - $ref: '#/components/schemas/OperationSucceeded'
+ - $ref: '#/components/schemas/OperationRestartRequired'
+ - $ref: '#/components/schemas/OperationFailed'
+ - $ref: '#/components/schemas/OperationCancelled'
+ discriminator:
+ mapping:
+ cancelled: '#/components/schemas/OperationCancelled'
+ failed: '#/components/schemas/OperationFailed'
+ restart-required: '#/components/schemas/OperationRestartRequired'
+ running: '#/components/schemas/OperationRunning'
+ succeeded: '#/components/schemas/OperationSucceeded'
+ propertyName: kind
required:
- op
+ - operation_id
+ - action
+ - status
+ - source
- packages
- title: InstallingPackageAlertNotification
+ - logs
+ - log_mode
+ title: EnvironmentOperationNotification
type: object
InterruptedNotification:
description: Kernel was interrupted by user (SIGINT/Ctrl+C).
@@ -1274,6 +1376,62 @@ components:
- cells
title: MultipleDefinitionError
type: object
+ OperationCancelled:
+ additionalProperties: false
+ properties:
+ kind:
+ enum:
+ - cancelled
+ required:
+ - kind
+ title: OperationCancelled
+ type: object
+ OperationFailed:
+ additionalProperties: false
+ properties:
+ error:
+ type: string
+ kind:
+ enum:
+ - failed
+ required:
+ - kind
+ - error
+ title: OperationFailed
+ type: object
+ OperationRestartRequired:
+ additionalProperties: false
+ properties:
+ kind:
+ enum:
+ - restart-required
+ reason:
+ type: string
+ required:
+ - kind
+ - reason
+ title: OperationRestartRequired
+ type: object
+ OperationRunning:
+ additionalProperties: false
+ properties:
+ kind:
+ enum:
+ - running
+ required:
+ - kind
+ title: OperationRunning
+ type: object
+ OperationSucceeded:
+ additionalProperties: false
+ properties:
+ kind:
+ enum:
+ - succeeded
+ required:
+ - kind
+ title: OperationSucceeded
+ type: object
QueryParamsAppendNotification:
description: "Appends value to URL query parameter.\n\n Attributes:\n \
\ key: Query parameter key.\n value: Value to append."
diff --git a/marimo/_server/api/endpoints/packages.py b/marimo/_server/api/endpoints/packages.py
index 5a22b2cf6b..9a6028f10b 100644
--- a/marimo/_server/api/endpoints/packages.py
+++ b/marimo/_server/api/endpoints/packages.py
@@ -14,6 +14,11 @@ from marimo._environments.errors import (
SandboxRestartRequired,
)
from marimo._environments.sandbox import Backend, NotebookSandbox
+from marimo._messaging.notification import (
+ EnvironmentOperationNotification,
+ PackageStatusType,
+)
+from marimo._runtime.packages.operations import environment_operation
from marimo._runtime.packages.package_manager import PackageManager
from marimo._runtime.packages.package_managers import create_package_manager
from marimo._runtime.packages.sandbox_package_manager import (
@@ -40,6 +45,8 @@ from marimo._server.router import APIRouter
from marimo._utils.http import HTTPException
if TYPE_CHECKING:
+ from collections.abc import Callable
+
from starlette.requests import Request
# Router for packages endpoints
@@ -73,36 +80,54 @@ async def add_package(request: Request) -> PackageOperationResponse:
f"Check out the docs for installation instructions: {package_manager.docs_url}"
)
- upgrade = body.upgrade or False
- group = body.group or None
- success = await package_manager.install(
- body.package, version=None, upgrade=upgrade, group=group
- )
-
- # Update the script metadata
- filename = _get_filename(request)
- if (
- success
- and filename is not None
- and GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA
- ):
- await asyncio.to_thread(
- package_manager.update_notebook_script_metadata,
- filepath=filename,
- packages_to_add=split_packages(body.package),
+ packages: PackageStatusType = {body.package: "running"}
+ with environment_operation(
+ "install", packages, "kernel", _operation_notifier(request)
+ ) as operation:
+ upgrade = body.upgrade or False
+ group = body.group or None
+ success = await package_manager.install(
+ body.package,
+ version=None,
upgrade=upgrade,
+ group=group,
+ log_callback=lambda line: operation.update({body.package: line}),
)
- if success:
- return PackageOperationResponse.of_success()
+ # Update the script metadata
+ filename = _get_filename(request)
+ if (
+ success
+ and filename is not None
+ and GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA
+ ):
+ await asyncio.to_thread(
+ package_manager.update_notebook_script_metadata,
+ filepath=filename,
+ packages_to_add=split_packages(body.package),
+ upgrade=upgrade,
+ )
+
+ packages[body.package] = (
+ "succeeded"
+ if success
+ else "restart-required"
+ if package_manager.restart_required
+ else "failed"
+ )
- if package_manager.restart_required:
- return PackageOperationResponse(success=False, restart_required=True)
+ if success:
+ return PackageOperationResponse.of_success()
- return PackageOperationResponse.of_failure(
- _failure_message(package_manager)
- or f"Failed to install {body.package}. See terminal for error logs."
- )
+ if package_manager.restart_required:
+ return PackageOperationResponse(
+ success=False, restart_required=True
+ )
+
+ return PackageOperationResponse.of_failure(
+ _failure_message(package_manager)
+ or f"Failed to install {body.package}. See terminal for error logs."
+ )
@router.post("/remove")
@@ -133,33 +158,62 @@ async def remove_package(request: Request) -> PackageOperationResponse:
f"Check out the docs for installation instructions: {package_manager.docs_url}"
)
- group = body.group or None
- success = await package_manager.uninstall(body.package, group=group)
-
- # Update the script metadata
- filename = _get_filename(request)
- if (
- success
- and filename is not None
- and GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA
+ packages: PackageStatusType = {body.package: "running"}
+ with environment_operation(
+ "remove", packages, "kernel", _operation_notifier(request)
):
- await asyncio.to_thread(
- package_manager.update_notebook_script_metadata,
- filepath=filename,
- packages_to_remove=split_packages(body.package),
- upgrade=False,
+ group = body.group or None
+ success = await package_manager.uninstall(body.package, group=group)
+
+ # Update the script metadata
+ filename = _get_filename(request)
+ if (
+ success
+ and filename is not None
+ and GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA
+ ):
+ await asyncio.to_thread(
+ package_manager.update_notebook_script_metadata,
+ filepath=filename,
+ packages_to_remove=split_packages(body.package),
+ upgrade=False,
+ )
+
+ packages[body.package] = (
+ "succeeded"
+ if success
+ else "restart-required"
+ if package_manager.restart_required
+ else "failed"
)
- if success:
- return PackageOperationResponse.of_success()
+ if success:
+ return PackageOperationResponse.of_success()
- if package_manager.restart_required:
- return PackageOperationResponse(success=False, restart_required=True)
+ if package_manager.restart_required:
+ return PackageOperationResponse(
+ success=False, restart_required=True
+ )
- return PackageOperationResponse.of_failure(
- _failure_message(package_manager)
- or f"Failed to uninstall {body.package}. See terminal for error logs."
- )
+ return PackageOperationResponse.of_failure(
+ _failure_message(package_manager)
+ or f"Failed to uninstall {body.package}. See terminal for error logs."
+ )
+
+
+def _operation_notifier(
+ request: Request,
+) -> Callable[[EnvironmentOperationNotification], None]:
+ session = AppState(request).get_current_session()
+ loop = asyncio.get_running_loop()
+
+ def notify(notification: EnvironmentOperationNotification) -> None:
+ if session is not None:
+ # Package-manager output may arrive on a worker thread. Keep it
+ # ordered with snapshots and other notifications on the session loop.
+ loop.call_soon_threadsafe(session.notify, notification, None)
+
+ return notify
def _failure_message(package_manager: PackageManager) -> str | None:
@@ -267,8 +321,13 @@ def _sandbox_source(
) -> tuple[NotebookSandbox | None, str | None, Backend | None]:
state = AppState(request)
manager = state.session_manager
- if mutation and manager.is_session_starting(
- state.require_current_session_id()
+ key = file_key or manager.workspace.get_unique_file_key()
+ if (
+ mutation
+ and key is not None
+ and manager.is_session_starting(
+ state.require_current_session_id(), key
+ )
):
raise HTTPException(409, "Wait for sandbox preparation to finish.")
session = state.get_current_session()
@@ -279,7 +338,6 @@ def _sandbox_source(
return None, None, None
if not manager.sandbox:
return None, None, None
- key = file_key or manager.workspace.get_unique_file_key()
path = manager.workspace.resolve(key) if key else None
return None, path, current_backend()
@@ -397,7 +455,12 @@ async def sync_sandbox(request: Request) -> SyncSandboxResponse:
# Connection creation owns provisioning and streams its progress.
return SyncSandboxResponse(success=True, reconnect=True)
try:
- await sandbox.sync_async()
+ with environment_operation(
+ "sync", {}, "kernel", _operation_notifier(request)
+ ) as operation:
+ await sandbox.sync_async(
+ on_output=lambda line: operation.update({"environment": line})
+ )
except SandboxRestartRequired as error:
return SyncSandboxResponse(
success=False, error=str(error), restart_required=True
diff --git a/marimo/_server/api/endpoints/ws/session_handler.py b/marimo/_server/api/endpoints/ws/session_handler.py
index 5989001c81..11955c5f20 100644
--- a/marimo/_server/api/endpoints/ws/session_handler.py
+++ b/marimo/_server/api/endpoints/ws/session_handler.py
@@ -14,6 +14,8 @@ from marimo._config.settings import GLOBAL_SETTINGS
from marimo._messaging.notification import (
AlertNotification,
BannerNotification,
+ EnvironmentOperationNotification,
+ EnvironmentStateNotification,
NotificationMessage,
ReconnectedNotification,
StartupProgressNotification,
@@ -202,10 +204,19 @@ class SessionHandler(SessionConsumer, abc.ABC):
)
def notify(self, notification: KernelMessage) -> None:
+ name = deserialize_kernel_notification_name(notification)
if (
self._startup_queue is not None
- and deserialize_kernel_notification_name(notification)
- == StartupProgressNotification.name
+ and self.status == ConnectionState.CONNECTING
+ and (
+ name == StartupProgressNotification.name
+ or self._session is None
+ and name
+ in (
+ EnvironmentOperationNotification.name,
+ EnvironmentStateNotification.name,
+ )
+ )
):
self._startup_queue.put_nowait(notification)
else:
@@ -300,6 +311,7 @@ class SessionHandler(SessionConsumer, abc.ABC):
description="You have reconnected to an existing session.",
)
)
+ self._write_environment_state(session)
return
self._write_kernel_ready_from_session_view(session, self.params.kiosk)
@@ -345,8 +357,24 @@ class SessionHandler(SessionConsumer, abc.ABC):
# Replay all operations
self._replay_previous_session(session)
+ def _write_environment_state(self, session: Session) -> None:
+ # Attachment and snapshot delivery run in one event-loop turn, before
+ # any later live deltas. Empty states also clear a previous session.
+ for source in ("kernel", "server"):
+ self._serialize_and_notify(
+ EnvironmentStateNotification(
+ source=source,
+ state=session.session_view.get_environment_state(source),
+ )
+ )
+ if session.session_view.startup_progress is not None:
+ # Completed startup follows kernel-ready/reconnected on the normal
+ # queue, so replay cannot put a ready notebook back into startup.
+ self._serialize_and_notify(session.session_view.startup_progress)
+
def _replay_previous_session(self, session: Session) -> None:
"""Replay the previous session view."""
+ self._write_environment_state(session)
notifications = session.session_view.notifications
if len(notifications) == 0:
LOGGER.debug("No notifications to replay")
diff --git a/marimo/_server/api/endpoints/ws/ws_session_connector.py b/marimo/_server/api/endpoints/ws/ws_session_connector.py
index 1774a4252c..dd64e0e4ba 100644
--- a/marimo/_server/api/endpoints/ws/ws_session_connector.py
+++ b/marimo/_server/api/endpoints/ws/ws_session_connector.py
@@ -88,6 +88,12 @@ class SessionConnector:
if self.params.kiosk:
return self._connect_kiosk()
+ # A completed launch may still be waiting for its first connection.
+ if self.manager.is_session_starting(
+ self.params.session_id, self.params.file_key
+ ):
+ return await self._create_new_session()
+
# 2. Reconnect to existing session with same ID
existing_by_id = self.manager.get_session(self.params.session_id)
if existing_by_id is not None:
diff --git a/marimo/_server/session_manager.py b/marimo/_server/session_manager.py
index c89d09e7f1..76665e642f 100644
--- a/marimo/_server/session_manager.py
+++ b/marimo/_server/session_manager.py
@@ -48,6 +48,7 @@ from marimo._session.managers.ipc import KernelStartupError
from marimo._session.model import ConnectionState, SessionMode
from marimo._session.session import Session, SessionImpl
from marimo._session.session_repository import SessionRepository
+from marimo._session.startup import SessionStartup
from marimo._session.types import KernelState
from marimo._types.ids import ConsumerId, SessionId
from marimo._utils.asyncio_utils import fire_and_forget
@@ -60,11 +61,16 @@ if TYPE_CHECKING:
LOGGER = _loggers.marimo_logger()
+_STARTUP_RECONNECT_SECONDS = 120.0
+
@dataclass
class _PendingSession:
task: asyncio.Task[Session]
+ startup: SessionStartup
waiters: int = 0
+ close_handle: asyncio.TimerHandle | None = None
+ expired: bool = False
class SessionManager:
@@ -120,7 +126,7 @@ class SessionManager:
)
self._repository = SessionRepository()
- self._pending: dict[SessionId, _PendingSession] = {}
+ self._pending: dict[str, _PendingSession] = {}
self._connection_locks: WeakValueDictionary[str, asyncio.Lock] = (
WeakValueDictionary()
)
@@ -190,17 +196,20 @@ class SessionManager:
"""Serialize reconnect decisions while a notebook is starting."""
if self._closed:
raise KernelStartupError("Session manager is shut down")
- key = (
- self._resolve_file_key(file_key) or file_key
- if self.mode == SessionMode.EDIT
- else session_id
- )
+ key = self._connection_key(session_id, file_key)
lock = self._connection_locks.get(key)
if lock is None:
lock = asyncio.Lock()
self._connection_locks[key] = lock
return lock
+ def _connection_key(
+ self, session_id: SessionId, file_key: MarimoFileKey
+ ) -> str:
+ if self.mode == SessionMode.EDIT:
+ return self._resolve_file_key(file_key) or file_key
+ return session_id
+
async def create_session(
self,
session_id: SessionId,
@@ -212,52 +221,127 @@ class SessionManager:
"""Return a ready session, retaining ownership during startup."""
if self._closed:
raise KernelStartupError("Session manager is shut down")
+ key = self._connection_key(session_id, file_key)
+ pending = self._pending.get(key)
existing = self._repository.get_sync(session_id)
- if existing is not None:
+ if pending is None and existing is not None:
return existing
- pending = self._pending.get(session_id)
+ if pending is not None and pending.expired:
+ # A new attempt must wait for an expired launch to release its resources.
+ await asyncio.shield(
+ asyncio.gather(pending.task, return_exceptions=True)
+ )
+ return await self.create_session(
+ session_id,
+ session_consumer,
+ query_params,
+ file_key,
+ auto_instantiate,
+ )
if pending is None:
+ startup = SessionStartup()
task = asyncio.create_task(
self._create_session(
session_id,
- session_consumer,
query_params,
file_key,
auto_instantiate,
+ startup,
),
name=f"session.start.{session_id}",
)
- pending = _PendingSession(task)
- self._pending[session_id] = pending
+ pending = _PendingSession(task, startup)
+ self._pending[key] = pending
def finished(task: asyncio.Task[Session]) -> None:
- self._pending.pop(session_id, None)
- # A disconnected caller may no longer be awaiting the error.
- if not task.cancelled():
- task.exception()
+ # Failed launches can be retried; successful ones await attachment.
+ if task.cancelled() or task.exception() is not None:
+ if pending.close_handle is not None:
+ pending.close_handle.cancel()
+ if self._pending.get(key) is pending:
+ self._pending.pop(key)
task.add_done_callback(finished)
+ if pending.close_handle is not None:
+ pending.close_handle.cancel()
+ pending.close_handle = None
pending.waiters += 1
+ attached = False
try:
- return await asyncio.shield(pending.task)
+ with pending.startup.subscribe(session_consumer):
+ session = await asyncio.shield(pending.task)
+ if self._closed:
+ raise KernelStartupError("Session manager is shut down")
+ previous_id = self._repository.get_session_id(session)
+ if (
+ previous_id is None
+ or session.connection_state() == ConnectionState.CLOSED
+ ):
+ if previous_id is not None:
+ self.close_session(previous_id)
+ if self._pending.get(key) is pending:
+ self._pending.pop(key)
+ raise KernelStartupError("Session closed during startup")
+ if session.room.main_consumer is not None:
+ # The connection lock serializes attachment per key, so a
+ # second main consumer means a caller bypassed it. The session
+ # is in use either way, so its startup bookkeeping is done.
+ if self._pending.get(key) is pending:
+ self._pending.pop(key)
+ raise RuntimeError("Session already has a main consumer")
+ if previous_id != session_id:
+ self._repository.update_session_id_sync(
+ previous_id, session_id
+ )
+ session.connect_consumer(session_consumer, main=True)
+ attached = True
+ return session
finally:
pending.waiters -= 1
- if pending.waiters == 0 and not pending.task.done():
- # The last disconnected caller releases its connection lock
- # only after the abandoned launch has cleaned up.
- pending.task.cancel()
- await asyncio.gather(pending.task, return_exceptions=True)
+ if pending.waiters == 0 and self._pending.get(key) is pending:
+ if attached:
+ self._pending.pop(key)
+ elif not self._closed:
+ # Nobody has seen an unattached launch, so a long session
+ # TTL must not keep abandoned kernels alive.
+ pending.close_handle = (
+ asyncio.get_running_loop().call_later(
+ min(self.ttl_seconds, _STARTUP_RECONNECT_SECONDS)
+ if self.ttl_seconds is not None
+ else _STARTUP_RECONNECT_SECONDS,
+ self._expire_startup,
+ key,
+ pending,
+ )
+ )
+
+ def _expire_startup(self, key: str, pending: _PendingSession) -> None:
+ pending.close_handle = None
+ if not pending.task.done():
+ pending.expired = True
+ pending.task.cancel()
+ return
+ self._pending.pop(key, None)
+ if pending.task.cancelled() or pending.task.exception() is not None:
+ return
+ session = pending.task.result()
+ if session.room.size == 0:
+ orphan_id = self._repository.get_session_id(session)
+ if orphan_id is not None:
+ self.close_session(orphan_id)
- def is_session_starting(self, session_id: SessionId) -> bool:
- return session_id in self._pending
+ def is_session_starting(
+ self, session_id: SessionId, file_key: MarimoFileKey
+ ) -> bool:
+ return self._connection_key(session_id, file_key) in self._pending
async def _create_session(
self,
session_id: SessionId,
- session_consumer: SessionConsumer,
query_params: SerializedQueryParams,
file_key: MarimoFileKey,
auto_instantiate: bool,
+ startup: SessionStartup,
) -> Session:
"""Create a new session."""
LOGGER.debug("Creating new session for id %s", session_id)
@@ -283,7 +367,8 @@ class SessionManager:
session = await SessionImpl.create(
initialization_id=file_key,
- session_consumer=session_consumer,
+ startup=startup,
+ session_consumer=None,
mode=self.mode,
app_metadata=AppMetadata(
query_params=query_params,
@@ -495,6 +580,17 @@ class SessionManager:
if session is None:
return False
+ for key, pending in list(self._pending.items()):
+ if (
+ pending.task.done()
+ and not pending.task.cancelled()
+ and pending.task.exception() is None
+ and pending.task.result() is session
+ ):
+ if pending.close_handle is not None:
+ pending.close_handle.cancel()
+ self._pending.pop(key)
+
fire_and_forget(
self._event_bus.emit_session_closed(session),
name="session.closed",
@@ -516,9 +612,13 @@ class SessionManager:
LOGGER.debug("Shutting down")
self._closed = True
pending = [entry.task for entry in self._pending.values()]
+ for entry in self._pending.values():
+ if entry.close_handle is not None:
+ entry.close_handle.cancel()
for task in pending:
task.cancel()
await asyncio.gather(*pending, return_exceptions=True)
+ self._pending.clear()
self.close_all_sessions()
if self._app_host_pool is not None:
self._app_host_pool.shutdown()
diff --git a/marimo/_session/_venv.py b/marimo/_session/_venv.py
index 56e3413a0d..4b05b21b1b 100644
--- a/marimo/_session/_venv.py
+++ b/marimo/_session/_venv.py
@@ -23,6 +23,8 @@ from marimo._environments.uv import UvCommandError, uv_async
from marimo._version import __version__
if TYPE_CHECKING:
+ from collections.abc import Callable
+
from marimo._config.config import VenvConfig
LOGGER = _loggers.marimo_logger()
@@ -180,18 +182,24 @@ async def check_python_version_compatibility(venv_python: str) -> bool:
return venv_version == current_version
-async def install_marimo_into_venv(venv_python: str) -> None:
+async def install_marimo_into_venv(
+ venv_python: str, *, on_output: Callable[[str], None] | None = None
+) -> None:
"""Install marimo into a venv.
Args:
venv_python: Path to the venv's Python interpreter.
+ on_output: Receive installation progress as it is produced.
"""
packages = [f"marimo=={__version__}"]
echo("Installing marimo into configured venv...", err=True)
try:
- await uv_async(["pip", "install", "--python", venv_python] + packages)
+ await uv_async(
+ ["pip", "install", "--python", venv_python] + packages,
+ on_output=on_output,
+ )
except UvCommandError as e:
LOGGER.warning(
f"Failed to install marimo into configured venv: {e.stderr}"
diff --git a/marimo/_session/events.py b/marimo/_session/events.py
index 5798e2d479..80124d6010 100644
--- a/marimo/_session/events.py
+++ b/marimo/_session/events.py
@@ -56,7 +56,7 @@ class SessionEventListener:
def on_notification_sent(
self, session: Session, notification: KernelMessage
) -> None:
- """Called when a notification is emitted by a session."""
+ """Called before a session notification is broadcast to consumers."""
del session
del notification
return
@@ -169,7 +169,7 @@ class SessionEventBus:
def emit_notification_sent(
self, session: Session, notification: KernelMessage
) -> None:
- """Emit a notification sent event."""
+ """Notify listeners before broadcasting to session consumers."""
self._emit(
"notification_sent",
lambda listener: listener.on_notification_sent(
diff --git a/marimo/_session/extensions/extensions.py b/marimo/_session/extensions/extensions.py
index 477b0b8120..ec4bf33842 100644
--- a/marimo/_session/extensions/extensions.py
+++ b/marimo/_session/extensions/extensions.py
@@ -392,14 +392,31 @@ class NotificationListenerExtension(SessionExtension):
def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:
del event_bus
- self.distributor = self._create_distributor(
+ loop = asyncio.get_running_loop()
+ distributor = self._create_distributor(
kernel_manager=self.kernel_manager,
queue_manager=self.queue_manager,
)
- self.distributor.add_consumer(
- lambda msg: self._on_kernel_message(session, msg)
- )
- self.distributor.start()
+ self.distributor = distributor
+
+ def consume(msg: KernelMessage) -> None:
+ # Queued callbacks can outlive the session that scheduled them.
+ if self.distributor is distributor:
+ self._on_kernel_message(session, msg)
+
+ def enqueue(msg: KernelMessage) -> None:
+ if self.distributor is distributor:
+ # QueueDistributor calls from a worker thread. Both transports
+ # must serialize document/view updates with consumer attachment.
+ try:
+ loop.call_soon_threadsafe(consume, msg)
+ except RuntimeError:
+ # Loop teardown can race with the worker's final messages.
+ if not loop.is_closed():
+ raise
+
+ distributor.add_consumer(enqueue)
+ distributor.start()
def on_detach(self) -> None:
if self.distributor is not None:
@@ -471,7 +488,7 @@ class SessionViewExtension(EventAwareExtension):
def on_notification_sent(
self, session: Session, notification: KernelMessage
) -> None:
- """Called when a notification is sent."""
+ """Retain a notification before consumers receive it."""
session.session_view.add_raw_notification(notification)
diff --git a/marimo/_session/managers/ipc.py b/marimo/_session/managers/ipc.py
index f970edfef2..015cf2f5ea 100644
--- a/marimo/_session/managers/ipc.py
+++ b/marimo/_session/managers/ipc.py
@@ -23,8 +23,13 @@ from marimo._config.config import VenvConfig
from marimo._config.manager import MarimoConfigReader
from marimo._config.settings import GLOBAL_SETTINGS
from marimo._environments.overlay import runtime_overlay
+from marimo._messaging.notification import (
+ NotificationMessage,
+ StartupProgressNotification,
+)
from marimo._messaging.types import KernelMessage
from marimo._runtime import commands
+from marimo._runtime.packages.operations import environment_operation
from marimo._session._venv import (
check_python_version_compatibility,
get_configured_venv_python,
@@ -52,7 +57,6 @@ if TYPE_CHECKING:
from marimo._ipc.types import ConnectionInfo
from marimo._runtime.commands import AppMetadata
from marimo._runtime.virtual_file.storage import VirtualFileStorageType
- from marimo._session.model import StartupPhase
from marimo._types.ids import CellId_t
LOGGER = _loggers.marimo_logger()
@@ -278,7 +282,7 @@ class IPCKernelManagerImpl(KernelManager):
app_metadata: AppMetadata,
config_manager: MarimoConfigReader,
redirect_console_to_browser: bool = True,
- on_progress: Callable[[StartupPhase], None] | None = None,
+ on_notification: Callable[[NotificationMessage], None] | None = None,
) -> None:
self.queue_manager = queue_manager
self.connection_info = connection_info
@@ -287,7 +291,7 @@ class IPCKernelManagerImpl(KernelManager):
self.app_metadata = app_metadata
self.config_manager = config_manager
self.redirect_console_to_browser = redirect_console_to_browser
- self._on_progress = on_progress
+ self._notify = on_notification or (lambda _: None)
self._process: subprocess.Popen[bytes] | None = None
self._start_new_session = False
@@ -321,132 +325,164 @@ class IPCKernelManagerImpl(KernelManager):
virtual_file_storage=_virtual_file_storage(),
)
- if self._on_progress is not None:
- self._on_progress("preparing-environment")
- venv_config = _get_venv_config(self.config_manager)
- try:
- configured_python = get_configured_venv_python(
- venv_config, base_path=self.app_metadata.filename
- )
- except ValueError as e:
- raise KernelStartupError(str(e)) from e
-
- # Ephemeral sandboxes are always writable; configured venvs respect the
- # flag.
- writable = True
- kernel_pythonpath: str | None = None
-
- # An explicitly configured venv takes precedence over an ephemeral
- # sandbox.
- if configured_python:
- echo(
- f"Using configured venv: {muted(configured_python)}",
- err=True,
+ self._notify(
+ StartupProgressNotification(
+ phase="preparing-environment", logs="", log_mode="replace"
)
- venv_python = configured_python
+ )
+ with environment_operation(
+ "prepare", {}, "kernel", self._notify
+ ) as operation:
+ venv_config = _get_venv_config(self.config_manager)
+ try:
+ configured_python = get_configured_venv_python(
+ venv_config, base_path=self.app_metadata.filename
+ )
+ except ValueError as e:
+ raise KernelStartupError(str(e)) from e
+
+ # Ephemeral sandboxes are always writable; configured venvs respect the
+ # flag.
+ writable = True
+ kernel_pythonpath: str | None = None
- writable = venv_config.get("writable", False)
+ # An explicitly configured venv takes precedence over an ephemeral
+ # sandbox.
+ if configured_python:
+ echo(
+ f"Using configured venv: {muted(configured_python)}",
+ err=True,
+ )
+ venv_python = configured_python
- # Configured environments are assumed to be read-only.
- # If not, then install marimo by default to ensure that the
- # environment can spawn a marimo kernel.
- if writable:
+ writable = venv_config.get("writable", False)
+
+ # Configured environments are assumed to be read-only.
+ # If not, then install marimo by default to ensure that the
+ # environment can spawn a marimo kernel.
+ if writable:
+ try:
+ await install_marimo_into_venv(
+ venv_python,
+ on_output=lambda line: operation.update(
+ {"environment": line}
+ ),
+ )
+ except Exception as e:
+ raise KernelStartupError(
+ f"Failed to install marimo into configured venv.\n\n{e}"
+ ) from e
+ elif not await has_marimo_installed(venv_python):
+ # Check Python version compatibility for binary deps
+ if not await check_python_version_compatibility(
+ venv_python
+ ):
+ # If we have gotten to this point
+ # - We have a prescribed venv
+ # - The venv is not writable
+ # - The venv does not contain marimo nor zmq
+ # As such there is nothing we can do, as we can't get marimo
+ # into the runtime without installing it somewhere else.
+ raise KernelStartupError(
+ f"Configured venv uses a different Python version than marimo.\n"
+ f"Binary dependencies (pyzmq, msgspec) aren't cross-version compatible.\n\n"
+ f"Options:\n"
+ f" 1. Set writable=true in [tool.marimo.venv] to allow marimo to install deps\n"
+ f" 2. Install marimo in your venv: uv pip install marimo --python {venv_python}\n"
+ f" 3. Remove [tool.marimo.venv].path to use an ephemeral sandbox instead"
+ )
+
+ # Inject PYTHONPATH for marimo and dependencies from the
+ # current runtime as a last chance effort to expose marimo
+ # to the kernel.
+ kernel_pythonpath = get_kernel_pythonpath()
+ # Store the venv python for package manager targeting
+ self._venv_python = venv_python
+ env = construct_kernel_env(
+ base_env=os.environ.copy(),
+ venv_python=venv_python,
+ is_ephemeral_sandbox=False,
+ writable=writable,
+ kernel_pythonpath=kernel_pythonpath,
+ )
+ cmd: list[str] = [
+ venv_python,
+ "-m",
+ "marimo._ipc.launch_kernel",
+ ]
+ plan_launched = False
+ else:
+ # The session retains this Interface so rename and package API
+ # operations update the same Manifest binding and Environment.
+ from marimo._environments import backends
+ from marimo._environments.errors import EnvironmentManagerError
+ from marimo._environments.sandbox import NotebookSandbox
+
+ backend = backends.current_backend()
+ kernel_args_list = ["-m", "marimo._ipc.launch_kernel"]
+ overlay = runtime_overlay()
+ filename = self.app_metadata.filename
+ sandbox = NotebookSandbox(filename, backend)
try:
- await install_marimo_into_venv(venv_python)
- except Exception as e:
+ plan = await sandbox.launch_async(
+ kernel_args_list,
+ overlay=overlay,
+ base_env=os.environ.copy(),
+ on_output=lambda line: operation.update(
+ {"environment": line}
+ ),
+ )
+ except EnvironmentManagerError as e:
+ sandbox.close()
raise KernelStartupError(
- f"Failed to install marimo into configured venv.\n\n{e}"
+ f"Failed to build sandbox environment.\n\n{e}"
) from e
- elif not await has_marimo_installed(venv_python):
- # Check Python version compatibility for binary deps
- if not await check_python_version_compatibility(venv_python):
- # If we have gotten to this point
- # - We have a prescribed venv
- # - The venv is not writable
- # - The venv does not contain marimo nor zmq
- # As such there is nothing we can do, as we can't get marimo
- # into the runtime without installing it somewhere else.
+ except BaseException:
+ sandbox.close()
+ raise
+ handle = sandbox.environment
+ if handle is None:
+ sandbox.close()
raise KernelStartupError(
- f"Configured venv uses a different Python version than marimo.\n"
- f"Binary dependencies (pyzmq, msgspec) aren't cross-version compatible.\n\n"
- f"Options:\n"
- f" 1. Set writable=true in [tool.marimo.venv] to allow marimo to install deps\n"
- f" 2. Install marimo in your venv: uv pip install marimo --python {venv_python}\n"
- f" 3. Remove [tool.marimo.venv].path to use an ephemeral sandbox instead"
+ "Failed to build sandbox environment: no Environment was returned"
)
- # Inject PYTHONPATH for marimo and dependencies from the
- # current runtime as a last chance effort to expose marimo
- # to the kernel.
- kernel_pythonpath = get_kernel_pythonpath()
- # Store the venv python for package manager targeting
- self._venv_python = venv_python
- env = construct_kernel_env(
- base_env=os.environ.copy(),
- venv_python=venv_python,
- is_ephemeral_sandbox=False,
- writable=writable,
- kernel_pythonpath=kernel_pythonpath,
- )
- cmd: list[str] = [venv_python, "-m", "marimo._ipc.launch_kernel"]
- plan_launched = False
- else:
- # The session retains this Interface so rename and package API
- # operations update the same Manifest binding and Environment.
- from marimo._environments import backends
- from marimo._environments.errors import EnvironmentManagerError
- from marimo._environments.sandbox import NotebookSandbox
-
- backend = backends.current_backend()
- kernel_args_list = ["-m", "marimo._ipc.launch_kernel"]
- overlay = runtime_overlay()
- filename = self.app_metadata.filename
- sandbox = NotebookSandbox(filename, backend)
- try:
- plan = await sandbox.launch_async(
- kernel_args_list,
- overlay=overlay,
- base_env=os.environ.copy(),
- on_output=lambda _line: None,
- )
- except EnvironmentManagerError as e:
- sandbox.close()
- raise KernelStartupError(
- f"Failed to build sandbox environment.\n\n{e}"
- ) from e
- except BaseException:
- sandbox.close()
- raise
- handle = sandbox.environment
- if handle is None:
- sandbox.close()
- raise KernelStartupError(
- "Failed to build sandbox environment: no Environment was returned"
+ self._notebook_sandbox = sandbox
+ self._venv_python = handle.python
+ echo(
+ f"Running kernel in script environment: {muted(handle.root)}",
+ err=True,
)
- self._notebook_sandbox = sandbox
- self._venv_python = handle.python
- echo(
- f"Running kernel in script environment: {muted(handle.root)}",
- err=True,
- )
-
- plan_launched = True
- env = plan.env
- env["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"
- env["MARIMO_SANDBOX_MODE"] = "multi"
- env["MARIMO_SANDBOX_BACKEND"] = backend
- cmd = list(plan.argv)
+ plan_launched = True
+ env = plan.env
+ env["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"
+ env["MARIMO_SANDBOX_MODE"] = "multi"
+ env["MARIMO_SANDBOX_BACKEND"] = backend
+ cmd = list(plan.argv)
self._start_new_session = (
plan.start_new_session if plan_launched else False
)
LOGGER.debug(f"Launching kernel: {' '.join(cmd)}")
handshake: asyncio.Future[list[str]] | None = None
+ loop = asyncio.get_running_loop()
+ streaming_startup = True
+
+ def report_startup_output(line: str) -> None:
+ if streaming_startup:
+ self._notify(
+ StartupProgressNotification(
+ phase="starting-kernel", logs=line, log_mode="append"
+ )
+ )
try:
- if self._on_progress is not None:
- self._on_progress("starting-kernel")
+ self._notify(
+ StartupProgressNotification(
+ phase="starting-kernel", logs="", log_mode="replace"
+ )
+ )
self._process = subprocess.Popen( # noqa: ASYNC220 — owns the child before yielding
cmd,
stdin=subprocess.PIPE,
@@ -471,6 +507,18 @@ class IPCKernelManagerImpl(KernelManager):
for line in iter(pipe.readline, b""):
if stream == "stderr":
stderr_tail.append(line)
+ if streaming_startup:
+ # Windows pipes carry CRLF; keep one stream shape.
+ text = line.decode(
+ "utf-8", errors="replace"
+ ).replace("\r\n", "\n")
+ try:
+ loop.call_soon_threadsafe(
+ report_startup_output, text
+ )
+ except RuntimeError:
+ if not loop.is_closed():
+ raise
try:
output = getattr(sys, stream).buffer
output.write(line)
@@ -508,7 +556,6 @@ class IPCKernelManagerImpl(KernelManager):
process.wait()
return lines
- loop = asyncio.get_running_loop()
handshake = loop.run_in_executor(None, exchange_handshake)
exited: asyncio.Future[int] = loop.create_future()
@@ -591,8 +638,11 @@ class IPCKernelManagerImpl(KernelManager):
f"Failed to start kernel subprocess.\n\n{e}"
) from e
finally:
- if self.kernel_task is None:
- await self._cleanup_failed_start(handshake)
+ try:
+ if self.kernel_task is None:
+ await self._cleanup_failed_start(handshake)
+ finally:
+ streaming_startup = False
async def _cleanup_failed_start(
self, handshake: asyncio.Future[list[str]] | None = None
diff --git a/marimo/_session/session.py b/marimo/_session/session.py
index 2acd068076..9294c72092 100644
--- a/marimo/_session/session.py
+++ b/marimo/_session/session.py
@@ -18,7 +18,6 @@ from marimo._config.manager import MarimoConfigManager, ScriptConfigManager
from marimo._messaging.notebook.document import NotebookDocument
from marimo._messaging.notification import (
NotificationMessage,
- StartupProgressNotification,
)
from marimo._messaging.serde import serialize_kernel_message
from marimo._messaging.types import KernelMessage
@@ -55,6 +54,7 @@ from marimo._session.managers import (
from marimo._session.model import ConnectionState, SessionMode
from marimo._session.notebook import AppFileManager
from marimo._session.room import Room
+from marimo._session.startup import SessionStartup
from marimo._session.state.session_view import SessionView
from marimo._session.types import (
KernelExitInfo,
@@ -100,7 +100,8 @@ class SessionImpl(Session):
cls,
*,
initialization_id: str,
- session_consumer: SessionConsumer,
+ session_consumer: SessionConsumer | None,
+ startup: SessionStartup,
mode: SessionMode,
app_metadata: AppMetadata,
app_file_manager: AppFileManager,
@@ -175,11 +176,7 @@ class SessionImpl(Session):
app_metadata=app_metadata,
config_manager=config_manager,
redirect_console_to_browser=redirect_console_to_browser,
- on_progress=lambda phase: session_consumer.notify(
- serialize_kernel_message(
- StartupProgressNotification(phase=phase)
- )
- ),
+ on_notification=startup.notify,
)
else:
# Original kernel: Process for edit, Thread for run
@@ -231,6 +228,7 @@ class SessionImpl(Session):
return cls(
initialization_id=initialization_id,
session_consumer=session_consumer,
+ session_view=startup.view,
kernel_manager=kernel_manager,
app_file_manager=app_file_manager,
config_manager=config_manager,
@@ -241,7 +239,8 @@ class SessionImpl(Session):
def __init__(
self,
initialization_id: str,
- session_consumer: SessionConsumer,
+ session_consumer: SessionConsumer | None,
+ session_view: SessionView,
kernel_manager: KernelManager,
app_file_manager: AppFileManager,
config_manager: MarimoConfigManager,
@@ -258,7 +257,7 @@ class SessionImpl(Session):
self.ttl_seconds = (
ttl_seconds if ttl_seconds is not None else _DEFAULT_TTL_SECONDS
)
- self.session_view = SessionView()
+ self.session_view = session_view
self.config_manager = config_manager
self.extensions = ExtensionRegistry()
self.extensions.add(*extensions)
@@ -274,7 +273,8 @@ class SessionImpl(Session):
self._attach_extensions()
# Connect the main consumer after attaching extensions,
# to avoid calling on_attach on the main consumer twice.
- self.connect_consumer(session_consumer, main=True)
+ if session_consumer is not None:
+ self.connect_consumer(session_consumer, main=True)
@property
def stable_id(self) -> StableSessionId:
@@ -492,8 +492,9 @@ class SessionImpl(Session):
else:
notification = serialize_kernel_message(operation)
- self.room.broadcast(notification, except_consumer=from_consumer_id)
+ # Consumers must observe a view that already includes this notification.
self._event_bus.emit_notification_sent(self, notification)
+ self.room.broadcast(notification, except_consumer=from_consumer_id)
def close(self, *, graceful: bool = False) -> None:
"""
diff --git a/marimo/_session/startup.py b/marimo/_session/startup.py
new file mode 100644
index 0000000000..24a29a5c82
--- /dev/null
+++ b/marimo/_session/startup.py
@@ -0,0 +1,75 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+from marimo._messaging.notification import (
+ EnvironmentStateNotification,
+ NotificationMessage,
+)
+from marimo._messaging.serde import serialize_kernel_message
+from marimo._session.state.session_view import SessionView
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+ from marimo._session.consumer import SessionConsumer
+
+
+class SessionStartup:
+ """Retain startup progress independently of the connections observing it."""
+
+ def __init__(self) -> None:
+ self.view = SessionView()
+ self._consumers: list[SessionConsumer] = []
+ # Producers may report from worker threads. The view and consumer
+ # queues belong to the loop that owns this startup.
+ try:
+ self._loop: asyncio.AbstractEventLoop | None = (
+ asyncio.get_running_loop()
+ )
+ except RuntimeError:
+ self._loop = None
+
+ def notify(self, notification: NotificationMessage) -> None:
+ if self._loop is not None and not self._on_loop():
+ try:
+ self._loop.call_soon_threadsafe(self.notify, notification)
+ except RuntimeError:
+ # Loop teardown can race with a worker's final output.
+ if not self._loop.is_closed():
+ raise
+ return
+ self.view.add_notification(notification)
+ message = serialize_kernel_message(notification)
+ for consumer in self._consumers:
+ consumer.notify(message)
+
+ def _on_loop(self) -> bool:
+ try:
+ return asyncio.get_running_loop() is self._loop
+ except RuntimeError:
+ return False
+
+ @contextmanager
+ def subscribe(self, consumer: SessionConsumer) -> Iterator[None]:
+ self._consumers.append(consumer)
+ try:
+ if self.view.startup_progress is not None:
+ consumer.notify(
+ serialize_kernel_message(self.view.startup_progress)
+ )
+ for source in ("kernel", "server"):
+ consumer.notify(
+ serialize_kernel_message(
+ EnvironmentStateNotification(
+ source=source,
+ state=self.view.get_environment_state(source),
+ )
+ )
+ )
+ yield
+ finally:
+ self._consumers.remove(consumer)
diff --git a/marimo/_session/state/environment.py b/marimo/_session/state/environment.py
new file mode 100644
index 0000000000..454c47aa50
--- /dev/null
+++ b/marimo/_session/state/environment.py
@@ -0,0 +1,56 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from marimo._messaging.notification import (
+ EnvironmentOperation,
+ EnvironmentOperationNotification,
+ EnvironmentState,
+ OperationRestartRequired,
+ OperationRunning,
+)
+
+
+def reduce_environment_state(
+ state: EnvironmentState,
+ notification: EnvironmentOperationNotification,
+) -> EnvironmentState:
+ """Retain preparation, active attempts, and the latest mutation result."""
+ operations = {
+ attempt.operation_id: attempt for attempt in state.operations
+ }
+ previous = operations.get(notification.operation_id)
+ if previous is None or not isinstance(
+ notification.status, OperationRunning
+ ):
+ operations = {
+ operation_id: attempt
+ for operation_id, attempt in operations.items()
+ if isinstance(attempt.status, OperationRunning)
+ or attempt.action == "prepare"
+ and notification.action != "prepare"
+ }
+ packages = dict(notification.packages)
+ logs = dict(previous.logs) if previous is not None else {}
+ for name, content in notification.logs.items():
+ if notification.log_mode == "replace":
+ logs[name] = content
+ else:
+ logs[name] = logs.get(name, "") + content
+
+ operations[notification.operation_id] = EnvironmentOperation(
+ packages=packages,
+ logs=logs,
+ source=notification.source,
+ operation_id=notification.operation_id,
+ action=notification.action,
+ status=notification.status,
+ )
+ return EnvironmentState(
+ # A later mutation cannot confirm that a different kernel was launched.
+ restart_required=(
+ state.restart_required
+ or isinstance(notification.status, OperationRestartRequired)
+ or "restart-required" in notification.packages.values()
+ ),
+ operations=list(operations.values()),
+ )
diff --git a/marimo/_session/state/serialize.py b/marimo/_session/state/serialize.py
index 8e118713e9..2988fba9da 100644
--- a/marimo/_session/state/serialize.py
+++ b/marimo/_session/state/serialize.py
@@ -595,7 +595,7 @@ class SessionCacheManager:
# Map the code_hash to the current cell_id from the key
code_hash_to_cell_id[code_hash] = cell_id
- self.session_view = deserialize_session(
- notebook_session, code_hash_to_cell_id
- )
+ cached = deserialize_session(notebook_session, code_hash_to_cell_id)
+ # Cached cell output must not replace this launch's environment state.
+ self.session_view.cell_notifications = cached.cell_notifications
return self.session_view
diff --git a/marimo/_session/state/session_view.py b/marimo/_session/state/session_view.py
index bd42302931..a490962957 100644
--- a/marimo/_session/state/session_view.py
+++ b/marimo/_session/state/session_view.py
@@ -16,8 +16,9 @@ from marimo._messaging.notification import (
CellNotification,
DatasetsNotification,
DataSourceConnectionsNotification,
+ EnvironmentOperationNotification,
+ EnvironmentState,
EsmSpec,
- InstallingPackageAlertNotification,
InterruptedNotification,
ModelClose,
ModelLifecycleNotification,
@@ -28,6 +29,7 @@ from marimo._messaging.notification import (
SQLTableListPreviewNotification,
SQLTablePreviewNotification,
StartupLogsNotification,
+ StartupProgressNotification,
StorageNamespacesNotification,
UIElementMessageNotification,
VariablesNotification,
@@ -47,6 +49,9 @@ from marimo._runtime.commands import (
UpdateUIElementCommand,
)
from marimo._runtime.layout.layout import LayoutConfig
+from marimo._session.state.environment import (
+ reduce_environment_state,
+)
from marimo._sql.connection_utils import (
update_schema_list_in_connection,
update_table_in_connection,
@@ -199,11 +204,14 @@ class SessionView:
# Startup logs for startup command - only one at a time
self.startup_logs: StartupLogsNotification | None = None
+ self.startup_progress: StartupProgressNotification | None = None
- # Package installation logs - accumulated per package
- self.package_logs: dict[
- str, str
- ] = {} # package name -> accumulated logs
+ self._environment_states: dict[
+ Literal["kernel", "server"], EnvironmentState
+ ] = {
+ "kernel": EnvironmentState(restart_required=False, operations=[]),
+ "server": EnvironmentState(restart_required=False, operations=[]),
+ }
# Server-side missing-package alerts already sent this session.
# NOT reset by _touch() — once alerted we don't re-alert.
@@ -464,6 +472,19 @@ class SessionView:
self.model_states.pop(model_id, None)
# ModelCustom is ephemeral — skip for replay
+ elif isinstance(notification, StartupProgressNotification):
+ previous_progress = self.startup_progress
+ logs = notification.logs
+ if (
+ notification.log_mode == "append"
+ and previous_progress is not None
+ and previous_progress.phase == notification.phase
+ ):
+ logs = previous_progress.logs + logs
+ self.startup_progress = StartupProgressNotification(
+ phase=notification.phase, logs=logs, log_mode="replace"
+ )
+
elif isinstance(notification, StartupLogsNotification):
prev = self.startup_logs.content if self.startup_logs else ""
self.startup_logs = StartupLogsNotification(
@@ -471,27 +492,19 @@ class SessionView:
status=notification.status,
)
- elif isinstance(notification, InstallingPackageAlertNotification):
- # Handle streaming logs if present
- if notification.logs and notification.log_status:
- for package_name, new_content in notification.logs.items():
- if notification.log_status == "start":
- # Start new log for this package
- self.package_logs[package_name] = new_content
- elif notification.log_status == "append":
- # Append to existing log
- prev_content = self.package_logs.get(package_name, "")
- self.package_logs[package_name] = (
- prev_content + new_content
- )
- elif notification.log_status == "done":
- # Append final content and mark as done
- prev_content = self.package_logs.get(package_name, "")
- self.package_logs[package_name] = (
- prev_content + new_content
- )
- # We could clean up completed logs here if desired,
- # but for now keep them for replay purposes
+ elif isinstance(notification, EnvironmentOperationNotification):
+ self._environment_states[notification.source] = (
+ reduce_environment_state(
+ self._environment_states[notification.source],
+ notification,
+ )
+ )
+
+ def get_environment_state(
+ self, source: Literal["kernel", "server"]
+ ) -> EnvironmentState:
+ """Snapshot a target environment's attempts and restart requirement."""
+ return copy.deepcopy(self._environment_states[source])
def get_cell_outputs(
self, ids: list[CellId_t]
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 962f17ed21..e8de89183e 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -1729,6 +1729,154 @@ components:
- theme
title: DisplayConfig
type: object
+ EnvironmentOperation:
+ description: Current progress and logs for one execution of environment work.
+ properties:
+ action:
+ enum:
+ - install
+ - prepare
+ - remove
+ - sync
+ logs:
+ additionalProperties:
+ type: string
+ type: object
+ operation_id:
+ type: string
+ packages:
+ additionalProperties:
+ enum:
+ - failed
+ - queued
+ - restart-required
+ - running
+ - succeeded
+ type: object
+ source:
+ enum:
+ - kernel
+ - server
+ status:
+ anyOf:
+ - $ref: '#/components/schemas/OperationRunning'
+ - $ref: '#/components/schemas/OperationSucceeded'
+ - $ref: '#/components/schemas/OperationRestartRequired'
+ - $ref: '#/components/schemas/OperationFailed'
+ - $ref: '#/components/schemas/OperationCancelled'
+ discriminator:
+ mapping:
+ cancelled: '#/components/schemas/OperationCancelled'
+ failed: '#/components/schemas/OperationFailed'
+ restart-required: '#/components/schemas/OperationRestartRequired'
+ running: '#/components/schemas/OperationRunning'
+ succeeded: '#/components/schemas/OperationSucceeded'
+ propertyName: kind
+ required:
+ - operation_id
+ - action
+ - status
+ - packages
+ - logs
+ - source
+ title: EnvironmentOperation
+ type: object
+ EnvironmentOperationNotification:
+ description: "Current operation progress and changes to its named log streams.\n\
+ \n Package statuses replace the previous map. Log chunks append to a stream,\n\
+ \ or replace it when `log_mode` is `replace`. The operation status determines\n\
+ \ completion independently of its packages and output streams."
+ properties:
+ action:
+ enum:
+ - install
+ - prepare
+ - remove
+ - sync
+ log_mode:
+ enum:
+ - append
+ - replace
+ logs:
+ additionalProperties:
+ type: string
+ type: object
+ op:
+ enum:
+ - environment-operation
+ operation_id:
+ type: string
+ packages:
+ additionalProperties:
+ enum:
+ - failed
+ - queued
+ - restart-required
+ - running
+ - succeeded
+ type: object
+ source:
+ enum:
+ - kernel
+ - server
+ status:
+ anyOf:
+ - $ref: '#/components/schemas/OperationRunning'
+ - $ref: '#/components/schemas/OperationSucceeded'
+ - $ref: '#/components/schemas/OperationRestartRequired'
+ - $ref: '#/components/schemas/OperationFailed'
+ - $ref: '#/components/schemas/OperationCancelled'
+ discriminator:
+ mapping:
+ cancelled: '#/components/schemas/OperationCancelled'
+ failed: '#/components/schemas/OperationFailed'
+ restart-required: '#/components/schemas/OperationRestartRequired'
+ running: '#/components/schemas/OperationRunning'
+ succeeded: '#/components/schemas/OperationSucceeded'
+ propertyName: kind
+ required:
+ - op
+ - operation_id
+ - action
+ - status
+ - source
+ - packages
+ - logs
+ - log_mode
+ title: EnvironmentOperationNotification
+ type: object
+ EnvironmentState:
+ description: Preparation, active operations, the latest mutation, and restarts.
+ properties:
+ operations:
+ items:
+ $ref: '#/components/schemas/EnvironmentOperation'
+ type: array
+ restart_required:
+ type: boolean
+ required:
+ - restart_required
+ - operations
+ title: EnvironmentState
+ type: object
+ EnvironmentStateNotification:
+ description: Replace the current state for one environment on connection.
+ properties:
+ op:
+ enum:
+ - environment-state
+ source:
+ enum:
+ - kernel
+ - server
+ state:
+ $ref: '#/components/schemas/EnvironmentState'
+ required:
+ - op
+ - source
+ - state
+ title: EnvironmentStateNotification
+ type: object
EnvironmentVariableDiscoveryValue:
description: A reference to an environment variable, never its value.
properties:
@@ -2749,52 +2897,6 @@ components:
- versions
title: InstallPackagesRequest
type: object
- InstallingPackageAlertNotification:
- description: "Package installation progress with streaming logs.\n\n Attributes:\n\
- \ packages: Package name to status (queued/installing/installed/failed).\n\
- \ logs: Optional streaming logs per package.\n log_status: Log\
- \ stream status (append/start/done).\n source: Which Python environment\
- \ packages are installed into.\n \"kernel\" (default) installs\
- \ in the kernel's venv; \"server\"\n installs in the server's\
- \ own Python env."
- properties:
- log_status:
- anyOf:
- - enum:
- - append
- - done
- - start
- - type: 'null'
- default: null
- logs:
- anyOf:
- - additionalProperties:
- type: string
- type: object
- - type: 'null'
- default: null
- op:
- enum:
- - installing-package-alert
- packages:
- additionalProperties:
- enum:
- - failed
- - installed
- - installing
- - queued
- - restart-required
- type: object
- source:
- default: kernel
- enum:
- - kernel
- - server
- required:
- - op
- - packages
- title: InstallingPackageAlertNotification
- type: object
InstantiateNotebookRequest:
properties:
autoRun:
@@ -3182,7 +3284,8 @@ components:
- $ref: '#/components/schemas/AlertNotification'
- $ref: '#/components/schemas/BannerNotification'
- $ref: '#/components/schemas/MissingPackageAlertNotification'
- - $ref: '#/components/schemas/InstallingPackageAlertNotification'
+ - $ref: '#/components/schemas/EnvironmentOperationNotification'
+ - $ref: '#/components/schemas/EnvironmentStateNotification'
- $ref: '#/components/schemas/StartupLogsNotification'
- $ref: '#/components/schemas/StartupProgressNotification'
- $ref: '#/components/schemas/KernelStartupErrorNotification'
@@ -3225,9 +3328,10 @@ components:
data-source-connections: '#/components/schemas/DataSourceConnectionsNotification'
data-source-discovery-result: '#/components/schemas/DataSourceDiscoveryResultNotification'
datasets: '#/components/schemas/DatasetsNotification'
+ environment-operation: '#/components/schemas/EnvironmentOperationNotification'
+ environment-state: '#/components/schemas/EnvironmentStateNotification'
focus-cell: '#/components/schemas/FocusCellNotification'
function-call-result: '#/components/schemas/FunctionCallResultNotification'
- installing-package-alert: '#/components/schemas/InstallingPackageAlertNotification'
interrupted: '#/components/schemas/InterruptedNotification'
kernel-ready: '#/components/schemas/KernelReadyNotification'
kernel-startup-error: '#/components/schemas/KernelStartupErrorNotification'
@@ -4321,6 +4425,62 @@ components:
- tutorialId
title: OpenTutorialRequest
type: object
+ OperationCancelled:
+ additionalProperties: false
+ properties:
+ kind:
+ enum:
+ - cancelled
+ required:
+ - kind
+ title: OperationCancelled
+ type: object
+ OperationFailed:
+ additionalProperties: false
+ properties:
+ error:
+ type: string
+ kind:
+ enum:
+ - failed
+ required:
+ - kind
+ - error
+ title: OperationFailed
+ type: object
+ OperationRestartRequired:
+ additionalProperties: false
+ properties:
+ kind:
+ enum:
+ - restart-required
+ reason:
+ type: string
+ required:
+ - kind
+ - reason
+ title: OperationRestartRequired
+ type: object
+ OperationRunning:
+ additionalProperties: false
+ properties:
+ kind:
+ enum:
+ - running
+ required:
+ - kind
+ title: OperationRunning
+ type: object
+ OperationSucceeded:
+ additionalProperties: false
+ properties:
+ kind:
+ enum:
+ - succeeded
+ required:
+ - kind
+ title: OperationSucceeded
+ type: object
PackageDescription:
properties:
name:
@@ -5526,8 +5686,16 @@ components:
title: StartupLogsNotification
type: object
StartupProgressNotification:
- description: Progress reported before a session's kernel is ready.
+ description: "Current startup phase and its output before the kernel is ready.\n\
+ \n Output appends within a phase. Snapshots replace it, and changing phases\n\
+ \ starts a new stream. Environment preparation logs belong to its operation."
properties:
+ log_mode:
+ enum:
+ - append
+ - replace
+ logs:
+ type: string
op:
enum:
- startup-progress
@@ -5538,6 +5706,8 @@ components:
required:
- op
- phase
+ - logs
+ - log_mode
title: StartupProgressNotification
type: object
StdinRequest:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 875c0486e2..16114ab42a 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -4873,6 +4873,89 @@ export interface components {
/** @enum {unknown} */
theme: "dark" | "light" | "system";
};
+ /**
+ * EnvironmentOperation
+ * @description Current progress and logs for one execution of environment work.
+ */
+ EnvironmentOperation: {
+ /** @enum {unknown} */
+ action: "install" | "prepare" | "remove" | "sync";
+ logs: {
+ [key: string]: string;
+ };
+ operation_id: string;
+ packages: {
+ [key: string]:
+ | "failed"
+ | "queued"
+ | "restart-required"
+ | "running"
+ | "succeeded";
+ };
+ /** @enum {unknown} */
+ source: "kernel" | "server";
+ status:
+ | components["schemas"]["OperationRunning"]
+ | components["schemas"]["OperationSucceeded"]
+ | components["schemas"]["OperationRestartRequired"]
+ | components["schemas"]["OperationFailed"]
+ | components["schemas"]["OperationCancelled"];
+ };
+ /**
+ * EnvironmentOperationNotification
+ * @description Current operation progress and changes to its named log streams.
+ *
+ * Package statuses replace the previous map. Log chunks append to a stream,
+ * or replace it when `log_mode` is `replace`. The operation status determines
+ * completion independently of its packages and output streams.
+ */
+ EnvironmentOperationNotification: {
+ /** @enum {unknown} */
+ action: "install" | "prepare" | "remove" | "sync";
+ /** @enum {unknown} */
+ log_mode: "append" | "replace";
+ logs: {
+ [key: string]: string;
+ };
+ /** @enum {unknown} */
+ op: "environment-operation";
+ operation_id: string;
+ packages: {
+ [key: string]:
+ | "failed"
+ | "queued"
+ | "restart-required"
+ | "running"
+ | "succeeded";
+ };
+ /** @enum {unknown} */
+ source: "kernel" | "server";
+ status:
+ | components["schemas"]["OperationRunning"]
+ | components["schemas"]["OperationSucceeded"]
+ | components["schemas"]["OperationRestartRequired"]
+ | components["schemas"]["OperationFailed"]
+ | components["schemas"]["OperationCancelled"];
+ };
+ /**
+ * EnvironmentState
+ * @description Preparation, active operations, the latest mutation, and restarts.
+ */
+ EnvironmentState: {
+ operations: components["schemas"]["EnvironmentOperation"][];
+ restart_required: boolean;
+ };
+ /**
+ * EnvironmentStateNotification
+ * @description Replace the current state for one environment on connection.
+ */
+ EnvironmentStateNotification: {
+ /** @enum {unknown} */
+ op: "environment-state";
+ /** @enum {unknown} */
+ source: "kernel" | "server";
+ state: components["schemas"]["EnvironmentState"];
+ };
/**
* EnvironmentVariableDiscoveryValue
* @description A reference to an environment variable, never its value.
@@ -5493,41 +5576,6 @@ export interface components {
[key: string]: string;
};
};
- /**
- * InstallingPackageAlertNotification
- * @description Package installation progress with streaming logs.
- *
- * Attributes:
- * packages: Package name to status (queued/installing/installed/failed).
- * logs: Optional streaming logs per package.
- * log_status: Log stream status (append/start/done).
- * source: Which Python environment packages are installed into.
- * "kernel" (default) installs in the kernel's venv; "server"
- * installs in the server's own Python env.
- */
- InstallingPackageAlertNotification: {
- /** @default null */
- log_status?: ("append" | "done" | "start") | null;
- /** @default null */
- logs?: {
- [key: string]: string;
- } | null;
- /** @enum {unknown} */
- op: "installing-package-alert";
- packages: {
- [key: string]:
- | "failed"
- | "installed"
- | "installing"
- | "queued"
- | "restart-required";
- };
- /**
- * @default kernel
- * @enum {unknown}
- */
- source?: "kernel" | "server";
- };
/** InstantiateNotebookRequest */
InstantiateNotebookRequest: {
/** @default true */
@@ -5763,7 +5811,8 @@ export interface components {
| components["schemas"]["AlertNotification"]
| components["schemas"]["BannerNotification"]
| components["schemas"]["MissingPackageAlertNotification"]
- | components["schemas"]["InstallingPackageAlertNotification"]
+ | components["schemas"]["EnvironmentOperationNotification"]
+ | components["schemas"]["EnvironmentStateNotification"]
| components["schemas"]["StartupLogsNotification"]
| components["schemas"]["StartupProgressNotification"]
| components["schemas"]["KernelStartupErrorNotification"]
@@ -6429,6 +6478,33 @@ export interface components {
)
| "markdown-format";
};
+ /** OperationCancelled */
+ OperationCancelled: {
+ /** @enum {unknown} */
+ kind: "cancelled";
+ };
+ /** OperationFailed */
+ OperationFailed: {
+ error: string;
+ /** @enum {unknown} */
+ kind: "failed";
+ };
+ /** OperationRestartRequired */
+ OperationRestartRequired: {
+ /** @enum {unknown} */
+ kind: "restart-required";
+ reason: string;
+ };
+ /** OperationRunning */
+ OperationRunning: {
+ /** @enum {unknown} */
+ kind: "running";
+ };
+ /** OperationSucceeded */
+ OperationSucceeded: {
+ /** @enum {unknown} */
+ kind: "succeeded";
+ };
/** PackageDescription */
PackageDescription: {
name: string;
@@ -7203,9 +7279,15 @@ export interface components {
};
/**
* StartupProgressNotification
- * @description Progress reported before a session's kernel is ready.
+ * @description Current startup phase and its output before the kernel is ready.
+ *
+ * Output appends within a phase. Snapshots replace it, and changing phases
+ * starts a new stream. Environment preparation logs belong to its operation.
*/
StartupProgressNotification: {
+ /** @enum {unknown} */
+ log_mode: "append" | "replace";
+ logs: string;
/** @enum {unknown} */
op: "startup-progress";
/** @enum {unknown} */
diff --git a/scripts/generate_schemas.py b/scripts/generate_schemas.py
index c155b6d632..f1bd73aaff 100755
--- a/scripts/generate_schemas.py
+++ b/scripts/generate_schemas.py
@@ -42,7 +42,8 @@ with app.setup:
o.CompletionResultNotification,
o.AlertNotification,
o.MissingPackageAlertNotification,
- o.InstallingPackageAlertNotification,
+ o.EnvironmentOperationNotification,
+ o.EnvironmentStateNotification,
o.ReconnectedNotification,
o.StartupLogsNotification,
o.BannerNotification,
diff --git a/tests/_code_mode/test_code_mode_context.py b/tests/_code_mode/test_code_mode_context.py
index 29ca5f9593..5df4855388 100644
--- a/tests/_code_mode/test_code_mode_context.py
+++ b/tests/_code_mode/test_code_mode_context.py
@@ -21,7 +21,9 @@ from marimo._messaging.notebook.document import (
notebook_document_context,
)
from marimo._messaging.notification import (
+ EnvironmentOperationNotification,
NotebookDocumentTransactionNotification,
+ OperationRunning,
)
from marimo._runtime.commands import ExecuteCellCommand
from marimo._runtime.packages.package_manager import PackageDescription
@@ -825,6 +827,7 @@ class TestPackages:
async def test_add_and_remove_in_same_batch(self, k: Kernel) -> None:
"""add and remove can coexist in the same batch, executed in order."""
with _ctx(k) as ctx:
+ _clear_messages(k)
pm = k.packages_callbacks.package_manager
assert pm is not None
@@ -832,7 +835,7 @@ class TestPackages:
async def track_install(package: str, **_kwargs: object) -> bool:
call_order.append(("add", package))
- return True
+ return package != "missing-package"
async def track_uninstall(package: str, **_kwargs: object) -> bool:
call_order.append(("remove", package))
@@ -845,8 +848,51 @@ class TestPackages:
async with ctx as nb:
nb.packages.add("polars")
nb.packages.remove("pandas")
+ nb.packages.add("numpy", "missing-package")
- assert call_order == [("add", "polars"), ("remove", "pandas")]
+ assert call_order == [
+ ("add", "polars"),
+ ("remove", "pandas"),
+ ("add", "numpy"),
+ ("add", "missing-package"),
+ ]
+ notifications = [
+ notification
+ for notification in k.stream.operations
+ if isinstance(notification, EnvironmentOperationNotification)
+ ]
+ assert [
+ (
+ notification.action,
+ notification.packages,
+ msgspec.to_builtins(notification.status)["kind"],
+ )
+ for notification in notifications
+ if not isinstance(notification.status, OperationRunning)
+ ] == snapshot(
+ [
+ (
+ "install",
+ {"polars": "succeeded"},
+ "succeeded",
+ ),
+ ("remove", {"pandas": "succeeded"}, "succeeded"),
+ (
+ "install",
+ {"numpy": "succeeded", "missing-package": "failed"},
+ "failed",
+ ),
+ ]
+ )
+ assert len({n.operation_id for n in notifications}) == 3
+ assert all(
+ n.action in ("install", "remove") for n in notifications
+ )
+ assert any(
+ n.logs
+ == {"missing-package": "Failed to install missing-package\n"}
+ for n in notifications
+ )
async def test_exception_discards_package_ops(self, k: Kernel) -> None:
"""If an exception occurs, queued package ops are discarded."""
@@ -954,7 +1000,9 @@ async def test_package_summary_reports_unsuccessful_outcomes(
restart_required: bool,
) -> None:
from marimo._messaging.notification import (
- InstallingPackageAlertNotification,
+ EnvironmentOperationNotification,
+ OperationFailed,
+ OperationRestartRequired,
)
with _ctx(k) as ctx:
@@ -985,11 +1033,29 @@ async def test_package_summary_reports_unsuccessful_outcomes(
alerts = [
n
for n in k.stream.operations
- if isinstance(n, InstallingPackageAlertNotification)
+ if isinstance(n, EnvironmentOperationNotification)
]
- assert alerts[-1].packages == {
- "boltons": "restart-required" if restart_required else "failed"
- }
+ operation_id = alerts[0].operation_id
+ assert operation_id is not None
+ assert {alert.operation_id for alert in alerts} == {operation_id}
+ outcome = "restart-required" if restart_required else "failed"
+ assert alerts[-1] == EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ logs={},
+ log_mode="append",
+ packages={"boltons": outcome},
+ operation_id=operation_id,
+ status=(
+ OperationRestartRequired(
+ reason="Dependency changes are saved; restart the kernel to apply them."
+ )
+ if restart_required
+ else OperationFailed(
+ error="Could not apply changes to boltons. See operation logs for details."
+ )
+ ),
+ )
class TestAutorunStaleState:
diff --git a/tests/_internal/snapshots/internal_api.txt b/tests/_internal/snapshots/internal_api.txt
index aac84ef919..f0461e8c96 100644
--- a/tests/_internal/snapshots/internal_api.txt
+++ b/tests/_internal/snapshots/internal_api.txt
@@ -69,10 +69,11 @@ notifications
DataColumnPreviewNotification
DataSourceConnectionsNotification
DatasetsNotification
+ EnvironmentOperationNotification
+ EnvironmentStateNotification
FocusCellNotification
FunctionCallResultNotification
HumanReadableStatus
- InstallingPackageAlertNotification
InterruptedNotification
KernelCapabilitiesNotification
KernelReadyNotification
diff --git a/tests/_messaging/test_notifications.py b/tests/_messaging/test_notifications.py
index 18b7d12ab1..1f1780e982 100644
--- a/tests/_messaging/test_notifications.py
+++ b/tests/_messaging/test_notifications.py
@@ -3,12 +3,21 @@ from __future__ import annotations
from unittest.mock import MagicMock
+import msgspec
+import pytest
+
from marimo._ast.toplevel import HINT_UNPARSABLE, TopLevelStatus
from marimo._messaging.notification import (
CellNotification,
- InstallingPackageAlertNotification,
+ EnvironmentOperationNotification,
+ EnvironmentOperationStatus,
ModelLifecycleNotification,
ModelOpen,
+ OperationCancelled,
+ OperationFailed,
+ OperationRestartRequired,
+ OperationRunning,
+ OperationSucceeded,
StartupLogsNotification,
UIElementMessageNotification,
)
@@ -16,6 +25,11 @@ from marimo._messaging.notification_utils import (
CellNotificationUtils,
broadcast_notification,
)
+from marimo._messaging.serde import (
+ deserialize_kernel_message,
+ serialize_kernel_message,
+)
+from marimo._messaging.types import KernelMessage
from marimo._messaging.variables import create_variable_value
from marimo._output.hypertext import Html
from marimo._plugins.ui._impl.input import slider
@@ -88,30 +102,77 @@ def test_startup_logs_all_statuses() -> None:
assert startup_log.content == f"Test {status}"
-def test_installing_package_alert_basic() -> None:
- """Test basic InstallingPackageAlert without streaming logs."""
- alert = InstallingPackageAlertNotification(
- packages={"numpy": "queued", "pandas": "installing"}
+ ("status", "expected"),
+ [
+ (OperationRunning(), {"kind": "running"}),
+ (OperationSucceeded(), {"kind": "succeeded"}),
+ (
+ OperationRestartRequired(reason="Python version changed"),
+ {"kind": "restart-required", "reason": "Python version changed"},
+ ),
+ (
+ OperationFailed(error="Could not resolve dependencies"),
+ {"kind": "failed", "error": "Could not resolve dependencies"},
+ ),
+ (OperationCancelled(), {"kind": "cancelled"}),
+ ],
+)
+def test_environment_operation_wire_format(
+ status: EnvironmentOperationStatus,
+ expected: dict[str, str],
+) -> None:
+ notification = EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ logs={},
+ log_mode="append",
+ operation_id="install",
+ status=status,
+ packages={},
)
- assert alert.name == "installing-package-alert"
- assert alert.packages == {"numpy": "queued", "pandas": "installing"}
- assert alert.logs is None
- assert alert.log_status is None
-
+ encoded = serialize_kernel_message(notification)
+ assert msgspec.json.decode(encoded) == {
+ "op": "environment-operation",
+ "action": "install",
+ "source": "kernel",
+ "logs": {},
+ "log_mode": "append",
+ "operation_id": "install",
+ "status": expected,
+ "packages": {},
+ }
+ assert deserialize_kernel_message(encoded) == notification
-def test_installing_package_alert_with_logs() -> None:
- """Test InstallingPackageAlert with streaming logs."""
- packages = {"numpy": "installing"}
- logs = {"numpy": "Installing numpy...\n"}
- alert = InstallingPackageAlertNotification(
- packages=packages, logs=logs, log_status="start"
+ "status",
+ [
+ {"kind": "failed"},
+ {"kind": "restart-required"},
+ {"kind": "succeeded", "error": "Could not resolve dependencies"},
+ "running",
+ ],
+)
+def test_installation_status_rejects_invalid_wire_state(
+ status: object,
+) -> None:
+ message = KernelMessage(
+ msgspec.json.encode(
+ {
+ "op": "environment-operation",
+ "operation_id": "install",
+ "action": "install",
+ "source": "kernel",
+ "logs": {},
+ "log_mode": "append",
+ "packages": {},
+ "status": status,
+ }
+ )
)
-
- assert alert.name == "installing-package-alert"
- assert alert.packages == packages
- assert alert.logs == logs
- assert alert.log_status == "start"
+ with pytest.raises(msgspec.ValidationError):
+ deserialize_kernel_message(message)
def test_send_ui_element_message_broadcast() -> None:
diff --git a/tests/_runtime/packages/test_operations.py b/tests/_runtime/packages/test_operations.py
new file mode 100644
index 0000000000..bfe58b63ef
--- /dev/null
+++ b/tests/_runtime/packages/test_operations.py
@@ -0,0 +1,124 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+import threading
+
+import pytest
+
+from marimo._messaging.notification import (
+ EnvironmentOperationNotification,
+ OperationCancelled,
+ OperationFailed,
+ OperationRestartRequired,
+ OperationRunning,
+ OperationSucceeded,
+ PackageStatusType,
+)
+from marimo._runtime.packages.operations import (
+ EnvironmentOperationReporter,
+ environment_operation,
+)
+
+
+def test_retries_have_distinct_ids_and_do_not_mutate_previous_updates() -> (
+ None
+):
+ notifications: list[EnvironmentOperationNotification] = []
+ packages: PackageStatusType = {"numpy": "failed"}
+ with environment_operation(
+ "install", packages, "kernel", notifications.append
+ ):
+ pass
+ first = notifications[-1]
+ with environment_operation(
+ "install", packages, "kernel", notifications.append
+ ):
+ packages["numpy"] = "succeeded"
+ retry = notifications[-1]
+ assert first.operation_id != retry.operation_id
+ assert (first.packages, retry.packages) == (
+ {"numpy": "failed"},
+ {"numpy": "succeeded"},
+ )
+
+
+ "packages",
+ [
+ {"numpy": "succeeded", "pandas": "queued"},
+ {"numpy": "restart-required", "pandas": "failed"},
+ ],
+)
+def test_incomplete_work_cannot_report_success(
+ packages: PackageStatusType,
+) -> None:
+ notifications: list[EnvironmentOperationNotification] = []
+ with environment_operation(
+ "install", packages, "kernel", notifications.append
+ ):
+ pass
+ status = notifications[-1].status
+ assert isinstance(status, OperationFailed)
+ assert "pandas" in status.error
+
+
+ ("packages", "expected"),
+ [
+ ({}, OperationSucceeded()),
+ ({"numpy": "succeeded"}, OperationSucceeded()),
+ (
+ {"numpy": "restart-required", "pandas": "succeeded"},
+ OperationRestartRequired(
+ reason="Dependency changes are saved; restart the kernel to apply them."
+ ),
+ ),
+ ],
+)
+def test_completed_work_reports_its_outcome(
+ packages: PackageStatusType,
+ expected: OperationSucceeded | OperationRestartRequired,
+) -> None:
+ notifications: list[EnvironmentOperationNotification] = []
+ with environment_operation(
+ "sync", packages, "kernel", notifications.append
+ ):
+ pass
+ assert [notification.status for notification in notifications] == [
+ OperationRunning(),
+ expected,
+ ]
+
+
+async def test_cancelled_worker_cannot_resume_a_finished_operation() -> None:
+ notifications: list[EnvironmentOperationNotification] = []
+ entered, release, finished = (threading.Event() for _ in range(3))
+
+ def output(operation: EnvironmentOperationReporter) -> None:
+ entered.set()
+ try:
+ assert release.wait(5)
+ operation.update({"numpy": "Late output\n"})
+ finally:
+ finished.set()
+
+ async def install() -> None:
+ with environment_operation(
+ "install", {}, "kernel", notifications.append
+ ) as operation:
+ await asyncio.to_thread(output, operation)
+
+ task = asyncio.create_task(install())
+ try:
+ assert await asyncio.to_thread(entered.wait, 5)
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ finally:
+ release.set()
+ assert await asyncio.to_thread(finished.wait, 5)
+ assert [notification.status for notification in notifications] == [
+ OperationRunning(),
+ OperationCancelled(),
+ ]
diff --git a/tests/_runtime/test_manage_script_metadata.py b/tests/_runtime/test_manage_script_metadata.py
index 27b6b420f4..ff7ca1fa7d 100644
--- a/tests/_runtime/test_manage_script_metadata.py
+++ b/tests/_runtime/test_manage_script_metadata.py
@@ -12,8 +12,10 @@ from marimo._config.settings import GLOBAL_SETTINGS
from marimo._dependencies.dependencies import DependencyManager
from marimo._dependencies.errors import ManyModulesNotFoundError
from marimo._messaging.notification import (
- InstallingPackageAlertNotification,
+ EnvironmentOperationNotification,
MissingPackageAlertNotification,
+ OperationFailed,
+ OperationSucceeded,
)
from marimo._runtime.commands import (
CommandMessage,
@@ -307,14 +309,14 @@ async def test_missing_packages_hook(
k = mocked_kernel.k
control_requests: list[CommandMessage] = []
broadcast_messages: list[
- InstallingPackageAlertNotification | MissingPackageAlertNotification
+ EnvironmentOperationNotification | MissingPackageAlertNotification
] = []
def mock_enqueue(request: CommandMessage) -> None:
control_requests.append(request)
def mock_broadcast(
- msg: InstallingPackageAlertNotification
+ msg: EnvironmentOperationNotification
| MissingPackageAlertNotification,
stream: Any = None,
) -> None:
@@ -415,14 +417,14 @@ def test_missing_packages_hook_pip(
k = mocked_kernel.k
control_requests: list[CommandMessage] = []
broadcast_messages: list[
- InstallingPackageAlertNotification | MissingPackageAlertNotification
+ EnvironmentOperationNotification | MissingPackageAlertNotification
] = []
def mock_enqueue(request: CommandMessage) -> None:
control_requests.append(request)
def mock_broadcast(
- msg: InstallingPackageAlertNotification
+ msg: EnvironmentOperationNotification
| MissingPackageAlertNotification,
stream: Any = None,
) -> None:
@@ -497,296 +499,13 @@ def test_missing_packages_hook_pip(
"scipy": "",
}
-
-async def test_install_missing_packages_with_streaming_logs(
- mocked_kernel: MockedKernel,
-) -> None:
- """Test that install_missing_packages uses streaming logs functionality."""
- k = mocked_kernel.k
- broadcast_messages: list[InstallingPackageAlertNotification] = []
-
- def mock_broadcast(msg, stream=None):
- """Mock the broadcast_notification function to capture alerts"""
- del stream
- if isinstance(msg, InstallingPackageAlertNotification):
- broadcast_messages.append(msg)
-
- # Mock package manager
- mock_package_manager = Mock(spec=PipPackageManager, restart_required=False)
- mock_package_manager.name = "pip"
- mock_package_manager.is_manager_installed.return_value = True
- mock_package_manager.attempted_to_install.return_value = False
- mock_package_manager.package_to_module.return_value = "test_module"
-
- # Mock successful installation with log callback
- async def mock_install(pkg: str, version=None, log_callback=None):
- del pkg, version
- if log_callback:
- log_callback("Starting installation...\n")
- log_callback("Downloading package...\n")
- log_callback("Installing package...\n")
- log_callback("Installation complete!\n")
- return True
-
- mock_package_manager.install = AsyncMock(side_effect=mock_install)
- mock_package_manager.stream_install = partial(
- PackageManager.stream_install, mock_package_manager
- )
-
- # Set up packages callbacks
- k.packages_callbacks.package_manager = mock_package_manager
-
- with (
- patch(
- "marimo._runtime.callbacks.packages.broadcast_notification",
- mock_broadcast,
- ),
- ):
- # Create install request
- request = InstallPackagesCommand(manager="pip", versions={"numpy": ""})
-
- await k.packages_callbacks.install_missing_packages(request)
-
- # Verify broadcast messages
- assert (
- len(broadcast_messages) >= 5
- ) # Initial + start + done + status updates
-
- # Check that streaming logs were sent
- streaming_alerts = [
- msg for msg in broadcast_messages if msg.logs is not None
- ]
- assert len(streaming_alerts) >= 2 # At least start and done
-
- # Verify start log
- start_alerts = [
- msg for msg in streaming_alerts if msg.log_status == "start"
- ]
- assert len(start_alerts) == 1
- assert "numpy" in start_alerts[0].logs
- assert "Installing numpy" in start_alerts[0].logs["numpy"]
-
- # Verify done log
- done_alerts = [
- msg for msg in streaming_alerts if msg.log_status == "done"
- ]
- assert len(done_alerts) == 1
- assert "numpy" in done_alerts[0].logs
- assert "Successfully installed numpy" in done_alerts[0].logs["numpy"]
-
- # Verify package manager was called with log callback
- mock_package_manager.install.assert_called_once()
- call_args = mock_package_manager.install.call_args
- assert call_args.kwargs.get("log_callback") is not None
-
-
-async def test_install_missing_packages_streaming_logs_failure(
- mocked_kernel: MockedKernel,
-) -> None:
- """Test streaming logs when package installation fails."""
- k = mocked_kernel.k
- broadcast_messages: list[InstallingPackageAlertNotification] = []
-
- def mock_broadcast(msg, stream=None):
- del stream
- if isinstance(msg, InstallingPackageAlertNotification):
- broadcast_messages.append(msg)
-
- # Mock package manager
- mock_package_manager = Mock(spec=PipPackageManager, restart_required=False)
- mock_package_manager.name = "pip"
- mock_package_manager.is_manager_installed.return_value = True
- mock_package_manager.attempted_to_install.return_value = False
- mock_package_manager.package_to_module.return_value = "test_module"
-
- # Mock failed installation with log callback
- async def mock_install_fail(pkg: str, version=None, log_callback=None):
- del pkg, version
- if log_callback:
- log_callback("Starting installation...\n")
- log_callback("Error: Package not found\n")
- return False # Installation failed
-
- mock_package_manager.install = AsyncMock(side_effect=mock_install_fail)
- mock_package_manager.stream_install = partial(
- PackageManager.stream_install, mock_package_manager
- )
- k.packages_callbacks.package_manager = mock_package_manager
-
- with (
- patch(
- "marimo._runtime.callbacks.packages.broadcast_notification",
- mock_broadcast,
- ),
- ):
- request = InstallPackagesCommand(
- manager="pip", versions={"nonexistent-package": ""}
- )
-
- await k.packages_callbacks.install_missing_packages(request)
-
- # Verify failure logs were sent
- streaming_alerts = [
- msg for msg in broadcast_messages if msg.logs is not None
- ]
- assert len(streaming_alerts) >= 2
-
- # Verify done log with failure message
- done_alerts = [
- msg for msg in streaming_alerts if msg.log_status == "done"
- ]
- assert len(done_alerts) == 1
- assert "nonexistent-package" in done_alerts[0].logs
- assert (
- "Failed to install" in done_alerts[0].logs["nonexistent-package"]
- )
-
-
-async def test_install_missing_packages_streaming_logs_multiple_packages(
- mocked_kernel: MockedKernel,
-) -> None:
- """Test streaming logs for multiple packages."""
- k = mocked_kernel.k
- broadcast_messages: list[InstallingPackageAlertNotification] = []
-
- def mock_broadcast(msg, stream=None):
- del stream
- if isinstance(msg, InstallingPackageAlertNotification):
- broadcast_messages.append(msg)
-
- # Mock package manager
- mock_package_manager = Mock(spec=PipPackageManager, restart_required=False)
- mock_package_manager.name = "pip"
- mock_package_manager.is_manager_installed.return_value = True
- mock_package_manager.attempted_to_install.return_value = False
- mock_package_manager.package_to_module.side_effect = lambda pkg: (
- pkg.replace("-", "_")
- )
-
- # Track which packages are being installed
- installation_calls = []
-
- async def mock_install(pkg: str, version=None, log_callback=None):
- del version
- installation_calls.append(pkg)
- if log_callback:
- log_callback(f"Installing {pkg}...\n")
- log_callback(f"Successfully installed {pkg}!\n")
- return True
-
- mock_package_manager.install = AsyncMock(side_effect=mock_install)
- mock_package_manager.stream_install = partial(
- PackageManager.stream_install, mock_package_manager
- )
- k.packages_callbacks.package_manager = mock_package_manager
-
- with (
- patch(
- "marimo._runtime.callbacks.packages.broadcast_notification",
- mock_broadcast,
- ),
- ):
- request = InstallPackagesCommand(
- manager="pip", versions={"numpy": "", "pandas": "", "scipy": ""}
- )
-
- await k.packages_callbacks.install_missing_packages(request)
-
- # Verify all packages were processed
- assert len(installation_calls) == 3
- assert set(installation_calls) == {"numpy", "pandas", "scipy"}
-
- # Verify streaming logs for each package
- streaming_alerts = [
- msg for msg in broadcast_messages if msg.logs is not None
- ]
-
- # Should have start and done logs for each package
- start_alerts = [
- msg for msg in streaming_alerts if msg.log_status == "start"
- ]
- done_alerts = [
- msg for msg in streaming_alerts if msg.log_status == "done"
- ]
-
- assert len(start_alerts) == 3
- assert len(done_alerts) == 3
-
- # Verify each package has its own logs
- packages_in_start_logs = set()
- for alert in start_alerts:
- packages_in_start_logs.update(alert.logs.keys())
-
- packages_in_done_logs = set()
- for alert in done_alerts:
- packages_in_done_logs.update(alert.logs.keys())
-
- assert packages_in_start_logs == {"numpy", "pandas", "scipy"}
- assert packages_in_done_logs == {"numpy", "pandas", "scipy"}
-
-
-async def test_install_missing_packages_no_logs_backward_compatibility(
- mocked_kernel: MockedKernel,
-) -> None:
- """Test that package installation still works without streaming logs (backward compatibility)."""
- k = mocked_kernel.k
- broadcast_messages: list[InstallingPackageAlertNotification] = []
-
- def mock_broadcast(msg, stream=None):
- del stream
- if isinstance(msg, InstallingPackageAlertNotification):
- broadcast_messages.append(msg)
-
- # Mock package manager that doesn't use log callbacks
- mock_package_manager = Mock(spec=PipPackageManager, restart_required=False)
- mock_package_manager.name = "pip"
- mock_package_manager.is_manager_installed.return_value = True
- mock_package_manager.attempted_to_install.return_value = False
- mock_package_manager.package_to_module.return_value = "test_module"
-
- # Mock installation without using log callback parameter
- async def mock_install_old_style(pkg: str, version=None, **kwargs: Any):
- del version, kwargs, pkg
- # Ignore log_callback if provided (simulating old package managers)
- return True
-
- mock_package_manager.install = AsyncMock(
- side_effect=mock_install_old_style
- )
- mock_package_manager.stream_install = partial(
- PackageManager.stream_install, mock_package_manager
- )
- k.packages_callbacks.package_manager = mock_package_manager
-
- with (
- patch(
- "marimo._runtime.callbacks.packages.broadcast_notification",
- mock_broadcast,
- ),
- ):
- request = InstallPackagesCommand(
- manager="pip", versions={"requests": ""}
- )
-
- await k.packages_callbacks.install_missing_packages(request)
-
- # Should still work and send basic status updates
- status_alerts = [msg for msg in broadcast_messages if msg.logs is None]
- assert len(status_alerts) >= 2 # At least installing and installed
-
- # Verify normal package status progression
- package_statuses = []
- for alert in status_alerts:
- if "requests" in alert.packages:
- package_statuses.append(alert.packages["requests"])
-
- # Should have at least installing and installed statuses
- assert "installed" in package_statuses
# Note: The exact sequence might vary, but we should have final success
[email protected]("succeed", [False, True])
async def test_install_logs_reach_the_stream_from_worker_threads(
mocked_kernel: MockedKernel,
+ succeed: bool,
) -> None:
"""Per-line install logs bind the kernel's stream when the callback
is created: the callback fires from worker threads, which do not
@@ -801,7 +520,9 @@ async def test_install_logs_reach_the_stream_from_worker_threads(
fake = Mock(restart_required=False)
fake.name = current.name
fake.is_manager_installed.return_value = True
- fake.attempted_to_install.return_value = False
+ fake.attempted_to_install.side_effect = lambda package: (
+ package == "skipped"
+ )
fake.module_to_package.side_effect = lambda module: module
fake.package_to_module.side_effect = lambda package: package
@@ -811,21 +532,65 @@ async def test_install_logs_reach_the_stream_from_worker_threads(
log_callback: Any = None,
**kwargs: Any,
) -> bool:
- del package, version, kwargs
+ del version, kwargs
worker = threading.Thread(
- target=log_callback, args=("streamed-from-a-bare-thread\n",)
+ target=log_callback, args=(f"Worker output for {package}\n",)
)
worker.start()
worker.join()
- return True
+ return succeed or package == "available"
fake.install = install
fake.stream_install = partial(PackageManager.stream_install, fake)
k.packages_callbacks.package_manager = fake
await k.packages_callbacks.install_missing_packages(
- InstallPackagesCommand(manager=fake.name, versions={"foobar": ""})
+ InstallPackagesCommand(
+ manager=fake.name,
+ versions={"available": "", "broken": "", "skipped": ""},
+ source="server",
+ )
)
- joined = "".join(str(message) for message in mocked_kernel.stream.messages)
- assert "streamed-from-a-bare-thread" in joined
+ updates = [
+ message
+ for message in mocked_kernel.stream.operations
+ if isinstance(message, EnvironmentOperationNotification)
+ ]
+ outcome = updates[-1]
+ assert isinstance(
+ outcome.status, OperationSucceeded if succeed else OperationFailed
+ )
+ assert outcome.packages == {
+ "available": "succeeded",
+ "broken": "succeeded" if succeed else "failed",
+ }
+ assert {
+ (update.operation_id, update.action, update.source)
+ for update in updates
+ } == {(outcome.operation_id, "install", "server")}
+ assert all("skipped" not in update.packages for update in updates)
+ final_messages = {
+ "available": "Successfully installed available\n",
+ "broken": (
+ "Successfully installed broken\n"
+ if succeed
+ else "Failed to install broken\n"
+ ),
+ }
+ for package, final_message in final_messages.items():
+ logged = [update for update in updates if package in update.logs]
+ # Each package starts its own stream, appends worker output, and
+ # ends with the outcome line.
+ assert (logged[0].logs, logged[0].log_mode) == (
+ {package: f"Installing {package}...\n"},
+ "replace",
+ )
+ assert any(
+ update.logs.get(package) == f"Worker output for {package}\n"
+ for update in logged
+ )
+ assert (logged[-1].logs, logged[-1].log_mode) == (
+ {package: final_message},
+ "append",
+ )
diff --git a/tests/_server/api/endpoints/test_kiosk.py b/tests/_server/api/endpoints/test_kiosk.py
index 4469b90ca9..4c978ba9ab 100644
--- a/tests/_server/api/endpoints/test_kiosk.py
+++ b/tests/_server/api/endpoints/test_kiosk.py
@@ -47,6 +47,11 @@ async def test_connect_kiosk_with_session(client: TestClient) -> None:
),
)
+ for _ in range(2):
+ assert (
+ other_websocket.receive_json()["op"] == "environment-state"
+ )
+
# Send document transaction to reorder cells
response = client.post(
"/api/document/transaction",
diff --git a/tests/_server/api/endpoints/test_packages.py b/tests/_server/api/endpoints/test_packages.py
index 23d0ba50be..d2853a97d0 100644
--- a/tests/_server/api/endpoints/test_packages.py
+++ b/tests/_server/api/endpoints/test_packages.py
@@ -1,16 +1,27 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import asyncio
+import threading
from typing import TYPE_CHECKING, Any
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import ANY, AsyncMock, MagicMock, patch
import msgspec
import pytest
+from marimo._environments.errors import (
+ EnvironmentManagerError,
+ SandboxRestartRequired,
+)
+from marimo._environments.sandbox import NotebookSandbox
+from marimo._messaging.notification import EnvironmentOperationNotification
from marimo._runtime.packages.package_manager import PackageManager
+from marimo._server.api.deps import AppState
+from marimo._session.state.session_view import SessionView
from tests._server.mocks import token_header
if TYPE_CHECKING:
+ from collections.abc import Callable
from unittest.mock import Mock
from starlette.testclient import TestClient
@@ -106,7 +117,11 @@ def test_add_package(client: TestClient, mock_package_manager: Mock) -> None:
"restartRequired": False,
}
mock_package_manager.install.assert_called_once_with(
- "test-package", version=None, upgrade=False, group=None
+ "test-package",
+ log_callback=ANY,
+ version=None,
+ upgrade=False,
+ group=None,
)
@@ -233,7 +248,11 @@ def test_add_package_with_upgrade(
"restartRequired": False,
}
mock_package_manager.install.assert_called_once_with(
- "test-package", version=None, upgrade=True, group=None
+ "test-package",
+ log_callback=ANY,
+ version=None,
+ upgrade=True,
+ group=None,
)
@@ -253,7 +272,11 @@ def test_add_package_without_upgrade(
"restartRequired": False,
}
mock_package_manager.install.assert_called_once_with(
- "test-package", version=None, upgrade=False, group=None
+ "test-package",
+ log_callback=ANY,
+ version=None,
+ upgrade=False,
+ group=None,
)
@@ -650,7 +673,7 @@ def test_add_package_with_spaced_extras_updates_metadata(
"restartRequired": False,
}
mock_package_manager_with_metadata.install.assert_awaited_once_with(
- package, version=None, upgrade=True, group=None
+ package, log_callback=ANY, version=None, upgrade=True, group=None
)
mock_package_manager_with_metadata.update_notebook_script_metadata.assert_called_once_with(
filepath="test.py",
@@ -822,7 +845,11 @@ def test_add_package_with_dev_dependency(
"restartRequired": False,
}
mock_package_manager.install.assert_called_once_with(
- "test-package", version=None, upgrade=True, group="dev"
+ "test-package",
+ log_callback=ANY,
+ version=None,
+ upgrade=True,
+ group="dev",
)
@@ -1062,3 +1089,139 @@ def test_manifest_file_errors_are_reported(
)
assert response.status_code == 400
assert "Permission denied for notebook manifest" in response.text
+
+
+def operation_session(
+ monkeypatch: pytest.MonkeyPatch,
+) -> tuple[Mock, SessionView]:
+
+ view = SessionView()
+ session = MagicMock()
+ session.app_file_manager.filename = None
+ session.notify.side_effect = lambda notification, _: view.add_notification(
+ notification
+ )
+ monkeypatch.setattr(AppState, "get_current_session", lambda _: session)
+ return session, view
+
+
+ ("endpoint", "action"), [("add", "install"), ("remove", "remove")]
+)
+ "outcome", ["succeeded", "failed", "restart-required"]
+)
+def test_package_changes_retain_outcome_and_worker_logs(
+ client: TestClient,
+ mock_package_manager: Mock,
+ operation_session: tuple[Mock, SessionView],
+ endpoint: str,
+ action: str,
+ outcome: str,
+) -> None:
+ session, view = operation_session
+ mock_package_manager.restart_required = outcome == "restart-required"
+
+ async def change(*_args: Any, **kwargs: Any) -> bool:
+ owner_thread = threading.get_ident()
+
+ def notify(
+ notification: EnvironmentOperationNotification, _: object
+ ) -> None:
+ assert threading.get_ident() == owner_thread
+ view.add_notification(notification)
+
+ session.notify.side_effect = notify
+ if callback := kwargs.get("log_callback"):
+ await asyncio.to_thread(callback, "Resolving\n")
+ await asyncio.to_thread(callback, "Applying\n")
+ return outcome == "succeeded"
+
+ getattr(
+ mock_package_manager, "install" if endpoint == "add" else "uninstall"
+ ).side_effect = change
+ response = client.post(
+ f"/api/packages/{endpoint}", headers=HEADERS, json={"package": "numpy"}
+ )
+ assert response.status_code == 200
+ status = {"kind": outcome}
+ if outcome == "failed":
+ status["error"] = (
+ "Could not apply changes to numpy. See operation logs for details."
+ )
+ elif outcome == "restart-required":
+ status["reason"] = (
+ "Dependency changes are saved; restart the kernel to apply them."
+ )
+ assert msgspec.to_builtins(view.get_environment_state("kernel")) == {
+ "restart_required": outcome == "restart-required",
+ "operations": [
+ {
+ "operation_id": ANY,
+ "action": action,
+ "status": status,
+ "source": "kernel",
+ "packages": {"numpy": outcome},
+ "logs": {"numpy": "Resolving\nApplying\n"}
+ if endpoint == "add"
+ else {},
+ }
+ ],
+ }
+
+
+ "outcome", ["succeeded", "failed", "restart-required"]
+)
+def test_sync_retains_outcome_and_logs_without_a_package_list(
+ client: TestClient,
+ monkeypatch: pytest.MonkeyPatch,
+ operation_session: tuple[Mock, SessionView],
+ outcome: str,
+) -> None:
+ _, view = operation_session
+ sandbox = MagicMock(spec=NotebookSandbox)
+
+ async def sync(*, on_output: Callable[[str], None]) -> None:
+ on_output("Syncing saved dependencies\n")
+ if outcome == "failed":
+ raise EnvironmentManagerError("Resolution failed")
+ if outcome == "restart-required":
+ raise SandboxRestartRequired("Python changed")
+
+ sandbox.sync_async.side_effect = sync
+ monkeypatch.setattr(
+ "marimo._server.api.endpoints.packages._sandbox_source",
+ lambda *_args, **_kwargs: (sandbox, "notebook.py", "uv"),
+ )
+ response = client.post("/api/packages/sync", headers=HEADERS, json={})
+ assert response.status_code == 200
+ assert response.json() == {
+ "success": outcome == "succeeded",
+ "error": {
+ "succeeded": None,
+ "failed": "Resolution failed",
+ "restart-required": "Python changed",
+ }[outcome],
+ "restartRequired": outcome == "restart-required",
+ "reconnect": False,
+ }
+ status = {"kind": outcome}
+ if outcome == "failed":
+ status["error"] = "Resolution failed"
+ elif outcome == "restart-required":
+ status["reason"] = "Python changed"
+ assert msgspec.to_builtins(view.get_environment_state("kernel")) == {
+ "restart_required": outcome == "restart-required",
+ "operations": [
+ {
+ "operation_id": ANY,
+ "action": "sync",
+ "status": status,
+ "source": "kernel",
+ "packages": {},
+ "logs": {"environment": "Syncing saved dependencies\n"},
+ }
+ ],
+ }
diff --git a/tests/_server/api/endpoints/test_resume_session.py b/tests/_server/api/endpoints/test_resume_session.py
index 0a9e1e16d7..7ed0367a44 100644
--- a/tests/_server/api/endpoints/test_resume_session.py
+++ b/tests/_server/api/endpoints/test_resume_session.py
@@ -1,16 +1,29 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import json
import os
import time
from contextlib import contextmanager
from typing import TYPE_CHECKING
+import pytest
+
from marimo._config.manager import UserConfigManager
from marimo._messaging.notification import (
CellNotification,
+ EnvironmentOperation,
+ EnvironmentOperationNotification,
+ EnvironmentOperationStatus,
+ EnvironmentState,
+ EnvironmentStateNotification,
KernelReadyNotification,
+ OperationFailed,
+ OperationRunning,
+ OperationSucceeded,
)
+from marimo._messaging.serde import serialize_kernel_message
+from marimo._server.api.endpoints.ws.ws_formatter import format_wire_message
from marimo._server.workspace import DirectoryWorkspace
from marimo._session import Session
from marimo._types.ids import SessionId
@@ -303,6 +316,8 @@ def test_resume_session_after_file_change(client: TestClient) -> None:
with client.websocket_connect(_create_ws_url("123")) as websocket:
data = websocket.receive_json()
assert_kernel_ready_response(data, create_response({}))
+ for _ in range(2):
+ assert websocket.receive_json()["op"] == "environment-state"
session = get_session(client, SessionId("123"))
assert session
@@ -361,3 +376,104 @@ def without_autorun_on_save(config: UserConfigManager):
yield
finally:
config.save_config(prev_config)
+
+
[email protected]("connection_id", ["123", "456"])
+ "outcome",
+ [
+ OperationRunning(),
+ OperationSucceeded(),
+ OperationFailed(error="Offline"),
+ ],
+)
+def test_environment_restored_after_disconnect(
+ client: TestClient,
+ connection_id: str,
+ outcome: EnvironmentOperationStatus,
+) -> None:
+ with client:
+ with client.websocket_connect(_create_ws_url("123")) as websocket:
+ assert_kernel_ready_response(websocket.receive_json())
+ for source in ("kernel", "server"):
+ assert websocket.receive_json() == {
+ "op": "environment-state",
+ "data": {
+ "op": "environment-state",
+ "source": source,
+ "state": {"restart_required": False, "operations": []},
+ },
+ }
+ session = get_session(client, SessionId("123"))
+ assert session is not None
+ progress = EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"numpy": "running"},
+ logs={"numpy": "Downloading\n"},
+ log_mode="replace",
+ )
+ websocket.portal.call(
+ lambda: session.notify(progress, from_consumer_id=None)
+ )
+
+ # Work can finish while no consumer is attached.
+ assert client.portal is not None
+ client.portal.call(
+ session.notify,
+ EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ operation_id="install",
+ status=outcome,
+ packages={
+ "numpy": "succeeded"
+ if isinstance(outcome, OperationSucceeded)
+ else "running"
+ },
+ logs={"numpy": "Latest\n"},
+ log_mode="append",
+ ),
+ None,
+ )
+ expected = EnvironmentStateNotification(
+ source="kernel",
+ state=EnvironmentState(
+ restart_required=False,
+ operations=[
+ EnvironmentOperation(
+ action="install",
+ operation_id="install",
+ source="kernel",
+ status=outcome,
+ packages={
+ "numpy": "succeeded"
+ if isinstance(outcome, OperationSucceeded)
+ else "running"
+ },
+ logs={"numpy": "Downloading\nLatest\n"},
+ )
+ ],
+ ),
+ )
+ with client.websocket_connect(
+ _create_ws_url(connection_id)
+ ) as websocket:
+ assert websocket.receive_json()["op"] == "reconnected"
+ if connection_id != "123":
+ assert websocket.receive_json()["op"] == "kernel-ready"
+ assert websocket.receive_json()["op"] == "banner"
+ else:
+ assert websocket.receive_json()["op"] == "alert"
+ assert websocket.receive_json() == json.loads(
+ format_wire_message(
+ expected.name, serialize_kernel_message(expected)
+ )
+ )
+ assert websocket.receive_json()["data"] == {
+ "op": "environment-state",
+ "source": "server",
+ "state": {"restart_required": False, "operations": []},
+ }
diff --git a/tests/_server/api/endpoints/test_sse.py b/tests/_server/api/endpoints/test_sse.py
index 4441a7663a..5f5cfc2015 100644
--- a/tests/_server/api/endpoints/test_sse.py
+++ b/tests/_server/api/endpoints/test_sse.py
@@ -329,6 +329,8 @@ async def test_sandbox_progress_during_preparation(
monkeypatch.setattr(ipc, "has_marimo_installed", check_environment)
manager = get_session_manager(client)
manager.sandbox = True
+ if outcome == "disconnect":
+ manager.ttl_seconds = 0
async with _connect(client) as connection:
event = await connection.next_event()
@@ -337,20 +339,34 @@ async def test_sandbox_progress_during_preparation(
"data": {
"op": "startup-progress",
"phase": "preparing-environment",
+ "logs": "",
+ "log_mode": "replace",
},
}
+ running = json.loads((await connection.next_event())["data"])
+ assert running["op"] == "environment-operation"
+ assert running["data"]["action"] == "prepare"
+ assert running["data"]["status"] == {"kind": "running"}
assert not manager.sessions
if outcome == "disconnect":
connection.disconnect()
await asyncio.wait_for(cleaned_up.wait(), timeout=5)
else:
release.set()
+ completed = json.loads((await connection.next_event())["data"])
+ assert (
+ completed["data"]["operation_id"]
+ == running["data"]["operation_id"]
+ )
+ assert completed["data"]["status"] == {"kind": "succeeded"}
event = await connection.next_event()
assert json.loads(event["data"]) == {
"op": "startup-progress",
"data": {
"op": "startup-progress",
"phase": "starting-kernel",
+ "logs": "",
+ "log_mode": "replace",
},
}
event = await connection.next_event()
@@ -513,7 +529,9 @@ async def test_disconnect_during_startup_progress_detaches_session() -> None:
session = handler.manager.get_session.return_value
handler.notify(
serialize_kernel_message(
- StartupProgressNotification(phase="starting-kernel")
+ StartupProgressNotification(
+ phase="starting-kernel", logs="", log_mode="replace"
+ )
)
)
diff --git a/tests/_server/api/endpoints/test_ws.py b/tests/_server/api/endpoints/test_ws.py
index 567af19a5d..e09145b9a8 100644
--- a/tests/_server/api/endpoints/test_ws.py
+++ b/tests/_server/api/endpoints/test_ws.py
@@ -13,7 +13,9 @@ from starlette.websockets import WebSocketDisconnect, WebSocketState
from marimo._config.config import ExperimentalConfig
from marimo._config.manager import UserConfigManager
from marimo._messaging.notification import (
+ EnvironmentOperationNotification,
KernelReadyNotification,
+ OperationSucceeded,
StartupProgressNotification,
)
from marimo._messaging.serde import serialize_kernel_message
@@ -33,6 +35,7 @@ from tests._server.api.endpoints.ws_helpers import (
assert_parse_ready_response,
create_response,
headers,
+ receive_until,
)
from tests._server.conftest import get_kernel_tasks, get_user_config_manager
from tests._server.mocks import get_session_manager
@@ -125,12 +128,16 @@ async def test_failed_startup_progress_delivery_detaches_session(
async def connect(_connection: Any) -> tuple[Any, ConnectionType]:
handler.on_attach(session, MagicMock())
- handler.status = ConnectionState.OPEN
+ # Progress reaches the startup queue only while the handler is still
+ # connecting; once open, it travels with session messages instead.
handler.notify(
serialize_kernel_message(
- StartupProgressNotification(phase="starting-kernel")
+ StartupProgressNotification(
+ phase="starting-kernel", logs="", log_mode="replace"
+ )
)
)
+ handler.status = ConnectionState.OPEN
return session, ConnectionType.NEW
with patch.object(handler, "_connect_session", side_effect=connect):
@@ -187,6 +194,59 @@ def test_disconnect_then_reconnect_then_refresh(client: TestClient) -> None:
assert manager.sessions[SessionId("456")].stable_id == stable_id
+def test_completed_startup_is_restored_on_reconnect_and_refresh(
+ client: TestClient,
+) -> None:
+ manager = get_session_manager(client)
+ progress = StartupProgressNotification(
+ phase="starting-kernel",
+ logs="Kernel startup output\n",
+ log_mode="append",
+ )
+ with client.websocket_connect(WS_URL) as websocket:
+ assert_kernel_ready_response(websocket.receive_json())
+ view = manager.sessions[SessionId("123")].session_view
+ view.add_notification(
+ EnvironmentOperationNotification(
+ operation_id="prepare",
+ action="prepare",
+ source="kernel",
+ status=OperationSucceeded(),
+ packages={},
+ logs={"environment": "Prepared environment\n"},
+ log_mode="replace",
+ )
+ )
+ view.add_notification(progress)
+ websocket.close()
+
+ for url in (WS_URL, OTHER_WS_URL):
+ with client.websocket_connect(url) as websocket:
+ assert websocket.receive_json()["op"] == "reconnected"
+ message = websocket.receive_json()
+ if url == OTHER_WS_URL:
+ assert_kernel_ready_response(
+ message, create_response({"resumed": True})
+ )
+ else:
+ assert message["op"] == "alert"
+ environment = receive_until("environment-state", websocket)["data"]
+ assert environment["source"] == "kernel"
+ assert environment["state"]["operations"][0]["logs"] == {
+ "environment": "Prepared environment\n"
+ }
+ restored = receive_until("startup-progress", websocket)
+ assert restored == {
+ "op": "startup-progress",
+ "data": {
+ "op": "startup-progress",
+ "phase": "starting-kernel",
+ "logs": "Kernel startup output\n",
+ "log_mode": "replace",
+ },
+ }
+
+
def test_allows_multiple_connections_with_other_sessions(
client: TestClient,
) -> None:
@@ -253,7 +313,7 @@ def test_second_connection_with_same_file_joins_as_viewer(
assert viewer.consumer_capabilities.edit is False
-async def test_file_watcher_calls_reload(client: TestClient) -> None:
+def test_file_watcher_calls_reload(client: TestClient) -> None:
session_manager: SessionManager = get_session_manager(client)
session_manager.mode = SessionMode.RUN
# Recreate the file change coordinator with the new mode's strategy
@@ -266,23 +326,18 @@ async def test_file_watcher_calls_reload(client: TestClient) -> None:
assert_kernel_ready_response(data)
filename = session_manager.workspace.get_unique_file_key()
assert filename
- with open(filename, "a") as f: # noqa: ASYNC230
+ with open(filename, "a") as f:
f.write("\n# test")
f.close()
assert session_manager._watcher_manager._watchers
watcher = next(
iter(session_manager._watcher_manager._watchers.values())
)
- await watcher.callback(Path(filename))
- # Drain messages until we get the reload message
- # (other messages like 'variables' may arrive first)
- expected = {"op": "reload", "data": {"op": "reload"}}
- for _ in range(10):
- data = websocket.receive_json()
- if data == expected:
- break
- else:
- raise AssertionError(f"Expected {expected}, but never received it")
+ websocket.portal.call(watcher.callback, Path(filename))
+ assert receive_until("reload", websocket) == {
+ "op": "reload",
+ "data": {"op": "reload"},
+ }
session_manager.watch = False
@@ -395,6 +450,8 @@ async def test_connects_to_existing_session_with_same_file(
with client.websocket_connect(ws_1) as websocket1:
data = websocket1.receive_json()
assert_parse_ready_response(data)
+ for _ in range(2):
+ assert websocket1.receive_json()["op"] == "environment-state"
# Instantiate the session
client.post(
@@ -418,6 +475,11 @@ async def test_connects_to_existing_session_with_same_file(
# which the room membership is observable.
data2 = websocket2.receive_json()
assert_parse_ready_response(data2)
+ for _ in range(2):
+ assert (
+ websocket2.receive_json()["op"] == "environment-state"
+ )
+
assert data2["data"]["resumed"] is True
# Check in the same room
@@ -854,7 +916,7 @@ async def test_websocket_message_queue_delivery(client: TestClient) -> None:
assert len(messages) >= 1
-def test_disconnect_cancels_pending_startup(
+def test_disconnect_expires_pending_startup(
client: TestClient, monkeypatch: pytest.MonkeyPatch
) -> None:
import asyncio
@@ -862,6 +924,8 @@ def test_disconnect_cancels_pending_startup(
from marimo._session.session import SessionImpl
+ get_session_manager(client).ttl_seconds = 0
+
started = threading.Event()
cleaned_up = threading.Event()
@@ -906,13 +970,109 @@ def test_sandbox_progress_before_preparation_failure(
"data": {
"op": "startup-progress",
"phase": "preparing-environment",
+ "logs": "",
+ "log_mode": "replace",
},
}
+ running = websocket.receive_json()
+ assert running["op"] == "environment-operation"
+ assert running["data"]["action"] == "prepare"
+ assert running["data"]["status"] == {"kind": "running"}
assert not get_session_manager(client).sessions
websocket.portal.call(release.set)
+ failed = websocket.receive_json()
+ assert failed["op"] == "environment-operation"
+ assert (
+ failed["data"]["operation_id"] == running["data"]["operation_id"]
+ )
+ assert failed["data"]["status"]["kind"] == "failed"
error = websocket.receive_json()
assert error["op"] == "kernel-startup-error"
assert "Could not resolve dependencies" in error["data"]["error"]
with pytest.raises(WebSocketDisconnect) as closed:
websocket.receive_json()
assert closed.value.reason == "MARIMO_KERNEL_STARTUP_ERROR"
+
+
[email protected]("replacement_url", [WS_URL, OTHER_WS_URL])
+def test_refresh_observes_existing_sandbox_preparation(
+ client: TestClient,
+ monkeypatch: pytest.MonkeyPatch,
+ replacement_url: str,
+) -> None:
+ from marimo._environments.errors import EnvironmentManagerError
+ from marimo._environments.sandbox import NotebookSandbox
+
+ release = asyncio.Event()
+ launches = 0
+
+ async def prepare(*_args: object, **kwargs: Any) -> None:
+ nonlocal launches
+ launches += 1
+ kwargs["on_output"]("Resolving dependencies\n")
+ await asyncio.wait_for(release.wait(), timeout=5)
+ raise EnvironmentManagerError("Could not resolve dependencies")
+
+ monkeypatch.setattr(NotebookSandbox, "launch_async", prepare)
+ manager = get_session_manager(client)
+ manager.sandbox = True
+ expected = {
+ "op": "startup-progress",
+ "data": {
+ "op": "startup-progress",
+ "phase": "preparing-environment",
+ "logs": "",
+ "log_mode": "replace",
+ },
+ }
+ # Keep one server loop alive across both browser connections.
+ with client:
+ with client.websocket_connect(WS_URL) as first:
+ assert first.receive_json() == expected
+ running = first.receive_json()
+ output = first.receive_json()
+ assert output["data"]["logs"] == {
+ "environment": "Resolving dependencies\n"
+ }
+ first.close()
+ with client.websocket_connect(replacement_url) as refreshed:
+ assert refreshed.receive_json() == expected
+ snapshot = refreshed.receive_json()
+ assert snapshot == {
+ "op": "environment-state",
+ "data": {
+ "op": "environment-state",
+ "source": "kernel",
+ "state": {
+ "restart_required": False,
+ "operations": [
+ {
+ "operation_id": running["data"][
+ "operation_id"
+ ],
+ "action": "prepare",
+ "status": {"kind": "running"},
+ "source": "kernel",
+ "packages": {},
+ "logs": {
+ "environment": "Resolving dependencies\n"
+ },
+ }
+ ],
+ },
+ },
+ }
+ assert refreshed.receive_json()["data"]["source"] == "server"
+ assert launches == 1
+ assert not manager.sessions
+ refreshed.portal.call(release.set)
+ failed = refreshed.receive_json()
+ assert failed["data"]["status"]["kind"] == "failed"
+ error = refreshed.receive_json()
+ assert error["op"] == "kernel-startup-error"
+ assert (
+ "Could not resolve dependencies" in error["data"]["error"]
+ )
+ with pytest.raises(WebSocketDisconnect) as closed:
+ refreshed.receive_json()
+ assert closed.value.reason == "MARIMO_KERNEL_STARTUP_ERROR"
diff --git a/tests/_server/test_session_manager.py b/tests/_server/test_session_manager.py
index f0ad254e9c..439eec43a3 100644
--- a/tests/_server/test_session_manager.py
+++ b/tests/_server/test_session_manager.py
@@ -21,6 +21,7 @@ from marimo._session import (
from marimo._session.consumer import SessionConsumer
from marimo._session.model import ConnectionState, SessionMode
from marimo._session.notebook import AppFileManager
+from marimo._session.room import Room
from marimo._types.ids import SessionId
if TYPE_CHECKING:
@@ -56,6 +57,8 @@ def mock_session():
session = Mock(spec=Session)
session.initialization_id = "test_init_id"
session.session_cache_manager = None
+ session.room = Room()
+ session.connect_consumer.side_effect = session.room.add_consumer
session.connection_state.return_value = ConnectionState.OPEN
session.kernel_manager = Mock(spec=KernelManager)
session.kernel_manager.kernel_task = None
@@ -596,6 +599,7 @@ async def test_connections_share_starting_notebook(
release = asyncio.Event()
mock_session.initialization_id = NEW_FILE
mock_session.room = MagicMock()
+ mock_session.room.main_consumer = None
mock_session.room.get_consumer.return_value = None
mock_session.app_file_manager = AppFileManager(filename=None)
launches = 0
@@ -642,3 +646,398 @@ async def test_connections_share_starting_notebook(
finally:
release.set()
await session_manager.shutdown()
+
+
[email protected]("replacement_id", ["first", "refreshed"])
[email protected]("finish_disconnected", [False, True])
+async def test_refresh_reuses_pending_startup(
+ session_manager: SessionManager,
+ mock_session: Session,
+ monkeypatch: pytest.MonkeyPatch,
+ replacement_id: str,
+ finish_disconnected: bool,
+) -> None:
+ from starlette.requests import HTTPConnection
+
+ from marimo._messaging.notification import (
+ EnvironmentState,
+ EnvironmentStateNotification,
+ StartupProgressNotification,
+ )
+ from marimo._messaging.serde import deserialize_kernel_message
+ from marimo._server.api.endpoints.ws.ws_connection_validator import (
+ ConnectionParams,
+ )
+ from marimo._server.api.endpoints.ws.ws_session_connector import (
+ ConnectionType,
+ SessionConnector,
+ )
+ from marimo._session.session import SessionImpl
+ from marimo._session.startup import SessionStartup
+
+ entered, release, finished, restored = (asyncio.Event() for _ in range(4))
+ progress = StartupProgressNotification(
+ phase="preparing-environment", logs="", log_mode="replace"
+ )
+ starting = StartupProgressNotification(
+ phase="starting-kernel", logs="Launching kernel\n", log_mode="replace"
+ )
+ launches = 0
+ mock_session.initialization_id = NEW_FILE
+ mock_session.app_file_manager = AppFileManager(filename=None)
+
+ async def create(*, startup: SessionStartup, **_kwargs: object) -> Session:
+ nonlocal launches
+ launches += 1
+ mock_session.session_view = startup.view
+ startup.notify(progress)
+ entered.set()
+ await release.wait()
+ startup.notify(starting)
+ startup.notify(
+ StartupProgressNotification(
+ phase="starting-kernel",
+ logs="Loading runtime\n",
+ log_mode="append",
+ )
+ )
+ finished.set()
+ return mock_session
+
+ monkeypatch.setattr(SessionImpl, "create", create)
+
+ def connector(sid: str) -> SessionConnector:
+ handler = MagicMock(consumer_id=sid)
+ return SessionConnector(
+ manager=session_manager,
+ handler=handler,
+ params=ConnectionParams(
+ session_id=SessionId(sid),
+ file_key=NEW_FILE,
+ kiosk=False,
+ auto_instantiate=False,
+ rtc_enabled=False,
+ ),
+ connection=HTTPConnection({"type": "http", "query_string": b""}),
+ )
+
+ first = connector("first")
+ first_connection = asyncio.create_task(first.connect())
+ try:
+ await asyncio.wait_for(entered.wait(), 5)
+ first_connection.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await first_connection
+ assert session_manager.is_session_starting(
+ SessionId(replacement_id), NEW_FILE
+ )
+ if finish_disconnected:
+ release.set()
+ await asyncio.wait_for(finished.wait(), 5)
+
+ refreshed = connector(replacement_id)
+ refreshed.handler.notify.side_effect = lambda _message: restored.set()
+ next_connection = asyncio.create_task(refreshed.connect())
+ await asyncio.wait_for(restored.wait(), 5)
+ assert [
+ deserialize_kernel_message(call.args[0])
+ for call in refreshed.handler.notify.call_args_list
+ ] == [
+ StartupProgressNotification(
+ phase="starting-kernel",
+ logs="Launching kernel\nLoading runtime\n",
+ log_mode="replace",
+ )
+ if finish_disconnected
+ else progress,
+ *[
+ EnvironmentStateNotification(
+ source=source,
+ state=EnvironmentState(
+ restart_required=False, operations=[]
+ ),
+ )
+ for source in ("kernel", "server")
+ ],
+ ]
+ release.set()
+ assert await asyncio.wait_for(next_connection, 5) == (
+ mock_session,
+ ConnectionType.NEW,
+ )
+ assert launches == 1
+ assert (
+ session_manager.get_session(SessionId(replacement_id))
+ is mock_session
+ )
+ assert mock_session.room.main_consumer is refreshed.handler
+ assert (
+ mock_session.session_view.startup_progress
+ == StartupProgressNotification(
+ phase="starting-kernel",
+ logs="Launching kernel\nLoading runtime\n",
+ log_mode="replace",
+ )
+ )
+ assert not session_manager.is_session_starting(
+ SessionId(replacement_id), NEW_FILE
+ )
+ refreshed.handler._write_kernel_ready.assert_called_once()
+ assert (
+ refreshed.handler._write_kernel_ready.call_args.kwargs["resumed"]
+ is False
+ )
+ finally:
+ release.set()
+ await session_manager.shutdown()
+
+
+async def test_abandoned_completed_startup_expires(
+ session_manager: SessionManager,
+ mock_session: Session,
+ mock_session_consumer: SessionConsumer,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._session.session import SessionImpl
+
+ entered, release, closed = (asyncio.Event() for _ in range(3))
+ session_manager.ttl_seconds = 0
+ mock_session.app_file_manager = AppFileManager(filename=None)
+ mock_session.close.side_effect = lambda: closed.set()
+
+ async def create(**_kwargs: object) -> Session:
+ entered.set()
+ await release.wait()
+ return mock_session
+
+ monkeypatch.setattr(SessionImpl, "create", create)
+ connection = asyncio.create_task(
+ session_manager.create_session(
+ session_id,
+ mock_session_consumer,
+ {},
+ NEW_FILE,
+ False,
+ )
+ )
+ try:
+ await asyncio.wait_for(entered.wait(), 5)
+ # Completion is queued before expiry, but the browser never attaches.
+ release.set()
+ connection.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await connection
+ await asyncio.wait_for(closed.wait(), 5)
+ assert not session_manager.sessions
+ assert not session_manager.is_session_starting(session_id, NEW_FILE)
+ finally:
+ await session_manager.shutdown()
+
+
+async def test_startup_retention_ignores_long_session_ttl(
+ session_manager: SessionManager,
+ mock_session: Session,
+ mock_session_consumer: SessionConsumer,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._server.session_manager import _STARTUP_RECONNECT_SECONDS
+ from marimo._session.session import SessionImpl
+
+ entered = asyncio.Event()
+ session_manager.ttl_seconds = 3600
+ mock_session.app_file_manager = AppFileManager(filename=None)
+
+ async def create(**_kwargs: object) -> Session:
+ entered.set()
+ await asyncio.Event().wait()
+ return mock_session
+
+ monkeypatch.setattr(SessionImpl, "create", create)
+ connection = asyncio.create_task(
+ session_manager.create_session(
+ session_id,
+ mock_session_consumer,
+ {},
+ NEW_FILE,
+ False,
+ )
+ )
+ try:
+ await asyncio.wait_for(entered.wait(), 5)
+ connection.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await connection
+ key = session_manager._connection_key(session_id, NEW_FILE)
+ handle = session_manager._pending[key].close_handle
+ assert handle is not None
+ remaining = handle.when() - asyncio.get_running_loop().time()
+ assert 0 < remaining <= _STARTUP_RECONNECT_SECONDS
+ finally:
+ await session_manager.shutdown()
+
+
+async def test_startup_never_hands_out_a_session_owned_by_another_consumer(
+ session_manager: SessionManager,
+ mock_session: Session,
+ mock_session_consumer: SessionConsumer,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._session.session import SessionImpl
+
+ mock_session.app_file_manager = AppFileManager(filename=None)
+ other = Mock(spec=SessionConsumer)
+ other.consumer_id = "other_consumer_id"
+ mock_session.room.add_consumer(other, main=True)
+
+ async def create(**_kwargs: object) -> Session:
+ return mock_session
+
+ monkeypatch.setattr(SessionImpl, "create", create)
+ try:
+ with pytest.raises(RuntimeError, match="main consumer"):
+ await session_manager.create_session(
+ session_id,
+ mock_session_consumer,
+ {},
+ NEW_FILE,
+ False,
+ )
+ assert mock_session.room.main_consumer is other
+ assert not session_manager.is_session_starting(session_id, NEW_FILE)
+ finally:
+ await session_manager.shutdown()
+
+
+async def test_retry_waits_for_expired_startup_cleanup(
+ session_manager: SessionManager,
+ mock_session: Session,
+ mock_session_consumer: SessionConsumer,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._session.session import SessionImpl
+
+ entered, cleaning_up, release_cleanup = (asyncio.Event() for _ in range(3))
+ session_manager.ttl_seconds = 0
+ mock_session.app_file_manager = AppFileManager(filename=None)
+ launches = 0
+
+ async def create(**_kwargs: object) -> Session:
+ nonlocal launches
+ launches += 1
+ if launches == 1:
+ entered.set()
+ try:
+ await asyncio.Event().wait()
+ finally:
+ cleaning_up.set()
+ await release_cleanup.wait()
+ return mock_session
+
+ monkeypatch.setattr(SessionImpl, "create", create)
+ first = asyncio.create_task(
+ session_manager.create_session(
+ session_id,
+ mock_session_consumer,
+ {},
+ NEW_FILE,
+ False,
+ )
+ )
+ try:
+ await asyncio.wait_for(entered.wait(), 5)
+ first.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await first
+ await asyncio.wait_for(cleaning_up.wait(), 5)
+ retry = asyncio.create_task(
+ session_manager.create_session(
+ SessionId("refreshed"),
+ mock_session_consumer,
+ {},
+ NEW_FILE,
+ False,
+ )
+ )
+ await asyncio.sleep(0)
+ assert launches == 1
+ release_cleanup.set()
+ assert await asyncio.wait_for(retry, 5) is mock_session
+ assert launches == 2
+ finally:
+ release_cleanup.set()
+ await session_manager.shutdown()
+
+
[email protected]("close_before_attachment", [False, True])
+async def test_closed_startup_cannot_be_attached(
+ session_manager: SessionManager,
+ mock_session: Session,
+ mock_session_consumer: SessionConsumer,
+ monkeypatch: pytest.MonkeyPatch,
+ close_before_attachment: bool,
+) -> None:
+ from marimo._session.managers.ipc import KernelStartupError
+ from marimo._session.session import SessionImpl
+
+ entered, release = asyncio.Event(), asyncio.Event()
+ mock_session.app_file_manager = AppFileManager(filename=None)
+
+ async def create(**_kwargs: object) -> Session:
+ entered.set()
+ await release.wait()
+ return mock_session
+
+ monkeypatch.setattr(SessionImpl, "create", create)
+ first = asyncio.create_task(
+ session_manager.create_session(
+ session_id, mock_session_consumer, {}, NEW_FILE, False
+ )
+ )
+ try:
+ await asyncio.wait_for(entered.wait(), 5)
+ pending = next(iter(session_manager._pending.values()))
+ if close_before_attachment:
+ # The task publishes its session before the waiter can attach.
+ pending.task.add_done_callback(
+ lambda _: session_manager.close_session(session_id)
+ )
+ release.set()
+ with pytest.raises(
+ KernelStartupError, match="closed during startup"
+ ):
+ await asyncio.wait_for(first, 5)
+ else:
+ first.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await first
+ release.set()
+ await asyncio.wait_for(asyncio.shield(pending.task), 5)
+ assert session_manager.close_session(session_id)
+
+ mock_session.connect_consumer.assert_not_called()
+ assert not session_manager.is_session_starting(session_id, NEW_FILE)
+ assert not session_manager.sessions
+
+ replacement = Mock(spec=Session)
+ replacement.room = Room()
+ replacement.connect_consumer.side_effect = (
+ replacement.room.add_consumer
+ )
+ replacement.connection_state.return_value = ConnectionState.ORPHANED
+ replacement.app_file_manager = mock_session.app_file_manager
+
+ async def restart(**_kwargs: object) -> Session:
+ return replacement
+
+ monkeypatch.setattr(SessionImpl, "create", restart)
+ assert (
+ await session_manager.create_session(
+ session_id, mock_session_consumer, {}, NEW_FILE, False
+ )
+ is replacement
+ )
+ assert session_manager.get_session(session_id) is replacement
+ assert replacement.room.main_consumer is mock_session_consumer
+ finally:
+ release.set()
+ await session_manager.shutdown()
diff --git a/tests/_server/test_sessions.py b/tests/_server/test_sessions.py
index 2599d27b86..9e257c8d69 100644
--- a/tests/_server/test_sessions.py
+++ b/tests/_server/test_sessions.py
@@ -55,6 +55,7 @@ from marimo._session.notebook import AppFileManager
from marimo._session.session import (
SessionImpl,
)
+from marimo._session.startup import SessionStartup
from marimo._session.state.session_view import SessionView
from marimo._types.ids import ConsumerId, SessionId
from marimo._utils.marimo_path import MarimoPath
@@ -358,6 +359,7 @@ async def test_session() -> None:
# Instantiate a Session
session = SessionImpl(
+ session_view=SessionView(),
initialization_id=session_id,
session_consumer=session_consumer,
kernel_manager=kernel_manager,
@@ -390,6 +392,7 @@ async def test_session() -> None:
def test_sessions_for_same_file_have_distinct_stable_ids() -> None:
sessions = [
SessionImpl(
+ session_view=SessionView(),
initialization_id="notebook.py",
session_consumer=MagicMock(),
kernel_manager=MagicMock(spec=KernelManagerImpl),
@@ -425,6 +428,7 @@ async def test_session_disconnect_reconnect() -> None:
# Instantiate a Session
session = SessionImpl(
+ session_view=SessionView(),
initialization_id=session_id,
session_consumer=session_consumer,
kernel_manager=kernel_manager,
@@ -484,6 +488,7 @@ async def test_session_with_kiosk_consumers() -> None:
# Instantiate a Session
session = SessionImpl(
+ session_view=SessionView(),
initialization_id=session_id,
session_consumer=session_consumer,
kernel_manager=kernel_manager,
@@ -1092,7 +1097,9 @@ async def test_session_with_script_config_overrides(
app_file_manager = AppFileManager(filename=str(tmp_file))
# Create session with the file that has script config
+ startup = SessionStartup()
session = await SessionImpl.create(
+ startup=startup,
initialization_id="test_id",
session_consumer=session_consumer,
mode=SessionMode.RUN,
@@ -1105,6 +1112,8 @@ async def test_session_with_script_config_overrides(
auto_instantiate=True,
)
+ assert session.session_view is startup.view
+
# Verify that the session's config is affected by the script config
assert (
session.config_manager.get_config()["formatting"]["line_length"] == 999
@@ -1192,6 +1201,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:
}
)
return await SessionImpl.create(
+ startup=SessionStartup(),
initialization_id="test_session",
session_consumer=session_consumer,
mode=mode,
diff --git a/tests/_session/app_host/test_app_host.py b/tests/_session/app_host/test_app_host.py
index 0dcbe20248..89c217f27f 100644
--- a/tests/_session/app_host/test_app_host.py
+++ b/tests/_session/app_host/test_app_host.py
@@ -3,6 +3,8 @@ from __future__ import annotations
import pytest
+from marimo._session.startup import SessionStartup
+
@pytest.mark.requires("zmq")
class TestAppHostCommands:
@@ -362,6 +364,7 @@ class TestAppHostMultipleClients:
):
for sid in ("session-1", "session-2"):
await SessionImpl.create(
+ startup=SessionStartup(),
initialization_id=file_key,
session_consumer=Mock(),
mode=SessionMode.RUN,
diff --git a/tests/_session/extensions/test_extensions.py b/tests/_session/extensions/test_extensions.py
index 6efbdd75f6..8ced0b9371 100644
--- a/tests/_session/extensions/test_extensions.py
+++ b/tests/_session/extensions/test_extensions.py
@@ -9,6 +9,7 @@ from unittest.mock import Mock, patch
import pytest
from marimo._messaging.notification import BannerNotification
+from marimo._messaging.serde import serialize_kernel_message
from marimo._session.events import SessionEventBus
from marimo._session.extensions.extensions import (
CacheMode,
@@ -228,7 +229,7 @@ class TestNotificationListenerExtension:
return manager
@patch("marimo._session.extensions.extensions.ConnectionDistributor")
- def test_lifecycle(
+ async def test_lifecycle(
self, mock_dist, mock_session, event_bus, kernel_manager, queue_manager
) -> None:
"""Test distributor creation, start, and stop."""
@@ -248,6 +249,26 @@ class TestNotificationListenerExtension:
mock_distributor.stop.assert_called_once()
assert extension.distributor is None
+ @patch("marimo._session.extensions.extensions.ConnectionDistributor")
+ async def test_detach_drops_pending_notifications(
+ self, mock_dist, mock_session, event_bus, kernel_manager, queue_manager
+ ) -> None:
+ extension = NotificationListenerExtension(
+ kernel_manager, queue_manager
+ )
+ extension.on_attach(mock_session, event_bus)
+ enqueue = mock_dist.return_value.add_consumer.call_args.args[0]
+ enqueue(
+ serialize_kernel_message(
+ BannerNotification(title="Queued", description="")
+ )
+ )
+
+ extension.on_detach()
+ await asyncio.sleep(0)
+
+ mock_session.notify.assert_not_called()
+
def test_uses_correct_distributor_type(
self, kernel_manager, queue_manager, queue_manager_with_stream
) -> None:
diff --git a/tests/_session/managers/test_ipc.py b/tests/_session/managers/test_ipc.py
index 75fb7ec678..895c33c3b9 100644
--- a/tests/_session/managers/test_ipc.py
+++ b/tests/_session/managers/test_ipc.py
@@ -448,6 +448,10 @@ async def test_startup_owns_kernel_process_and_pipes(
from marimo._config.manager import get_default_config_manager
from marimo._environments.environment import ProcessPlan
from marimo._ipc import QueueManager
+ from marimo._messaging.notification import (
+ NotificationMessage,
+ StartupProgressNotification,
+ )
from marimo._runtime.commands import AppMetadata
from marimo._session.managers.ipc import (
IPCKernelManagerImpl,
@@ -455,8 +459,21 @@ async def test_startup_owns_kernel_process_and_pipes(
KernelStartupError,
)
from marimo._session.model import SessionMode
+ from marimo._session.startup import SessionStartup
started = asyncio.Event()
+ output_received = asyncio.Event()
+ event_loop = asyncio.get_running_loop()
+ progress = SessionStartup()
+
+ def notify(notification: NotificationMessage) -> None:
+ assert asyncio.get_running_loop() is event_loop
+ progress.notify(notification)
+ if (
+ isinstance(notification, StartupProgressNotification)
+ and notification.logs
+ ):
+ output_received.set()
async def ready(
reader: asyncio.StreamReader, writer: asyncio.StreamWriter
@@ -483,6 +500,7 @@ async def test_startup_owns_kernel_process_and_pipes(
)
)
output_ready = tmp_path / "output-ready"
+ handshake_ready = tmp_path / "handshake-ready"
if outcome == "output":
child_code = "import sys; sys.stdout.write('x' * 131072)"
code = (
@@ -490,9 +508,12 @@ async def test_startup_owns_kernel_process_and_pipes(
"from pathlib import Path\n"
"sys.stdin.read()\n"
f"socket.create_connection(('127.0.0.1', {port})).send(b'x')\n"
+ "print('Resolving runtime', file=sys.stderr, flush=True)\n"
+ f"while not Path({str(handshake_ready)!r}).exists(): time.sleep(0.01)\n"
"print('KERNEL_READY', flush=True)\n"
"print(f'KERNEL_INFO {os.getpid()} {sys.executable}', flush=True)\n"
f"while not Path({str(output_ready)!r}).exists(): time.sleep(0.01)\n"
+ "print('Runtime output', file=sys.stderr, flush=True)\n"
# Inherit the kernel's stdout and fill more than the pipe buffer.
f"result = subprocess.run([sys.executable, '-c', {child_code!r}], stdout=sys.stdout)\n"
"sys.exit(result.returncode)\n"
@@ -545,16 +566,27 @@ async def test_startup_owns_kernel_process_and_pipes(
app_config=_AppConfig(),
),
config_manager=get_default_config_manager(current_path=None),
+ on_notification=notify,
)
startup = asyncio.create_task(manager.start_kernel())
try:
await asyncio.wait_for(started.wait(), 5)
if outcome == "output":
+ await asyncio.wait_for(output_received.wait(), 5)
+ assert not startup.done()
+ expected_progress = StartupProgressNotification(
+ phase="starting-kernel",
+ logs="Resolving runtime\n",
+ log_mode="replace",
+ )
+ assert progress.view.startup_progress == expected_progress
+ handshake_ready.touch() # noqa: ASYNC240
await asyncio.wait_for(startup, 5)
output_ready.touch() # noqa: ASYNC240
assert manager.kernel_task is not None
await asyncio.to_thread(manager.kernel_task.join, 5)
assert manager.kernel_task.exitcode == 0
+ assert progress.view.startup_progress == expected_progress
elif outcome == "cancel":
startup.cancel()
with pytest.raises(asyncio.CancelledError):
diff --git a/tests/_session/state/test_serialize_session.py b/tests/_session/state/test_serialize_session.py
index 8da3a2daa0..c241ac7e7a 100644
--- a/tests/_session/state/test_serialize_session.py
+++ b/tests/_session/state/test_serialize_session.py
@@ -14,7 +14,10 @@ from marimo._ast.cell_manager import CellManager
from marimo._messaging.cell_output import CellChannel, CellOutput
from marimo._messaging.errors import MarimoExceptionRaisedError, UnknownError
from marimo._messaging.notebook.document import NotebookCell, NotebookDocument
-from marimo._messaging.notification import CellNotification
+from marimo._messaging.notification import (
+ CellNotification,
+ StartupProgressNotification,
+)
from marimo._runtime.commands import ExecuteCellsCommand
from marimo._schemas.session import NotebookSessionV1
from marimo._session.state.serialize import (
@@ -1215,7 +1218,12 @@ class TestSessionCacheManager:
cache_file.write_text(json.dumps(data))
# Read back
- manager = SessionCacheManager(SessionView(), doc, path, 0.1)
+ current = SessionView()
+ progress = StartupProgressNotification(
+ phase="starting-kernel", logs="", log_mode="replace"
+ )
+ current.add_notification(progress)
+ manager = SessionCacheManager(current, doc, path, 0.1)
loaded_view = manager.read_session_view(
SessionCacheKey(
codes=(
@@ -1226,5 +1234,7 @@ class TestSessionCacheManager:
cell_ids=(CELL1, CELL2),
)
)
+ assert loaded_view is current
+ assert loaded_view.startup_progress == progress
# cache hit: codes and version match
assert len(loaded_view.cell_notifications) == 2
diff --git a/tests/_session/state/test_session_view.py b/tests/_session/state/test_session_view.py
index 1a39667a5b..d2e9b2b39c 100644
--- a/tests/_session/state/test_session_view.py
+++ b/tests/_session/state/test_session_view.py
@@ -1,10 +1,11 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from typing import Any
+from typing import Any, Literal
from unittest.mock import patch
import msgspec
+import pytest
from marimo._ast.cell import RuntimeStateType
from marimo._data.models import (
@@ -21,13 +22,22 @@ from marimo._messaging.notification import (
CellNotification,
DatasetsNotification,
DataSourceConnectionsNotification,
+ EnvironmentAction,
+ EnvironmentOperation,
+ EnvironmentOperationNotification,
+ EnvironmentOperationStatus,
+ EnvironmentState,
EsmSpec,
- InstallingPackageAlertNotification,
ModelClose,
ModelCustom,
ModelLifecycleNotification,
ModelOpen,
ModelUpdate,
+ OperationFailed,
+ OperationRestartRequired,
+ OperationRunning,
+ OperationSucceeded,
+ PackageStatusType,
SQLDatabaseMetadata,
SQLMetadata,
SQLSchemaListPreviewNotification,
@@ -1853,217 +1863,338 @@ def test_session_view_startup_logs_standalone_done(
assert session_view.startup_logs.status == "done"
-def test_session_view_package_logs_initialization(
+def test_package_operations_separate_environments(
session_view: SessionView,
) -> None:
- """Test that SessionView initializes package_logs correctly."""
- assert hasattr(session_view, "package_logs")
- assert isinstance(session_view.package_logs, dict)
- assert len(session_view.package_logs) == 0
-
-
-def test_session_view_package_logs_start(session_view: SessionView) -> None:
- """Test SessionView handles package logs start status."""
-
- alert = InstallingPackageAlertNotification(
- packages={"numpy": "installing"},
- logs={"numpy": "Installing numpy...\n"},
- log_status="start",
- )
-
- session_view.add_notification(alert)
-
- assert "numpy" in session_view.package_logs
- assert session_view.package_logs["numpy"] == "Installing numpy...\n"
-
-
-def test_session_view_package_logs_append(session_view: SessionView) -> None:
- """Test SessionView handles package logs append status."""
-
- # Start with initial log
- start_alert = InstallingPackageAlertNotification(
- packages={"pandas": "installing"},
- logs={"pandas": "Starting installation...\n"},
- log_status="start",
- )
- session_view.add_notification(start_alert)
-
- # Append more logs
- append_alert = InstallingPackageAlertNotification(
- packages={"pandas": "installing"},
- logs={"pandas": "Downloading dependencies...\n"},
- log_status="append",
- )
- session_view.add_notification(append_alert)
-
- expected_content = (
- "Starting installation...\nDownloading dependencies...\n"
- )
- assert session_view.package_logs["pandas"] == expected_content
-
-
-def test_session_view_package_logs_done(session_view: SessionView) -> None:
- """Test SessionView handles package logs done status."""
-
- # Start installation
- start_alert = InstallingPackageAlertNotification(
- packages={"scipy": "installing"},
- logs={"scipy": "Installing scipy...\n"},
- log_status="start",
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"ruff": "running"},
+ logs={"ruff": "Kernel install\n"},
+ log_mode="replace",
+ source="kernel",
+ )
)
- session_view.add_notification(start_alert)
-
- # Add progress log
- append_alert = InstallingPackageAlertNotification(
- packages={"scipy": "installing"},
- logs={"scipy": "Building wheels...\n"},
- log_status="append",
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"ruff": "running"},
+ logs={"ruff": "Server install\n"},
+ log_mode="replace",
+ source="server",
+ )
)
- session_view.add_notification(append_alert)
-
- # Finish installation
- done_alert = InstallingPackageAlertNotification(
- packages={"scipy": "installed"},
- logs={"scipy": "Successfully installed scipy!\n"},
- log_status="done",
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"ruff": "failed"},
+ logs={"ruff": "Server failure\n"},
+ log_mode="append",
+ source="server",
+ )
)
- session_view.add_notification(done_alert)
- expected_content = (
- "Installing scipy...\n"
- "Building wheels...\n"
- "Successfully installed scipy!\n"
- )
- assert session_view.package_logs["scipy"] == expected_content
+ assert (
+ session_view.get_environment_state("kernel").operations
+ + session_view.get_environment_state("server").operations
+ ) == [
+ EnvironmentOperation(
+ action="install",
+ operation_id="install",
+ status=OperationRunning(),
+ source="kernel",
+ packages={"ruff": "running"},
+ logs={"ruff": "Kernel install\n"},
+ ),
+ EnvironmentOperation(
+ action="install",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"ruff": "failed"},
+ logs={"ruff": "Server install\nServer failure\n"},
+ source="server",
+ ),
+ ]
-def test_session_view_package_logs_multiple_packages(
+def test_package_log_start_resets_only_that_package(
session_view: SessionView,
) -> None:
- """Test SessionView handles logs for multiple packages simultaneously."""
-
- # Start installing multiple packages
- multi_alert = InstallingPackageAlertNotification(
- packages={"numpy": "installing", "pandas": "installing"},
- logs={
- "numpy": "Starting numpy install...\n",
- "pandas": "Starting pandas install...\n",
- },
- log_status="start",
- )
- session_view.add_notification(multi_alert)
-
- # Add logs for numpy only
- numpy_alert = InstallingPackageAlertNotification(
- packages={"numpy": "installing", "pandas": "installing"},
- logs={"numpy": "Numpy progress...\n"},
- log_status="append",
- )
- session_view.add_notification(numpy_alert)
-
- # Add logs for pandas only
- pandas_alert = InstallingPackageAlertNotification(
- packages={"numpy": "installing", "pandas": "installing"},
- logs={"pandas": "Pandas progress...\n"},
- log_status="append",
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"numpy": "succeeded", "pandas": "failed"},
+ logs={"numpy": "Installed\n", "pandas": "Failed\n"},
+ log_mode="append",
+ )
)
- session_view.add_notification(pandas_alert)
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"numpy": "succeeded", "pandas": "running"},
+ logs={"pandas": ""},
+ log_mode="replace",
+ )
+ )
+ assert session_view.get_environment_state("kernel").operations == [
+ EnvironmentOperation(
+ action="install",
+ operation_id="install",
+ status=OperationRunning(),
+ source="kernel",
+ packages={"numpy": "succeeded", "pandas": "running"},
+ logs={"numpy": "Installed\n", "pandas": ""},
+ )
+ ]
- assert len(session_view.package_logs) == 2
- assert "numpy" in session_view.package_logs
- assert "pandas" in session_view.package_logs
- assert session_view.package_logs["numpy"] == (
- "Starting numpy install...\nNumpy progress...\n"
- )
- assert session_view.package_logs["pandas"] == (
- "Starting pandas install...\nPandas progress...\n"
[email protected]("packages", [{"pandas": "queued"}, {}])
+def test_package_operations_replace_statuses_and_keep_named_logs(
+ session_view: SessionView, packages: PackageStatusType
+) -> None:
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"numpy": "failed"},
+ logs={"numpy": "Failed\n"},
+ log_mode="append",
+ )
)
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ logs={},
+ log_mode="append",
+ operation_id="install",
+ status=OperationRunning(),
+ packages=packages,
+ )
+ )
+ assert session_view.get_environment_state("kernel").operations == [
+ EnvironmentOperation(
+ action="install",
+ operation_id="install",
+ status=OperationRunning(),
+ logs={"numpy": "Failed\n"},
+ source="kernel",
+ packages=packages,
+ )
+ ]
-def test_session_view_package_logs_without_logs(
+def test_package_installation_snapshot_does_not_share_mutable_state(
session_view: SessionView,
) -> None:
- """Test SessionView handles InstallingPackageAlert without logs (backward compatibility)."""
-
- # Old-style alert without logs
- alert = InstallingPackageAlertNotification(
- packages={"requests": "installing"}
- )
- session_view.add_notification(alert)
-
- # Should not add any package logs
- assert len(session_view.package_logs) == 0
+ notification = EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"numpy": "running"},
+ logs={"numpy": "Installing\n"},
+ log_mode="replace",
+ )
+ session_view.add_notification(notification)
+ state = session_view.get_environment_state("kernel").operations
+
+ notification.packages["numpy"] = "failed"
+ state[0].packages.clear()
+ state[0].logs.clear()
+ state.clear()
+
+ assert session_view.get_environment_state("kernel").operations == [
+ EnvironmentOperation(
+ action="install",
+ operation_id="install",
+ status=OperationRunning(),
+ source="kernel",
+ packages={"numpy": "running"},
+ logs={"numpy": "Installing\n"},
+ )
+ ]
-def test_session_view_package_logs_partial_logs(
+def test_package_operations_retain_active_and_latest_completed_attempts(
session_view: SessionView,
) -> None:
- """Test SessionView handles alerts with logs but no log_status."""
-
- # Alert with logs but no log_status
- alert = InstallingPackageAlertNotification(
- packages={"matplotlib": "installing"},
- logs={"matplotlib": "Some log content...\n"},
- # log_status is None
- )
- session_view.add_notification(alert)
+ for operation_id in ("first", "second", "active"):
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ logs={"numpy": operation_id},
+ log_mode="append",
+ packages={"numpy": "running"},
+ operation_id=operation_id,
+ status=OperationRunning(),
+ )
+ )
+ for operation_id in ("first", "second"):
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ logs={"numpy": " failed"},
+ log_mode="append",
+ packages={"numpy": "failed"},
+ operation_id=operation_id,
+ status=OperationFailed(error=operation_id),
+ )
+ )
- # Should not add any package logs since log_status is missing
- assert len(session_view.package_logs) == 0
+ assert session_view.get_environment_state("kernel").operations == [
+ EnvironmentOperation(
+ action="install",
+ logs={"numpy": "second failed"},
+ source="kernel",
+ packages={"numpy": "failed"},
+ operation_id="second",
+ status=OperationFailed(error="second"),
+ ),
+ EnvironmentOperation(
+ action="install",
+ logs={"numpy": "active"},
+ source="kernel",
+ packages={"numpy": "running"},
+ operation_id="active",
+ status=OperationRunning(),
+ ),
+ ]
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ operation_id="retry",
+ status=OperationRunning(),
+ packages={"numpy": "queued"},
+ logs={},
+ log_mode="append",
+ )
+ )
+ assert [
+ (op.operation_id, op.logs)
+ for op in session_view.get_environment_state("kernel").operations
+ ] == [
+ ("active", {"numpy": "active"}),
+ ("retry", {}),
+ ]
-def test_session_view_package_logs_start_without_existing(
+ "result",
+ [OperationSucceeded(), OperationFailed(error="A later operation failed")],
+)
+def test_restart_requirement_survives_replacing_operation_results(
session_view: SessionView,
+ result: EnvironmentOperationStatus,
) -> None:
- """Test package logs start status on package that doesn't exist yet."""
-
- alert = InstallingPackageAlertNotification(
- packages={"new_package": "installing"},
- logs={"new_package": "Starting fresh install...\n"},
- log_status="start",
+ source: Literal["kernel", "server"] = "kernel"
+ initial = session_view.get_environment_state(source)
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ logs={},
+ log_mode="append",
+ operation_id="first",
+ source=source,
+ status=OperationRunning(),
+ packages={"numpy": "restart-required", "pandas": "running"},
+ )
)
- session_view.add_notification(alert)
+ assert session_view.get_environment_state(source).restart_required
- assert (
- session_view.package_logs["new_package"]
- == "Starting fresh install...\n"
+ # A batch can fail after an earlier package saved changes needing restart.
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ logs={},
+ log_mode="append",
+ operation_id="first",
+ source=source,
+ status=OperationFailed(error="Could not install pandas"),
+ packages={"numpy": "restart-required", "pandas": "failed"},
+ )
)
-
-
-def test_session_view_package_logs_append_without_existing(
- session_view: SessionView,
-) -> None:
- """Test package logs append status on package that doesn't exist yet."""
-
- # Append to non-existing package should start with empty string
- alert = InstallingPackageAlertNotification(
- packages={"orphan_package": "installing"},
- logs={"orphan_package": "Appending to nothing...\n"},
- log_status="append",
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ logs={},
+ log_mode="append",
+ operation_id="second",
+ source=source,
+ status=OperationRunning(),
+ packages={"polars": "running"},
+ )
+ )
+ packages: PackageStatusType = {
+ "polars": "succeeded"
+ if isinstance(result, OperationSucceeded)
+ else "failed"
+ }
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="install",
+ logs={},
+ log_mode="append",
+ operation_id="second",
+ source=source,
+ status=result,
+ packages=packages,
+ )
+ )
+
+ assert session_view.get_environment_state(source) == EnvironmentState(
+ restart_required=True,
+ operations=[
+ EnvironmentOperation(
+ action="install",
+ operation_id="second",
+ source=source,
+ status=result,
+ packages=packages,
+ logs={},
+ )
+ ],
)
- session_view.add_notification(alert)
-
+ other = "server" if source == "kernel" else "kernel"
assert (
- session_view.package_logs["orphan_package"]
- == "Appending to nothing...\n"
- )
+ initial,
+ session_view.get_environment_state(other),
+ SessionView().get_environment_state(source),
+ ) == (EnvironmentState(restart_required=False, operations=[]),) * 3
-def test_session_view_package_logs_empty_content(
+def test_restart_outcome_retains_requirement_without_package_progress(
session_view: SessionView,
) -> None:
- """Test SessionView handles empty log content."""
-
- alert = InstallingPackageAlertNotification(
- packages={"empty_logs": "installing"},
- logs={"empty_logs": ""},
- log_status="start",
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ action="sync",
+ source="kernel",
+ logs={},
+ log_mode="append",
+ operation_id="first",
+ status=OperationRestartRequired(reason="Python version changed"),
+ packages={},
+ )
)
- session_view.add_notification(alert)
-
- assert "empty_logs" in session_view.package_logs
- assert session_view.package_logs["empty_logs"] == ""
+ assert session_view.get_environment_state("kernel").restart_required
class TestUpdateCellOutputs:
@@ -2234,3 +2365,66 @@ class TestUpdateCellOutputs:
assert (
session_view.cell_notifications[cell_id].output == malformed_output
)
+
+
+def test_preparation_remains_available_after_package_changes(
+ session_view: SessionView,
+) -> None:
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ operation_id="prepare",
+ action="prepare",
+ source="kernel",
+ status=OperationSucceeded(),
+ packages={},
+ logs={"environment": "Prepared environment\n"},
+ log_mode="replace",
+ )
+ )
+ preparation = session_view.get_environment_state("kernel").operations[0]
+ actions: tuple[EnvironmentAction, ...] = ("install", "sync", "remove")
+ for action in actions:
+ for status in (OperationRunning(), OperationSucceeded()):
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ operation_id=action,
+ action=action,
+ source="kernel",
+ status=status,
+ packages={},
+ logs={"environment": action},
+ log_mode="replace",
+ )
+ )
+ assert session_view.get_environment_state("kernel").operations == [
+ preparation,
+ EnvironmentOperation(
+ operation_id=action,
+ action=action,
+ source="kernel",
+ status=OperationSucceeded(),
+ packages={},
+ logs={"environment": action},
+ ),
+ ]
+ session_view.add_notification(
+ EnvironmentOperationNotification(
+ operation_id="new-preparation",
+ action="prepare",
+ source="kernel",
+ status=OperationRunning(),
+ packages={},
+ logs={},
+ log_mode="replace",
+ )
+ )
+ assert session_view.get_environment_state("kernel").operations == [
+ EnvironmentOperation(
+ operation_id="new-preparation",
+ action="prepare",
+ source="kernel",
+ status=OperationRunning(),
+ packages={},
+ logs={},
+ ),
+ ]
diff --git a/tests/_session/test_notification_ordering.py b/tests/_session/test_notification_ordering.py
new file mode 100644
index 0000000000..40e6980ceb
--- /dev/null
+++ b/tests/_session/test_notification_ordering.py
@@ -0,0 +1,237 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+import queue
+import threading
+from typing import TYPE_CHECKING
+from unittest.mock import MagicMock, Mock
+
+import pytest
+
+from marimo._ast.app import App, InternalApp
+from marimo._config.manager import get_default_config_manager
+from marimo._messaging.notification import (
+ EnvironmentOperation,
+ EnvironmentOperationNotification,
+ EnvironmentState,
+ EnvironmentStateNotification,
+ OperationRunning,
+)
+from marimo._messaging.serde import (
+ deserialize_kernel_message,
+ serialize_kernel_message,
+)
+from marimo._messaging.types import KernelMessage
+from marimo._server.api.endpoints.ws.ws_connection_validator import (
+ ConnectionParams,
+)
+from marimo._server.api.endpoints.ws_endpoint import WebSocketHandler
+from marimo._session.consumer import SessionConsumer
+from marimo._session.extensions.extensions import (
+ NotificationListenerExtension,
+ SessionViewExtension,
+)
+from marimo._session.managers import KernelManagerImpl
+from marimo._session.model import ConnectionState, SessionMode
+from marimo._session.notebook import AppFileManager
+from marimo._session.session import SessionImpl
+from marimo._session.state.session_view import SessionView
+from marimo._types.ids import ConsumerId, SessionId
+from marimo._utils.distributor import QueueDistributor
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+
+def session_and_consumer() -> Iterator[tuple[SessionImpl, Mock]]:
+ consumer = Mock(spec=SessionConsumer)
+ consumer.consumer_id = ConsumerId("main")
+ consumer.connection_state.return_value = ConnectionState.OPEN
+ session = SessionImpl(
+ session_view=SessionView(),
+ initialization_id="notebook.py",
+ session_consumer=consumer,
+ kernel_manager=Mock(spec=KernelManagerImpl),
+ app_file_manager=AppFileManager.from_app(InternalApp(App())),
+ config_manager=get_default_config_manager(current_path=None),
+ ttl_seconds=None,
+ extensions=[SessionViewExtension()],
+ )
+ try:
+ yield session, consumer
+ finally:
+ session.close()
+
+
+def _progress(log: str) -> EnvironmentOperationNotification:
+ return EnvironmentOperationNotification(
+ action="install",
+ source="kernel",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"numpy": "running"},
+ logs={"numpy": log},
+ log_mode="append",
+ )
+
+
+def _state(log: str) -> EnvironmentState:
+ return EnvironmentState(
+ restart_required=False,
+ operations=[
+ EnvironmentOperation(
+ action="install",
+ operation_id="install",
+ status=OperationRunning(),
+ packages={"numpy": "running"},
+ logs={"numpy": log},
+ source="kernel",
+ )
+ ],
+ )
+
+
+def test_notification_is_retained_before_consumer_receives_it(
+ session_and_consumer: tuple[SessionImpl, Mock],
+) -> None:
+ session, consumer = session_and_consumer
+ observed: list[EnvironmentState] = []
+
+ def receive(_message: KernelMessage) -> None:
+ observed.append(
+ session.get_current_state().get_environment_state("kernel")
+ )
+
+ consumer.notify.side_effect = receive
+ progress = _progress("Downloading\n")
+ session.notify(
+ progress,
+ from_consumer_id=None,
+ )
+
+ assert observed == [_state("Downloading\n")]
+
+
+async def test_queued_kernel_messages_update_and_deliver_on_session_loop(
+ session_and_consumer: tuple[SessionImpl, Mock],
+) -> None:
+ session, consumer = session_and_consumer
+ loop = asyncio.get_running_loop()
+ loop_thread = threading.get_ident()
+ delivered = asyncio.Event()
+ observed: list[tuple[int, EnvironmentState]] = []
+
+ def receive(_message: KernelMessage) -> None:
+ observed.append(
+ (
+ threading.get_ident(),
+ session.get_current_state().get_environment_state("kernel"),
+ )
+ )
+ if len(observed) == 2:
+ loop.call_soon_threadsafe(delivered.set)
+
+ consumer.notify.side_effect = receive
+ messages: queue.Queue[KernelMessage | None] = queue.Queue()
+ queue_manager = Mock(stream_queue=messages)
+ listener = NotificationListenerExtension(Mock(), queue_manager)
+ listener.on_attach(session, session._event_bus)
+ distributor = listener.distributor
+ try:
+ assert isinstance(distributor, QueueDistributor)
+ messages.put(serialize_kernel_message(_progress("Downloading\n")))
+ messages.put(serialize_kernel_message(_progress("Installing\n")))
+ await asyncio.wait_for(delivered.wait(), timeout=5)
+ finally:
+ listener.on_detach()
+ if (
+ isinstance(distributor, QueueDistributor)
+ and distributor.thread is not None
+ ):
+ await asyncio.to_thread(distributor.thread.join, 5)
+
+ assert observed == [
+ (loop_thread, _state("Downloading\n")),
+ (loop_thread, _state("Downloading\nInstalling\n")),
+ ]
+
+
+async def test_reconnect_snapshot_precedes_a_queued_live_update(
+ session_and_consumer: tuple[SessionImpl, Mock],
+) -> None:
+ session, consumer = session_and_consumer
+ session.disconnect_consumer(consumer)
+ session.notify(_progress("Before\n"), from_consumer_id=None)
+ handler = WebSocketHandler(
+ websocket=MagicMock(),
+ manager=MagicMock(),
+ params=ConnectionParams(
+ session_id=SessionId("reconnected"),
+ file_key="notebook.py",
+ kiosk=False,
+ auto_instantiate=False,
+ rtc_enabled=False,
+ ),
+ mode=SessionMode.EDIT,
+ )
+ asyncio.get_running_loop().call_soon(
+ lambda: session.notify(_progress("After\n"), from_consumer_id=None)
+ )
+ handler._reconnect_session(session, replay=False)
+ await asyncio.sleep(0)
+
+ messages = []
+ while not handler.message_queue.empty():
+ messages.append(
+ deserialize_kernel_message(handler.message_queue.get_nowait())
+ )
+ assert [
+ message
+ for message in messages
+ if isinstance(
+ message,
+ (EnvironmentStateNotification, EnvironmentOperationNotification),
+ )
+ ] == [
+ EnvironmentStateNotification(
+ source="kernel", state=_state("Before\n")
+ ),
+ EnvironmentStateNotification(
+ source="server",
+ state=EnvironmentState(restart_required=False, operations=[]),
+ ),
+ _progress("After\n"),
+ ]
+
+
+def test_queue_can_be_reused_after_its_listener_loop_closes(
+ session_and_consumer: tuple[SessionImpl, Mock],
+) -> None:
+ session, consumer = session_and_consumer
+ messages: queue.Queue[KernelMessage | None] = queue.Queue()
+ listener = NotificationListenerExtension(
+ Mock(), Mock(stream_queue=messages)
+ )
+ loop = asyncio.new_event_loop()
+
+ async def attach() -> QueueDistributor[KernelMessage]:
+ listener.on_attach(session, session._event_bus)
+ assert isinstance(listener.distributor, QueueDistributor)
+ return listener.distributor
+
+ distributor = loop.run_until_complete(attach())
+ loop.close()
+ try:
+ messages.put(serialize_kernel_message(_progress("Late output\n")))
+ # Queue the sentinel after the late message, before detaching, to
+ # exercise a callback racing with loop teardown.
+ distributor.stop()
+ assert distributor.thread is not None
+ distributor.thread.join(5)
+ assert not distributor.thread.is_alive()
+ assert messages.empty()
+ consumer.notify.assert_not_called()
+ finally:
+ listener.on_detach()
diff --git a/tests/_session/test_startup_threading.py b/tests/_session/test_startup_threading.py
new file mode 100644
index 0000000000..316085296d
--- /dev/null
+++ b/tests/_session/test_startup_threading.py
@@ -0,0 +1,44 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+import threading
+from unittest.mock import Mock
+
+from marimo._messaging.notification import StartupProgressNotification
+from marimo._messaging.serde import deserialize_kernel_message
+from marimo._session.consumer import SessionConsumer
+from marimo._session.startup import SessionStartup
+
+
+async def test_worker_output_reaches_consumers_on_the_session_loop() -> None:
+ loop_thread = threading.current_thread()
+ startup = SessionStartup()
+ delivered = asyncio.Event()
+ seen: list[tuple[threading.Thread, str | None]] = []
+ consumer = Mock(spec=SessionConsumer)
+
+ def notify(_message: bytes) -> None:
+ progress = startup.view.startup_progress
+ # Consumers observe a view that already includes the notification.
+ seen.append(
+ (
+ threading.current_thread(),
+ progress.phase if progress is not None else None,
+ )
+ )
+ delivered.set()
+
+ consumer.notify.side_effect = notify
+ progress = StartupProgressNotification(
+ phase="starting-kernel", logs="", log_mode="replace"
+ )
+ with startup.subscribe(consumer):
+ await asyncio.to_thread(startup.notify, progress)
+ await asyncio.wait_for(delivered.wait(), 5)
+
+ assert seen == [(loop_thread, "starting-kernel")]
+ assert (
+ deserialize_kernel_message(consumer.notify.call_args.args[0])
+ == progress
+ )