pi-repl-py 0.2.1 → 0.2.3

package/README.md

@@ -43,15 +43,15 @@ clear notice. How the interpreter is resolved is in [docs/ARCHITECTURE.md](docs/
 - **A real `ipython` kernel**, not a hand-rolled `exec` loop.
 - **Shell and file IO as plain Python.** `!cmd` and `%%bash` run shell fire-and-forget,
   `subprocess.run(...)` brings the result back into a variable, and `open()` / `pathlib`
-  read and write files — no wrapper API to learn, and nothing extra to describe to the model.
+  read and write files. No wrapper API to learn, and nothing extra to describe to the model.
 - **Error survival.** A cell that throws reports the traceback and the kernel keeps going.
 - **An honest evaluator.** If it restarts, it names what state it could revive and what it lost, so you don't trust memory that's gone.
 
 ## Helpers
 
-A **helper** is a `.py` file that gets exec'd into every kernel, so whatever it defines —
-functions, classes, constants, imports, or a module that manages a tricky piece of
-complexity — is available in the workspace. Drop a file in the one helpers directory and
+A **helper** is a `.py` file that gets exec'd into every kernel, so whatever it defines
+(like functions, classes, constants, imports, or a module that manages a tricky piece of
+complexity) is available in the workspace. Drop a file in the one helpers directory and
 restart the session; e.g. `helpers/double.py` defining `def double(x)` becomes callable as
 `double(...)`. It ships **empty** (shell and file IO are already plain Python), so a fresh
 install preloads nothing until you add one. Each helper's `helper_description` is shown to
@@ -66,7 +66,7 @@ Everything the extension keeps lives under one folder in your home directory:
   state/        per-session namespace snapshots
 ```
 
-The helpers directory is fixed at `~/.pi/agent/pi-repl/helpers` — no config file.
+The helpers directory is fixed at `~/.pi/agent/pi-repl/helpers`. No config file.
 
 Changing a helper (adding/removing a file, renaming one with a `_` prefix) needs a
 **session restart / `/reload`**: the prompt list is built when `execute` is registered and
@@ -91,4 +91,4 @@ The Python interpreter is auto-resolved (the venv, else `$PYTHON`/`python3`).
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"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

@@ -2,30 +2,18 @@
 /**
  * postinstall: build the stable per-user Python venv the evaluator needs.
  *
- * The evaluator (src/engine/kernel.ts) drives a real ipykernel directly over
- * the Jupyter protocol; `ipykernel` is the only hard runtime dependency. When
- * this is installed as a pi package there is no repo-local `.venv` (gitignored
- * and excluded from the npm tarball), so we create one at a stable path the
- * engine also knows about:
+ * On a package install the venv is built at a stable path the engine knows:
  *
  *   ~/.pi/agent/pi-repl/venv/bin/python3
  *
- * HELPERS live ONLY in the user-owned config dir:
- *
- *   ~/.pi/agent/pi-repl/helpers/
- *
- * There is no helper/config folder anywhere in this package (no
- * src/engine/helpers, no templates/). The helpers dir is created if missing,
- * but no default helpers are seeded — the REPL itself already provides shell
- * (via `!cmd`, `%%bash`, `subprocess`) and file IO (via `open`, `pathlib`).
- * Users add their own helper .py files freely; existing files are never clobbered.
- *
- * Failures are non-fatal: if there's no system python3 or no network we print a
- * clear notice and let the engine fall back to '$PYTHON' or 'python3' at runtime.
+ * 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.
  */
 
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -34,6 +22,17 @@ 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.
+function ipykernelOk() {
+  try {
+    execSync(`${PY} -c "import ipykernel"`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function log(m) {
   process.stdout.write(`[pi-repl] ${m}\n`);
 }
@@ -65,29 +64,41 @@ function seedHelpersDir() {
 
 function main() {
   seedHelpersDir();
-  if (existsSync(PY)) {
-    log(`venv already present at ${VENV_DIR}`);
+  if (ipykernelOk()) {
+    log(`venv ready (ipykernel present) at ${VENV_DIR}`);
     return;
   }
   const systemPython = findSystemPython();
   if (!systemPython) {
-    warn(
+    fail(
       `no python3 found on PATH; could not create the evaluator venv. ` +
-        `Install python3 and run '${PY.slice(-60)} -m venv' manually, or set $PYTHON to point at one.`
+        `Install python3 and run '${PY.slice(-60)} -m venv' manually.`
     );
     return;
   }
-  log(`creating evaluator venv at ${VENV_DIR} (uses ${systemPython})...`);
+  log(`building evaluator venv at ${VENV_DIR} (uses ${systemPython})...`);
   try {
     mkdirSync(join(VENV_DIR, ".."), { recursive: true });
-    execSync(`${systemPython} -m venv ${VENV_DIR}`, { stdio: "inherit" });
+    // flush a half-built venv so pip starts from a clean, knowable slate
+    execSync(`${systemPython} -m venv --clear ${VENV_DIR}`, { stdio: "inherit" });
     execSync(`${PY} -m pip install --upgrade pip`, { stdio: "inherit" });
     execSync(`${PY} -m pip install ${DEPS.join(" ")}`, { stdio: "inherit" });
+    if (!ipykernelOk()) {
+      fail(`ipykernel still not importable after install; the evaluator won't start.`);
+      return;
+    }
     log("done. The pi-repl evaluator will use this venv.");
   } catch (error) {
-    warn(`could not build the evaluator venv (${error && error.message ? error.message : error}). `);
-    warn("You must install ipykernel in that venv before the evaluator runs.");
+    // 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.
+    fail(`could not build the evaluator venv (${error && error.message ? error.message : error}). `);
   }
 }
 
