@nteract/pi 0.1.1 → 0.1.4

package/README.md

@@ -1,29 +1,53 @@
 # @nteract/pi
 
-Pi extensions for running Python through the local nteract `runtimed` daemon.
-The package provides a persistent notebook-backed REPL for coding agents and
-terminal workflows that need stateful Python execution.
+**Persistent notebook-backed Python REPL for Pi coding agents.** Stateful execution, hot dependency sync, zero cold starts.
 
-## Extensions
+Run Python in a real IPython runtime. State (variables, imports, matplotlib figures) persists between agent turns. Perfect for data analysis, plotting, and multi-step workflows.
 
-- `extensions/repl.ts` registers a persistent `python` tool backed by
-  `@runtimed/node`.
-- `python_add_dependencies` records notebook UV dependencies.
-- `python_save_notebook` saves the backing notebook.
-- `/python-reset` starts a fresh notebook session.
+## What you get
+
+- **`python_repl`** — Execute Python in your persistent REPL. Backed by a real IPython runtime. Variables, imports, and state stick around between calls. The last expression is the result; use `print()` or `display()` for intermediate output. Images (matplotlib, PIL, widgets) are returned inline.
+  
+- **`python_add_dependencies`** — Install packages mid-session without restarting the kernel. Or pass `dependencies` on the first `python_repl` call to pre-install before kernel start.
+
+- **`python_save_notebook`** — Save your session as an `.ipynb` file you can open in Jupyter or nteract.
+
+- **`/python-reset`** — Start fresh: new kernel, clean slate.
 
 ## Install
 
 ```bash
-pi install npm:@nteract/pi@next
+pi install npm:@nteract/pi
 ```
 
-Use the `next` tag for prerelease builds until the package is promoted to the
-default npm tag.
+## How it works
+
+This extension uses **`@runtimed/node`**, the Node.js bindings for the nteract daemon (the same runtime that powers the nteract desktop app). If you have nteract installed, you already have everything you need. The daemon manages isolated Jupyter kernels and environments per working directory, handles dependency installation via `uv`, and keeps your Python state hot between agent calls.
+
+## Building your own
+
+This extension is a starting point. Want more control? Build your own Pi extensions using `@runtimed/node`.
+
+See [`packages/runtimed-node/README.md`](../../packages/runtimed-node/README.md) for the full API. The source for this extension ([`extensions/repl.ts`](./extensions/repl.ts)) shows how to wire it up to Pi's tool registration.
+
+### Inspecting and managing sessions
+
+The daemon is controlled by the `runt` CLI (installed with nteract). Use it to inspect active sessions, open notebooks in the desktop app, or troubleshoot:
+
+```bash
+# List active Python sessions
+runt list
+
+# Open a session in nteract Desktop
+runt show <notebook-id>
+
+# Check daemon status
+runt daemon status
+```
 
-## Local Use
+## Local development
 
