pi-repl-py 0.6.11 → 0.6.13

package/docs/ARCHITECTURE.md

@@ -102,6 +102,14 @@ backstop for cells wedged in C code (which ignore interrupts), the engine gives
 cell up to 20 seconds to settle and keeps the kernel if it does; only a cell that is still
 running after that grace is killed, and the next call rebuilds from the last snapshot.
 
+**History is off.** Every execute goes out with `store_history: false`. IPython's `In`/`Out`
+retention keeps every last-expression result object alive in the kernel, and that retention
+cannot be reclaimed from a user cell — deleting `Out` and `_`/`__`/`___` from `user_ns`
+followed by `gc.collect()` leaves the objects alive (measured: 62 MB idle grows past 400 MB
+after two bare big results and never comes back). Disabling history bounds the kernel to at
+most the latest result. The transcript is the record instead, and results still publish over
+iopub: single-mode execution calls `sys.displayhook` regardless of `store_history`.
+
 ## Helpers loading
 
 At boot, the kernel and the host both read the same merged helper list (project
@@ -144,11 +152,15 @@ pickle cannot revive them, since they live in `__main__`). Bindings that still f
 handles, open resources, source-less functions — are reported by name, never dropped silently.
 Entries are capped per-binding and in total (128 MiB default), and the snapshot file is written
 via temp-file-and-rename so a crash cannot corrupt the last good copy; old session snapshot
-directories are pruned to the newest 25. If the evaluator was rebuilt mid-session, the next
+directories are pruned to the newest 25, and snapshot dirs whose owning conversation file no
+longer exists in any project session root are swept entirely (deleting a conversation deletes
+its snapshots with it). "ephemeral" and the live session are always exempt. If the evaluator was rebuilt mid-session, the next
 cell's result is prefixed with a `<repl_engine_reset>` block that names what was revived and
-what was lost, so the model re-verifies before reusing state that may be gone. A resumed
-conversation announces the same block on its first cell, but only when the conversation has a
-saved past; a first-ever session starts quiet.
+what was lost, so the model re-verifies before reusing state that may be gone. The human gets
+only a terse `ui.notify` toast ("repl kernel rebuilt, 3 names revived") instead of the marker;
+the two are derived from the same restore result, so they never disagree. A resumed
+conversation announces the same pair on its first cell, but only when the conversation has a
+saved past; a first-ever session stays quiet.
 
 ## Failure modes
 
@@ -193,6 +205,14 @@ global one and both sides are guaranteed to agree. The venv is built automatical
 interpreter follows the order above. No setting is needed. The per-cell silence watchdog is
 off by default (`PI_REPL_TIMEOUT_MS=0`: a silent but working cell may run on).
 
+The boot itself is bounded regardless: kernel start, helpers preload, and snapshot restore are
+kernel cells with no deadline of their own, and `acquire()` dedupes, so one wedged boot (an npm
+update swapping the venv under a live kernel, a snapshot value whose unpickling never returns)
+would hang the first cell and every cell after it. The lifecycle races each boot attempt against
+`PI_REPL_BOOT_TIMEOUT_MS` (default 90s): a wedged attempt is killed and retried once with the
+snapshot deliberately skipped, landing on an honest "wedged while reviving; skipped" notice; a
+second wedge fails the cell loudly instead of hanging.
+
 ## Reference documentation
 
 - Design rationale: [design.md](design.md)

package/index.ts

@@ -5,9 +5,9 @@ import { homedir } from "node:os";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import { withSkillsBlock } from "./src/extension/skill-hook.js";
-import { EngineManager, pruneSnapshotDirs } from "./src/engine/index.js";
+import { EngineManager, pruneOrphanedSnapshotDirs, pruneSnapshotDirs } from "./src/engine/index.js";
 import { ExecuteCellComponent, type ExecuteDetails, type ExecuteRenderState } from "./src/extension/render.js";
