@marimo-team/frontend 0.25.2-dev38 → 0.25.2-dev39

package/src/components/editor/actions/__tests__/pair-with-agent-commands.test.ts

@@ -154,63 +154,54 @@ describe("getTerminalCommand", () => {
       ).toBe(
         String.raw`${cli} "$(MARIMO_PAIR_NEXT=1 uvx marimo@latest pair prompt \
   --url http://localhost:8000 \
-  --file notebooks/example.py \
   --session s_ab12cd \
   --with-token)"`,
       );
     },
   );
 
-  it("includes the url and file for each agent", () => {
+  it("includes the url and agent flag for each agent", () => {
     expect(getTerminalCommand("claude", CONNECTION, false)).toBe(
-      `claude "$(uv run marimo pair prompt --url http://localhost:8000 --file notebooks/example.py --claude)"`,
+      `claude "$(uv run marimo pair prompt --url http://localhost:8000 --claude)"`,
     );
     expect(getTerminalCommand("codex", CONNECTION, false)).toBe(
-      `codex "$(uv run marimo pair prompt --url http://localhost:8000 --file notebooks/example.py --codex)"`,
+      `codex "$(uv run marimo pair prompt --url http://localhost:8000 --codex)"`,
     );
     expect(getTerminalCommand("opencode", CONNECTION, false)).toBe(
-      `opencode --prompt "$(uv run marimo pair prompt --url http://localhost:8000 --file notebooks/example.py --opencode)"`,
+      `opencode --prompt "$(uv run marimo pair prompt --url http://localhost:8000 --opencode)"`,
     );
   });
 
-  it("omits the file flag when the page URL has no file", () => {
-    const command = getTerminalCommand(
-      "claude",
-      CONNECTION_WITHOUT_FILE,
-      false,
-    );
+  it("never passes a file to marimo pair prompt", () => {
+    const command = getTerminalCommand("claude", CONNECTION, false);
     expect(command).not.toContain("--file");
-    expect(command).not.toContain("--session");
+    expect(command).not.toContain("notebooks/example.py");
   });
 
-  it("shell-escapes a url containing metacharacters", () => {
-    const command = getTerminalCommand(
-      "claude",
-      { url: "http://host:8000?auth=a&b", file: "notebook.py" },
-      false,
+  it("omits the session outside the preview", () => {
+    expect(getTerminalCommand("claude", CONNECTION, false)).not.toContain(
+      "--session",
     );
-    expect(command).toContain("--url 'http://host:8000?auth=a&b'");
   });
 
-  it.each([
-    ["relative/my notebook.py", "--file 'relative/my notebook.py'"],
-    ["/tmp/my notebook.py", "--file '/tmp/my notebook.py'"],
-    [
-      String.raw`C:\Users\Jane Doe\notebook.py`,
-      String.raw`--file 'C:\Users\Jane Doe\notebook.py'`,
-    ],
-    [
-      String.raw`\\server\share\my notebook.py`,
-      String.raw`--file '\\server\share\my notebook.py'`,
-    ],
-    ["notebooks/it's.py", `--file 'notebooks/it'"'"'s.py'`],
-  ])("shell-escapes file path %s", (file, expected) => {
+  it("omits the session when it is unknown", () => {
+    expect(
+      getTerminalCommand(
+        "claude",
+        CONNECTION_WITHOUT_FILE,
+        false,
+        PAIR_PREVIEW,
+      ),
+    ).not.toContain("--session");
+  });
+
+  it("shell-escapes a url containing metacharacters", () => {
     const command = getTerminalCommand(
       "claude",
-      { url: CONNECTION.url, file },
+      { url: "http://host:8000?auth=a&b" },
       false,
     );
-    expect(command).toContain(expected);
+    expect(command).toContain("--url 'http://host:8000?auth=a&b'");
   });
 
   it("adds --with-token before the agent flag when requested", () => {
@@ -230,23 +221,22 @@ describe("getRawPrompt", () => {
     expect(
       getRawPrompt(
         {
-          url: "http://host/{file}",
-          file: "{session}/it's.py",
-          session: "{command}",
+          url: "http://host/{session}",
+          session: "{command}/it's",
         },
-        "tok'en {file} $&",
+        "tok'en {session} $&",
         {
           ...PAIR_PREVIEW,
           command: "custom marimo",
           templates: {
             ...PAIR_PREVIEW.templates,
-            prompt: "{command}\n{url}\n{file}{session}{authentication}",
+            prompt: "{command}\n{url}\n{session}{authentication}",
           },
         },
       ),
     ).toBe(
-      "custom marimo\nhttp://host/{file}\nFile: {session}/it's.py\nSession: {command}\n" +
-        `\n\nFor authenticated Pair commands, set \`export MARIMO_TOKEN='tok'"'"'en {file} $&'\` in the shell that runs marimo.`,
+      "custom marimo\nhttp://host/{session}\nSession: {command}/it's\n" +
+        `\n\nFor authenticated Pair commands, set \`export MARIMO_TOKEN='tok'"'"'en {session} $&'\` in the shell that runs marimo.`,
     );
   });
 
@@ -256,10 +246,7 @@ describe("getRawPrompt", () => {
       { ...CONNECTION_WITHOUT_FILE, session: "s_ab12cd" },
       "Session: s_ab12cd\n",
     ],
-    [
-      { ...CONNECTION_WITHOUT_FILE, file: "notebook.py" },
-      "File: notebook.py\n",
-    ],
+    [{ ...CONNECTION_WITHOUT_FILE, file: "notebook.py" }, ""],
   ])("omits absent preview fields for %j", (connection, fields) => {
     expect(getRawPrompt(connection, null, PAIR_PREVIEW)).toBe(
       "Pair with me on this running marimo notebook.\n\n" +
@@ -270,13 +257,12 @@ describe("getRawPrompt", () => {
     );
   });
 
-  it("renders the shared preview template with optional session context", () => {
+  it("renders the shared preview template with the session and no file", () => {
     expect(
       getRawPrompt({ ...CONNECTION, session: "s_ab12cd" }, null, PAIR_PREVIEW),
     ).toBe(
       "Pair with me on this running marimo notebook.\n\n" +
         "URL: http://localhost:8000\n" +
-        "File: notebooks/example.py\n" +
         "Session: s_ab12cd\n\n" +
         "Run `uvx marimo@latest pair --help` first.\n" +
         "Use `uvx marimo@latest` for all marimo commands.\n\n" +

package/src/components/editor/actions/__tests__/pair-with-agent-modal.test.tsx

@@ -15,7 +15,10 @@ import { PAIR_PREVIEW } from "@/__tests__/fixtures/pair-preview";
 import { Dialog } from "@/components/ui/dialog";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import { pairPreviewAtom } from "@/core/config/pair";
-import { getSessionId } from "@/core/kernel/session";
+import {
+  type StableSessionId,
+  stableSessionIdAtom,
+} from "@/core/kernel/session";
 import { filenameAtom } from "@/core/saving/file-state";
 import {
   DEFAULT_RUNTIME_CONFIG,
@@ -39,10 +42,13 @@ function wrapper({ children }: { children: React.ReactNode }) {
   );
 }
 
+const STABLE_ID = "sess-stable-1" as StableSessionId;
+
 describe("PairWithAgentModal", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     store.set(pairPreviewAtom, PAIR_PREVIEW);
+    store.set(stableSessionIdAtom, STABLE_ID);
     store.set(filenameAtom, "/project/my notebook.py");
     store.set(runtimeConfigAtom, {
       ...DEFAULT_RUNTIME_CONFIG,
@@ -57,12 +63,13 @@ describe("PairWithAgentModal", () => {
 
   afterEach(() => {
     store.set(pairPreviewAtom, undefined);
+    store.set(stableSessionIdAtom, null);
     store.set(filenameAtom, null);
     vi.unstubAllGlobals();
   });
 
   it.each(["Claude", "Codex", "OpenCode", "Prompt"])(
-    "omits skill installation and includes the current session in %s preview",
+    "omits skill installation and targets the stable session in %s preview",
     async (tab) => {
       await act(async () => {
         render(<PairWithAgentModal onClose={vi.fn()} />, { wrapper });
@@ -74,59 +81,41 @@ describe("PairWithAgentModal", () => {
 
       const panel = screen.getByRole("tabpanel");
       expect(within(panel).queryAllByText(/skill/i)).toEqual([]);
-      expect(panel).toHaveTextContent(getSessionId());
-      expect(panel).toHaveTextContent(
-        tab === "Prompt" ? "File: notebook.py" : "--file notebook.py",
-      );
-      expect(panel).not.toHaveTextContent("/project/my notebook.py");
+      expect(panel).toHaveTextContent(STABLE_ID);
+      expect(panel).not.toHaveTextContent("--file");
+      expect(panel).not.toHaveTextContent("File:");
+      expect(panel).not.toHaveTextContent("notebook.py");
       expect(panel).toHaveTextContent(
         tab === "Prompt" ? "1. Copy this prompt" : "1. Run in your terminal",
       );
-    },
-  );
-
-  it.each(["Claude", "Codex", "OpenCode", "Prompt"])(
-    "includes the known notebook file in %s preview when the URL has no file",
-    async (tab) => {
-      window.history.replaceState({}, "", "/");
-      await act(async () => {
-        render(<PairWithAgentModal onClose={vi.fn()} />, { wrapper });
-      });
-      fireEvent.mouseDown(screen.getByRole("tab", { name: tab }), {
-        button: 0,
-        ctrlKey: false,
-      });
-
-      const panel = screen.getByRole("tabpanel");
-      const fileHint =
-        tab === "Prompt"
-          ? "File: /project/my notebook.py"
-          : "--file '/project/my notebook.py'";
-      expect(panel).toHaveTextContent(fileHint);
       fireEvent.click(
         within(panel).getByRole("button", {
           name: tab === "Prompt" ? "Copy prompt" : "Copy command",
         }),
       );
       await waitFor(() => expect(copyToClipboard).toHaveBeenCalledOnce());
-      expect(vi.mocked(copyToClipboard).mock.calls[0][0]).toContain(fileHint);
+      const copied = vi.mocked(copyToClipboard).mock.calls[0][0];
+      expect(copied).toContain(STABLE_ID);
+      expect(copied).not.toContain("notebook.py");
     },
   );
 
-  it.each([null, ""])(
-    "omits the file when the URL and notebook filename are absent (%s)",
-    async (filename) => {
-      window.history.replaceState({}, "", "/");
-      store.set(filenameAtom, filename);
+  it.each(["Claude", "Prompt"])(
+    "omits the session in %s preview before kernel-ready arrives",
+    async (tab) => {
+      store.set(stableSessionIdAtom, null);
       await act(async () => {
         render(<PairWithAgentModal onClose={vi.fn()} />, { wrapper });
       });
-      expect(screen.getByRole("tabpanel")).not.toHaveTextContent("--file");
-      fireEvent.mouseDown(screen.getByRole("tab", { name: "Prompt" }), {
+      fireEvent.mouseDown(screen.getByRole("tab", { name: tab }), {
         button: 0,
         ctrlKey: false,
       });
-      expect(screen.getByRole("tabpanel")).not.toHaveTextContent("File:");
+
+      const panel = screen.getByRole("tabpanel");
+      expect(panel).not.toHaveTextContent("--session");
+      expect(panel).not.toHaveTextContent("Session:");
+      expect(panel).toHaveTextContent("http://localhost:8000");
     },
   );
 
@@ -147,7 +136,8 @@ describe("PairWithAgentModal", () => {
       expect(
         within(panel).getByText("npx skills add marimo-team/marimo-pair"),
       ).toBeVisible();
-      expect(panel).not.toHaveTextContent(getSessionId());
+      expect(panel).not.toHaveTextContent(STABLE_ID);
+      expect(panel).not.toHaveTextContent("--file");
       expect(panel).not.toHaveTextContent("MARIMO_PAIR_NEXT");
       expect(panel).not.toHaveTextContent("/project/my notebook.py");
       expect(panel).toHaveTextContent(
@@ -205,8 +195,7 @@ describe("PairWithAgentModal", () => {
       expect(copyToClipboard).toHaveBeenCalledWith(
         String.raw`claude "$(MARIMO_PAIR_NEXT=1 uvx marimo@latest pair prompt \
   --url http://localhost:8000/ \
-  --file notebook.py \
-  --session ${getSessionId()} \
+  --session ${STABLE_ID} \
   --with-token)"`,
       ),
     );

package/src/components/editor/actions/pair-with-agent-commands.ts

@@ -38,8 +38,9 @@ function getFileFlag(file: string | undefined): string {
 /** Identifies the specific running notebook to pair on. */
 export interface ConnectionInfo {
   url: string;
-  /** The server's file key or notebook filename, when known. */
+  /** The server's file key, when known. */
   file?: string;
+  /** The stable session ID, when known. */
   session?: string;
 }
 
@@ -49,7 +50,7 @@ export interface ConnectionInfo {
  */
 export function getTerminalCommand(
   agent: Exclude<AgentTab, "prompt">,
-  { url, file, session }: ConnectionInfo,
+  { url, session }: ConnectionInfo,
   withToken: boolean,
   preview?: PairPreviewConfig,
 ): string {
@@ -58,7 +59,6 @@ export function getTerminalCommand(
   const base = [
     `${prefix}${command} pair prompt`,
     `--url ${shellQuote(url)}`,
-    file ? `--file ${shellQuote(file)}` : "",
     preview && session ? `--session ${shellQuote(session)}` : "",
     withToken ? "--with-token" : "",
     preview ? "" : `--${agent}`,
@@ -92,7 +92,6 @@ export function getRawPrompt(
     return formatPrompt(templates.prompt, {
       command,
       url,
-      file: file ? formatPrompt(templates.file, { file }) : "",
       session: session ? formatPrompt(templates.session, { session }) : "",
       authentication: token
         ? formatPrompt(templates.token, { token: shellQuote(token) })

package/src/components/editor/actions/pair-with-agent-modal.tsx

@@ -18,8 +18,7 @@ import { Tooltip } from "@/components/ui/tooltip";
 import { asRemoteURL, useRuntimeManager } from "@/core/runtime/config";
 import { API } from "@/core/network/api";
 import { pairPreviewAtom } from "@/core/config/pair";
-import { getSessionId } from "@/core/kernel/session";
-import { useFilename } from "@/core/saving/filename";
+import { stableSessionIdAtom } from "@/core/kernel/session";
 import {
   AGENT_LABELS,
   AGENT_TABS,
@@ -54,16 +53,14 @@ export const PairWithAgentModal: React.FC<{
   const [activeTab, setActiveTab] = useState<AgentTab>("claude");
   const runtimeManager = useRuntimeManager();
   const preview = useAtomValue(pairPreviewAtom);
-  const filename = useFilename();
+  const stableSessionId = useAtomValue(stableSessionIdAtom);
   const commandStep = preview ? 1 : 2;
   const authToken = useAuthToken();
   const hasToken = Boolean(authToken);
   const connection: ConnectionInfo = {
     url: runtimeManager.httpURL.toString(),
-    file:
-      getFileFromURL(window.location.href) ??
-      (preview ? filename || undefined : undefined),
-    session: preview ? getSessionId() : undefined,
+    file: preview ? undefined : getFileFromURL(window.location.href),
+    session: preview ? (stableSessionId ?? undefined) : undefined,
   };
 
   return (

package/src/core/config/pair.ts

@@ -7,7 +7,6 @@ export const pairPreviewSchema = z.object({
   command: z.string(),
   templates: z.object({
     prompt: z.string(),
-    file: z.string(),
     session: z.string(),
     token_file: z.string(),
     token: z.string(),

package/src/core/kernel/session.ts

@@ -1,5 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import { init } from "@paralleldrive/cuid2";
+import { atom } from "jotai";
 import { Logger } from "@/utils/Logger";
 import type { TypedString } from "@/utils/typed";
 import { updateQueryParams } from "@/utils/urls";
@@ -9,6 +10,14 @@ import { store } from "../state/jotai";
 
 export type SessionId = TypedString<"SessionId">;
 
+/**
+ * Server-owned identity of the notebook Session. It survives browser reloads
+ * and reconnects and ends with the Session.
+ */
+export type StableSessionId = TypedString<"StableSessionId">;
+
+export const stableSessionIdAtom = atom<StableSessionId | null>(null);
+
 const createId = init({ length: 6 });
 
 export function generateSessionId(): SessionId {

package/src/core/websocket/useMarimoKernelConnection.tsx

@@ -60,7 +60,11 @@ import {
   handleRemoveUIElements,
 } from "../kernel/handlers";
 import { queryParamHandlers } from "../kernel/queryParamHandlers";
-import type { SessionId } from "../kernel/session";
+import {
+  type SessionId,
+  type StableSessionId,
+  stableSessionIdAtom,
+} from "../kernel/session";
 import { initialRunCompletedAtom, kernelStateAtom } from "../kernel/state";
 import { type LayoutState, useLayoutActions } from "../layout/state";
 import { kioskModeAtom } from "../mode";
@@ -231,6 +235,7 @@ export function useMarimoKernelConnection(opts: {
     addStartupLog,
   } = useAlertActions();
   const setKioskMode = useSetAtom(kioskModeAtom);
+  const setStableSessionId = useSetAtom(stableSessionIdAtom);
   const setCapabilities = useSetAtom(capabilitiesAtom);
   const runtimeManager = useRuntimeManager();
   const transportType = useAtomValue(connectionTransportTypeAtom);
@@ -284,6 +289,10 @@ export function useMarimoKernelConnection(opts: {
           invalidateDataSourceDiscovery();
         }
         setKioskMode(msg.data.kiosk);
+        setStableSessionId(
+          (msg.data.stable_session_id as StableSessionId | null | undefined) ??
+            null,
+        );
         // A freshly started kernel has no breakpoints of its own; re-push
         // the client's set so they still apply, and clear the stale
         // highlighted line from the previous kernel instance.