-From this checkout:
+From this repo:
 
 ```bash
 pi --extension ./plugins/nteract/pi/extensions/repl.ts

package/extensions/repl.ts

@@ -7,7 +7,11 @@
  *
  * Config (env vars):
  *   NTERACT_RUNTIMED_NODE_PATH  override the runtimed-node package path.
- *   NTERACT_SOCKET_PATH         override the daemon socket path.
+ *
+ * Daemon socket selection follows the runtimed-node contract:
+ * `RUNTIMED_SOCKET_PATH` overrides outright, `RUNTIMED_WORKSPACE_PATH` (or
+ * `RUNTIMED_DEV=1` plus a git checkout) selects the per-worktree dev daemon,
+ * otherwise the running channel is auto-detected.
  *
  * After editing, run `/reload` in pi.
  */
@@ -25,16 +29,19 @@ import { Type } from "typebox";
 
 type RuntimedNode = {
   defaultSocketPath(): string;
-  socketPathForChannel(channel: "stable" | "nightly"): string;
+  PackageManager?: { Uv: "uv"; Conda: "conda"; Pixi: "pixi" };
   createNotebook(opts?: {
     runtime?: string;
     workingDir?: string;
     socketPath?: string;
     peerLabel?: string;
+    description?: string;
+    dependencies?: string[];
+    packageManager?: "uv" | "conda" | "pixi";
   }): Promise<Session>;
   openNotebook(
     notebookId: string,
-    opts?: { socketPath?: string; peerLabel?: string },
+    opts?: { socketPath?: string; peerLabel?: string; description?: string },
   ): Promise<Session>;
   readParquetFile(
     filePath: string,
@@ -68,18 +75,44 @@ type JsOutput = {
 
 type CellResult = {
   cellId: string;
+  executionId: string;
   executionCount?: number;
   status: string; // "done" | "error" | "timeout" | "kernel_error"
   success: boolean;
-  outputs: JsOutput[];
+  outputs?: JsOutput[];
+};
+
+type QueuedExecution = {
+  cellId: string;
+  executionId: string;
 };
 
 type Session = {
   readonly notebookId: string;
-  runCell(source: string, opts?: { timeoutMs?: number; cellType?: string }): Promise<CellResult>;
-  addUvDependency(pkg: string): Promise<void>;
+  runCell(
+    source: string,
+    opts?: { timeoutMs?: number; cellType?: string; onUpdate?: (progress: CellResult) => void },
+  ): Promise<CellResult>;
+  queueCell(source: string, opts?: { cellType?: string }): Promise<QueuedExecution>;
+  waitForExecution(
+    executionId: string,
+    opts?: { timeoutMs?: number; cellId?: string; onUpdate?: (progress: CellResult) => void },
+  ): Promise<CellResult>;
+  addUvDependency?(pkg: string): Promise<void>;
+  addDependencies?(
+    packages: string[],
+    opts?: { packageManager?: "uv" | "conda" | "pixi" },
+  ): Promise<void>;
+  getDependencyStatus?(): Promise<{ uv?: { dependencies: string[] }; fingerprint?: string }>;
+  getRuntimeStatus?(): Promise<{
+    status: string;
+    lifecycle: string;
+    errorReason?: string;
+    errorDetails?: string;
+  }>;
   syncEnvironment(): Promise<void>;
   saveNotebook(path?: string): Promise<void>;
+  shutdownNotebook?(): Promise<boolean>;
   close(): Promise<void>;
 };
 
@@ -105,15 +138,42 @@ function loadRuntimedNode(): RuntimedNode | null {
   return null;
 }
 
-function resolveSocketPath(rn: RuntimedNode): string {
-  if (process.env.NTERACT_SOCKET_PATH) return process.env.NTERACT_SOCKET_PATH;
+// --- bootstrap detection -----------------------------------------------------
+
+const INSTALL_HINT =
+  "The nteract daemon (runtimed) isn't installed yet.\n" +
+  "Quick install:  curl -fsSL https://sh.nteract.io | bash\n" +
+  "Or visit:       https://nteract.io";
 
-  for (const channel of ["nightly", "stable"] as const) {
-    const socketPath = rn.socketPathForChannel(channel);
-    if (existsSync(socketPath)) return socketPath;
+type BootstrapStatus =
+  | { kind: "ready"; rn: RuntimedNode }
+  | { kind: "missing"; reason: "binding" | "daemon" };
+
+function findOnPath(cmd: string): string | undefined {
+  const dirs = (process.env.PATH ?? "").split(path.delimiter);
+  for (const dir of dirs) {
+    if (!dir) continue;
+    const candidate = path.join(dir, cmd);
+    if (existsSync(candidate)) return candidate;
   }
+  return undefined;
+}
 
-  return rn.defaultSocketPath();
+function detectBootstrap(): BootstrapStatus {
+  const rn = loadRuntimedNode();
+  if (!rn) return { kind: "missing", reason: "binding" };
+  // defaultSocketPath() already honors RUNTIMED_SOCKET_PATH and the dev /
+  // worktree-aware resolution from runt-workspace, so this is the single point
+  // of truth. The socket file only exists while the daemon is running, but the
+  // parent cache dir survives shutdowns, so dir-existence covers "installed
+  // but stopped".
+  const socket = rn.defaultSocketPath();
+  const installed =
+    existsSync(socket) ||
+    existsSync(path.dirname(socket)) ||
+    Boolean(findOnPath("runt")) ||
+    Boolean(findOnPath("runt-nightly"));
+  return installed ? { kind: "ready", rn } : { kind: "missing", reason: "daemon" };
 }
 
 // --- DataTable TUI component --------------------------------------------------
@@ -148,6 +208,63 @@ function formatStat(stats: ColumnStats | null): string {
   }
 }
 
+const SPARK_CHARS = "▁▂▃▄▅▆▇█";
+
+function sparkline(values: number[], width: number): string {
+  if (values.length === 0 || width <= 0) return "";
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const bins = new Array(Math.min(width, 8)).fill(0);
+  if (min === max) {
+    return SPARK_CHARS[3].repeat(bins.length);
+  }
+  const range = max - min;
+  for (const v of values) {
+    const bi = Math.min(Math.floor(((v - min) / range) * bins.length), bins.length - 1);
+    bins[bi]++;
+  }
+  const maxCount = Math.max(...bins);
+  return bins
+    .map(
+      (c) =>
+        SPARK_CHARS[maxCount === 0 ? 0 : Math.round((c / maxCount) * (SPARK_CHARS.length - 1))],
+    )
+    .join("");
+}
+
+function sparklineForColumn(
+  rows: string[][],
+  ci: number,
+  stats: ColumnStats | null,
+  colType: string,
+  width: number,
+): string {
+  if (stats?.kind === "boolean") {
+    const t = stats.true_count ?? 0;
+    const f = stats.false_count ?? 0;
+    const total = t + f;
+    if (total === 0) return "";
+    const barW = Math.min(width, 8);
+    const filled = Math.round((t / total) * barW);
+    return (
+      SPARK_CHARS[SPARK_CHARS.length - 1].repeat(filled) + SPARK_CHARS[0].repeat(barW - filled)
+    );
+  }
+  if (stats?.kind === "numeric" || /int|float|decimal|uint/.test(colType)) {
+    const nums: number[] = [];
+    for (const row of rows) {
+      const n = parseFloat(row[ci]);
+      if (!isNaN(n)) nums.push(n);
+    }
+    return sparkline(nums, width);
+  }
+  if (stats?.kind === "string" && stats.top && stats.top.length > 0) {
+    const counts = stats.top.map(([, c]) => c);
+    return sparkline(counts, Math.min(width, counts.length));
+  }
+  return "";
+}
+
 class DataTable {
   private columns: string[];
   private rows: string[][];
@@ -189,11 +306,12 @@ class DataTable {
     }
 
     const t = this.theme;
-    const numCols = this.columns.length;
     const numRows = this.rows.length;
+    const totalCols = this.columns.length;
+    const MIN_COL_W = 6;
 
-    // Calculate column widths: max of header, type, stat, and data
-    const colWidths = this.columns.map((col, ci) => {
+    // Calculate natural column widths: max of header, type, stat, and data
+    const naturalWidths = this.columns.map((col, ci) => {
       let w = col.length;
       w = Math.max(w, (this.colTypes[ci] ?? "").length);
       const statStr = formatStat(this.colStats[ci] ?? null);
@@ -204,14 +322,35 @@ class DataTable {
       return w;
     });
 
-    // Clamp total width — shrink columns proportionally if needed
-    const borderOverhead = 1 + numCols * 3; // "│ " + " │ " * (n-1) + " │"
+    // Greedily fit columns left-to-right within the available width.
+    // Each column costs its width + 3 chars of border ("│ " + " │").
+    let budget = width - 1; // leading "│"
+    let visibleCount = 0;
+    for (let i = 0; i < totalCols; i++) {
+      const colCost = Math.max(naturalWidths[i], MIN_COL_W) + 3;
+      if (budget - colCost < 0 && visibleCount > 0) break;
+      budget -= colCost;
+      visibleCount++;
+    }
+    visibleCount = Math.max(1, visibleCount);
+    const hiddenCols = totalCols - visibleCount;
+
+    // Slice to visible columns
+    const columns = this.columns.slice(0, visibleCount);
+    const colTypes = this.colTypes.slice(0, visibleCount);
+    const colStats = this.colStats.slice(0, visibleCount);
+    const rows = this.rows.map((r) => r.slice(0, visibleCount));
+    const numCols = columns.length;
+    const colWidths = naturalWidths.slice(0, visibleCount);
+
+    // Shrink proportionally only if still over budget after column pruning
+    const borderOverhead = 1 + numCols * 3;
     const totalColWidth = colWidths.reduce((a, b) => a + b, 0);
     const availableForCols = width - borderOverhead;
     if (totalColWidth > availableForCols && availableForCols > numCols) {
       const ratio = availableForCols / totalColWidth;
       for (let i = 0; i < numCols; i++) {
-        colWidths[i] = Math.max(3, Math.floor(colWidths[i] * ratio));
+        colWidths[i] = Math.max(MIN_COL_W, Math.floor(colWidths[i] * ratio));
       }
     }
 
@@ -226,7 +365,7 @@ class DataTable {
     };
 
     // Detect numeric columns for right-alignment
-    const isNumeric = this.colTypes.map((dt) => /int|float|decimal|uint/.test(dt));
+    const isNumeric = colTypes.map((dt) => /int|float|decimal|uint/.test(dt));
 
     const align = (s: string, ci: number, w: number) => (isNumeric[ci] ? rpad(s, w) : pad(s, w));
 
@@ -237,21 +376,28 @@ class DataTable {
     lines.push(topBorder);
 
     // ── Column headers ──
-    const headerCells = this.columns.map((col, ci) =>
-      t.fg("accent", t.bold(pad(col, colWidths[ci]))),
-    );
+    const headerCells = columns.map((col, ci) => t.fg("accent", t.bold(pad(col, colWidths[ci]))));
     lines.push(
       t.fg("muted", "│") + " " + headerCells.join(t.fg("muted", " │ ")) + " " + t.fg("muted", "│"),
     );
 
     // ── Type row ──
-    const typeCells = this.colTypes.map((dt, ci) => t.fg("dim", pad(dt, colWidths[ci])));
+    const typeCells = colTypes.map((dt, ci) => t.fg("dim", pad(dt, colWidths[ci])));
     lines.push(
       t.fg("muted", "│") + " " + typeCells.join(t.fg("muted", " │ ")) + " " + t.fg("muted", "│"),
     );
 
-    // ── Stats row (sparkline or range) ──
-    const statCells = this.colStats.map((stats, ci) => {
+    // ── Sparkline row ──
+    const sparkCells = colStats.map((stats, ci) => {
+      const spark = sparklineForColumn(rows, ci, stats, colTypes[ci] ?? "", colWidths[ci]);
+      return t.fg("dim", pad(spark, colWidths[ci]));
+    });
+    lines.push(
+      t.fg("muted", "│") + " " + sparkCells.join(t.fg("muted", " │ ")) + " " + t.fg("muted", "│"),
+    );
+
+    // ── Stats row ──
+    const statCells = colStats.map((stats, ci) => {
       const statStr = formatStat(stats);
       return t.fg("dim", pad(statStr, colWidths[ci]));
     });
@@ -265,7 +411,7 @@ class DataTable {
 
     // ── Data rows ──
     for (let r = 0; r < numRows; r++) {
-      const row = this.rows[r];
+      const row = rows[r];
       const cells = row.map((v, ci) => align(v, ci, colWidths[ci]));
       const rowStr =
         t.fg("muted", "│") + " " + cells.join(t.fg("muted", " │ ")) + " " + t.fg("muted", "│");
@@ -277,8 +423,12 @@ class DataTable {
     lines.push(botBorder);
 
     // ── Footer info ──
-    const showing = numRows < this.totalRows ? `showing ${numRows} of ` : "";
-    const info = t.fg("dim", `${showing}${this.totalRows} rows × ${numCols} columns`);
+    const showingRows = numRows < this.totalRows ? `showing ${numRows} of ` : "";
+    const hiddenSuffix = hiddenCols > 0 ? ` (${hiddenCols} more columns)` : "";
+    const info = t.fg(
+      "dim",
+      `${showingRows}${this.totalRows} rows × ${totalCols} columns${hiddenSuffix}`,
+    );
     lines.push(info);
 
     // Indent all lines to align with Out[n]: prompt
@@ -304,16 +454,18 @@ function formatResult(result: CellResult): {
   content: (TextContent | ImageContent)[];
   isError: boolean;
 } {
+  const outputs = result.outputs ?? [];
   const isError =
     result.status === "error" ||
     result.status === "kernel_error" ||
-    result.outputs.some((o) => o.outputType === "error");
+    result.status === "kernel_failed" ||
+    outputs.some((o) => o.outputType === "error");
 
   const parts: (TextContent | ImageContent)[] = [];
   const header = `cell ${result.cellId} [${result.executionCount ?? "?"}] ${result.status}`;
   const textChunks: string[] = [];
 
-  for (const o of result.outputs) {
+  for (const o of outputs) {
     switch (o.outputType) {
       case "stream": {
         const prefix = o.name === "stderr" ? "[stderr] " : "";
@@ -381,13 +533,41 @@ function formatResult(result: CellResult): {
   return { content: parts, isError };
 }
 
+function findParquetBlobPath(result: CellResult): string | undefined {
+  for (const o of result.outputs ?? []) {
+    if (!o.blobPathsJson) continue;
+    try {
+      const paths = JSON.parse(o.blobPathsJson);
+      const pqPath = paths["application/vnd.apache.parquet"];
+      if (typeof pqPath === "string") return pqPath;
+    } catch {}
+  }
+  return undefined;
+}
+
 // --- extension ---------------------------------------------------------------
 
+// Braille frames for the "waiting on first token" spinner shown in `In [*]:`
+// before any input_json_delta arrives. Anthropic validates the JSON server-side,
+// so the gap between toolcall_start and the first delta can be hundreds of ms.
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 80;
+
+type InCallState = {
+  spinner?: { frame: number; timer: ReturnType<typeof setInterval> };
+};
+
 const PYTHON_PARAMS = Type.Object({
   code: Type.String({
     description:
       "Python source to execute in the persistent notebook session. Use print(...) for side effects; the last expression's repr is returned as the result.",
   }),
+  dependencies: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Packages to add before executing this code. On the first call they are recorded before the kernel starts; on later calls they are hot-synced into the running environment.",
+    }),
+  ),
   timeout_secs: Type.Optional(
     Type.Number({
       description: "Max seconds to wait for execution (default 120).",
@@ -397,25 +577,76 @@ const PYTHON_PARAMS = Type.Object({
 });
 
 export default function nteractReplExtension(pi: ExtensionAPI) {
-  const rn = loadRuntimedNode();
-  if (!rn) {
-    console.error("[nteract-repl] runtimed-node not loaded; python tool will not be registered.");
+  const bootstrap = detectBootstrap();
+  if (bootstrap.kind === "missing") {
+    // Surface a one-liner toast each session so the user sees the hint without
+    // having to invoke the tool first.
+    pi.on("session_start", async (_event, ctx) => {
+      ctx.ui.notify(INSTALL_HINT, "warning");
+    });
+    // Register python_repl with a stub execute() so the LLM can still advertise
+    // the capability and surface install guidance the moment it tries to run
+    // Python. Throwing routes the message into the tool-result channel that the
+    // model relays back to the user.
+    pi.registerTool({
+      name: "python_repl",
+      label: "Python REPL",
+      description:
+        "Execute Python in your persistent REPL. Requires the nteract daemon (runtimed). " +
+        "If unavailable, recommend the user install with `curl -fsSL https://sh.nteract.io | bash` " +
+        "or download the desktop app at https://nteract.io.",
+      promptSnippet:
+        "python_repl: requires the nteract daemon. Install with `curl -fsSL https://sh.nteract.io | bash` or via https://nteract.io.",
+      parameters: PYTHON_PARAMS,
+      async execute() {
+        throw new Error(INSTALL_HINT);
+      },
+    });
     return;
   }
