pi-repl-py 0.6.14 → 0.7.1

package/src/extension/render-core.ts

@@ -114,12 +114,7 @@ function marker(state: ExecuteRenderState, deps: RenderDeps): string {
 	}
 }
 
-/**
- * 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.
- */
+/** highlight.js emits no scope for bare Python identifiers — re-color only raw runs outside colored spans. */
 function colorBareIdentifiers(line: string, paint: (id: string) => string): string {
 	if (!line.includes("\x1b") && !/[a-zA-Z_]/.test(line)) return line;
 	const out: string[] = [];
@@ -160,7 +155,6 @@ function colorBareIdentifiers(line: string, paint: (id: string) => string): stri
 			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++;
@@ -242,9 +236,7 @@ function sanitizeTuiOutput(text: string): string {
 		.replace(/[\x00-\x08\x0b-\x0c\x0e-\x1f\x7f-\x9f]/g, "�");
 }
 
-/** Wrap a ready-colored span into `lines`: first row takes the prefix, wrapped
- * continuations take indent (and an optional extra indent), each row is
- * truncated to pane width and closed if it ends on an open SGR color. */
+/** Wrap a colored span: first row takes the prefix, continuations the indent; truncate to width and close open SGR colors. */
 function pushWrappedLines(
 	lines: string[],
 	prefix: string,
@@ -306,12 +298,7 @@ function renderCode(state: ExecuteRenderState, lines: string[], width: number, d
 	return true;
 }
 
-/**
- * Streaming output is append-only, so a wrapped blob only changes at its tail.
- * The cache lives on the (persistent) state object via a WeakMap, letting an
- * updated body re-wrap just the appended delta: O(chunk) instead of O(output).
- * Fresh states (unit tests, first render) fall back to a full wrap.
- */
+/** Output is append-only: the cached wrap re-wraps just the tail — O(chunk) instead of O(output). */
 interface BlobWrapEntry {
 	text: string;
 	color: string;
@@ -321,20 +308,14 @@ interface BlobWrapEntry {
 }
 
 const blobWrapCache = new WeakMap<ExecuteRenderState, Map<number, BlobWrapEntry>>();
-/** Wrapped+highlighted rows rebuild only when their inputs (text/width) change; the
- * TUI re-renders bodies on every frame, so these caches turn per-frame work into
- * one build per change. They live on the persistent per-call state, which the host
- * keeps for the session, so a small bound per state keeps resize churn bounded. */
+/** Row caches keyed by text/width turn per-frame renders into one build per change; bounded per state against resize churn. */
 interface CodeEntry {
 	code: string;
 	lines: string[];
 }
 const codeWrapCache = new WeakMap<ExecuteRenderState, Map<number, CodeEntry>>();
 
-/** Window resizes add a per-width entry per cell; keep a small bound so a long
- * session with resize churn cannot grow the wrap caches without limit. Map
- * iteration order is insertion order, so evicting the first key drops the oldest
- * width rather than the one in use. */
+/** Bound per-width cache entries; insertion order evicts the oldest width first. */
 const MAX_CACHED_WIDTHS_PER_STATE = 3;
 function boundWidthCache(perWidth: Map<number, unknown>): void {
 	while (perWidth.size >= MAX_CACHED_WIDTHS_PER_STATE) {
@@ -352,9 +333,7 @@ function widthOf(ch: string): number {
 	return code < 0x80 ? 1 : CJK_WIDE_RE.test(ch) ? 2 : 1;
 }
 
-/** Fast single-pass word wrap for ANSI-free text: pi-tui's ANSI-aware wrap is
- * ~45ms on a 45K blob; sanitized output needs no ANSI handling, so this splits
- * at spaces with an O(width) scan per row and hard-breaks overlong words. */
+/** Fast word wrap for sanitized text: pi-tui's ANSI-aware wrap costs ~45ms on a 45K blob. */
 function wrapPlainText(text: string, width: number): string[] {
 	if (width <= 0 || text.length <= width) return [text];
 	// --- fast path: pure ASCII, break by char index ---
@@ -430,8 +409,7 @@ function wrapPlainText(text: string, width: number): string[] {
 	return rows;
 }
 
-/** Wrap a raw output line exactly the way the section loops did: sanitize, wrap (fast),
- * then colorize row-by-row so the color span never bleeds across rows. */
+/** Sanitize → fast wrap → colorize rows, so an SGR span never bleeds across rows. */
 function wrapRawOutputLine(lines: string[], raw: string, color: string, width: number, deps: RenderDeps): string[] {
 	const before = lines.length;
 	const safe = sanitizeTuiOutput(raw || " ");
@@ -517,8 +495,7 @@ 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 ---
+		// --- a traceback IS output: without this, a pure-traceback error cell also rendered "no output" below it ---
 		renderedText = true;
 		output.push(` ${OUTPUT_INDENT}${deps.fg("dim", "traceback:")}`);
 		for (const line of details.errorStack) {
@@ -532,10 +509,7 @@ 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.) ---
+	// --- the panel always ends with one blank row: streams end with a newline, tracebacks and placeholders don't ---
 	const lastRow = output[output.length - 1];
 	if (lastRow !== undefined && lastRow.replace(SGR_PATTERN, "").trim() !== "") output.push("");
 
@@ -544,7 +518,6 @@ function renderOutput(
 	lines.push(...output);
 }
 
-/** 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)));

package/src/extension/render.ts

@@ -30,10 +30,7 @@ function makeDeps(theme: Theme): RenderDeps {
 	};
 }
 
-/** O(1) key: a host-bumped dirty counter plus mode state. `withSpinner` folds
- * the animation frame so the header alone animates while running; the body key
- * excludes it, so a running cell only redraws when output actually changes
- * instead of re-wrapping the whole body every 120ms. */
+/** O(1) body key excludes the spinner frame, so a running cell redraws only when output changes, not every 120ms. */
 function renderVersion(state: ExecuteRenderState, withSpinner: boolean): string {
 	const spinner = withSpinner && statusKind(state) === "running" ? Math.floor(Date.now() / 120) % 4 : -1;
 	return `${state.version ?? 0}|${state.expanded}|${spinner}`;

package/src/extension/session-engine.ts

@@ -1,8 +1,6 @@
-// The lifecycle owns boot, session binding, and the reset announcements. Recovery is a
-// background engine job (the quiet-gap restore): the first tool call waits only for the
-// kernel to come up, and the reset notice lands on the first cell AFTER the restore lands.
+// Lifecycle: boot, session binding, reset announcements. Recovery is a background quiet-gap job; the notice lands on the first cell after the restore.
 
-import type { RestoreResult } from "../engine/index.js";
+import type { HelperLoadResult, RestoreResult } from "../engine/index.js";
 
 /** Show enough names to orient, then count the rest (a revive can carry hundreds). */
 function summarizeNames(names: readonly string[], limit: number): string {
@@ -14,8 +12,7 @@ function summarizeNames(names: readonly string[], limit: number): string {
 export interface RevivableEngine {
 	/** Boot the kernel (and preload helpers), independent of snapshot recovery. */
 	start(skipRestore?: boolean): Promise<void>;
-	/** Resolves once this engine's recovery has settled: revived names, or null when there was
-	 * nothing to revive, recovery was skipped, or recovery failed. Never rejects. */
+	/** Recovery outcome: revived names, or null when nothing to revive / skipped / failed. Never rejects. */
 	restoreResult(): Promise<RestoreResult | null>;
 	/** True when recovery was deliberately skipped (a prior revive wedged). */
 	restoreWasSkipped(): boolean;
@@ -24,25 +21,21 @@ export interface RevivableEngine {
 }
 
 export interface EngineLifecycleDeps<E extends RevivableEngine> {
-	/** Builds a fresh engine. Called at most once per lifecycle generation; `skipRestore` is
-	 * true on the retry after a wedged boot, so the poisoned snapshot cannot wedge twice. */
+	/** Fresh engine; skipRestore is the retry after a wedged boot, so a poisoned snapshot can't wedge twice. */
 	create(skipRestore?: boolean): E;
 	/** Tears the current engine down, flushing its final snapshot. */
 	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) that outlives it is killed
-	 * and retried fresh. Default 90s. Recovery is NOT inside this deadline: it runs in the
-	 * background and is bounded by the engine's own restore-cell watchdog. */
+	/** Boot deadline (default 90s): an overlong boot is killed and retried. Recovery is outside it — background, bounded by the restore-cell watchdog. */
 	bootTimeoutMs?: number;
 }
 
-/** `startup` restores then announces when the conversation has a saved past; `cell` means an engine was rebuilt mid-session and announces immediately. */
+/** startup: announce when the conversation has a saved past; cell: a mid-session rebuild 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
@@ -50,9 +43,7 @@ function revivedNoticeBody(origin: AcquireOrigin): string {
 		: "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. ---
+// --- human toast, separate from the model marker; counts come from the same restore, so the two never disagree ---
 export function formatResetToast(origin: AcquireOrigin, restore: RestoreResult | null, wedged = false): string {
 	const resumed = origin === "startup";
 	const verb = resumed ? "repl session resumed" : "repl kernel rebuilt";
@@ -118,22 +109,48 @@ function formatEngineResetNotice(restore: RestoreResult | null, origin: AcquireO
 	return lines.join("\n");
 }
 
+/** Human toast when a /fork'd conversation inherited its parent's namespace — same counts as the reset marker, named as a fork so it can't pass for a plain resume. */
+export function formatForkToast(restore: RestoreResult | null): string {
+	const revived = restore?.restored.length ?? 0;
+	if (revived > 0) {
+		const noun = revived === 1 ? "name" : "names";
+		return `repl fork started — ${revived} ${noun} inherited from the parent session`;
+	}
+	return restore === null
+		? "repl fork started — nothing to inherit"
+		: "repl fork started — parent snapshot revived nothing";
+}
+
+// --- split audience: toast for the human whenever a boot preloaded anything; a marker for the model ONLY when a helper failed (all-good boots are silent) ---
+
+export function formatHelperToast(report: readonly HelperLoadResult[]): string {
+	const loaded = report.filter((h) => h.ok).map((h) => h.name);
+	const failed = report.filter((h) => !h.ok);
+	const loadedPart = loaded.length > 0 ? `helpers loaded: ${loaded.join(", ")}` : "no helpers loaded";
+	const failedPart =
+		failed.length > 0 ? ` · failed: ${failed.map((f) => `${f.name} (${f.error ?? "failed to load"})`).join(", ")}` : "";
+	return `repl ${loadedPart}${failedPart}`;
+}
+
+export function formatHelperFailuresLine(report: readonly HelperLoadResult[] | null): string | undefined {
+	if (!report) return undefined;
+	const failed = report.filter((h) => !h.ok);
+	if (failed.length === 0) return undefined;
+	return `<repl_helpers_failed: ${failed.map((f) => `${f.name} (${f.error ?? "failed to load"})`).join(", ")}>`;
+}
+
 export class EngineLifecycle<E extends RevivableEngine> {
 	private engine?: E;
 	private pendingNotice?: string;
 	private pendingReset?: { origin: AcquireOrigin; restore: RestoreResult | null; wedged: boolean };
 	private teardown?: Promise<void>;
-	/** First-build in progress. */
 	private acquiring?: Promise<{ engine: E; restore: RestoreResult | null; created: boolean }>;
 	/** The conversation this engine was built for; a different key on acquire tears it down. */
 	private boundKey?: string;
 
 	constructor(private readonly deps: EngineLifecycleDeps<E>) {}
 
-	/** Race one BOOT attempt (kernel start + helpers preload) against the deadline. Recovery is
-	 * deliberately outside this race: it runs as a background quiet-gap job and is bounded by the
-	 * engine's own restore-cell watchdog. A failed start is soft — the first cell observes it and
-	 * the caller rebuilds. */
+	/** Race one boot (kernel start + helpers preload) against the deadline; a failed start is soft — the first cell observes it and rebuilds. */
 	private bootOnce(engine: E, deadlineMs: number): Promise<boolean> {
 		const work = Promise.resolve()
 			.then(() => engine.start(false))
@@ -146,16 +163,7 @@ export class EngineLifecycle<E extends RevivableEngine> {
 		return Promise.race([work.then(() => true), guard]).finally(() => clearTimeout(timer));
 	}
 
-	/**
-	 * Built and booted on demand; the snapshot restore proceeds in the background, so acquire()
-	 * NEVER waits on it. The engine's revive is announced (reset notice + toast) on the first
-	 * cell after it completes.
-	 *
-	 * `sessionKey` guards against sessions bleeding into each other: pi tears the old session
-	 * down before starting the next, but a missed or out-of-order shutdown must never serve one
-	 * conversation's engine and namespace to another — acquire for a different key tears the
-	 * bound engine down (flushing its snapshot) before building the new one.
-	 */
+	/** Built on demand; acquire() never waits on the background restore (announced on the first cell after it completes). sessionKey: a different conversation's acquire tears the bound engine down, so sessions can't bleed into each other. */
 	async acquire(
 		origin: AcquireOrigin,
 		sessionKey?: string,
@@ -179,8 +187,7 @@ export class EngineLifecycle<E extends RevivableEngine> {
 			this.engine = engine;
 			let booted = await this.bootOnce(engine, deadline);
 			if (!booted) {
-				// --- the kernel is alive but stuck; only a kill frees it. Retry once WITHOUT the
-				// --- snapshot, so a poisoned snapshot cannot wedge the session twice in a row. ---
+				// --- the kernel is stuck, not dead; kill and retry once WITHOUT the snapshot so a poisoned one can't wedge twice ---
 				await (this.deps.discard ?? this.deps.dispose)(engine);
 				engine = this.deps.create(true);
 				this.engine = engine;
@@ -192,11 +199,7 @@ export class EngineLifecycle<E extends RevivableEngine> {
 					throw new Error("evaluator boot timed out twice (kernel/helpers wedged); no session was started");
 				}
 			}
-			// --- recovery is async and off the first call's critical path: the engine revives in
-			// --- the first quiet gap and the notice lands on the first cell AFTER it completes
-			// --- (index.ts takes it with takeResetNotice after the next execute). announce when
-			// --- mid-session rebuilds happen, or on startup for a conversation with a saved past;
-			// --- a first-ever session stays quiet. ---
+			// --- the notice lands on the first cell AFTER the restore completes; announce mid-session rebuilds and resumes with a saved past, never first sessions ---
 			const announce = origin === "cell" || (origin === "startup" && engine.hasSnapshotHistory());
 			void engine.restoreResult().then((restore) => {
 				if (this.engine !== engine) return; // a replacement engine took over; no stale notice
@@ -222,8 +225,7 @@ export class EngineLifecycle<E extends RevivableEngine> {
 		}
 	}
 
-	/** Returns the pending reset notice exactly once (alongside its origin, restore result, and
-	 * whether the restore was skipped), then clears it. */
+	/** The pending reset notice, taken exactly once. */
 	takeResetNotice():
 		| { notice: string; origin: AcquireOrigin; restore: RestoreResult | null; wedged: boolean }
 		| undefined {

package/src/extension/skill-hook.ts

@@ -1,5 +1,4 @@
-// --- skills cannot reach the prompt in --repl: pi gates <available_skills> on the read tool
-// (hasRead), which repl doesn't have. Re-emit them with pi's own formatter in pi's slot. ---
+// --- pi gates skills on the read tool (absent in repl); re-emit them with pi's own formatter in pi's slot ---
 import { formatSkillsForPrompt, type Skill } from "@mariozechner/pi-coding-agent";
 
 const CWD_MARKER = "\nCurrent working directory:"; // skills sit just before this, pi's last line

package/src/extension/state-layout.ts

@@ -1,34 +1,21 @@
-// --- where a conversation's kernel state lives: ~/.pi/agent/pi-repl/state/<key>.
-// --- Keys must never collide across conversations, so the project-root slug joins the
-// --- conversation name. Pre-slug legacy dirs (bare name) migrate to the slug key on the
-// --- owning conversation's next start; the orphan sweep still recognizes both formats,
-// --- so nothing live is ever swept and a deleted conversation loses all its snapshots. ---
-import { existsSync, renameSync } from "node:fs";
+// --- state lives at ~/.pi/agent/pi-repl/state/<slug>__<conv>: legacy bare-name dirs migrate on the owning conversation's next start, and the sweep knows both formats, so nothing live is swept and a deleted conversation loses its snapshots ---
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
-/** The conversation's own name: the session file's basename without .jsonl (unique per conversation). */
 export function conversationName(sessionFile: string): string {
 	return basename(sessionFile).replace(/\.jsonl$/, "");
 }
 
-/** Slug-keyed state dir name: unique among all conversations under one sessions root, so two
- * conversations whose files happen to share a basename (copied/renamed session files) can never
- * share a snapshot. */
+/** Slug-keyed dir name: conversations whose files share a basename can never share a snapshot. */
 export function sessionStateDirName(sessionFile: string): string {
 	return `${basename(dirname(sessionFile))}__${conversationName(sessionFile)}`;
 }
 
-/** The pre-slug dir name; still honored when migrating or scanning live conversations. */
 function legacyStateDirName(sessionFile: string): string {
 	return conversationName(sessionFile);
 }
 
-/**
- * Resolve a conversation's state dir and snapshot file, migrating a legacy bare-name dir to the
- * slug key on first start. Two conversations whose files share a basename therefore never share a
- * snapshot file: whichever starts first migrates the legacy dir to its own key; the other starts
- * empty rather than bleeding into the first's namespace.
- */
+/** Resolve the state dir, migrating a legacy bare-name dir on first start — whichever conversation starts first owns the legacy dir; the other starts empty. */
 export function resolveStateDir(stateRoot: string, sessionFile: string): { dir: string; snapshotPath: string } {
 	const dir = join(stateRoot, sessionStateDirName(sessionFile));
 	const legacy = join(stateRoot, legacyStateDirName(sessionFile));
@@ -43,3 +30,29 @@ export function resolveStateDir(stateRoot: string, sessionFile: string): { dir:
 	}
 	return { dir, snapshotPath: join(dir, "namespace.snapshot") };
 }
+
+/** The /fork header's parentSession -> the parent's own snapshot file, when the fork has no history yet. */
+export function forkParentSnapshot(stateRoot: string, sessionFile: string, snapshotPath: string): string | undefined {
+	if (existsSync(snapshotPath)) return undefined; // the fork already built its own history
+	let header: { parentSession?: unknown };
+	try {
+		const first = readFileSync(sessionFile, "utf8").split("\n", 1)[0] ?? "";
+		header = JSON.parse(first) as { parentSession?: unknown };
+	} catch {
+		return undefined; // unreadable / not a session file — not a fork
+	}
+	if (typeof header.parentSession !== "string" || header.parentSession === "") return undefined;
+	const parent = resolveStateDir(stateRoot, header.parentSession);
+	return existsSync(parent.snapshotPath) ? parent.snapshotPath : undefined;
+}
+
+/** Copy the parent's last snapshot into the fork's own key once (true when something was inherited); the fork then restores like any resume, and the parent is never touched. */
+export function inheritForkSnapshot(stateRoot: string, sessionFile: string, snapshotPath: string): boolean {
+	const parentSnap = forkParentSnapshot(stateRoot, sessionFile, snapshotPath);
+	if (parentSnap === undefined) return false;
+	mkdirSync(dirname(snapshotPath), { recursive: true });
+	const tmp = `${snapshotPath}.tmp`;
+	copyFileSync(parentSnap, tmp);
+	renameSync(tmp, snapshotPath);
+	return true;
+}

package/src/extension/tool-meta.ts

@@ -1,15 +1,8 @@
-// --- 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 { buildHelpersMap, buildHelpersMapForCwd } from "./helpers.js";
 import { buildPromptGuidelines, executePromptSnippet, executeToolDescription } from "./prompt.js";
 
 export const EXECUTE_DESCRIPTION = executeToolDescription;
 export const EXECUTE_PROMPT_SNIPPET = executePromptSnippet;
 
-// --- build the guidelines from project + global helper dirs ---
-export function buildExecutePromptGuidelines(cwd?: string): string[] {
-	const map = cwd ? buildHelpersMapForCwd(cwd) : buildHelpersMap();
-	const preloaded = map.length > 0 ? map : [];
-	return buildPromptGuidelines(preloaded);
+export function buildExecutePromptGuidelines(): string[] {
+	return buildPromptGuidelines([]);
 }