pi-repl-py 0.1.0

package/src/extension/render-core.ts

@@ -0,0 +1,348 @@
+// --- pure layout, free of pi imports so unit tests can drive it directly ---
+
+export interface ExecuteDetails {
+	status?: "ok" | "error" | "aborted" | string;
+	durationMs?: number;
+	errorName?: string;
+	stdout?: string;
+	stderr?: string;
+	result?: string;
+	errorStack?: string[];
+}
+
+export interface ExecuteRenderState {
+	code: string;
+	details?: ExecuteDetails;
+	contentText?: string;
+	isPartial: boolean;
+	isError: boolean;
+	expanded: boolean;
+	executionStarted: boolean;
+	hasResult: boolean;
+}
+
+import { previewCell } from "./preview-core.js";
+
+export type StatusKind = "error" | "aborted" | "running" | "queued" | "done";
+export type BgKind = "toolPendingBg" | "toolSuccessBg" | "toolErrorBg";
+
+export interface RenderDeps {
+	fg(color: string, text: string): string;
+	getBgAnsi(bg: BgKind): string;
+	highlight(code: string): string[];
+	keyHint(expanded: boolean): string;
+	visibleWidth(text: string): number;
+	truncateToWidth(text: string, width: number, ellipsis: string): string;
+	wrapTextWithAnsi(text: string, width: number): string[];
+	/** Injected for deterministic spinner frames in tests. */
+	now?(): number;
+}
+
+const OUTPUT_INDENT = "  ";
+const SPINNER_FRAMES = ["◐", "◓", "◑", "◒"];
+
+export function formatDuration(durationMs: number | undefined): string | undefined {
+	if (durationMs === undefined) return undefined;
+	if (durationMs < 1000) return `${Math.round(durationMs)}ms`;
+	return `${(durationMs / 1000).toFixed(1)}s`;
+}
+
+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.
+ */
+export function closeOpenSgr(line: string): string {
+	let fgOpen = false;
+	let bgOpen = false;
+	for (const match of line.matchAll(SGR_PATTERN)) {
+		const params = match[1] === "" ? ["0"] : (match[1] ?? "").split(";");
+		for (let i = 0; i < params.length; i++) {
+			const code = Number(params[i]);
+			if (code === 0) {
+				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.
+				if (code === 38) fgOpen = true;
+				else bgOpen = true;
+				const mode = Number(params[i + 1]);
+				i += mode === 2 ? 4 : mode === 5 ? 2 : 1;
+			} else if (code === 39) {
+				fgOpen = false;
+			} else if (code === 49) {
+				bgOpen = false;
+			} else if ((code >= 30 && code <= 37) || (code >= 90 && code <= 97)) {
+				fgOpen = true;
+			} else if ((code >= 40 && code <= 47) || (code >= 100 && code <= 107)) {
+				bgOpen = true;
+			}
+		}
+	}
+	return fgOpen || bgOpen ? `${line}\x1b[0m` : line;
+}
+
+export function statusKind(state: ExecuteRenderState): StatusKind {
+	const status = state.details?.status;
+	if (state.isError || status === "error") return "error";
+	if (status === "aborted") return "aborted";
+	if (!state.isPartial && (status !== undefined || state.hasResult)) return "done";
+	if (state.isPartial || state.executionStarted) return "running";
+	return "queued";
+}
+
+export function backgroundFor(kind: StatusKind): BgKind {
+	if (kind === "error" || kind === "aborted") return "toolErrorBg";
+	if (kind === "done") return "toolSuccessBg";
+	return "toolPendingBg";
+}
+
+function marker(state: ExecuteRenderState, deps: RenderDeps): string {
+	switch (statusKind(state)) {
+		case "error":
+			return deps.fg("error", "✗");
+		case "aborted":
+			return deps.fg("warning", "✗");
+		case "done":
+			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]);
+		}
+		default:
+			return deps.fg("muted", "◇");
+	}
+}
+
+function highlightLines(code: string, deps: RenderDeps): string[] {
+	if (!code) return [];
+	return deps.highlight(code);
+}
+
+function outputText(state: ExecuteRenderState): string {
+	const details = state.details;
+	if (details && (details.stdout || details.stderr || details.result)) {
+		return [details.stdout, details.stderr, details.result]
+			.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+			.join("\n");
+	}
+	return state.contentText?.trim() ?? "";
+}
+
+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 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.
+	const suffixParts: string[] = [];
+	suffixParts.push(deps.keyHint(state.expanded));
+
+	const errorName = !state.isPartial ? state.details?.errorName : undefined;
+	if (errorName) {
+		// --- the error message usually beats a bare name when it fits ---
+		const summary = sanitizeTuiOutput(state.details?.errorStack?.[0] ?? "");
+		suffixParts.push(deps.fg("error", summary && deps.visibleWidth(summary) <= 48 ? summary : errorName));
+	}
+
+	const duration = formatDuration(state.details?.durationMs);
+	if (duration) suffixParts.push(deps.fg("muted", duration));
+
+	// --- counts settle-only: live-updating them mid-stream jitters the header ---
+	if (!state.isPartial && statusKind(state) !== "running") {
+		const inputLines = code.split("\n").filter((line) => line.trim().length > 0).length;
+		const output = outputText(state);
+		const outputLines = output ? output.split("\n").length : 0;
+		const counts: string[] = [];
+		if (inputLines > 0) counts.push(`↑ ${inputLines}`);
+		if (outputLines > 0) counts.push(`↓ ${outputLines}`);
+		if (counts.length > 0) suffixParts.push(deps.fg("muted", `${counts.join(" ")} lines`));
+	}
+
+	const separator = deps.fg("dim", " · ");
+	const separatorWidth = deps.visibleWidth(separator);
+	const suffix = suffixParts.join(separator);
+	// Budget: total width minus leading space, prefix, suffix, 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.
+	let middle = "";
+	if (preview.text) {
+		const previewText =
+			preview.kind === "ts"
+				? (deps.highlight(preview.text)[0] ?? deps.fg("accent", preview.text))
+				: deps.fg("accent", preview.text);
+		middle = deps.truncateToWidth(previewText, previewBudget, "…");
+	} else if (!state.executionStarted) {
+		middle = deps.fg("muted", "waiting for code");
+	}
+
+	return [prefix, ...(middle ? [middle] : []), suffix].join(separator);
+}
+
+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 ␍.
+	return text
+		.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+		.replace(/\x1b/g, "␛")
+		.replace(/\r/g, "␍")
+		.replace(/\t/g, "    ")
+		.replace(/[\x00-\x08\x0b-\x0c\x0e-\x1f\x7f-\x9f]/g, "�");
+}
+
+type PreviewEntry = { kind: "line"; line: string } | { kind: "hidden"; hidden: number };
+
+/** Head/tail truncation with a hidden-line marker, adapted from pi-fabric. */
+function selectPreviewLines(lines: string[], limit: number): PreviewEntry[] {
+	const lineEntry = (line: string): PreviewEntry => ({ kind: "line", line });
+	if (lines.length <= limit || limit <= 0) return lines.map(lineEntry);
+	if (limit < 8) return [...lines.slice(0, limit).map(lineEntry), { kind: "hidden", hidden: lines.length - limit }];
+	const head = Math.ceil(limit * 0.65);
+	const tail = Math.max(1, limit - head - 1);
+	return [
+		...lines.slice(0, head).map(lineEntry),
+		{ kind: "hidden", hidden: lines.length - head - tail },
+		...lines.slice(-tail).map(lineEntry),
+	];
+}
+
+function addWrapped(
+	lines: string[],
+	prefix: string,
+	text: string,
+	width: number,
+	deps: RenderDeps,
+	options: { sanitize?: boolean } = {},
+): 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, ""));
+	}
+}
+
+function renderCode(state: ExecuteRenderState, lines: string[], width: number, deps: RenderDeps): boolean {
+	const code = state.code.trimEnd();
+	if (!code) return false;
+	lines.push("");
+	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.
+		addWrapped(lines, prefix, highlighted[index] ?? rawLine, width, deps, { sanitize: false });
+	}
+	return true;
+}
+
+const MAX_OUTPUT_LINES = 50;
+
+function renderOutput(
+	state: ExecuteRenderState,
+	lines: string[],
+	width: number,
+	hasCode: boolean,
+	deps: RenderDeps,
+): void {
+	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.
+	const sections: Array<{ text: string | undefined; color: string; label: string }> = [
+		{ text: details?.stdout, color: "toolOutput", label: "stdout" },
+		{ text: details?.stderr, color: "warning", label: "stderr" },
+		{ text: details?.result, color: "accent", label: "result" },
+	];
+	let renderedText = false;
+	for (const { text, color, label } of sections) {
+		if (!text?.trim()) continue;
+		renderedText = true;
+		output.push(` ${OUTPUT_INDENT}${deps.fg("dim", `${label}:`)}`);
+		for (const line of text.split("\n")) {
+			const safe = sanitizeTuiOutput(line || " ");
+			addWrapped(output, OUTPUT_INDENT, deps.fg(color, safe), width, deps, { sanitize: false });
+		}
+	}
+
+	if (!renderedText && !details && state.contentText?.trim()) {
+		renderedText = true;
+		const color = state.isError ? "error" : "toolOutput";
+		for (const line of state.contentText.trim().split("\n")) {
+			const safe = sanitizeTuiOutput(line || " ");
+			addWrapped(output, OUTPUT_INDENT, deps.fg(color, safe), width, deps, { sanitize: false });
+		}
+	}
+
+	if (details?.errorStack && details.errorStack.length > 0) {
+		output.push(` ${OUTPUT_INDENT}${deps.fg("dim", "traceback:")}`);
+		for (const line of details.errorStack) {
+			const safe = sanitizeTuiOutput(line || " ");
+			addWrapped(output, OUTPUT_INDENT, deps.fg("error", safe), width, deps, { sanitize: false });
+		}
+	}
+
+	if (!renderedText) {
+		const message = state.isPartial || statusKind(state) === "running" ? "waiting for output..." : "no output";
+		addWrapped(output, OUTPUT_INDENT, deps.fg("muted", message), width, deps, { sanitize: false });
+	}
+
+	const entries = selectPreviewLines(output, MAX_OUTPUT_LINES);
+	if (entries.length > 0 && hasCode) lines.push("");
+	for (const entry of entries) {
+		if (entry.kind === "hidden") {
+			const marker = ` … ${entry.hidden} line${entry.hidden === 1 ? "" : "s"} hidden … `;
+			lines.push(` ${OUTPUT_INDENT}${deps.fg("muted", marker)}`);
+		} else {
+			lines.push(entry.line);
+		}
+	}
+}
+
+/** Paint the status-matched panel background across the row, surviving inner SGR resets. */
+export function paintBackground(line: string, width: number, kind: StatusKind, deps: RenderDeps): string {
+	const bgAnsi = deps.getBgAnsi(backgroundFor(kind));
+	const padded = line + " ".repeat(Math.max(0, width - deps.visibleWidth(line)));
+	const rearmed = padded.replaceAll("\x1b[0m", `\x1b[0m${bgAnsi}`);
+	return `${bgAnsi}${rearmed}\x1b[0m`;
+}
+
+export function renderExecuteHeader(state: ExecuteRenderState, width: number, deps: RenderDeps): string[] {
+	const safeWidth = Math.max(1, width);
+	const line = deps.truncateToWidth(` ${topLine(state, safeWidth, deps)}`, safeWidth, "");
+	const kind = statusKind(state);
+	return [paintBackground(line, safeWidth, kind, deps)];
+}
+
+export function renderExecuteBody(state: ExecuteRenderState, width: number, deps: RenderDeps): string[] {
+	if (!state.expanded) return [];
+	const safeWidth = Math.max(1, width);
+	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));
+}
+
+export function renderExecuteCell(state: ExecuteRenderState, width: number, deps: RenderDeps): string[] {
+	return [...renderExecuteHeader(state, width, deps), ...renderExecuteBody(state, width, deps)];
+}

