pi-repl-py 0.1.0 → 0.2.0

package/src/extension/preview/scan.ts

@@ -0,0 +1,59 @@
+// --- scan: tokenizer source → template spans, string constants, and masks ---
+import { BACKTICK, type Span } from "./types.js";
+
+// --- capture the template opened at start; tracks escapes + interpolation nesting so a shell command reads whole, and an unclosed template returns the rest (partial is better than none) ---
+export function scanTemplate(source: string, start: number): Span {
+	let depth = 0;
+	let inNested = false;
+	for (let i = start + 1; i < source.length; i++) {
+		const ch = source[i];
+		if (ch === "\\") {
+			i += 1;
+			continue;
+		}
+		if (ch === BACKTICK) {
+			if (depth === 0 && !inNested) return { start, end: i + 1, body: source.slice(start + 1, i) };
+			inNested = !inNested;
+			continue;
+		}
+		if (!inNested && ch === "$" && source[i + 1] === "{") {
+			depth += 1;
+			i += 1;
+			continue;
+		}
+		if (!inNested && depth > 0 && ch === "}") depth -= 1;
+	}
+	return { start, end: source.length, body: source.slice(start + 1) };
+}
+
+const CONST_STRING_PATTERN = new RegExp(
+	'(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*(?:"([^"\\n]*)"|' +
+		"'([^'\\n]*)'|" +
+		BACKTICK +
+		"([^" +
+		BACKTICK +
+		"$\\n]*)" +
+		BACKTICK +
+		")",
+	"g",
+);
+
+// --- collected simple string constants, for resolving interpolations and path args ---
+export function stringConsts(source: string): Map<string, string> {
+	const vars = new Map<string, string>();
+	for (const match of source.matchAll(CONST_STRING_PATTERN)) {
+		const name = match[1];
+		const value = match[2] ?? match[3] ?? match[4];
+		if (name && value !== undefined) vars.set(name, value);
+	}
+	return vars;
+}
+
+export function substituteVars(text: string, vars: ReadonlyMap<string, string>): string {
+	return text.replace(/\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g, (whole, name: string) => vars.get(name) ?? whole);
+}
+
+// --- blank a claimed span so later detectors don't re-read what an earlier one took ---
+export function maskSpan(source: string, span: Span): string {
+	return source.slice(0, span.start) + " ".repeat(span.end - span.start) + source.slice(span.end);
+}

package/src/extension/preview/shell.ts

