pi-repl-py 0.1.0 → 0.2.0

package/index.ts

@@ -1,10 +1,10 @@
 // --- pi-repl: one execute tool over Python; everything else runs as functions inside it ---
 
 import { basename, join } from "node:path";
+import { homedir } from "node:os";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
-import { EngineBusyError, EngineManager } from "./src/engine/index.js";
-import { loadConfig } from "./src/extension/config.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 { EXECUTE_DESCRIPTION, buildExecutePromptGuidelines, EXECUTE_PROMPT_SNIPPET } from "./src/extension/tool-meta.js";
@@ -44,8 +44,6 @@ function composeErrorLines(error: { name: string; message: string; stack: string
 	return stack[0]?.trim() === header ? stack : [header, ...stack];
 }
 
-const CFG = loadConfig();
-
 export default function (pi: ExtensionAPI) {
 	pi.registerFlag("repl", {
 		type: "boolean",
@@ -62,12 +60,10 @@ export default function (pi: ExtensionAPI) {
 		create() {
 			const { cwd, sessionFile } = location;
 			const sessionKey = sessionFile ? basename(sessionFile).replace(/\.jsonl$/, "") : undefined;
-			const stateDir = join(cwd, ".pi-repl", sessionKey ?? "ephemeral");
+			// --- kernel namespace state lives under ~/.pi/agent/pi-repl, keyed by session, so it never clutters the project ---
+			const stateDir = join(homedir(), ".pi", "agent", "pi-repl", "state", sessionKey ?? "ephemeral");
 			return new EngineManager({
 				cwd,
-				pythonPath: CFG.pythonPath,
-				timeoutMs: CFG.timeoutMs,
-				toolboxDir: CFG.toolboxDir,
 				// --- snapshots are keyed to a session file; ephemeral sessions get none ---
 				snapshot: sessionKey ? { path: join(stateDir, "namespace.snapshot") } : undefined,
 			});
@@ -81,11 +77,7 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	// --- no custom prompt: pi's default prompt stands. session_start collapses
-	//     the active set to just `execute`, so the default prompt's built-in
-	//     read/bash/edit/write never appear. All REPL knowledge (description,
-	//     promptSnippet, promptGuidelines) lives on the tool itself, not in a
-	//     prompt builder. ---
+	// --- no custom prompt: pi's default prompt stands; active tools collapse to execute, so REPL knowledge lives on the tool ---
 
 	pi.on("session_start", async (_event, ctx) => {
 		if (!active()) {
@@ -132,7 +124,7 @@ export default function (pi: ExtensionAPI) {
 		label: "execute",
 		description: EXECUTE_DESCRIPTION,
 		promptSnippet: EXECUTE_PROMPT_SNIPPET,
-		promptGuidelines: buildExecutePromptGuidelines(CFG.toolboxDir),
+		promptGuidelines: buildExecutePromptGuidelines(),
 		parameters: executeSchema,
 		renderShell: "self",
 		renderCall(args, theme, context) {
@@ -191,25 +183,10 @@ export default function (pi: ExtensionAPI) {
 				pendingErrorResults.set(toolCallId, { details });
 				throw new Error(text || "(no output)");
 			}
-			if (r.status === "aborted") {
-				// A cancelled cell's kernel may still be executing work the guest
-				// single-threaded loop can't interrupt. Discard the engine so the
-				// NEXT run gets a fresh kernel instead of queuing behind the
-				// still-busy one (same class as the stalled-timeout recovery).
-				await lifecycle.discard();
-			}
+			// --- an aborted cell was interrupted, not wedged: the kernel keeps running, nothing to discard ---
 			return result;
 		} catch (error) {
-			if (error instanceof EngineBusyError) {
-				// --- discard the wedged engine; the next cell revives from the last snapshot ---
-				await lifecycle.discard();
-				throw new Error(
-					"The evaluator was wedged by a previously interrupted cell and has been killed. " +
-						"Run the next cell to get a fresh evaluator revived from the last snapshot; " +
-						"anything newer than that snapshot is gone, so re-verify variables before reusing them.",
-				);
-			}
-			// --- a guest that died leaves the engine shutdown; drop it so the next cell rebuilds fresh ---
+			// --- a kernel that died (or was killed as the abort backstop) is down; drop it so the next cell rebuilds ---
 			if (m.isRunning === false) {
 				await lifecycle.discard();
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.1.0",
+	"version": "0.2.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": [
@@ -11,6 +11,14 @@
 		"repl"
 	],
 	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/k3-2o/pi-repl-py.git"
+	},
+	"homepage": "https://github.com/k3-2o/pi-repl-py",
+	"bugs": {
+		"url": "https://github.com/k3-2o/pi-repl-py/issues"
+	},
 	"pi": {
 		"extensions": [
 			"./index.ts"
@@ -22,20 +30,18 @@
 		"docs",
 		"index.ts",
 		"README.md",
-		"ARCHITECTURE.md",
 		"LICENSE"
 	],
 	"engines": {
 		"node": ">=22"
 	},
-"scripts": {
+	"scripts": {
 		"typecheck": "tsc --noEmit",
 		"format": "biome format --write .",
 		"lint": "biome check .",
 		"knip": "knip",
-		"check": "tsc --noEmit && biome check . && npm run test:ts && npm run test:py",
+		"check": "biome check . && npm run test:ts",
 		"test:ts": "bun test test/units.test.ts test/preview-core.test.ts",
-		"test:py": ".venv/bin/python -m pytest test/guest_contract.py -q",
 		"test:integ": "bun test test/engine.integration.test.ts",
 		"postinstall": "node scripts/setup-venv.mjs"
 	},
@@ -54,4 +60,4 @@
 		"typebox": "^1.3.11",
 		"typescript": "^5.6.0"
 	}
-}
+}

package/scripts/setup-venv.mjs

@@ -1,18 +1,27 @@
 #!/usr/bin/env node
 /**
- * postinstall: build the stable per-user Python venv the guest evaluator needs.
+ * postinstall: build the stable per-user Python venv the evaluator needs.
  *
- * The guest (src/engine/guest.py) runs a real ipykernel, which requires
- * `ipykernel` + `jupyter_client` installed in a Python environment. When this
- * is installed as a pi package there is no repo-local `.venv` (it's gitignored
- * and excluded from the npm tarball), so we create one at a stable path that
- * the engine also knows about:
+ * 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:
  *
- *   ~/.pi/agent/pi-repl-venv/bin/python3
+ *   ~/.pi/agent/pi-repl/venv/bin/python3
  *
- * 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 (where the user is told how to install the deps).
+ * 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.
  */
 
 import { execSync } from "node:child_process";
@@ -20,15 +29,16 @@ import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-const VENV_DIR = join(homedir(), ".pi", "agent", "pi-repl-venv");
+const VENV_DIR = join(homedir(), ".pi", "agent", "pi-repl", "venv");
 const PY = join(VENV_DIR, "bin", "python3");
-const DEPS = ["ipykernel", "jupyter_client"];
+const DEPS = ["ipykernel"];
+const HELPERS_DIR = join(homedir(), ".pi", "agent", "pi-repl", "helpers");
 
-function log(msg) {
-  process.stdout.write(`[pi-repl] ${msg}\n`);
+function log(m) {
+  process.stdout.write(`[pi-repl] ${m}\n`);
 }
-function warn(msg) {
-  process.stderr.write(`[pi-repl] warning: ${msg}\n`);
+function warn(m) {
+  process.stderr.write(`[pi-repl] warning: ${m}\n`);
 }
 
 function findSystemPython() {
@@ -41,8 +51,20 @@ 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.
+function seedHelpersDir() {
+  try {
+    mkdirSync(HELPERS_DIR, { recursive: true });
+  } catch (e) {
+    warn(`could not create the helpers dir (${e?.message ?? e}); custom helpers won't preload.`);
+  }
+}
+
 function main() {
-  // Already built from a previous install/run.
+  seedHelpersDir();
   if (existsSync(PY)) {
     log(`venv already present at ${VENV_DIR}`);
     return;
@@ -51,7 +73,7 @@ function main() {
   if (!systemPython) {
     warn(
       `no python3 found on PATH; could not create the evaluator venv. ` +
-        `Install python3 and run '${PY.slice(-60)} -m venv' manually, or set PI_REPL pythonPath.`
+        `Install python3 and run '${PY.slice(-60)} -m venv' manually, or set $PYTHON to point at one.`
     );
     return;
   }
@@ -64,7 +86,7 @@ function main() {
     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 may need to run npm rebuild pi-repl after fixing python/network, or install ipykernel manually.");
+    warn("You must install ipykernel in that venv before the evaluator runs.");
   }
 }