pi-repl-py 0.6.14 → 0.7.0

package/docs/ARCHITECTURE.md

@@ -107,9 +107,11 @@ mid-session rebuild (kernel death) forces the restore before the cell that found
 Functions and classes defined in cells are captured by source and re-executed on restore (plain
 pickle cannot revive them in `__main__`); bindings that still fail are reported by name, never
 dropped silently. Entries are capped per-binding and in total (128 MiB default); the file is
-written via temp-file-and-rename so a crash cannot corrupt the last good copy; session dirs are
+written via temp-file-and-rename so a crash cannot corrupt the last good copy; a binding skipped
+at save time is named in the resume notice, never dropped silently, and a failed snapshot leaves
+the retry gate in place (only a persisted write advances it); a periodic refresh (default 2 min, `snapshot.periodMs`, 0 disables) bounds the loss window for same-name mutations and stands down when the last snapshot exceeded 8 MiB; value entries are zlib-compressed (file format version 3 — v1/v2 files remain restorable); session dirs are
 pruned to the newest 25, and dirs whose conversation file no longer exists are swept entirely —
-deleting a conversation deletes its snapshots. "ephemeral" and the live session are exempt.
+deleting a conversation deletes its snapshots. "ephemeral" and the live session are exempt. A /fork'd conversation inherits the parent's last snapshot — copied once into the fork's own key at first start, so it resumes with state, carries the standard reset marker on its first cell, and the human gets a dedicated fork toast; the parent is untouched.
 
 A revive that never completes (a poisoned pickle) is bounded by an engine restore-cell watchdog
 (`PI_REPL_BOOT_TIMEOUT_MS`, default 90s): the kernel is killed and the restore marked skipped —

package/docs/helpers.md