package/src/extension/render.ts

@@ -0,0 +1,93 @@
+/**
+ * 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.
+ */
+
+import { highlightCode, keyHint, keyText, rawKeyHint, type Theme } from "@mariozechner/pi-coding-agent";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+import {
+	type BgKind,
+	type ExecuteRenderState,
+	type RenderDeps,
+	renderExecuteBody,
+	renderExecuteCell,
+	renderExecuteHeader,
+	statusKind,
+} from "./render-core.js";
+
+export type { ExecuteDetails, ExecuteRenderState } from "./render-core.js";
+
+function makeDeps(theme: Theme): RenderDeps {
+	return {
+		fg: (color, text) => theme.fg(color as Parameters<Theme["fg"]>[0], text),
+		getBgAnsi: (bg: BgKind) => theme.getBgAnsi(bg),
+		highlight: (code) => highlightCode(code, "python"),
+		keyHint: (expanded) => {
+			const text = expanded ? "to collapse" : "to expand";
+			const key = keyText("app.tools.expand");
+			return key ? keyHint("app.tools.expand", text) : rawKeyHint("ctrl+o", text);
+		},
+		visibleWidth,
+		truncateToWidth,
+		wrapTextWithAnsi,
+	};
+}
+
+/**
+ * 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).
+ */
+function renderVersion(state: ExecuteRenderState): string {
+	const details = state.details ? JSON.stringify(state.details) : "";
+	return [
+		state.code.length,
+		state.contentText?.length ?? 0,
+		details.length,
+		state.isPartial,
+		state.isError,
+		state.expanded,
+		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,
+	].join("|");
+}
+
+export class ExecuteCellComponent {
+	private readonly deps: RenderDeps;
+	private cachedKey = "";
+	private cachedWidth = -1;
+	private cachedLines?: string[];
+
+	constructor(
+		private readonly state: ExecuteRenderState,
+		theme: Theme,
+		private readonly mode: "cell" | "header" | "body" = "cell",
+	) {
+		this.deps = makeDeps(theme);
+	}
+
+	invalidate(): void {
+		this.cachedLines = undefined;
+	}
+
+	render(width: number): string[] {
+		const key = `${renderVersion(this.state)}|${this.mode}`;
+		if (this.cachedLines && this.cachedWidth === width && this.cachedKey === key) {
+			return this.cachedLines;
+		}
+		const lines =
+			this.mode === "header"
+				? renderExecuteHeader(this.state, width, this.deps)
+				: this.mode === "body"
+					? renderExecuteBody(this.state, width, this.deps)
+					: renderExecuteCell(this.state, width, this.deps);
+		this.cachedKey = key;
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+}

package/src/extension/session-engine.ts

@@ -0,0 +1,155 @@
+// A session may get teardown without session_start on reload, so revival is part of create() (was a real defect)
+
+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.
+ */
+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`;
+}
+
+/** The part of EngineManager this lifecycle needs; narrowed so tests can fake it. */
+export interface RevivableEngine {
+	restoreState(): Promise<RestoreResult | null>;
+}
+
+export interface EngineLifecycleDeps<E extends RevivableEngine> {
+	/** Builds a fresh engine. Called at most once per lifecycle generation. */
+	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.
+	 */
+	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.
+ */
+export type AcquireOrigin = "startup" | "cell";
+
+function formatEngineResetNotice(restore: RestoreResult | null): string {
+	const lines = ["<rlm_engine_reset>"];
+	if (!restore) {
+		// --- no snapshot at all: namespace is genuinely empty ---
+		lines.push(
+			"The evaluator restarted and its namespace is empty; no snapshot was available to revive.",
+			"Every variable from earlier in this session is gone. Rebuild what you need before using it.",
+		);
+	} else if (restore.restored.length === 0) {
+		// --- a snapshot existed but restored nothing; say why, don't claim "no snapshot" ---
+		lines.push(
+			"The evaluator restarted and a snapshot was found, but nothing in it could be revived.",
+			restore.failed.length > 0
+				? `Failed to revive (${restore.failed.length}): ${summarizeNames(
+						restore.failed.map((f) => f.name),
+						20,
+					)}`
+				: "The snapshot was empty.",
+			"Every variable from earlier in this session is gone. Rebuild what you need before using it.",
+		);
+	} else {
+		lines.push(
+			"The evaluator restarted. Its namespace was rebuilt from the last snapshot, so it may be behind.",
+			`Revived (${restore.restored.length}): ${summarizeNames(restore.restored, 20)}`,
+		);
+		if (restore.failed.length > 0) {
+			lines.push(
+				`Lost (${restore.failed.length}): ${summarizeNames(
+					restore.failed.map((f) => f.name),
+					20,
+				)}`,
+				"Functions, classes, and live handles cannot be snapshotted; redefine them.",
+			);
+		}
+		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>");
+	return lines.join("\n");
+}
+
+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. */
+	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.
+	 */
+	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;
+				return { engine: held, restore: await this.revival!, created: false };
+			}
+			const engine = this.deps.create();
+			this.engine = engine;
+			this.revival = engine.restoreState().catch(() => null);
+			const restore = await this.revival;
+			if (origin === "cell") this.pendingNotice = formatEngineResetNotice(restore);
+			return { engine, restore, created: true };
+		})();
+		this.acquiring = build;
+		try {
+			return await build;
+		} finally {
+			if (this.acquiring === build) this.acquiring = undefined;
+		}
+	}
+
+	/** Returns the pending reset notice exactly once, then clears it. */
+	takeResetNotice(): string | undefined {
+		const notice = this.pendingNotice;
+		this.pendingNotice = undefined;
+		return notice;
+	}
+
+	async shutdown(): Promise<void> {
+		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.
+	 */
+	async discard(): Promise<void> {
+		await this.teardownWith((engine) => (this.deps.discard ?? this.deps.dispose)(engine));
+	}
+
+	private async teardownWith(run: (engine: E) => Promise<void>): Promise<void> {
+		const engine = this.engine;
+		this.engine = undefined;
+		this.revival = undefined;
+		this.pendingNotice = undefined;
+		if (!engine) return;
+		const teardown = run(engine).finally(() => {
+			if (this.teardown === teardown) this.teardown = undefined;
+		});
+		this.teardown = teardown;
+		await teardown;
+	}
+}

package/src/extension/tool-meta.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+
+import { buildToolboxMap } from "./toolbox.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_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.",
+	];
+}