pi-repl-py 0.2.0 → 0.2.2

package/README.md

@@ -43,18 +43,19 @@ 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 Python function you preload into every kernel. Drop a file in the one
-helpers directory, restart the session, and the function is callable from the workspace —
-for example, `helpers/double.py` exposing `def double` becomes `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 the model verbatim;
-the full contract lives in [docs/how-to-functions.md](docs/how-to-functions.md).
+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
+the model verbatim; the full contract lives in [docs/helpers.md](docs/helpers.md).
 
 Everything the extension keeps lives under one folder in your home directory:
 
@@ -65,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
@@ -90,4 +91,4 @@ The Python interpreter is auto-resolved (the venv, else `$PYTHON`/`python3`).
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/docs/ARCHITECTURE.md

@@ -121,7 +121,7 @@ The model discovers what is loaded by listing the namespace with ordinary Python
 ```
 
 For the full helper contract — the description, the docstring, disabling — see
-[how-to-functions.md](how-to-functions.md).
+[helpers.md](helpers.md).
 
 ## Snapshots & honest resets
 
@@ -179,4 +179,4 @@ but working cell may run on).
 ## Reference documentation
 
 - Philosophy and design rationale: [philosophy.md](philosophy.md)
-- Adding a helper: [how-to-functions.md](how-to-functions.md)
+- Adding a helper: [helpers.md](helpers.md)

package/docs/{how-to-functions.md → helpers.md}

@@ -1,12 +1,12 @@
 # How to write a helper
 
-A **helper** is a Python function you write once that becomes available to the agent in
-every `pi --repl` session. You drop a `.py` file into one folder, restart the session, and
-the function is callable from the workspace — like a bookmark for code the agent keeps
-reaching for.
+A **helper** is a `.py` file that gets exec'd into every kernel, so anything it defines —
+functions, classes, constants, imports, or a module that owns a fragile or opaque piece of
+work — becomes part of the agent's workspace; you drop the file into one folder, restart
+the session, and it's available. Like a bookmark for code the agent keeps reaching for.
 
-This guide shows the smallest helper that works, then explains the three parts every
-helper file has and the habits that make a helper useful.
+This guide shows the smallest callable helper that works, then explains the parts of a
+helper file and the habits that make a helper useful.
 
 ## Prerequisites
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"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();