+  const rn = bootstrap.rn;
 
   let session: Session | null = null;
   let opening: Promise<Session> | null = null;
   let nextExecCount: number | null = 1;
 
-  async function ensureSession(): Promise<Session> {
-    if (session) return session;
-    if (opening) return opening;
+  async function addDependenciesAndSync(sess: Session, packages: string[]): Promise<void> {
+    const unique = Array.from(new Set(packages.map((pkg) => pkg.trim()).filter(Boolean)));
+    if (!unique.length) return;
+    if (sess.addDependencies) {
+      await sess.addDependencies(unique);
+    } else if (sess.addUvDependency) {
+      for (const pkg of unique) {
+        await sess.addUvDependency(pkg);
+      }
+    } else {
+      throw new Error("@runtimed/node Session does not support dependency edits");
+    }
+    await sess.syncEnvironment();
+  }
+
+  async function ensureSession(initialDependencies: string[] = []): Promise<Session> {
+    const dependencies = Array.from(
+      new Set(initialDependencies.map((pkg) => pkg.trim()).filter(Boolean)),
+    );
+    if (session) {
+      await addDependenciesAndSync(session, dependencies);
+      return session;
+    }
+    if (opening) {
+      const opened = await opening;
+      await addDependenciesAndSync(opened, dependencies);
+      return opened;
+    }
     opening = (async () => {
-      const socketPath = resolveSocketPath(rn);
+      // Omit socketPath so the binding resolves through defaultSocketPath(),
+      // which honors RUNTIMED_SOCKET_PATH / RUNTIMED_WORKSPACE_PATH and the
+      // channel auto-detect.
       session = await rn.createNotebook({
         runtime: "python",
-        socketPath,
         peerLabel: "pi",
+        description: "pi Python REPL",
+        dependencies,
       });
       return session;
     })();
@@ -426,28 +657,59 @@ export default function nteractReplExtension(pi: ExtensionAPI) {
     }
   }
 
-  pi.registerTool({
-    name: "python",
-    label: "Python (nteract)",
+  pi.registerTool<typeof PYTHON_PARAMS, unknown, InCallState>({
+    name: "python_repl",
+    label: "Python REPL",
     description:
-      "Execute Python in a persistent nteract notebook session backed by the local runtimed daemon. State (variables, imports) persists across calls within this pi session. Stdout, the final expression value, and exceptions are returned as text. Images (matplotlib.show(), IPython.display.Image, etc.) are returned inline so you can see them.",
+      "Execute Python in your persistent REPL. Backed by a real IPython runtime. Variables, imports, and state stick around between calls. The last expression is the result; use print() or display() for intermediate output. Images (matplotlib, PIL, widgets) are returned inline.",
     promptSnippet:
-      "python: run Python code against a persistent nteract kernel (state persists across calls; stdout + last-expr value + any images are returned).",
+      "python_repl: run Python in your persistent REPL (variables and imports persist; returns stdout + last expression + images).",
     promptGuidelines: [
-      "Prefer `python` over `bash python -c ...` for anything stateful, multi-step, or data-heavy.",
-      "State (imports, variables) persists across `python` calls in this session.",
-      "Use print() for side-effect output; the last expression is echoed back as the result.",
-      "Matplotlib / PIL images are returned inline — you can iterate on plots by looking at them.",
-      "Install packages with the `python_add_dependencies` tool (it uses the notebook's UV env and hot-reloads without restarting the kernel).",
+      "Use `python_repl` for data analysis, plotting, and multi-step workflows. State persists between calls in a real IPython runtime.",
+      "Variables and imports stick around. No need to re-import or redefine on every turn unless the user has reloaded the session.",
+      "The last expression is the result; use print() or display() for intermediate output.",
+      "Images (matplotlib, PIL, widgets) come back inline. The user sees them if their terminal supports graphics.",
+      "Pass `dependencies` on the first call to pre-install packages before the kernel starts.",
+      "Use `python_add_dependencies` to install packages mid-session without restarting the kernel.",
     ],
     parameters: PYTHON_PARAMS,
     renderCall(args, theme, _context) {
       const text =
         (_context.lastComponent as InstanceType<typeof Text> | undefined) ?? new Text("", 0, 0);
-      const code = args?.code ?? "";
+      const code = (args?.code ?? "").replace(/^\n+/, "");
       const count = nextExecCount;
       const prompt = count != null ? `In [${count}]:` : "In [*]:";
       const promptStr = theme.fg("accent", theme.bold(prompt));
+
+      // Anthropic gates input_json_delta on server-side validation, so there is
+      // a visible pause between toolcall_start and the first token of `code`.
+      // Show a braille spinner in the prompt slot until either the first
+      // character streams in or the call resolves another way.
+      const state = _context.state as InCallState;
+      const waitingForFirstToken =
+        !code && !_context.executionStarted && !_context.argsComplete && !_context.isError;
+      if (waitingForFirstToken) {
+        if (!state.spinner) {
+          const timer = setInterval(() => {
+            const s = state.spinner;
+            if (!s) return;
+            s.frame = (s.frame + 1) % SPINNER_FRAMES.length;
+            _context.invalidate();
+          }, SPINNER_INTERVAL_MS);
+          // Don't keep the event loop alive on the spinner alone.
+          timer.unref?.();
+          state.spinner = { frame: 0, timer };
+        }
+        const frame = SPINNER_FRAMES[state.spinner.frame];
+        text.setText(`${promptStr} ${theme.fg("muted", frame)}`);
+        return text;
+      }
+
+      if (state.spinner) {
+        clearInterval(state.spinner.timer);
+        state.spinner = undefined;
+      }
+
       const lines = highlightCode(code, "python");
       // Indent continuation lines to align with first line after prompt
       const pad = " ".repeat(prompt.length + 1);
@@ -506,8 +768,14 @@ export default function nteractReplExtension(pi: ExtensionAPI) {
             const text =
               (_context.lastComponent instanceof Text ? _context.lastComponent : undefined) ??
               new Text("", 0, 0);
-            const tableLines = dt.render(200);
-            text.setText(`${promptStr}\n${tableLines.join("\n")}`);
+            const termWidth = process.stdout.columns || 120;
+            const tableLines = dt.render(termWidth - indent);
+            // Put first table line on the Out[n]: line instead of below it
+            const indentStr = " ".repeat(indent);
+            if (tableLines.length > 0 && tableLines[0].startsWith(indentStr)) {
+              tableLines[0] = `${promptStr} ${tableLines[0].slice(indent)}`;
+            }
+            text.setText(tableLines.join("\n"));
             return text;
           }
         } catch {}
@@ -519,8 +787,8 @@ export default function nteractReplExtension(pi: ExtensionAPI) {
         .map((c: any) => c.text)
         .join("\n");
 
-      // Strip the "cell cell-xxx [n] status" header we put in the text content
-      const body = textContent.replace(/^cell cell-[^\n]*\n?/, "").trim();
+      // Strip the "cell <id> [n] status" header we put in the text content
+      const body = textContent.replace(/^cell \S* \[[^\]]*\] \S*\n?/, "").trim();
 
       const text =
         (_context.lastComponent instanceof Text ? _context.lastComponent : undefined) ??
@@ -543,26 +811,31 @@ export default function nteractReplExtension(pi: ExtensionAPI) {
       }
       return text;
     },
-    async execute(_toolCallId, params, signal) {
+    async execute(_toolCallId, params, signal, onUpdate) {
       if (signal?.aborted) throw new Error("aborted");
-      const sess = await ensureSession();
+      const sess = await ensureSession(params.dependencies ?? []);
       const timeoutSecs = Math.max(1, params.timeout_secs ?? 120);
       const result = await sess.runCell(params.code, {
         timeoutMs: Math.round(timeoutSecs * 1000),
+        onUpdate: (progress) => {
+          const { content, isError } = formatResult(progress);
+          onUpdate?.({
+            content,
+            details: {
+              notebook_id: sess.notebookId,
+              cell_id: progress.cellId,
+              execution_id: progress.executionId,
+              status: progress.status,
+              execution_count: progress.executionCount,
+              is_error: isError,
+              parquet_blob_path: findParquetBlobPath(progress),
+              streaming: true,
+            },
+          });
+        },
       });
       // Extract parquet blob path for human-side table rendering
-      let parquetBlobPath: string | undefined;
-      for (const o of result.outputs) {
-        if (!o.blobPathsJson) continue;
-        try {
-          const paths = JSON.parse(o.blobPathsJson);
-          const pqPath = paths["application/vnd.apache.parquet"];
-          if (typeof pqPath === "string") {
-            parquetBlobPath = pqPath;
-            break;
-          }
-        } catch {}
-      }
+      const parquetBlobPath = findParquetBlobPath(result);
 
       const { content, isError } = formatResult(result);
       return {
@@ -570,10 +843,14 @@ export default function nteractReplExtension(pi: ExtensionAPI) {
         details: {
           notebook_id: sess.notebookId,
           cell_id: result.cellId,
+          execution_id: result.executionId,
           status: result.status,
           execution_count: result.executionCount,
           is_error: isError,
           parquet_blob_path: parquetBlobPath,
+          runtime: sess.getRuntimeStatus
+            ? await sess.getRuntimeStatus().catch(() => undefined)
+            : undefined,
         },
       };
     },
@@ -581,11 +858,11 @@ export default function nteractReplExtension(pi: ExtensionAPI) {
 
   pi.registerTool({
     name: "python_add_dependencies",
-    label: "Add Dependencies (nteract)",
+    label: "Add Dependencies",
     description:
-      "Add packages to the current nteract notebook's UV environment and hot-sync them so the running kernel can import them immediately. Accepts pip-style specs, e.g. 'matplotlib', 'numpy>=2', 'requests'.",
+      "Install packages into the running Python environment without restarting. Accepts pip-style specs like 'matplotlib', 'numpy>=2', 'requests'. The kernel stays hot.",
     promptSnippet:
-      "python_add_dependencies: add packages to the persistent Python notebook env (hot-installs without restarting the kernel).",
+      "python_add_dependencies: install packages into the running Python session (no restart needed).",
     parameters: Type.Object({
       packages: Type.Array(Type.String(), {
         description: "Package specs (e.g. ['matplotlib', 'pandas>=2']).",
@@ -597,10 +874,7 @@ export default function nteractReplExtension(pi: ExtensionAPI) {
         return { content: [{ type: "text", text: "No packages given." }], details: {} };
       }
       const sess = await ensureSession();
-      for (const pkg of params.packages) {
-        await sess.addUvDependency(pkg);
-      }
-      await sess.syncEnvironment();
+      await addDependenciesAndSync(sess, params.packages);
       return {
         content: [
           {
@@ -615,10 +889,10 @@ export default function nteractReplExtension(pi: ExtensionAPI) {
 
   pi.registerTool({
     name: "python_save_notebook",
-    label: "Save Notebook (nteract)",
+    label: "Save Notebook",
     description:
-      "Save the current nteract notebook to an .ipynb file on disk. If no path is given, saves to the original location (if it was opened from a file). Provide a path to save to a new location.",
-    promptSnippet: "python_save_notebook: save the current notebook session to an .ipynb file.",
+      "Save the current Python session as an .ipynb file. If no path is given, saves to the original location (if it was opened from a file). Provide a path to save elsewhere.",
+    promptSnippet: "python_save_notebook: save the current session as an .ipynb file.",
     parameters: Type.Object({
       path: Type.Optional(
         Type.String({
@@ -641,18 +915,22 @@ export default function nteractReplExtension(pi: ExtensionAPI) {
 
   pi.registerCommand("python-reset", {
     description:
-      "Start a fresh nteract Python notebook session (next /python call opens a new kernel)",
+      "Start fresh: next /python_repl call opens a new kernel (clean slate, no prior variables or imports)",
     handler: async (_args, ctx) => {
       const old = session;
       session = null;
       nextExecCount = 1;
       if (old) {
         try {
-          await old.close();
+          if (old.shutdownNotebook) {
+            await old.shutdownNotebook();
+          } else {
+            await old.close();
+          }
         } catch {}
       }
       ctx.ui.notify(
-        "nteract REPL: session closed; next python call will start a fresh kernel.",
+        "Python session closed. Next python_repl call will start a fresh kernel.",
         "info",
       );
     },
@@ -661,7 +939,11 @@ export default function nteractReplExtension(pi: ExtensionAPI) {
   pi.on("session_shutdown", async () => {
     if (session) {
       try {
-        await session.close();
+        if (session.shutdownNotebook) {
+          await session.shutdownNotebook();
+        } else {
+          await session.close();
+        }
       } catch {}
       session = null;
     }

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@nteract/pi",
-  "version": "0.1.1",
-  "description": "Pi extensions that run Python through the local nteract runtimed daemon.",
+  "version": "0.1.4",
+  "description": "Persistent notebook-backed Python REPL for Pi coding agents. Stateful execution, hot dependency sync, zero cold starts.",
+  "author": "nteract contributors",
+  "icon": "icon.png",
   "type": "module",
   "license": "BSD-3-Clause",
   "repository": {
@@ -30,10 +32,11 @@
   },
   "files": [
     "README.md",
+    "icon.png",
     "extensions"
   ],
   "dependencies": {
-    "@runtimed/node": "0.1.1"
+    "@runtimed/node": "0.2.2"
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
@@ -43,6 +46,10 @@
   "publishConfig": {
     "access": "public"
   },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "@mariozechner/pi-tui": "^0.73.0"
+  },
   "scripts": {
     "pack:dry-run": "pnpm pack --dry-run"
   }