+function fail(m) {
+  process.stderr.write(`[pi-repl] ERROR: ${m}\n`);
+  process.exit(1);
+}
+
 main();

package/src/extension/prompt.ts

@@ -1,76 +1,70 @@
 // --- prompt: the execute tool's model-facing contract (pure, no pi/helper dep) ---
+//
+// Verbatim clauses from CodeAct (arXiv 2402.01030) and RLM (arXiv 2512.24601)
+// are trimmed to what pi-repl actually has — no sub-LLMs, no recursion, no
+// context variable — and the rest is stripped for lean context. Less prose,
+// 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, functions, and data survive across cells and turns. Use this tool to read files, " +
-	"run shell commands, search code, transform data, and build up solutions — all inside Python. " +
-	"Helpers in `~/.pi/agent/pi-repl/helpers/` are loaded at boot as functions; see what's loaded with " +
-	"`[k for k in globals() if not k.startswith('_')]`. A cell returns its final expression; printed output " +
-	"is captured separately.";
+	"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; list them with " +
+	"`[k for k in globals() if not k.startswith('_')]`. A cell returns its final expression; printed output is " +
+	"captured separately.";
 
 export const executePromptSnippet =
-	"Use the Python workspace: keep state in variables, batch independent reads/searches in one cell, " +
-	"edit files safely, and iterate in small cells.";
+	"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 workspace doctrine riding the execute tool ---
 export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
-		"## This workspace is your only tool",
-		"In `--repl` mode, `execute` is the only callable tool. Read files, run shell, search, and edit " +
-			"all happen inside Python.",
+		"## 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.",
 		"",
-		"## The loop is generate → execute → observe → iterate",
-		"Write a cell, run it, observe the result, then write the next cell. Build solutions incrementally.",
+		"## 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.",
 		"",
-		"## State persists",
-		"Variables, imports, and functions survive across cells and turns. Assign read/search results to " +
-			"named variables and reuse them.",
+		"## 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.",
 		"",
-		"## Chain big tasks into verifiable steps",
-		"Break ambitious requests into independently checkable steps. Confirm assumptions before writing " +
-			"code that depends on them.",
+		"## Revise on observations",
+		"Revise prior actions or emit new actions upon new observations.", // CodeAct core
 		"",
-		"## Shell & files are plain Python",
-		"`!cmd` / `%%bash` for fire-and-forget shell; `subprocess.run(..., timeout=...)` when you need the result back " +
-			"as a value — always set a `timeout` on anything that could hang (the evaluator does not kill a " +
-			"silent cell automatically). `open()` / `pathlib` read and write files. For safe edits: read the full " +
-			"file, modify in memory, write once, then re-read to verify.",
+		"## 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.",
 		"",
-		"## Batch independent work, keep exploratory cells small",
-		"Batch independent reads, searches, and setup steps in one cell to reduce round-trips. Keep " +
-			"exploratory/iterative cells small so you can observe and adjust.",
-		"",
-		"## Search efficiently",
-		"Use `rg`, `fd`, `grep`, `find` via `subprocess.run` for deep searches, not Python loops.",
+		"## Batch and print sparingly",
+		"Batch as much independent work as reasonably possible into one call. Keep large values in variables; " +
+			"print slices, counts, and summaries.",
 		"",
 		...(preloaded.length
 			? [
 					"## Helpers",
-					"User helpers load from `~/.pi/agent/pi-repl/helpers/`. Their descriptions appear below. " +
-						"List what's loaded with `[k for k in globals() if not k.startswith('_')]`.",
+					"User helpers load from `~/.pi/agent/pi-repl/helpers/` as workspace definitions. Their descriptions " +
+						"appear below. List what is loaded with `[k for k in globals() if not k.startswith('_')]`.",
 					"",
 					...preloaded,
 					"",
 				]
 			: []),
-		"## Compose and reuse",
-		"If the same pattern appears more than once, wrap it in a `def` and reuse it.",
-		"",
-		"## Output discipline",
-		"Printing is a context cost: everything a cell prints stays in the transcript. Print slices, " +
-			"counts, and summaries. Keep large values in variables. End a cell with `;` to suppress the " +
-			"last-expression echo.",
+		"## 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.",
 		"",
 		"## 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 just to make that project run there. Run external projects " +
-			"through their own interface and normal commands.",
+			"dependencies into the evaluator. Run external projects through their own interface and normal commands.",
 		"",
 		"## Engine reset guard",
-		"If the output begins with `<repl_engine_reset>`, the kernel was rebuilt from the last snapshot. " +
-			"Some variables may be revived, some lost, and anything defined after the snapshot is gone. " +
-			"Re-verify variables before reusing them — never interpolate a restored variable into a shell " +
-			"command until you have confirmed it still holds what you expect. Functions, classes, and live " +
-			"handles cannot be snapshotted and must be redefined.",
+		"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.",
 	];
 }