pi-repl-py 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.6.0",
+	"version": "0.6.2",
 	"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

@@ -162,6 +162,15 @@ export class EngineManager {
 				env: this.options.env,
 				timeoutMs,
 			});
+			// --- an unexpected kernel death must not survive the next execute: drop the dying
+			// --- instance and clear the boot cache so start() rebuilds it on the next cell. ---
+			const current = this.kernel;
+			current.setOnUnexpectedExit(() => {
+				if (this.kernel !== current) return;
+				this.kernel = undefined;
+				this.startPromise = undefined;
+				this.lastNamespaceNames = undefined;
+			});
 		} catch (error) {
 			if (this.state === "starting") this.state = "idle";
 			liveEngines.delete(this);
@@ -215,6 +224,13 @@ export class EngineManager {
 				throw new Error("Engine has been shut down");
 			}
 			await this.start();
+			// --- the kernel may have died after the boot promise resolved but before the async
+			// --- exit event surfaced it; drop the zombie and rebuild so the next cell runs. ---
+			if (this.kernel && !this.kernel.isRunning) {
+				this.kernel = undefined;
+				this.startPromise = undefined;
+				await this.start();
+			}
 			if (this.isShutdown()) {
 				throw new Error("Engine has been shut down");
 			}

package/src/engine/kernel.ts

@@ -19,6 +19,7 @@ import {
 import { ZmtpSocket } from "./zmtp.js";
 
 const KERNEL_READY_TIMEOUT_MS = 30_000;
+const SILENCE_KILL_GRACE_MS = 2000;
 const DEFAULT_MAX_OUTPUT_CHARS = 1_000_000;
 
 export interface KernelOptions {
@@ -169,8 +170,13 @@ export class KernelClient {
 	private ready = false;
 	/** Serializes all kernel ops: one execute at a time, snapshots between cells. */
 	private queue: Promise<unknown> = Promise.resolve();
-	private onUnexpectedExit?: () => void;
+	private _onUnexpectedExit?: () => void;
+	/** Engine hook: an unexpected kernel death (not a deliberate kill) should drop the instance. */
+	setOnUnexpectedExit(fn: () => void): void {
+		this._onUnexpectedExit = fn;
+	}
 	private watchdog?: ReturnType<typeof setInterval>;
+	private silenceKillTimer?: ReturnType<typeof setTimeout>;
 	private pendingReplies = new Map<
 		string,
 		{ resolve(m: ParsedMessage): void; timer?: ReturnType<typeof setTimeout> }
@@ -223,9 +229,18 @@ export class KernelClient {
 		kc.child = child;
 		kc.connectionFilePath = connPath;
 		child.on("exit", () => {
-			// --- a dead kernel settles the running cell; the engine rebuilds ---
+			// --- a dead kernel settles the running cell; the engine rebuilds. clear child/ready
+			// --- so isRunning reflects death and the engine never resumes a zombie process. ---
 			kc.settleActive(new Error("kernel process exited"));
-			kc.onUnexpectedExit?.();
+			kc.child = undefined;
+			kc.ready = false;
+			kc.shell?.close();
+			kc.control?.close();
+			kc.iopub?.close();
+			kc.shell = undefined;
+			kc.control = undefined;
+			kc.iopub = undefined;
+			kc._onUnexpectedExit?.();
 		});
 
 		try {
@@ -494,6 +509,12 @@ export class KernelClient {
 				if (quiet >= this.timeoutMs && !active.settled) {
 					active.timedOut = true;
 					this.interrupt();
+					// --- the interrupt is a real KeyboardInterrupt, but a cell that swallows/ignores
+					// --- it never replies; escalate to a kill so the queue is freed, mirroring index.ts. ---
+					this.silenceKillTimer ??= setTimeout(() => {
+						if (!active.settled) this.kill();
+					}, SILENCE_KILL_GRACE_MS);
+					this.silenceKillTimer.unref?.();
 				}
 			},
 			Math.min(250, this.timeoutMs),
@@ -506,6 +527,10 @@ export class KernelClient {
 			clearInterval(this.watchdog);
 			this.watchdog = undefined;
 		}
+		if (this.silenceKillTimer) {
+			clearTimeout(this.silenceKillTimer);
+			this.silenceKillTimer = undefined;
+		}
 	}
 
 	/** Genuine KeyboardInterrupt via control-channel interrupt_request; the kernel survives. */

package/src/extension/helpers.ts

@@ -41,6 +41,6 @@ export function buildHelpersMap(dir?: string): string[] {
 	return loadHelperEntries(dir).map((t) =>
 		t.description
 			? `- ${t.description.replace(/\n/g, "\n  ")}`
-			: `- ${t.name} (no description — inspect it with print(${t.name}.__doc__))`,
+			: `- ${t.name} (no description, inspect it with print(${t.name}.__doc__))`,
 	);
 }

package/src/extension/prompt.ts

@@ -1,9 +1,4 @@
-// --- prompt: the execute tool's model-facing contract (pure, no pi/helper dep) ---
-//
-// Verbatim clauses from CodeAct (arXiv 2402.01030) and RLM (arXiv 2512.24601)
-// are trimmed to what pi-repl actually has — no sub-LLMs, no recursion, no
-// context variable — and the rest is stripped for lean context. Less prose,
-// more signal; the machine reads every line every turn.
+// --- execute tool: the model-facing contract + workspace doctrine (pure, no pi/helper dep) ---
 
 export const executeToolDescription =
 	"Execute Python cells in a persistent ipython kernel; state survives across cells and turns, replacing " +
@@ -17,36 +12,27 @@ export const executePromptSnippet =
 export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
 		"## Your only workspace",
-		"You are an engineer in a persistent Python REPL. `execute` is the only callable surface — it replaces read, bash, edit, write, and search. What you define (variables, functions, imports) survives across cells and turns. The work is proven by the result each cell returns, and by nothing else.",
-		"",
-		"## Get up to speed first",
-		"Orient before you act: `%pwd`, glance at the namespace, read any state or progress file, skim recent history. A few tokens, it buys a right first move. Work from what you confirmed, not assumptions.",
+		"You are an engineer in a persistent Python REPL. `execute` is the only callable surface, it replaces read, bash, edit, write, and search. What you define (variables, functions, imports) survives across cells and turns, so define any function once and call it in later cells. The work is proven by the result each cell returns, and by nothing else.",
 		"",
 		"## Reason, then say, then stop",
-		"Reason as much as the task needs, but reason inside the cell and keep the reasoning out of the transcript: do it in variables and filters, then return only the outcome. Every printed value is expensive — it enters the context now and stays, costing later tokens every time — so print only what the next decision consumes. A bare final expression auto-prints, so assign instead. Concise reasoning still works — length you cut is reward you don't lose, because the evidence is the returned result, not the words around it.",
+		"Reason inside the cell, not the transcript: do the thinking in variables and filters, return only the outcome. End on an assignment, a bare expression auto-prints. Keep the reasoning you need, drop the rest, the returned result is the evidence of the work, not the words around it.",
 		"",
 		"## The environment answers you",
-		"The cell's output is the ground truth — what actually ran, what errored, what came back. Trust it over any narrative: if a cell already proved it, point at that. When you're unsure what a fetch contains, read a slice, don't guess and don't dump it whole to 'check'.",
+		"The cell's output is the ground truth, what actually ran, what errored, what came back. Trust it over any narrative: if a cell already proved it, point at that. When you're unsure what a fetch contains, read a slice, don't guess and don't dump it whole to 'check'.",
 		"",
 		"## Gather, slice, decide",
-		"Fetch into a variable, never into the transcript. Search results, reads, command output, file contents — assign. A bare expression prints, so end those cells on the assignment. Then advance on a bounded slice: print only the fragment that decides the next step, hold the rest in the variable, peel into the pieces you need without re-fetching, and when the reasoning lands, print the conclusion.",
+		"Fetch into a variable, never into the transcript. Search results, reads, command output, file contents, assign. A bare expression prints, so end those cells on the assignment. Then advance on a bounded slice: print only the fragment that decides the next step, hold the rest in the variable, peel into the pieces you need without re-fetching, and when the reasoning lands, print the conclusion.",
 		"",
-		"Reading whole is fine when the task needs all of it — hold it and reason on it; the point isn't to never read fully, it's to not re-fetch the same big thing twice.",
+		"Reading whole is fine when the task needs all of it, hold it and reason on it; the point isn't to never read fully, it's to not re-fetch the same big thing twice.",
 		"",
 		"## Output format",
-		"In reply text: the conclusion and the handful of results that prove it — the slice you acted on, the returned value, a one-line takeaway. Do not transcribe the run, restate every variable, or narrate what the cell already showed.",
-		"",
-		"## Worked example",
-		"Gather and slice — two cells, thin transcript:\n  cell 1:  doc = open('notes.txt').read()\n  cell 2:  print(doc.splitlines()[:5])\nThe whole file lands in doc (nothing printed); the second cell prints only the first five lines, the rest stays in doc for later.",
-		"",
-		"## Compose and reuse",
-		"Compose filesystem, shell, search, transforms, checks, edits in ordinary Python in one cell, and end on the value the next step consumes. A step seen twice becomes a function you call once — proven work, reused. Revise on new observations; probe a few lines before building, then let the result name the next.",
+		"In reply text: the conclusion and the handful of results that prove it, the slice you acted on, the returned value, a one-line takeaway. Do not transcribe the run, restate every variable, or narrate what the cell already showed.",
 		"",
 		"## Edits and repo discipline",
-		"Surgical old-text/new-text: read the region, fix an exact unique anchor that appears once, replace, verify. Many small edits over one big rewrite — a parse error can strand an anchor; after an error, read the file back from disk first. Make the smallest valid change, preserve conventions, never invent files, APIs, conventions, or test results. Prune generated dirs when walking trees.",
+		"Surgical old-text/new-text: read the region, fix an exact unique anchor that appears once, replace, verify. Many small edits over one big rewrite, a parse error can strand an anchor; after an error, read the file back from disk first. Make the smallest valid change, preserve conventions, never invent files, APIs, conventions, or test results. Prune generated dirs when walking trees. Pass a `timeout` to any `subprocess.run(...)`, a silent cell must die, not hang.",
 		"",
-		"## Shell & search",
-		"Always pass a `timeout` to `subprocess.run(...)` — a silent cell must die, not hang. Capture output in a variable and read a slice, not the whole stdout. Use `rg`/`grep`/`find` for deep searches, not Python loops.",
+		"## Print is expensive",
+		"Print small, exact slices, bounded to what the decision actually needs. Keep the whole in a variable and print only on demand. Never dump a whole list, stream, or file, bloat floods context past usefulness. Prefer quality over quantity.",
 		"",
 		...(preloaded.length
 			? [
@@ -58,9 +44,9 @@ export function buildPromptGuidelines(preloaded: string[]): string[] {
 				]
 			: []),
 		"## Environment & rescue",
-		"The evaluator runs in a project-local venv, not the system Python. Do not install a project's dependencies into the evaluator; run external projects through their own interface. If output begins with `<repl_engine_reset>`, the kernel rebuilt — re-verify a revived variable before reusing it.",
+		"The evaluator runs in a project-local venv, not the system Python. Do not install a project's dependencies into the evaluator; run external projects through their own interface. If output begins with `<repl_engine_reset>`, the kernel rebuilt, re-verify a revived variable before reusing it.",
 		"",
-		"## When a rule doesn't cover it",
-		"If something isn't spelled out, keep working rather than asking: hold it in the workspace, prove it with a returned result, and keep the transcript to what you act on. Make the sensible default and correct it from the result.",
+		"## These rules are the surface",
+		"The rules above are the surface of how this workspace works, not the whole of it. Internalize their intent, apply it to cases they don't mention, and follow them diligently.",
 	];
 }

package/src/extension/render-core.ts

@@ -39,7 +39,7 @@ export interface RenderDeps {
 }
 
 const OUTPUT_INDENT = "  ";
-const SPINNER_FRAMES = ["◐", "◓", "◑", "◒"];
+const SPINNER_FRAMES = [">..", ".>.", "..>", ".>."];
 
 export function formatDuration(durationMs: number | undefined): string | undefined {
 	if (durationMs === undefined) return undefined;
@@ -105,13 +105,68 @@ function marker(state: ExecuteRenderState, deps: RenderDeps): string {
 			return deps.fg("success", "✓");
 		case "running": {
 			const now = deps.now?.() ?? Date.now();
-			return deps.fg("accent", SPINNER_FRAMES[Math.floor(now / 160) % SPINNER_FRAMES.length]);
+			return deps.fg("accent", SPINNER_FRAMES[Math.floor(now / 120) % SPINNER_FRAMES.length]);
 		}
 		default:
 			return deps.fg("muted", "◇");
 	}
 }
 
+/**
+ * highlight.js python emits no scope for plain identifiers, so they arrive as raw (uncolored)
+ * text mixed with SGR-colored tokens and bare punctuation. Re-color only whole identifier runs
+ * that sit outside any colored span, leaving keywords, strings, numbers, and other already
+ * colored tokens untouched.
+ */
+function colorBareIdentifiers(line: string, paint: (id: string) => string): string {
+	if (!line.includes("\x1b") && !/[a-zA-Z_]/.test(line)) return line;
+	const out: string[] = [];
+	let pending = "";
+	let colored = false;
+	const pushRaw = (s: string) => {
+		let last = 0;
+		for (const m of s.matchAll(/[a-zA-Z_][a-zA-Z0-9_]*/g)) {
+			const index = m.index ?? 0;
+			out.push(s.slice(last, index), paint(m[0]));
+			last = index + m[0].length;
+		}
+		out.push(s.slice(last));
+	};
+	let i = 0;
+	const isFgColor = (seq: string) => /\x1b\[(?:38|9?[0-7])/.test(seq);
+	while (i < line.length) {
+		if (line[i] === "\x1b") {
+			const end = line.indexOf("m", i) + 1;
+			const seq = line.slice(i, end);
+			if (isFgColor(seq)) {
+				if (pending) {
+					pushRaw(pending);
+					pending = "";
+				}
+				out.push(seq);
+				colored = true;
+			} else if (seq.includes("39") || seq.includes("0m")) {
+				if (colored) {
+					out.push(seq);
+					colored = false;
+				} else {
+					pending += seq;
+				}
+			} else {
+				pending += seq;
+			}
+			i = end;
+			continue;
+		}
+		// only raw (uncolored) text may be repainted; colored tokens pass through untouched
+		if (colored) out.push(line[i]);
+		else pending += line[i];
+		i++;
+	}
+	if (pending) pushRaw(pending);
+	return out.join("");
+}
+
 function highlightLines(code: string, deps: RenderDeps): string[] {
 	if (!code) return [];
 	return deps.highlight(code);
@@ -211,14 +266,15 @@ function addWrapped(
 	text: string,
 	width: number,
 	deps: RenderDeps,
-	options: { sanitize?: boolean } = {},
+	options: { sanitize?: boolean; indentAfter?: number } = {},
 ): void {
 	const safe = options.sanitize === false ? text : sanitizeTuiOutput(text);
 	const available = Math.max(1, width - 1 - deps.visibleWidth(prefix));
 	const wrapped = deps.wrapTextWithAnsi(safe, available);
 	for (const [index, line] of (wrapped.length > 0 ? wrapped : [""]).entries()) {
 		const linePrefix = index === 0 ? prefix : " ".repeat(deps.visibleWidth(prefix));
-		lines.push(deps.truncateToWidth(` ${linePrefix}${closeOpenSgr(line)}`, width, ""));
+		const continuationIndent = index > 0 && options.indentAfter ? " ".repeat(options.indentAfter) : "";
+		lines.push(deps.truncateToWidth(` ${linePrefix}${continuationIndent}${closeOpenSgr(line)}`, width, ""));
 	}
 }
 
@@ -229,8 +285,13 @@ function renderCode(state: ExecuteRenderState, lines: string[], width: number, d
 	const highlighted = highlightLines(code, deps);
 	for (const [index, rawLine] of code.split("\n").entries()) {
 		const prefix = index === 0 ? deps.fg("dim", "› ") : deps.fg("dim", "  ");
-		// --- code is already highlighted; don't strip its ANSI ---
-		addWrapped(lines, prefix, highlighted[index] ?? rawLine, width, deps, { sanitize: false });
+		const paint = (id: string) => deps.fg("syntaxVariable", id);
+		const hlLine = colorBareIdentifiers(highlighted[index] ?? rawLine, paint);
+		const indent = /^[ \t]*/.exec(rawLine)?.[0] ?? "";
+		addWrapped(lines, prefix, hlLine, width, deps, {
+			sanitize: false,
+			indentAfter: deps.visibleWidth(indent),
+		});
 	}
 	return true;
 }

package/src/extension/render.ts

@@ -43,7 +43,7 @@ function renderVersion(state: ExecuteRenderState): string {
 		state.executionStarted,
 		state.hasResult,
 		// --- fold the animation frame in while running so the spinner still turns ---
-		statusKind(state) === "running" ? Math.floor(Date.now() / 160) % 4 : -1,
+		statusKind(state) === "running" ? Math.floor(Date.now() / 120) % 4 : -1,
 	].join("|");
 }