pi-repl-py 0.2.8 → 0.4.0

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/index.ts

@@ -4,9 +4,10 @@ import { basename, join } from "node:path";
 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 { 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 +88,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 () => {
@@ -119,6 +110,16 @@ 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) => {
+		if (!active()) return;
+		const systemPrompt = withSkillsBlock(
+			event.systemPrompt,
+			event.systemPromptOptions?.skills ?? [],
+		);
+		return systemPrompt === undefined ? undefined : { systemPrompt };
+	});
+
 	pi.registerTool<typeof executeSchema, ExecuteDetails, Partial<ExecuteRenderState>>({
 		name: "execute",
 		label: "execute",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.2.8",
+	"version": "0.4.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,14 +6,17 @@
 // more signal; the machine reads every line every turn.
 
 export const executeToolDescription =
-	"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.";
+	"Execute Python cells in a persistent ipython kernel that stays alive across cells and turns. " +
+	"It replaces the default read, bash, edit, write, and search tools — file work, shell commands, and " +
+	"searches all run as Python. Everything you define (variables, imports, and helpers preloaded into the " +
+	"workspace namespace) survives for reuse in later cells. A cell returns its final expression; printed " +
+	"output is captured separately. Oversized output is truncated: 1,000,000 characters per cell, 4,096 per " +
+	"line. Reads are expensive — every printed value enters the context, so hold artifacts in variables, " +
+	"parse before printing, and print only the small bounded slice the next decision needs. Keep cells lean; " +
+	"full-file dumps and raw result lists bloat the conversation.";
 
 export const executePromptSnippet =
-	"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.";
+	"Execute Python cells in a persistent ipython kernel (replaces read, bash, edit, write, and search; state survives across cells and turns)";
 
 // --- the workspace doctrine riding the execute tool ---
 export function buildPromptGuidelines(preloaded: string[]): string[] {
@@ -45,7 +48,7 @@ export function buildPromptGuidelines(preloaded: string[]): string[] {
 		...(preloaded.length
 			? [
 					"## Helpers",
-					"These helpers are given to you by the user to use directly (loaded from `~/.pi/agent/pi-repl/helpers/`). Descriptions appear below.",
+					"These helpers are already defined in the workspace namespace. Use them by name as you would any other loaded function, class, or variable. Their code already executed at kernel boot. Descriptions appear below.",
 					"",
 					...preloaded,
 					"",

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`;
 }

package/src/extension/skill-hook.ts

@@ -0,0 +1,22 @@
+// --- 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. ---
+import { formatSkillsForPrompt, type Skill } from "@mariozechner/pi-coding-agent";
+
+const CWD_MARKER = "\nCurrent working directory:"; // skills sit just before this, pi's last line
+const READ_LINE = "Use the read tool to load a skill's file when the task matches its description."; // canon line
+const EXECUTE_LINE = "Load a skill's SKILL.md file contents via execute (read the file with Python)."; // repl has no read
+
+/** The prompt with the skills block in pi's slot; undefined if nothing should change. */
+export function withSkillsBlock(
+	prompt: string,
+	skills: Skill[],
+	alreadyPresent = prompt.includes("<available_skills>"),
+): string | undefined {
+	if (skills.length === 0) return undefined;
+	let extra = formatSkillsForPrompt(skills);
+	if (!extra) return undefined;
+	if (alreadyPresent) return undefined;
+	extra = extra.replace(READ_LINE, EXECUTE_LINE);
+	const idx = prompt.indexOf(CWD_MARKER);
+	return idx === -1 ? prompt + extra : prompt.slice(0, idx) + extra + prompt.slice(idx);
+}