-import { EngineLifecycle } from "./src/extension/session-engine.js";
+import { EngineLifecycle, formatResetToast } from "./src/extension/session-engine.js";
 import { EXECUTE_DESCRIPTION, buildExecutePromptGuidelines, EXECUTE_PROMPT_SNIPPET } from "./src/extension/tool-meta.js";
 
 const executeSchema = Type.Object({
@@ -58,6 +58,11 @@ export default function (pi: ExtensionAPI) {
 	const pendingErrorResults = new Map<string, { details: ExecuteDetails }>();
 
 	const lifecycle = new EngineLifecycle<EngineManager>({
+		// --- boot deadline: bounds kernel start + helpers preload + snapshot restore. An npm
+		// --- update swaps the venv and helpers under a live kernel, and the first boot after
+		// --- it can wedge (poisoned pickle, half-built venv); without this the first cell
+		// --- hangs forever, because acquire() dedupes onto the same hung boot. ---
+		bootTimeoutMs: Number(process.env.PI_REPL_BOOT_TIMEOUT_MS ?? 90_000) || 90_000,
 		create() {
 			const { cwd, sessionFile } = location;
 			const sessionKey = sessionFile ? basename(sessionFile).replace(/\.jsonl$/, "") : undefined;
@@ -68,6 +73,13 @@ export default function (pi: ExtensionAPI) {
 				try {
 					pruneSnapshotDirs(join(stateDir, ".."), 25, sessionKey);
 				} catch {}
+				// --- cascade deletions: if a conversation is deleted, its snapshots die with it.
+				// --- sessionFile is sessions/<project-root>/<name>.jsonl, so the sessions root is
+				// --- two parent hops up; dirs whose conversation file exists in no project root
+				// --- (and that aren't this session or the ephemeral fallback) are swept. ---
+				try {
+					pruneOrphanedSnapshotDirs(join(stateDir, ".."), sessionFile ? dirname(dirname(sessionFile)) : undefined, sessionKey);
+				} catch {}
 			}
 			return new EngineManager({
 				cwd,
@@ -174,8 +186,11 @@ export default function (pi: ExtensionAPI) {
 						onUpdate?.({ content: [{ type: "text", text: streamed }], details: {} });
 					},
 				});
-				// --- reset notice leads so the model reads that its namespace was rebuilt ---
-				const sections = [lifecycle.takeResetNotice(), r.stdout, r.stderr, r.result];
+				// --- reset notice leads so the model reads that its namespace was rebuilt; the
+				// --- human gets a terse notification instead of the marker, fire and forget ---
+				const reset = lifecycle.takeResetNotice();
+				if (reset?.notice) ctx?.ui?.notify?.(formatResetToast(reset.origin, reset.restore), "info");
+				const sections = [reset?.notice, r.stdout, r.stderr, r.result];
 				const errorLines = r.error ? composeErrorLines(r.error) : undefined;
 				if (r.status === "error" && errorLines) sections.push(errorLines.join("\n"));
 				if (r.status === "aborted") sections.push("[cell aborted]");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.6.11",
+	"version": "0.6.13",
 	"type": "module",
 	"description": "A pi extension with a single tool: execute, running a TypeScript host with a persistent Python (ipykernel) evaluator and a user-configurable toolbox of functions.",
 	"keywords": [

package/src/engine/index.ts

@@ -141,6 +141,44 @@ export function pruneSnapshotDirs(stateRoot: string, keep: number = DEFAULT_KEEP
 	}
 }
 
+// --- Orphaned-snapshot sweep: snapshot dirs are keyed by conversation file basename, so when
+// --- an owning conversation is deleted (pi removes the .jsonl), its directory becomes dead
+// --- weight. This drops any state dir whose conversation file exists in NONE of the project
+// --- session roots, so deleting a conversation deletes its snapshots with it. Safety rules:
+// --- only dirs that look like ours (contain a namespace.snapshot manifest) are touched, and
+// --- the live session plus the no-session "ephemeral" fallback dir are always exempt. ---
+export function pruneOrphanedSnapshotDirs(
+	stateRoot: string,
+	sessionsRoot: string | undefined,
+	currentDir?: string,
+): number {
+	if (!sessionsRoot || !existsSync(sessionsRoot)) return 0;
+	const liveNames = new Set<string>();
+	try {
+		for (const proj of readdirSync(sessionsRoot, { withFileTypes: true })) {
+			if (!proj.isDirectory()) continue;
+			for (const f of readdirSync(join(sessionsRoot, proj.name))) {
+				if (f.endsWith(".jsonl")) liveNames.add(f.slice(0, -".jsonl".length));
+			}
+		}
+	} catch {
+		return 0;
+	}
+	let removed = 0;
+	try {
+		for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
+			if (!entry.isDirectory() || entry.name === currentDir || entry.name === "ephemeral") continue;
+			if (liveNames.has(entry.name)) continue;
+			if (!existsSync(join(stateRoot, entry.name, "namespace.snapshot"))) continue;
+			rmSync(join(stateRoot, entry.name), { recursive: true, force: true });
+			removed++;
+		}
+	} catch {
+		// readdir can race a concurrent sweep; give up quietly rather than partial-delete
+	}
+	return removed;
+}
+
 export class EngineManager {
 	private readonly options: EngineOptions;
 	private kernel?: KernelClient;
@@ -349,11 +387,15 @@ export class EngineManager {
 		}
 	}
 
-	async restoreState(): Promise<RestoreResult | null> {
+	async restoreState(skip = false): Promise<RestoreResult | null> {
+		// --- start unconditionally: the boot deadline in the lifecycle bounds this call, so
+		// --- booting eagerly here (even with nothing to revive) is what makes a wedged boot
+		// --- detectable instead of deferring the wedge to the first cell. ---
+		await this.start();
+		if (skip) return null;
 		const config = this.options.snapshot;
 		if (!config) return null;
 		if (!existsSync(config.path)) return null;
-		await this.start();
 		try {
 			const payload = JSON.parse(readFileSync(config.path, "utf8")) as {
 				version?: number;

package/src/engine/session.ts

@@ -123,10 +123,16 @@ export class JupyterSession {
 }
 
 export function executeRequest(code: string, silent: boolean): Record<string, unknown> {
+	// --- store_history is always false: IPython retains every last-expression result in its
+	// --- In/Out history, and that retention is NOT reclaimable from user cells (deleting Out
+	// --- entries and _/__/___ from user_ns leaves the objects alive). With history off, cells
+	// --- stop feeding that growth entirely. The contract does not depend on In/Out: results
+	// --- are published over iopub via the display hook (single-mode execution, unaffected by
+	// --- store_history) and returned in the cell's transcript. ---
 	return {
 		code,
 		silent,
-		store_history: !silent,
+		store_history: false,
 		user_expressions: {},
 		allow_stdin: false,
 		stop_on_error: true,

package/src/extension/prompt.ts

@@ -14,7 +14,7 @@ export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
 		"Write modern idiomatic Python.",
 		"Find, filter, fetch, sample: narrow the output in Python, then print only the window that decides the next step (a head, a shape, a slice), not the whole.",
-		"Make surgical, precise changes over rewrites or whole-file dumps: a small unique anchor, replace, verify, read the file back before trusting it.",
+		"Make surgical, precise changes over rewrites or whole-file dumps: replace, verify, read the file back before trusting it.",
 		"Prefer to reuse existing variables, functions, imports, classes, and data from prior cells/namespaces over recomputing.",
 		"If output begins with <repl_engine_reset>, the runtime rebuilt and the notebook was restored from the last snapshot; reverify surviving names before building on them.",
 		...(preloaded.length

package/src/extension/render-core.ts

@@ -517,6 +517,9 @@ function renderOutput(
 	}
 
 	if (details?.errorStack && details.errorStack.length > 0) {
+		// --- a traceback IS output: without this flag a pure-traceback error cell (no
+		// --- stdout/stderr/result, the common error shape) also rendered "no output" below it ---
+		renderedText = true;
 		output.push(` ${OUTPUT_INDENT}${deps.fg("dim", "traceback:")}`);
 		for (const line of details.errorStack) {
 			const safe = sanitizeTuiOutput(line || " ");
@@ -529,6 +532,13 @@ function renderOutput(
 		addWrapped(output, OUTPUT_INDENT, deps.fg("muted", message), width, deps, { sanitize: false });
 	}
 
+	// --- bottom cushion: streams end with a newline, so blobs already render a trailing blank
+	// --- row; traceback and the placeholder have no such newline and would sit flush against
+	// --- the panel's bottom edge. Normalize: the panel always ends with one blank painted row.
+	// --- (SGR stripped before the blank test; the colored rows themselves stay untouched.) ---
+	const lastRow = output[output.length - 1];
+	if (lastRow !== undefined && lastRow.replace(SGR_PATTERN, "").trim() !== "") output.push("");
+
 	// --- expanded cells render the whole output: the data cap bounds it ---
 	if (output.length > 0 && hasCode) lines.push("");
 	lines.push(...output);

package/src/extension/session-engine.ts

@@ -10,7 +10,8 @@ function summarizeNames(names: readonly string[], limit: number): string {
 
 /** The part of EngineManager this lifecycle needs; narrowed so tests can fake it. */
 export interface RevivableEngine {
-	restoreState(): Promise<RestoreResult | null>;
+	/** Boot the engine and revive the snapshot; `skip` boots fresh, deliberately not reviving. */
+	restoreState(skip?: boolean): Promise<RestoreResult | null>;
 	/** True when this conversation's state dir already exists, so the engine was resumed. */
 	hasSnapshotHistory(): boolean;
 }
@@ -22,11 +23,50 @@ export interface EngineLifecycleDeps<E extends RevivableEngine> {
 	dispose(engine: E): Promise<void>;
 	/** Kill-then-rebuild when a wedged engine cannot serve the snapshot flush. */
 	discard?(engine: E): Promise<void>;
+	/** Boot deadline in ms; a boot (kernel start, helpers preload, snapshot restore) that
+	 * outlives it is killed and retried fresh. Default 90s. */
+	bootTimeoutMs?: number;
 }
 
+/** Sentinel: the boot outlived its deadline. Distinct from null, which means "booted, nothing revived". */
+const BOOT_WEDGED = Symbol("boot wedged");
+
 /** `startup` restores then announces on the first cell when the conversation has a saved past; `cell` means an engine was rebuilt mid-session and announces immediately. */
 export type AcquireOrigin = "startup" | "cell";
 
+const DEFAULT_BOOT_TIMEOUT_MS = 90_000;
+
+/** Model-facing body for a boot whose snapshot revive wedged and was skipped. */
+function revivedNoticeBody(origin: AcquireOrigin): string {
+	const resumed = origin === "startup";
+	return resumed
+		? "This session's evaluator wedged while reviving the saved namespace, so the snapshot was skipped and the namespace is empty."
+		: "The evaluator wedged while reviving its saved namespace, so the snapshot was skipped and the namespace is empty.";
+}
+
+// --- Terse TUI toast for the human, separate from the model-facing cell marker: the user
+// --- asked for the classic subtle notification instead of a showy in-cell message. Counts
+// --- come from the same restore the marker describes, so the two never disagree. ---
+export function formatResetToast(origin: AcquireOrigin, restore: RestoreResult | null): string {
+	const resumed = origin === "startup";
+	const revived = restore?.restored.length ?? 0;
+	const lost = restore?.failed.length ?? 0;
+	if (restore && revived > 0) {
+		const counts = lost > 0 ? `, ${lost} lost` : "";
+		const noun = revived === 1 ? "name" : "names";
+		return resumed
+			? `repl session resumed, ${revived} ${noun} revived${counts}`
+			: `repl kernel rebuilt, ${revived} ${noun} revived${counts}`;
+	}
+	return resumed
+		? restore === null
+			? "repl session resumed, nothing saved to revive"
+			: "repl session resumed, nothing could be revived"
+		: restore === null
+			? "repl kernel rebuilt, nothing saved to revive"
+			: "repl kernel rebuilt, nothing could be revived";
+}
+
 function formatEngineResetNotice(restore: RestoreResult | null, origin: AcquireOrigin): string {
 	const resumed = origin === "startup";
 	const lines = ["<repl_engine_reset>"];
@@ -82,12 +122,30 @@ export class EngineLifecycle<E extends RevivableEngine> {
 	private engine?: E;
 	private revival?: Promise<RestoreResult | null>;
 	private pendingNotice?: string;
+	private pendingReset?: { origin: AcquireOrigin; restore: RestoreResult | null };
 	private teardown?: Promise<void>;
 	/** First-build in progress. */
 	private acquiring?: Promise<{ engine: E; restore: RestoreResult | null; created: boolean }>;
 
 	constructor(private readonly deps: EngineLifecycleDeps<E>) {}
 
+	/** Race one boot attempt against the deadline. The losing attempt is abandoned (and the
+	 * engine killed by the caller): its promise gets a no-op catch so killing the kernel
+	 * cannot surface an unhandled rejection later. */
+	private bootOnce(
+		engine: E,
+		deadlineMs: number,
+		skipRestore: boolean,
+	): Promise<RestoreResult | null | typeof BOOT_WEDGED> {
+		const work = engine.restoreState(skipRestore).catch(() => null);
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const guard = new Promise<typeof BOOT_WEDGED>((resolve) => {
+			timer = setTimeout(() => resolve(BOOT_WEDGED), deadlineMs);
+			timer.unref?.();
+		});
+		return Promise.race([work, guard]).finally(() => clearTimeout(timer));
+	}
+
 	/** Built and revived on demand; awaited so callers never see an un-revived namespace. */
 	async acquire(origin: AcquireOrigin): Promise<{ engine: E; restore: RestoreResult | null; created: boolean }> {
 		if (this.engine) {
@@ -100,14 +158,46 @@ export class EngineLifecycle<E extends RevivableEngine> {
 				const held: E = this.engine;
 				return { engine: held, restore: await this.revival!, created: false };
 			}
-			const engine = this.deps.create();
+			let engine = this.deps.create();
 			this.engine = engine;
-			this.revival = engine.restoreState().catch(() => null);
-			const restore = await this.revival;
+			// --- the boot is bounded: kernel start, helpers preload, and snapshot restore all
+			// --- run as kernel cells with no deadline of their own, and acquire() dedupes, so
+			// --- one wedged boot (venv swapped mid-update, a poisoned pickle) would otherwise
+			// --- hang the first cell and every cell after it. ---
+			const deadline = this.deps.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS;
+			let restore = await this.bootOnce(engine, deadline, false);
+			if (restore === BOOT_WEDGED) {
+				// --- the kernel is alive but stuck; only a kill frees it. Retry once WITHOUT the
+				// --- snapshot, so a poisoned pickle cannot wedge the session twice in a row. ---
+				await (this.deps.discard ?? this.deps.dispose)(engine);
+				engine = this.deps.create();
+				this.engine = engine;
+				restore = await this.bootOnce(engine, deadline, true);
+				if (restore === BOOT_WEDGED) {
+					await (this.deps.discard ?? this.deps.dispose)(engine);
+					this.engine = undefined;
+					throw new Error("evaluator boot timed out twice (kernel/helpers wedged); no session was started");
+				}
+				// --- the snapshot existed but reviving it is what wedged: say exactly that, not
+				// --- "no snapshot available", so the model doesn't go hunting for a missing file ---
+				if (origin === "cell" || (origin === "startup" && engine.hasSnapshotHistory())) {
+					this.pendingNotice = [
+						"<repl_engine_reset>",
+						revivedNoticeBody(origin),
+						"Re-verify a variable before reusing it, especially inside shell interpolation.",
+						"</repl_engine_reset>",
+					].join("\n");
+					this.pendingReset = { origin, restore: null };
+				}
+				this.revival = Promise.resolve(null);
+				return { engine, restore: null, created: true };
+			}
+			this.revival = Promise.resolve(restore);
 			// --- mid-session rebuilds always announce; startup announces only when the
 			// --- conversation has a saved past, so a first-ever session stays quiet ---
 			if (origin === "cell" || (origin === "startup" && engine.hasSnapshotHistory())) {
 				this.pendingNotice = formatEngineResetNotice(restore, origin);
+				this.pendingReset = { origin, restore };
 			}
 			return { engine, restore, created: true };
 		})();
@@ -119,11 +209,14 @@ export class EngineLifecycle<E extends RevivableEngine> {
 		}
 	}
 
-	/** Returns the pending reset notice exactly once, then clears it. */
-	takeResetNotice(): string | undefined {
+	/** Returns the pending reset notice exactly once (alongside its origin and restore result), then clears it. */
+	takeResetNotice(): { notice: string; origin: AcquireOrigin; restore: RestoreResult | null } | undefined {
+		const reset = this.pendingReset;
 		const notice = this.pendingNotice;
 		this.pendingNotice = undefined;
-		return notice;
+		this.pendingReset = undefined;
+		if (!notice || !reset) return undefined;
+		return { notice, origin: reset.origin, restore: reset.restore };
 	}
 
 	async shutdown(): Promise<void> {