pi-repl-py 0.2.7 → 0.3.0

package/README.md

@@ -96,6 +96,7 @@ The Python interpreter is auto-resolved (the venv, else `$PYTHON`/`python3`).
 - Why this design: [docs/design.md](docs/design.md)
 - How it works, the venv, and the kernel: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 - How to write and load helpers: [docs/helpers.md](docs/helpers.md)
+- Working examples you can copy: [example/](example/) — helpers under `example/helper/` and skills under `example/skills/`
 - Termux / Android installation: [docs/termux.md](docs/termux.md)
 
 ## It is not

package/docs/ARCHITECTURE.md

@@ -57,15 +57,17 @@ That path is stable across updates because it sits outside the package's own dir
 which npm replaces on each update. If `python3` or the network is missing at install time,
 `postinstall` prints a clear notice and the host falls back at runtime.
 
-At spawn, `resolvePythonPath` picks the interpreter in this order:
+At spawn, `resolvePythonPath` uses exactly one interpreter, the install venv:
 
-1. the repo's own `.venv` (development)
-2. a venv in the current directory (per-project)
-3. `~/.pi/agent/pi-repl/venv` (package install)
-4. `$PYTHON`, then `python3` (the fallback)
+1. `~/.pi/agent/pi-repl/venv` (the package install)
+2. `$PYTHON`, then `python3` (only if the install venv is missing)
 
-The first one that exists wins. The tool's prompt tells the model it runs in a project-local
-venv, not the system interpreter, so it does not leak the wrong assumption into commands.
+It deliberately does NOT auto-pick the repo's or current directory's `.venv`: a per-project
+venv is not guaranteed to have `ipykernel`, so preferring it (as earlier versions did) made
+the kernel die from a `ModuleNotFoundError` whenever cwd happened to contain such a venv. The
+kernel therefore always runs in the stable install environment. The kernel starts in the
+session's cwd, falling back to the host's own cwd if that directory no longer exists (a
+deleted project dir), so a stale cwd can never prevent the kernel from coming up.
 
 ## The kernel client
 

package/docs/helpers.md

@@ -119,6 +119,26 @@ the workspace.
 
 Because helpers execute at kernel startup, top-level code has consequences. Definitions are fine; imports should be reasonable; network calls, prints, subprocesses, and expensive work should usually happen inside an explicit function or method call.
 
+## Third-party packages in the install venv
+
+The evaluator runs from a real Python virtualenv (`~/.pi/agent/pi-repl/venv`); `sys.path` includes
+its `site-packages`. Packages you install there are importable from helpers and from any cell:
+
+```bash
+~/.pi/agent/pi-repl/venv/bin/pip3 install -U numpy pandas
+```
+
+```python
+import numpy as np
+```
+
+That is how a helper reaches a package the repl does not ship by default (the venv is created
+minimal — it has no `requests`, `numpy`, `pandas`, etc.). ipykernel only pulls its own dependencies.
+
+Because it is a project-local venv, the packages you add are personal to you: nothing about them
+ships with pi-repl. A helper that depends on a package runs only on machines that have installed
+it, so say so in the helper description or docstring when your helper imports one.
+
 ## Choosing what belongs in a helper
 
 Write a helper when it owns a part of the work that is easy to get wrong or tedious to repeat:

package/index.ts

@@ -6,7 +6,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import { EngineManager } from "./src/engine/index.js";
 import { ExecuteCellComponent, type ExecuteDetails, type ExecuteRenderState } from "./src/extension/render.js";