@@ -0,0 +1,156 @@
+// --- shell: resolve the strongest single line of a (possibly chained) shell command ---
+import { descriptor } from "./descriptor.js";
+
+const CD_PREFIX_PATTERN = /^\s*cd\s+([^&;|]+?)\s*(?:&&|;)\s*/;
+const SHELL_SETUP_PATTERN = /^(?:export\s+\w+=|set\s+[-+]|source\s+\S+|\.\s+\S+)/;
+const HEREDOC_PATTERN = /<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/;
+
+export function shellWords(line: string): string[] {
+	const words: string[] = [];
+	for (const match of line.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) {
+		words.push(match[1] ?? match[2] ?? match[3] ?? "");
+	}
+	return words;
+}
+
+function pathTail(path: string): string {
+	const cleaned = path.replace(/\/+$/, "");
+	const tail = cleaned.slice(cleaned.lastIndexOf("/") + 1);
+	return tail || cleaned;
+}
+
+function simplifyRunnerCommand(line: string): string | undefined {
+	const words = shellWords(line);
+	if (words[0] === "npm" || words[0] === "pnpm") {
+		const runIndex = words.indexOf("run");
+		if (runIndex >= 0 && words[runIndex + 1]) {
+			return `${words[0]} ${words.slice(runIndex + 1).join(" ")}`.trim();
+		}
+	}
+	if (line.includes("node_modules/.bin/")) {
+		return line.replace(/\S*node_modules\/\.bin\//g, "");
+	}
+	return undefined;
+}
+
+function simplifyMutationCommand(line: string): string | undefined {
+	const words = shellWords(line);
+	if (words.length === 0) return undefined;
+	if (words[0] === "cat" && words[1] === ">" && words[2]) return `write ${pathTail(words[2])}`;
+	if (words[0] === "tee" && words.at(-1)) {
+		return (words.includes("-a") ? "append " : "write ") + pathTail(words.at(-1) ?? "");
+	}
+	return undefined;
+}
+
+// --- collapse noisier command forms (runners, writes) down to the intent ---
+function simplifyShellLine(line: string): string {
+	return simplifyRunnerCommand(line) ?? simplifyMutationCommand(line) ?? line;
+}
+
+// --- commands that prepare the ground; the shell only wins when it is the story ---
+export const SHELL_SETUP_WORDS = new Set([
+	"mkdir",
+	"cd",
+	"export",
+	"touch",
+	"chmod",
+	"chown",
+	"ln",
+	"echo",
+	"true",
+	"sleep",
+	"which",
+	"sync",
+]);
+
+const SHELL_ACTION_WORDS = new Set([
+	"rm",
+	"mv",
+	"cp",
+	"git",
+	"npm",
+	"pnpm",
+	"bun",
+	"bunx",
+	"npx",
+	"make",
+	"cargo",
+	"docker",
+	"curl",
+	"gh",
+	"pi",
+]);
+
+function shellLineScore(line: string, index: number): number {
+	const simplified = simplifyShellLine(line);
+	const words = shellWords(line);
+	let score = 30;
+	if (simplified !== line) score += 40;
+	if (SHELL_ACTION_WORDS.has(words[0] ?? "")) score += 20;
+	if (/\b(?:rm|mv|cp|git\s+(?:add|commit|push)|sed\s+-i|perl\s+-pi|tee|cat\s*>)\b/.test(line)) score += 40;
+	return score + index;
+}
+
+function heredocBody(lines: readonly string[], startIndex: number, delimiter: string): string | undefined {
+	const body: string[] = [];
+	for (let i = startIndex + 1; i < lines.length; i++) {
+		if ((lines[i] ?? "").trim() === delimiter) return body.join("\n");
+		body.push(lines[i] ?? "");
+	}
+	return body.length > 0 ? body.join("\n") : undefined;
+}
+
+function previewHeredoc(lines: readonly string[]): string | undefined {
+	for (let i = 0; i < lines.length; i++) {
+		const line = (lines[i] ?? "").trim();
+		const delimiter = line.match(HEREDOC_PATTERN)?.[1];
+		if (!delimiter) continue;
+		const body = heredocBody(lines, i, delimiter);
+		if (!body) continue;
+		// --- the write target is the story; the body is detail for the expanded view ---
+		const catWrite = line.match(/\b(?:cat|tee)\b.*(?:>|\s)(\S+)\s*<<-?/);
+		if (catWrite?.[1]) return (line.includes("tee -a") ? "append " : "write ") + pathTail(catWrite[1]);
+		return descriptor(body);
+	}
+	return undefined;
+}
+
+export function previewShellCommand(command: string): string {
+	return previewShellCommandScored(command).text;
+}
+
+// --- like previewShellCommand but keeps the winning line's strength so several shell calls can rank ---
+export function previewShellCommandScored(command: string): { text: string; strength: number } {
+	const lines = command.split("\n");
+	const heredoc = previewHeredoc(lines);
+	if (heredoc) return { text: descriptor(heredoc), strength: 90 };
+
+	let best: { text: string; score: number } | undefined;
+	let cwdSuffix: string | undefined;
+	let index = 0;
+	for (const rawLine of lines) {
+		for (const rawPart of rawLine.split(/\s*(?:&&|;)\s*/)) {
+			let part = rawPart.trim();
+			if (!part || part.startsWith("#") || SHELL_SETUP_PATTERN.test(part)) continue;
+			const cd = part.match(CD_PREFIX_PATTERN);
+			if (cd?.[1]) {
+				cwdSuffix = pathTail(cd[1].trim());
+				part = part.replace(CD_PREFIX_PATTERN, "").trim();
+			} else if (/^cd\s+\S+$/.test(part)) {
+				cwdSuffix = pathTail(part.slice(2).trim());
+				continue;
+			}
+			if (!part) continue;
+			const candidate = { text: simplifyShellLine(part), score: shellLineScore(part, index) };
+			if (!best || candidate.score > best.score) best = candidate;
+			index += 1;
+		}
+	}
+	if (!best) return { text: "", strength: 0 };
+	// --- trailing redirections are plumbing, not intent ---
+	const cleaned = best.text.replace(/(?:\s*(?:2>&1|[12]?>\s*\/dev\/null|&>\s*\/dev\/null))+\s*$/, "");
+	// --- a stripped cd prefix still matters when it names a non-default dir ---
+	const text = cwdSuffix && !cleaned.includes(cwdSuffix) ? `${cleaned} (${cwdSuffix})` : cleaned;
+	return { text: descriptor(text), strength: best.score };
+}

package/src/extension/preview/types.ts

@@ -0,0 +1,23 @@
+// --- shared preview types; tiny module so every consumer imports only the shape it needs ---
+type CellPreviewKind = "shell" | "ts";
+
+export interface CellPreview {
+	kind: CellPreviewKind;
+	text: string;
+}
+
+// --- a [start, end) slice of the source with its captured body ---
+export interface Span {
+	start: number;
+	end: number;
+	body: string;
+}
+
+// --- the winner of each detector, ranked by score in the orchestration ---
+export interface Candidate {
+	kind: CellPreviewKind;
+	text: string;
+	score: number;
+}
+
+export const BACKTICK = "\u0060";

package/src/extension/prompt.ts

@@ -0,0 +1,76 @@
+// --- prompt: the execute tool's model-facing contract (pure, no pi/helper dep) ---
+
+export const executeToolDescription =
+	"You have one tool: a persistent Python workspace backed by a real `ipython` kernel. " +
+	"Variables, imports, functions, and data survive across cells and turns. Use this tool to read files, " +
+	"run shell commands, search code, transform data, and build up solutions — all inside Python. " +
+	"Helpers in `~/.pi/agent/pi-repl/helpers/` are loaded at boot as functions; see what's loaded with " +
+	"`[k for k in globals() if not k.startswith('_')]`. A cell returns its final expression; printed output " +
+	"is captured separately.";
+
+export const executePromptSnippet =
+	"Use the Python workspace: keep state in variables, batch independent reads/searches in one cell, " +
+	"edit files safely, and iterate in small cells.";
+
+// --- the workspace doctrine riding the execute tool ---
+export function buildPromptGuidelines(preloaded: string[]): string[] {
+	return [
+		"## This workspace is your only tool",
+		"In `--repl` mode, `execute` is the only callable tool. Read files, run shell, search, and edit " +
+			"all happen inside Python.",
+		"",
+		"## The loop is generate → execute → observe → iterate",
+		"Write a cell, run it, observe the result, then write the next cell. Build solutions incrementally.",
+		"",
+		"## State persists",
+		"Variables, imports, and functions survive across cells and turns. Assign read/search results to " +
+			"named variables and reuse them.",
+		"",
+		"## Chain big tasks into verifiable steps",
+		"Break ambitious requests into independently checkable steps. Confirm assumptions before writing " +
+			"code that depends on them.",
+		"",
+		"## Shell & files are plain Python",
+		"`!cmd` / `%%bash` for fire-and-forget shell; `subprocess.run(..., timeout=...)` when you need the result back " +
+			"as a value — always set a `timeout` on anything that could hang (the evaluator does not kill a " +
+			"silent cell automatically). `open()` / `pathlib` read and write files. For safe edits: read the full " +
+			"file, modify in memory, write once, then re-read to verify.",
+		"",
+		"## Batch independent work, keep exploratory cells small",
+		"Batch independent reads, searches, and setup steps in one cell to reduce round-trips. Keep " +
+			"exploratory/iterative cells small so you can observe and adjust.",
+		"",
+		"## Search efficiently",
+		"Use `rg`, `fd`, `grep`, `find` via `subprocess.run` for deep searches, not Python loops.",
+		"",
+		...(preloaded.length
+			? [
+					"## Helpers",
+					"User helpers load from `~/.pi/agent/pi-repl/helpers/`. Their descriptions appear below. " +
+						"List what's loaded with `[k for k in globals() if not k.startswith('_')]`.",
+					"",
+					...preloaded,
+					"",
+				]
+			: []),
+		"## Compose and reuse",
+		"If the same pattern appears more than once, wrap it in a `def` and reuse it.",
+		"",
+		"## Output discipline",
+		"Printing is a context cost: everything a cell prints stays in the transcript. Print slices, " +
+			"counts, and summaries. Keep large values in variables. End a cell with `;` to suppress the " +
+			"last-expression echo.",
+		"",
+		"## Environment boundary",
+		"The evaluator runs in a project-local venv, not the system Python. Do not install a target project's " +
+			"dependencies into the evaluator just to make that project run there. Run external projects " +
+			"through their own interface and normal commands.",
+		"",
+		"## Engine reset guard",
+		"If the output begins with `<repl_engine_reset>`, the kernel was rebuilt from the last snapshot. " +
+			"Some variables may be revived, some lost, and anything defined after the snapshot is gone. " +
+			"Re-verify variables before reusing them — never interpolate a restored variable into a shell " +
+			"command until you have confirmed it still holds what you expect. Functions, classes, and live " +
+			"handles cannot be snapshotted and must be redefined.",
+	];
+}

package/src/extension/render-core.ts

@@ -1,4 +1,4 @@
-// --- pure layout, free of pi imports so unit tests can drive it directly ---
+/** Pure layout, free of pi imports so unit tests drive it directly. */
 
 export interface ExecuteDetails {
 	status?: "ok" | "error" | "aborted" | string;
@@ -21,7 +21,7 @@ export interface ExecuteRenderState {
 	hasResult: boolean;
 }
 
-import { previewCell } from "./preview-core.js";
+import { previewCell } from "./preview/index.js";
 
 export type StatusKind = "error" | "aborted" | "running" | "queued" | "done";
 export type BgKind = "toolPendingBg" | "toolSuccessBg" | "toolErrorBg";
@@ -49,11 +49,7 @@ export function formatDuration(durationMs: number | undefined): string | undefin
 
 const SGR_PATTERN = /\x1b\[([0-9;]*)m/g;
 
-/**
- * Append a reset when `line` ends with a foreground or background color still
- * open, so a span that wrapping split across lines cannot bleed into the
- * trailing padding or the next row.
- */
+/** Close an open color so a line wrapped across words can't bleed into padding or the next row. */
 export function closeOpenSgr(line: string): string {
 	let fgOpen = false;
 	let bgOpen = false;
@@ -65,8 +61,7 @@ export function closeOpenSgr(line: string): string {
 				fgOpen = false;
 				bgOpen = false;
 			} else if (code === 38 || code === 48) {
-				// Skip the payload of 38;5;n / 38;2;r;g;b so a component (e.g. 38)
-				// is not read as another SGR code.
+				// --- skip the 38;5;n / 38;2;r;g;b payload so a component isn't read as another SGR code ---
 				if (code === 38) fgOpen = true;
 				else bgOpen = true;
 				const mode = Number(params[i + 1]);
@@ -135,14 +130,10 @@ function outputText(state: ExecuteRenderState): string {
 function topLine(state: ExecuteRenderState, width: number, deps: RenderDeps): string {
 	const code = state.code.trimEnd();
 	const preview = previewCell(code);
-	const language = preview.kind === "shell" ? "repl · shell" : preview.kind === "agent" ? "repl · agent" : "repl";
+	const language = preview.kind === "shell" ? "repl · shell" : "repl";
 	const prefix = `${marker(state, deps)} ${deps.fg("muted", language)}`;
 
-	// Fixed metadata after the preview must always survive; the preview
-	// absorbs all truncation. Counts settle-only: live updates jitter the header.
-	// Suffix order is by priority: the expand hint must survive first, then the
-	// error, then duration, then counts. Truncation happens from the right, so
-	// low-priority items are elided before the user loses the expand keybinding.
+	// --- suffix priority: expand hint > error > duration > counts, so truncation never hides the expand key ---
 	const suffixParts: string[] = [];
 	suffixParts.push(deps.keyHint(state.expanded));
 
@@ -170,12 +161,10 @@ function topLine(state: ExecuteRenderState, width: number, deps: RenderDeps): st
 	const separator = deps.fg("dim", " · ");
 	const separatorWidth = deps.visibleWidth(separator);
 	const suffix = suffixParts.join(separator);
-	// Budget: total width minus leading space, prefix, suffix, separators.
+	// --- budget: width minus leading space, prefix, suffix, and separators ---
 	const fixed = 1 + deps.visibleWidth(prefix) + separatorWidth + deps.visibleWidth(suffix);
 	const previewBudget = Math.max(8, width - fixed - separatorWidth);
-	// A semantic preview is a one-line summary of the code. Highlight Python
-	// code the same way the expanded block is highlighted; shell/agent previews
-	// stay accent-colored so they read as intent, not syntax.
+	// --- a semantic preview is a one-line summary; highlight Python code, accent shell intent ---
 	let middle = "";
 	if (preview.text) {
 		const previewText =
@@ -191,12 +180,7 @@ function topLine(state: ExecuteRenderState, width: number, deps: RenderDeps): st
 }
 
 function sanitizeTuiOutput(text: string): string {
-	// Terminal escape sequences and control characters from user code output can
-	// move the cursor, change colors, or print zero-width glyphs that break the
-	// TUI layout. Color SGR / CSI sequences (e.g. IPython's colored tracebacks)
-	// are STRIPPED so text stays readable; a remaining lone escape byte and other
-	// control chars are shown as Unicode control pictures so nothing is silently
-	// eaten. Tabs expand to 4 spaces; CR becomes ␍.
+	// --- strip ANSI SGR/CSI and escape control chars for a readable TUI; tabs expand, CR becomes ␍ ---
 	return text
 		.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
 		.replace(/\x1b/g, "␛")
@@ -245,7 +229,7 @@ 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 syntax-highlighted; don't strip its ANSI.
+		// --- code is already highlighted; don't strip its ANSI ---
 		addWrapped(lines, prefix, highlighted[index] ?? rawLine, width, deps, { sanitize: false });
 	}
 	return true;
@@ -263,9 +247,7 @@ function renderOutput(
 	const details = state.details;
 	const output: string[] = [];
 
-	// stdout/stderr/result are color-coded and labeled so you can tell which
-	// stream a line came from at a glance. Sanitize the raw text before
-	// applying the section color, or our own ANSI gets escaped as user output.
+	// --- stdout/stderr/result are color-coded; sanitize before section color so our ANSI isn't escaped ---
 	const sections: Array<{ text: string | undefined; color: string; label: string }> = [
 		{ text: details?.stdout, color: "toolOutput", label: "stdout" },
 		{ text: details?.stderr, color: "warning", label: "stderr" },
@@ -337,8 +319,6 @@ export function renderExecuteBody(state: ExecuteRenderState, width: number, deps
 	const lines: string[] = [];
 	const hasCode = renderCode(state, lines, safeWidth, deps);
 	renderOutput(state, lines, safeWidth, hasCode, deps);
-	// A thin bottom border separates the expanded cell from whatever follows.
-	if (lines.length > 0) lines.push(` ${deps.fg("dim", "─".repeat(Math.max(1, safeWidth - 1)))}`);
 	const kind = statusKind(state);
 	return lines.map((line) => paintBackground(line, safeWidth, kind, deps));
 }

package/src/extension/render.ts

@@ -1,9 +1,4 @@
-/**
- * TUI adapter for the `execute` cell renderer.
- *
- * Binds pi's theme, syntax highlighting, key hints, and width primitives to the
- * pure layout in render-core.ts, which is unit-tested outside pi's runtime.
- */
+/** TUI adapter binding pi's theme/width to the unit-tested pure layout in render-core.ts. */
 
 import { highlightCode, keyHint, keyText, rawKeyHint, type Theme } from "@mariozechner/pi-coding-agent";
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
@@ -35,11 +30,7 @@ function makeDeps(theme: Theme): RenderDeps {
 	};
 }
 
-/**
- * The layout of a cell only changes when its state or the spinner frame does,
- * but the TUI repaints on every frame. Rendering from a key of both stops the
- * recompute-per-frame (and with it, flicker on wide panes).
- */
+/** The layout only changes on state/spinner change, but the TUI repaints every frame; key by both to avoid recompute flicker. */
 function renderVersion(state: ExecuteRenderState): string {
 	const details = state.details ? JSON.stringify(state.details) : "";
 	return [

package/src/extension/session-engine.ts

@@ -1,12 +1,8 @@
-// A session may get teardown without session_start on reload, so revival is part of create() (was a real defect)
+// revival is part of create() so a session that gets teardown without a session_start reload still revives
 
 import type { RestoreResult } from "../engine/index.js";
 
-/**
- * A revived session can carry hundreds of variables; listing them all turns
- * the banner and the reset notice into a wall. Show enough to orient, then
- * count the rest.
- */
+/** Show enough names to orient, then count the rest (a revive can carry hundreds). */
 export function summarizeNames(names: readonly string[], limit: number): string {
 	if (names.length <= limit) return names.join(", ");
 	return `${names.slice(0, limit).join(", ")} … and ${names.length - limit} more`;
@@ -22,23 +18,15 @@ export interface EngineLifecycleDeps<E extends RevivableEngine> {
 	create(): E;
 	/** Tears the current engine down, flushing its final snapshot. */
 	dispose(engine: E): Promise<void>;
-	/**
-	 * Tears down an engine that cannot cooperate — a wedged guest cannot serve
-	 * the snapshot flush dispose would ask of it. Falls back to dispose.
-	 */
+	/** Kill-then-rebuild when a wedged engine cannot serve the snapshot flush. */
 	discard?(engine: E): Promise<void>;
 }
 
-/**
- * Why an engine came into existence. `startup` is the expected path and is
- * already announced in the transcript; `cell` means an engine had to be built
- * to serve a tool call, which only happens when the previous one went away
- * mid-session — the case the model needs told about in-band.
- */
+/** `startup` is announced in the transcript; `cell` means an engine was rebuilt mid-session and needs an in-band notice. */
 export type AcquireOrigin = "startup" | "cell";
 
 function formatEngineResetNotice(restore: RestoreResult | null): string {
-	const lines = ["<rlm_engine_reset>"];
+	const lines = ["<repl_engine_reset>"];
 	if (!restore) {
 		// --- no snapshot at all: namespace is genuinely empty ---
 		lines.push(
@@ -73,7 +61,7 @@ function formatEngineResetNotice(restore: RestoreResult | null): string {
 		}
 		lines.push("Anything defined after the last snapshot is also gone.");
 	}
-	lines.push("Re-verify a variable before reusing it, especially inside shell interpolation.", "</rlm_engine_reset>");
+	lines.push("Re-verify a variable before reusing it, especially inside shell interpolation.", "</repl_engine_reset>");
 	return lines.join("\n");
 }
 
@@ -81,25 +69,19 @@ export class EngineLifecycle<E extends RevivableEngine> {
 	private engine?: E;
 	private revival?: Promise<RestoreResult | null>;
 	private pendingNotice?: string;
-	/** Teardown in progress; a rebuild must not overlap the final snapshot flush. */
 	private teardown?: Promise<void>;
-	/** First-build in progress: concurrent acquire() must not spawn two engines. */
+	/** First-build in progress. */
 	private acquiring?: Promise<{ engine: E; restore: RestoreResult | null; created: boolean }>;
 
 	constructor(private readonly deps: EngineLifecycleDeps<E>) {}
 
-	/**
-	 * The live engine, built and revived if it does not exist yet.
-	 * Revival is awaited here so a caller never sees an un-revived namespace.
-	 */
+	/** 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) {
 			return { engine: this.engine, restore: await this.revival!, created: false };
 		}
-		// --- two concurrent acquires on an empty engine must share one build ---
 		if (this.acquiring) return this.acquiring;
 		const build = (async () => {
-			// --- a teardown flushing its final snapshot must finish before the rebuild reads it ---
 			while (this.teardown) await this.teardown;
 			if (this.engine) {
 				const held: E = this.engine;
@@ -131,11 +113,7 @@ export class EngineLifecycle<E extends RevivableEngine> {
 		await this.teardownWith((engine) => this.deps.dispose(engine));
 	}
 
-	/**
-	 * Teardown for an engine that cannot cooperate (e.g. wedged in synchronous
-	 * code). Skips the snapshot flush a graceful dispose would attempt; the next
-	 * acquire builds a fresh engine revived from the last completed snapshot.
-	 */
+	/** Kill-then-rebuild for a wedged engine; skips the final snapshot flush, uses the last good one. */
 	async discard(): Promise<void> {
 		await this.teardownWith((engine) => (this.deps.discard ?? this.deps.dispose)(engine));
 	}

package/src/extension/tool-meta.ts

@@ -1,58 +1,15 @@
-/**
- * The `execute` tool's prompt surface.
- *
- * pi's default system prompt is used as-is; all REPL knowledge rides on the
- * tool via these fields, so index.ts stays thin.
- *
- *  - description   — working summary (schema card).
- *  - promptSnippet — one line in the default `Available tools`.
- *  - promptGuidelines — the function doctrine + tokens + safety.
- *
- * The function map is derived from the toolbox source via buildToolboxMap()
- * (function_description docstring + def-signature regex), so it always matches
- * what the kernel loads.
- */
+// --- tool-meta: thin surface assembling the execute tool's prompt from pure modules ---
+// --- the model contract lives in prompt.ts; only the helpers wiring stays here ---
 
-import { buildToolboxMap } from "./toolbox.js";
+import { buildHelpersMap } from "./helpers.js";
+import { buildPromptGuidelines, executePromptSnippet, executeToolDescription } from "./prompt.js";
 
-export const EXECUTE_DESCRIPTION =
-	"Execute Python to a persistent evaluator: the session's working memory. " +
-	"Variables, imports, functions, and data survive across calls. There are no " +
-	"separate file or shell tools; read, write, edit, bash, and anything you build " +
-	"are Python functions you call inside a cell. A cell returns its final " +
-	"expression; anything else is printed. Build one reusable function per routine " +
-	"and call it by arguments, since a new def overwrites the previous one; don't " +
-	"narrate that machinery to the user. Runs in a project-local venv, so a command " +
-	"that starts python or pip must target that venv.";
+export const EXECUTE_DESCRIPTION = executeToolDescription;
+export const EXECUTE_PROMPT_SNIPPET = executePromptSnippet;
 
-export const EXECUTE_PROMPT_SNIPPET =
-	"Execute Python in a persistent evaluator whose variables, imports, and functions " +
-	"survive across calls; preloaded functions plus any you define and reuse as " +
-	"callable tools; ls() lists them, help(name) shows usage";
-
-/**
- * promptGuidelines for the execute tool. `toolboxDir` is optional; it defaults to
- * the shipped toolbox.
- */
-export function buildExecutePromptGuidelines(toolboxDir?: string): string[] {
-	const map = buildToolboxMap(toolboxDir);
-	const preloaded = map.length > 0 ? map : ["(none preloaded: define your own)"];
-	return [
-		"Preloaded functions available in every kernel:",
-		...preloaded,
-		"ls() prints what is loaded; help(name) shows a function's signature and notes. Use them instead of guessing.",
-		"Functions you define are reusable tools: one parameterized helper per task, call it by arguments. Never write a routine twice and never fork a duplicate; extend the existing `def` (a new `def` of the same name overwrites).",
-		"Before a multi-line cell, ask whether you will run that shape again with different inputs. If yes, define the function now so each later request is one call.",
-		"Good, defined once then called by arguments only:",
-		"def fetch_news(query, hl='en', gl='US', ceid='US:en', limit=15):\n    <fetch + parse to a list>\nfetch_news('Turkey')\nfetch_news('Nigeria', hl='en-NG')",
-		"Don't build a near-copy (avoid fetch_news and fetch_news_region); add the varying bits to the original `def` and let it supersede the old.",
-		"Other reusable shapes build the same way:",
-		"def find_files(pred, root='.'):\n    <walk root, filter by pred>\nfind_files('*.csv')\nfind_files('*.py', root='src')\ndef count_lines(paths): ... # compose: count_lines(find_files('*.csv'))",
-		"Use functions proportionally: build one when it will be reused, otherwise run it in a plain cell. Don't wrap a one-off and don't over-engineer.",
-		"Never narrate your mechanism to the user (don't say 'I defined a function' or 'I built a tool'). Do the job, then answer with the result.",
-		"Be token efficient: everything a cell prints is context for the rest of the turn. When reading or searching, print slices, matches, or counts rather than whole files, and keep large values in variables.",
-		"For whole-filesystem or large-dir scans, use the kernel's tools via bash, not a Python walk: find, du, fd, grep. Chain them (find -xdev -type f -size +100M | sort -rn | head; du -x | sort -h | tail) and prune descent by skipping node_modules, .git, caches, venvs. A Python os.walk + lstat loop pays a slow syscall per file and runs minutes to 10+ min on a big tree; reserve Python for analysing the results, not for enumerating the disk.",
-		"If the output starts with <rlm_engine_reset>, the kernel was rebuilt: only data is restored, your functions are gone. Recreate any helper you need and re-verify a variable before trusting it.",
-		"Don't install packages into the evaluator; the standard library is available. Run out-of-tree projects through their own environment.",
-	];
+// --- build the guidelines from the one helpers dir (default ~/.pi/agent/pi-repl/helpers) ---
+export function buildExecutePromptGuidelines(): string[] {
+	const map = buildHelpersMap();
+	const preloaded = map.length > 0 ? map : [];
+	return buildPromptGuidelines(preloaded);
 }