@@ -79,6 +79,10 @@ A helper may define `helper_description`:
 helper_description = """double(x) — multiply a value by two."""
 ```
 
+The value must be a **triple-quoted string** (`"""..."""` or `'''...'''`): a plain-quoted
+assignment is not recognized, and the helper is advertised with a pointer text telling the
+model to inspect it (`print(double.__doc__)`) instead.
+
 The host reads this value and puts it in the `execute` tool description verbatim. It is guidance for the model, not a registration mechanism or generated API. Keep it short: it
 is included in the model's context on every turn.
 
@@ -127,6 +131,15 @@ At startup, two parts of pi-repl read the same merged helper list (project dirs
 1. The kernel executes each eligible `.py` file. Its definitions become names in the Python workspace.
 2. The host reads `helper_description` to build the helper guidance shown to the model.
 
+Both resolve the list from the **session's working directory** (not the folder pi was launched
+from), so a resumed session advertises exactly the helpers its kernel loads. The per-session
+list is rebuilt at every agent start and stated in the system prompt.
+
+Each helper file executes in its **own cell**, so a broken helper (a syntax error or a top-level
+raise) fails alone and does not stop the others. When a helper fails to load, the next cell's
+output carries a `<repl_helpers_failed: name (error)>` line, and you get a toast; an
+all-good boot stays silent.
+
 The host does not inspect `def` lines or infer signatures from filenames. A helper does not need to define one particular symbol. The file is the unit of loading; its public names are the names it defines or imports for use in
 the workspace.
 

package/index.ts

@@ -5,10 +5,11 @@ import { homedir } from "node:os";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import { withSkillsBlock } from "./src/extension/skill-hook.js";
+import { buildHelpersPromptSection } from "./src/extension/helpers.js";
 import { EngineManager, pruneOrphanedSnapshotDirs, pruneSnapshotDirs } from "./src/engine/index.js";
 import { ExecuteCellComponent, type ExecuteDetails, type ExecuteRenderState } from "./src/extension/render.js";
-import { EngineLifecycle, formatResetToast } from "./src/extension/session-engine.js";
-import { conversationName, resolveStateDir } from "./src/extension/state-layout.js";
+import { EngineLifecycle, formatForkToast, formatHelperFailuresLine, formatHelperToast, formatResetToast } from "./src/extension/session-engine.js";
+import { conversationName, inheritForkSnapshot, resolveStateDir } from "./src/extension/state-layout.js";
 import { EXECUTE_DESCRIPTION, buildExecutePromptGuidelines, EXECUTE_PROMPT_SNIPPET } from "./src/extension/tool-meta.js";
 
 const executeSchema = Type.Object({
@@ -59,44 +60,38 @@ export default function (pi: ExtensionAPI) {
 	const pendingErrorResults = new Map<string, { details: ExecuteDetails }>();
 
 	const lifecycle = new EngineLifecycle<EngineManager>({
-		// --- boot deadline: bounds kernel start + helpers preload (recovery is a background
-		// --- quiet-gap job, bounded by the engine's own restore-cell watchdog). An npm update
-		// --- swaps the venv and helpers under a live kernel, and the first boot after it can
-		// --- wedge; without this the first cell hangs forever, because acquire() dedupes onto
-		// --- the same hung boot. ---
+		// --- bound the boot: a wedged first boot would hang every cell (acquire() dedupes onto it) ---
 		bootTimeoutMs: Number(process.env.PI_REPL_BOOT_TIMEOUT_MS ?? 90_000) || 90_000,
 		create(skipRestore = false) {
 			const { cwd, sessionFile } = location;
-			// --- kernel namespace state lives under ~/.pi/agent/pi-repl/state, keyed by
-			// --- <project-slug>__<conversation>, so it never clutters the project and two
-			// --- conversations can never share a snapshot dir (resolveStateDir migrates any
-			// --- pre-slug legacy dir on start). Ephemeral sessions get no snapshot at all. ---
+			// --- state lives under ~/.pi/agent/pi-repl/state/<slug>__<conv>; conversations never share a snapshot; ephemeral sessions get none ---
 			const stateRoot = join(homedir(), ".pi", "agent", "pi-repl", "state");
 			let snapshot: { path: string } | undefined;
+			let forkInherited = false;
 			let currentDir: string | undefined;
 			if (sessionFile) {
 				const { dir, snapshotPath } = resolveStateDir(stateRoot, sessionFile);
 				currentDir = basename(dir);
 				snapshot = { path: snapshotPath };
+				// --- a /fork'd conversation inherits the parent's last namespace (copied once into the fork's own key) ---
+				try {
+					forkInherited = inheritForkSnapshot(stateRoot, sessionFile, snapshotPath);
+				} catch {}
 				// --- keep the state root from growing one dir per session forever; the live dir is exempt ---
 				try {
 					pruneSnapshotDirs(stateRoot, 25, currentDir);
 				} catch {}
-				// --- cascade deletions: if a conversation is deleted, its snapshots die with it.
-				// --- sessionFile is sessions/<project-root>/<name>.jsonl, so the sessions root is
-				// --- two parent hops up; dirs whose conversation file exists in no project root
-				// --- (and that aren't this session or the ephemeral fallback) are swept, in both
-				// --- the legacy bare-name and slug-keyed formats. ---
+				// --- sweep state dirs whose conversation file exists in no project root: deleting a conversation deletes its snapshots (both dir formats) ---
 				try {
 					pruneOrphanedSnapshotDirs(stateRoot, sessionFile ? dirname(dirname(sessionFile)) : undefined, currentDir);
 				} catch {}
 			}
 			return new EngineManager({
 				cwd,
-				// --- snapshots are keyed to the conversation; ephemeral sessions get none.
-				// --- skipRestore is true on the lifecycle's retry after a wedged boot. ---
+				// --- snapshots are per-conversation; skipRestore marks the wedged-boot retry ---
 				snapshot,
 				skipRestore,
+				forkInherited,
 			});
 		},
 		async dispose(engine) {
@@ -116,15 +111,12 @@ export default function (pi: ExtensionAPI) {
 			pi.setActiveTools(pi.getActiveTools().filter((name) => name !== "execute"));
 			return;
 		}
-		// --- active: the whole surface collapses to the one tool ---
 		pi.setActiveTools(["execute"]);
-		// --- warm the engine (and its revive) in the background; no popup. ---
-		// --- acquire() dedupes, so the first execute awaits this same in-flight boot ---
+		// --- warm the engine in the background; acquire() dedupes, so the first execute awaits this same boot ---
 		location = { cwd: ctx.cwd, sessionFile: ctx.sessionManager.getSessionFile() ?? undefined };
 		const sessionKey = location.sessionFile ? conversationName(location.sessionFile) : undefined;
 		void lifecycle.acquire("startup", sessionKey).catch(() => {
-			// --- boot/revive handled on the execute path; swallow so a background warm can never
-			// --- surface an unhandled rejection. A resume's notice lands on the first cell. ---
+			// --- swallow the warm boot's rejection: boot/revive are handled on the execute path ---
 		});
 	});
 
@@ -141,14 +133,14 @@ export default function (pi: ExtensionAPI) {
 		return { content: event.content, details: stashed.details, isError: true };
 	});
 
-	// --- pi gates skills on the read tool (absent in repl); re-emit them via withSkillsBlock. ---
-	pi.on("before_agent_start", (event) => {
+	// --- pi gates skills on the read tool (absent in repl); the helper roster is rebuilt per session from the session cwd, not the launch cwd, so resumes advertise what the kernel loaded ---
+	pi.on("before_agent_start", (event, ctx) => {
 		if (!active()) return;
-		const systemPrompt = withSkillsBlock(
-			event.systemPrompt,
-			event.systemPromptOptions?.skills ?? [],
-		);
-		return systemPrompt === undefined ? undefined : { systemPrompt };
+		const skillsPrompt = withSkillsBlock(event.systemPrompt, event.systemPromptOptions?.skills ?? []);
+		let systemPrompt = skillsPrompt ?? event.systemPrompt;
+		const helpersBlock = buildHelpersPromptSection(ctx?.cwd ?? process.cwd());
+		if (helpersBlock) systemPrompt = `${systemPrompt}\n\n${helpersBlock}`;
+		return systemPrompt === event.systemPrompt ? undefined : { systemPrompt };
 	});
 
 	pi.registerTool<typeof executeSchema, ExecuteDetails, Partial<ExecuteRenderState>>({
@@ -156,7 +148,7 @@ export default function (pi: ExtensionAPI) {
 		label: "execute",
 		description: EXECUTE_DESCRIPTION,
 		promptSnippet: EXECUTE_PROMPT_SNIPPET,
-		promptGuidelines: buildExecutePromptGuidelines(process.cwd()),
+		promptGuidelines: buildExecutePromptGuidelines(),
 		parameters: executeSchema,
 		renderShell: "self",
 		renderCall(args, theme, context) {
@@ -184,10 +176,8 @@ export default function (pi: ExtensionAPI) {
 				throw new Error("pi-repl is dormant in this session. Start pi with --repl (or PI_REPL_FORCE=1) to use execute.");
 			}
 			if (ctx?.cwd) location = { cwd: ctx.cwd, sessionFile: ctx.sessionManager?.getSessionFile?.() ?? undefined };
-			// --- establish the body slot at call time so Ctrl+O can expand a live (still-awaiting) stream;
-			// --- without this the host only renders the result once the first partial or the final result lands ---
+			// --- establish the body slot at call time so Ctrl+O can expand a live, still-streaming cell ---
 			onUpdate?.({ content: [], details: {} });
-			// --- previous engine died mid-session; acquire revives it ---
 			const sessionKey = location.sessionFile ? conversationName(location.sessionFile) : undefined;
 			const { engine: m } = await lifecycle.acquire("cell", sessionKey);
 			try {
@@ -200,11 +190,23 @@ export default function (pi: ExtensionAPI) {
 						onUpdate?.({ content: [{ type: "text", text: streamed }], details: {} });
 					},
 				});
-				// --- reset notice leads so the model reads that its namespace was rebuilt; the
-				// --- human gets a terse notification instead of the marker, fire and forget ---
+				// --- reset notice leads so the model reads the rebuild; the human gets a terse toast instead ---
 				const reset = lifecycle.takeResetNotice();
-				if (reset?.notice) ctx?.ui?.notify?.(formatResetToast(reset.origin, reset.restore, reset.wedged), "info");
-				const sections = [reset?.notice, r.stdout, r.stderr, r.result];
+				if (reset?.notice)
+					ctx?.ui?.notify?.(
+						m.inheritedFromFork ? formatForkToast(reset.restore) : formatResetToast(reset.origin, reset.restore, reset.wedged),
+						"info",
+					);
+				// --- helper verdicts once per boot: toast for the human, marker for the model only when a helper failed (all-good boots stay silent) ---
+				const helperReport = m.takeHelperReport();
+				if (helperReport && helperReport.length > 0) ctx?.ui?.notify?.(formatHelperToast(helperReport), "info");
+				const sections = [
+					reset?.notice,
+					formatHelperFailuresLine(helperReport),
+					r.stdout,
+					r.stderr,
+					r.result,
+				];
 				const errorLines = r.error ? composeErrorLines(r.error) : undefined;
 				if (r.status === "error" && errorLines) sections.push(errorLines.join("\n"));
 				if (r.status === "aborted") sections.push("[cell aborted]");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.6.14",
+	"version": "0.7.0",
 	"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/scripts/setup-venv.mjs

@@ -1,16 +1,5 @@
 #!/usr/bin/env node
-/**
- * postinstall: build the stable per-user Python venv the evaluator needs.
- *
- * On a package install the venv is built at a stable path the engine knows:
- *
- *   ~/.pi/agent/pi-repl/venv/bin/python3
- *
- * The venv is repaired in place: if it exists but ipykernel is not importable,
- * this reflushes the venv and reinstalls rather than trusting a half-built one.
- * Failures are NOT silent: a bad build exits non-zero so `npm install` / `pi
- * install` visibly fails instead of leaving a broken evaluator.
- */
+/** postinstall: build the stable per-user venv at ~/.pi/agent/pi-repl/venv; repair in place if ipykernel is missing; a bad build fails the install loudly. */
 
 import { execSync } from "node:child_process";
 import { mkdirSync } from "node:fs";
@@ -22,8 +11,7 @@ const PY = join(VENV_DIR, "bin", "python3");
 const DEPS = ["ipykernel"];
 const HELPERS_DIR = join(homedir(), ".pi", "agent", "pi-repl", "helpers");
 
-// A venv that exists but can't import ipykernel is broken. Never trust the
-// binary alone — a half-built venv otherwise looks "already up" forever.
+// A venv that can't import ipykernel is broken — never trust the binary alone.
 function ipykernelOk() {
   try {
     execSync(`${PY} -c "import ipykernel"`, { stdio: "ignore" });
@@ -50,10 +38,7 @@ function findSystemPython() {
   return null;
 }
 
-// ---------------------------------------------------------------- helpers dir
-// The helpers dir is user-owned. We create it empty on install. The REPL
-// provides shell and file IO natively; helpers are for things the user adds
-// themselves (e.g. web_search, custom skills). Existing files are never clobbered.
+// --- helpers dir: user-owned, created empty; existing files are never clobbered ---
 function seedHelpersDir() {
   try {
     mkdirSync(HELPERS_DIR, { recursive: true });
@@ -89,9 +74,7 @@ function main() {
     }
     log("done. The pi-repl evaluator will use this venv.");
   } catch (error) {
-    // A real failure must not exit 0 with a broken venv. npm/pi will see the
-    // nonzero exit and report the install as failed instead of silently
-    // handing the user a dead evaluator.
+    // a real failure must exit non-zero — never hand the user a dead evaluator
     fail(`could not build the evaluator venv (${error && error.message ? error.message : error}). `);
   }
 }
@@ -101,4 +84,4 @@ function fail(m) {
   process.exit(1);
 }
 
-main();
+main();

package/src/engine/helpers-locate.ts

@@ -5,7 +5,6 @@ import { dirname, join, resolve } from "node:path";
 
 const GLOBAL_HELPERS_DIR = join(homedir(), ".pi", "agent", "pi-repl", "helpers");
 
-/** Ordered candidate dirs: nearest .pi/helpers up to the git root, then the global dir last. */
 export function resolveHelperDirs(cwd?: string, globalDir?: string): string[] {
 	const dirs: string[] = [];
 	if (cwd) {