-import { EngineLifecycle, summarizeNames } from "./src/extension/session-engine.js";
+import { EngineLifecycle } from "./src/extension/session-engine.js";
 import { EXECUTE_DESCRIPTION, buildExecutePromptGuidelines, EXECUTE_PROMPT_SNIPPET } from "./src/extension/tool-meta.js";
 
 const executeSchema = Type.Object({
@@ -87,23 +87,13 @@ export default function (pi: ExtensionAPI) {
 		}
 		// --- active: the whole surface collapses to the one tool ---
 		pi.setActiveTools(["execute"]);
-		// --- revive the previous run; the engine also self-revives if session_start was skipped ---
+		// --- warm the engine (and its revive) in the background; no popup. ---
+		// --- acquire() dedupes, so the first execute awaits this same in-flight boot ---
 		location = { cwd: ctx.cwd, sessionFile: ctx.sessionManager.getSessionFile() ?? undefined };
-		const { restore } = await lifecycle.acquire("startup");
-		if (restore && restore.restored.length > 0) {
-			pi.sendMessage({
-				customType: "pi-repl-restore",
-				content: `Revived ${restore.restored.length} variable(s) from the previous run: ${summarizeNames(restore.restored, 8)}${
-					restore.failed.length > 0
-						? `. Failed: ${summarizeNames(
-								restore.failed.map((f) => f.name),
-								8,
-							)}`
-						: ""
-				}`,
-				display: true,
-			});
-		}
+		void lifecycle.acquire("startup").catch(() => {
+			// --- boot/revive handled on the execute path; swallow so a background warm can never
+			// --- surface an unhandled rejection and the model never needs the restore notice ---
+		});
 	});
 
 	pi.on("session_shutdown", async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.2.7",
+	"version": "0.3.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/src/engine/index.ts

@@ -5,21 +5,16 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { KernelClient } from "./kernel.js";
 
-const GUEST_REL = fileURLToPath(new URL("./kernel.js", import.meta.url));
-
 function installVenvPython(): string {
 	return join(homedir(), ".pi", "agent", "pi-repl", "venv", "bin", "python3");
 }
 
 /** Prefer a venv with ipykernel; else $PYTHON or python3. */
-function resolvePythonPath(cwd: string | undefined): string {
-	const repoVenv = join(dirname(GUEST_REL), "..", "..", ".venv", "bin", "python3");
-	if (existsSync(repoVenv)) return repoVenv;
-	const cwdVenv = cwd ? join(cwd, ".venv", "bin", "python3") : "";
-	if (cwdVenv && existsSync(cwdVenv)) return cwdVenv;
+function resolvePythonPath(_cwd: string | undefined): string {
+	// Only ever use the install venv: a project or repo `.venv` may lack ipykernel and
+	// shadow the good environment, killing the kernel. No auto-picking.
 	const installVenv = installVenvPython();
 	if (existsSync(installVenv)) return installVenv;
 	return process.env.PYTHON ?? "python3";

package/src/engine/kernel.ts

@@ -54,7 +54,14 @@ export interface SnapshotReply {
 // --- boot preload: exec each helper; ls()/help() are gone, discovery is globals() ---
 
 /** Read the helpers dir (same skip rules as the extension's prompt loader). */
-export function readHelperSources(dir?: string): { name: string; source: string }[] {
+/** A directory for the kernel to start in; if the requested cwd is gone, fall back to the
+ * evaluator's own cwd rather than letting spawn() die with ENOENT. A deleted project dir is
+ * a real resume case (pi guards it too) — the kernel must still come up. */
+function resolveCwd(requested?: string): string {
+	if (requested && existsSync(requested)) return requested;
+	return process.cwd();
+}
+function readHelperSources(dir?: string): { name: string; source: string }[] {
 	// --- one fixed dir, resolved like the prompt side (helpers.ts) so both always agree ---
 	const d = dir ?? join(homedir(), ".pi", "agent", "pi-repl", "helpers");
 	if (!existsSync(d)) return [];
@@ -179,7 +186,7 @@ export class KernelClient {
 	static async start(pythonPath: string, opts: KernelOptions = {}): Promise<KernelClient> {
 		const connPath = join(tmpdir(), `pi-repl-kernel-${randomUUID()}.json`);
 		const child = spawn(pythonPath, ["-m", "ipykernel", "-f", connPath, "--no-stdout"], {
-			cwd: opts.cwd,
+			cwd: resolveCwd(opts.cwd),
 			env: { ...process.env, ...(opts.env ?? {}) },
 			stdio: ["ignore", "pipe", "pipe"],
 		});

package/src/extension/prompt.ts

@@ -6,81 +6,58 @@
 // more signal; the machine reads every line every turn.
 
 export const executeToolDescription =
-	"You have one tool: a persistent Python workspace backed by a real `ipython` kernel. " +
-	"Variables, imports, and definitions survive across cells and turns — it is your working memory and action " +
-	"language. " +
-	"Helpers in `~/.pi/agent/pi-repl/helpers/` load at boot. A cell returns its final expression; printed output is " +
-	"captured separately.";
+	"You have one tool: a real `ipython` kernel that stays alive across cells and turns. " +
+	"This persistent Python workspace is your only surface — it does the work of bash, read, write, edit, " +
+	"search, and file handling, and everything you define (variables, imports, helpers loaded from " +
+	"`~/.pi/agent/pi-repl/helpers/`) survives for reuse in later cells. A cell returns its final expression; " +
+	"printed output is captured separately.";
 
 export const executePromptSnippet =
-	"Work in the workspace: keep artifacts in variables, compose related actions in Python, print only what " +
-	"the next step needs, and revise from what you observe.";
+	"The persistent Python workspace is your only tool: keep artifacts in variables across cells for reuse, use the loaded helpers, prefer surgical reads/edits over full-file dumps and rewrites, and parse before you print so context stays lean.";
 
 // --- the workspace doctrine riding the execute tool ---
 export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
 		"## Your only workspace",
-		"`execute` is the only callable tool. Python replaces a read, shell, search, and edit tool rack. State " +
-			"persists across cells and turns.",
+		"`execute` is the only callable tool. Python replaces a read, shell, search, and edit tool rack. State persists across cells and turns.",
 		"",
 		"## Work in the workspace, not the transcript",
-		"Load files, command results, search hits, and computed artifacts into variables once; filter, compare, " +
-			"branch, edit, and verify them in later cells. Do not re-read or paste raw material back. Print only the " +
-			"small observation needed for the next decision; keep the full artifact in a variable.",
+		"Load files, command results, searches, and computed artifacts into variables once; filter, compare, branch, edit, and verify them in later cells. Do not re-read or paste raw material back. Print only the small observation you'll decide on next; keep the full artifact in a variable. A bare final expression is auto-displayed by IPython — assign instead and print only what the next step needs.",
 		"",
 		"## A cell is a small program",
-		"Compose filesystem access, shell commands, searches, transforms, checks, and edits in ordinary Python " +
-			"when they belong to the same step.",
+		"Compose filesystem access, shell commands, searches, transforms, checks, and edits in ordinary Python in the same step.",
 		"",
 		"## Revise on observations",
 		"Revise prior actions or emit new actions upon new observations.", // CodeAct core
 		"",
 		"## Probe, then build",
-		"Inspect what is present — count, print a few lines, list what is loaded — before committing. Build one " +
-			"step, run it, and use its output to choose the next.",
+		"Inspect what is present — count, print a few lines, list what is loaded — before committing; build one step, run it, and use its output to choose the next.",
 		"",
-		"## Precise file and search work",
-		"Search narrowly and inspect only the lines you need. Do not dump whole files or repeat unchanged context. " +
-			"When walking directories, prune generated and hidden dirs — node_modules, .git, .venv, dist, __pycache__ — " +
-			"in the walk filter; never print a raw tree. " +
-			"For existing files, prefer a surgical old-text/new-text replacement over rewriting the file. Read the " +
-			"target region first, make the smallest unique replacement, then verify the changed region and file validity. " +
-			"Use complete writes only for new files or intentional full rewrites. Never leave a bare final expression: " +
-			"IPython displays it automatically; assign results and explicitly print only what you need.",
+		"## File and search work",
+		"Prefer a surgical old-text/new-text replacement over rewriting a file: read the region first, make the smallest unique replacement, verify the change and file validity. Use complete writes only for new files or intentional full rewrites. When walking directories, prune generated dirs — node_modules, .git, .venv, dist, __pycache__ — and never print a raw tree.",
 		"",
 		"## Repository discipline",
-		"Inspect before changing. Preserve project conventions and unrelated content. Make the smallest valid change, " +
-			"verify it afterward, and never invent files, APIs, conventions, or test results.",
+		"Make the smallest valid change, preserve conventions, verify afterward, and never invent files, APIs, conventions, or test results.",
 		"",
-		"## Batch and print sparingly",
-		"Every printed value enters the conversation and consumes context. Treat output as expensive: do not print " +
-			"raw, recursive, or unbounded results. Explore and filter in variables first, then print only the small, " +
-			"bounded observation needed to make the next decision. Never dump an artifact and rely on truncation to " +
-			"control it. Quality of output is paramount.",
-		"Batch as much independent work as reasonably possible into one call. Keep large values in variables; " +
-			"print slices, counts, and summaries.",
+		"## Context is expensive",
+		"Every printed value enters the conversation. Explore and filter in variables; print only the small, bounded slice for the next decision. Never dump a whole file, a raw result list, or an unbounded output, and never rely on truncation to control it.",
 		"",
 		...(preloaded.length
 			? [
 					"## Helpers",
-					"User helpers load from `~/.pi/agent/pi-repl/helpers/` as workspace definitions. Their descriptions " +
-						"appear below.",
+					"These helpers are given to you by the user to use directly (loaded from `~/.pi/agent/pi-repl/helpers/`). Descriptions appear below.",
 					"",
 					...preloaded,
 					"",
 				]
 			: []),
 		"## Shell and search",
-		"`subprocess.run(..., timeout=...)` when you need a result — always set a `timeout`, the evaluator does not " +
-			"kill a silent cell. Use `rg`/`grep`/`find` via `subprocess.run` for deep searches, not Python loops.",
+		"Always pass a `timeout` to `subprocess.run(...)` — a silent cell must die, not hang. Use `rg`/`grep`/`find` via the subprocess for deep searches, not Python loops.",
 		"",
-		"## 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. Run external projects through their own interface and normal commands.",
+		"## Environment & rescue",
+		"The evaluator runs in a project-local venv, not the system Python. Do not install a project's dependencies into the evaluator; run external projects through their own interface. If output begins with `<repl_engine_reset>`, the kernel was rebuilt — re-verify any revived variable before reusing it.",
 		"",
-		"## Engine reset guard",
-		"If output begins with `<repl_engine_reset>`, the kernel was rebuilt from the last snapshot. Re-verify a " +
-			"revived variable before reusing it — especially in a shell command. Functions, classes, and live handles " +
-			"are not snapshotted and must be redefined.",
+		"## Follow these as the operating manual",
+		"These guidelines are how this workspace works — internalize their intent and adapt to this environment by applying it to decisions they do not spell out. Follow them diligently.",
 	];
 }

package/src/extension/session-engine.ts

@@ -3,7 +3,7 @@
 import type { RestoreResult } from "../engine/index.js";
 
 /** Show enough names to orient, then count the rest (a revive can carry hundreds). */
-export function summarizeNames(names: readonly string[], limit: number): string {
+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`;
 }