pi-repl-py 0.1.0

package/src/engine/protocol.ts

@@ -0,0 +1,66 @@
+// --- trust: fd3 is protocol-only (user output stays on stdout), and a cell can't forge frames (minted nonce) ---
+
+interface HostToGuest {
+	run: { type: "run"; cellId: string; code: string };
+	abort: { type: "abort"; cellId: string };
+	ping: { type: "ping"; id: string };
+	snapshot: { type: "snapshot"; id: string };
+	restore: { type: "restore"; id: string; vars: Record<string, string> };
+	list_names: { type: "list_names"; id: string };
+}
+
+export type HostToGuestMessage = HostToGuest[keyof HostToGuest];
+
+interface GuestToHost {
+	ready: { type: "ready" };
+	stream: { type: "stream"; cellId: string; name: "stdout" | "stderr"; chunk: string };
+	done: {
+		type: "done";
+		cellId: string;
+		status: "ok" | "error" | "aborted";
+		result?: string;
+		error?: { name: string; message: string; stack: string[] };
+	};
+	pong: { type: "pong"; id: string };
+	snapshot_result: {
+		type: "snapshot_result";
+		id: string;
+		vars: Record<string, string>;
+		failed: { name: string; reason: string }[];
+		/** False means the kernel didn't finish serializing; keep the last good file. */
+		complete?: boolean;
+	};
+	restore_result: {
+		type: "restore_result";
+		id: string;
+		restored: string[];
+		failed: { name: string; reason: string }[];
+	};
+	names_result: { type: "names_result"; id: string; names: string[] };
+}
+
+export type GuestToHostMessage = GuestToHost[keyof GuestToHost];
+
+const ENVELOPE_KEY = "__rlm";
+/** Env var carrying the per-process nonce to the guest. */
+export const NONCE_ENV = "PI_RLM_NONCE";
+/** Protocol pipe: guest → host. */
+export const PROTOCOL_FD = 3;
+
+export function encodeMessage(message: HostToGuestMessage | GuestToHostMessage, nonce?: string): string {
+	const envelope: Record<string, unknown> = { [ENVELOPE_KEY]: 1, ...message };
+	if (nonce) envelope.n = nonce;
+	return `${JSON.stringify(envelope)}\n`;
+}
+
+export function decodeMessage<T>(line: string, nonce?: string): T | null {
+	if (!line.trim()) return null;
+	try {
+		const parsed = JSON.parse(line);
+		if (parsed?.[ENVELOPE_KEY] !== 1 || typeof parsed.type !== "string") return null;
+		if (nonce && parsed.n !== nonce) return null;
+		return parsed as T;
+	} catch {
+		return null;
+	}
+}

package/src/engine/toolbox/bash.py

@@ -0,0 +1,72 @@
+function_description = """Run a shell command in a fresh subshell and return its result."""
+
+import os as _os
+import signal as _sig
+import subprocess as _sp
+
+
+def _kill_group(proc):
+    """Kill the whole process group of a child (its shell AND any grandchildren).
+
+    The shell's children inherit the fresh session's id, so they are the only
+    ones a timeout must reap; without this a `find | sort` that outlives the
+    call would keep chewing CPU long after bash() returned.
+    """
+    try:
+        _os.killpg(_os.getpgid(proc.pid), _sig.SIGKILL)
+    except Exception:
+        pass
+
+
+def bash(command, cwd=None, env=None, input=None, timeout=None):
+    """Run a shell command and return a CompletedProcess.
+
+    Argument notes:
+      command - the shell command string to run.
+      cwd     - optional directory to run it in; uses the evaluator's cwd if omitted.
+      env     - optional dict of environment variables merged into the current env.
+      input   - optional string to feed as stdin.
+      timeout - optional timeout in seconds; raises TimeoutExpired (after killing
+                the command's whole process group) if exceeded.
+
+    Result:
+      Returns subprocess.CompletedProcess. Read .stdout, .stderr, .returncode.
+      Example:  out = bash("git log --oneline"); print(out.returncode, out.stdout)
+
+    Behaviour:
+      - Runs via the shell, so pipes/&&/etc. work. Each call runs a FRESH
+        subshell: cd, export, and shell variables do NOT carry across calls.
+        Hold state in Python variables instead.
+      - The shell runs in its own process group, so a timeout kills the group —
+        no orphaned children keep running afterwards.
+      - `env` is merged into the current environment, not a replacement.
+
+    Environment:
+      This evaluator runs in a project-local Python venv, not the system
+      interpreter. A command that starts python/pip should target the same venv.
+    """
+    merged_env = dict(_os.environ)
+    if env:
+        merged_env.update(env)
+    with _sp.Popen(
+        command,
+        shell=True,
+        stdin=_sp.PIPE,
+        stdout=_sp.PIPE,
+        stderr=_sp.PIPE,
+        text=True,
+        cwd=cwd,
+        env=merged_env,
+        # --- new session => shell+children form one process group a timeout kills ---
+        start_new_session=_os.name == "posix",
+    ) as proc:
+        try:
+            stdout, stderr = proc.communicate(input=input, timeout=timeout)
+        except _sp.TimeoutExpired:
+            _kill_group(proc)
+            try:
+                proc.communicate()  # --- drain so no zombie is left ---
+            except Exception:
+                pass
+            raise
+    return _sp.CompletedProcess(args=command, returncode=proc.returncode, stdout=stdout, stderr=stderr)

package/src/engine/toolbox/edit.py

@@ -0,0 +1,37 @@
+function_description = """Replace old_text with new_text in a file; fails if old_text is not found exactly once."""
+
+
+def edit(path, old_text, new_text):
+    """Perform a targeted single replacement in a file.
+
+    Argument notes:
+      old_text - exact, unique text already in the file to replace.
+      new_text - text to substitute for it.
+
+    Behaviour:
+      - Requires old_text to appear EXACTLY once in the file. Zero or multiple
+        matches raise an error instead of guessing, so it can never silently
+        mangle a file it wasn't sure about.
+      - If it fails, the file is left untouched.
+
+    Environment:
+      This evaluator runs in a project-local Python venv, not the system
+      interpreter. For a package install that is ~/.pi/agent/pi-repl-venv; for a
+      repo checkout it is .venv/. The file edited is a real file on disk.
+    """
+    with open(path, encoding="utf-8") as f:
+        content = f.read()
+    count = content.count(old_text)
+    if count == 0:
+        raise ValueError(
+            f"edit: could not find the given old_text in {path} — it may have already been "
+            "applied or the file changed. Re-read the file and retry."
+        )
+    if count > 1:
+        raise ValueError(
+            f"edit: old_text occurs {count} times in {path} — make it more specific so it matches exactly once."
+        )
+    content = content.replace(old_text, new_text, 1)
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(content)
+    return f"edited {path}"

package/src/engine/toolbox/read.py

@@ -0,0 +1,26 @@
+function_description = """Return the text of a file, optionally a slice of its lines."""
+
+
+def read(path, offset=1, limit=None):
+    """Read a file's UTF-8 text and return it, optionally a slice of its lines.
+
+    Argument notes:
+      offset - 1-based first line to return (default 1).
+      limit  - maximum number of lines to return (default: all of them).
+
+    Behaviour:
+      - Decoding errors are replaced instead of raising, so a binary-adjacent
+        file still returns most of its text.
+      - Keeps only what you ask for so a huge file can't flood context.
+
+    Environment:
+      This evaluator runs in a project-local Python venv, not the system
+      interpreter. For a package install that is ~/.pi/agent/pi-repl-venv; for a
+      repo checkout it is .venv/. python / pip on PATH may point elsewhere, so
+      do not assume the system python is what's running.
+    """
+    with open(path, encoding="utf-8", errors="replace") as f:
+        lines = f.readlines()
+    start = max(0, (offset or 1) - 1)
+    end = None if limit is None else start + limit
+    return "".join(lines[start:end])

package/src/engine/toolbox/write.py

@@ -0,0 +1,23 @@
+function_description = """Write content to a file, creating it or overwriting its entire contents."""
+
+
+def write(path, content):
+    """Write a file wholesale, creating it if missing or replacing its contents.
+
+    Argument notes:
+      content - string (or anything stringifiable) to write in full.
+
+    Behaviour:
+      - Unconditional: overwrites whatever is there. There is no size cap.
+      - Use edit() for a targeted change inside an existing file; write() is for
+        a new file or a full rewrite.
+
+    Environment:
+      This evaluator runs in a project-local Python venv, not the system
+      interpreter. For a package install that is ~/.pi/agent/pi-repl-venv; for a
+      repo checkout it is .venv/. Files you write are real files on disk in the
+      working directory, visible to the host and other processes.
+    """
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(content if isinstance(content, str) else str(content))
+    return f"wrote {path} ({len(str(content))} chars)"

package/src/extension/config.ts

@@ -0,0 +1,65 @@
+/**
+ * config.ts — reads the user's pi-repl config.
+ *
+ * Where the venv python path, the toolbox directory, and timeouts are
+ * configured. First-found-wins, never throws on a missing/malformed file.
+ *
+ *   $PI_REPL_CONFIG            explicit env override
+ *   ~/.pi/agent/pi-repl.json   user-global (same dir as pi's settings.json)
+ *
+ * The loadable function set is the toolbox directory (see engine/toolbox/);
+ * there is no separate helpers list. The extension ships with the four default
+ * functions (read/write/edit/bash) and a user points toolboxDir at their own
+ * folder to replace them.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface ReplConfig {
+	/** Python interpreter used to spawn the guest. Defaults to the venv / PATH. */
+	pythonPath?: string;
+	/** Directory of toolbox function files, exec'd into every kernel. */
+	toolboxDir?: string;
+	/** Stall watchdog, ms: 0 = no cap, nonzero = no-output-for-N-ms trips it. */
+	timeoutMs: number;
+	/** Debounce for the auto-snapshot after an ok cell, ms. Default 1500. */
+	snapshotDebounceMs: number;
+}
+
+const DEFAULT_CONFIG: ReplConfig = {
+	// 0 = no stall provecap: cells run until they finish. A nonzero value is a
+	// SILENCE watchdog (no output for N ms), not a wall-clock deadline.
+	timeoutMs: 0,
+	snapshotDebounceMs: 1500,
+};
+
+function num(v: unknown, dflt: number): number {
+	return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : dflt;
+}
+
+function configCandidates(): string[] {
+	const env = process.env.PI_REPL_CONFIG;
+	const user = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".pi", "agent"), "pi-repl.json");
+	return [env, user].filter((p): p is string => !!p && p.length > 0);
+}
+
+/** Load + validate; return defaults on any failure. */
+export function loadConfig(): ReplConfig {
+	for (const file of configCandidates()) {
+		try {
+			if (!existsSync(file)) continue;
+			const raw: unknown = JSON.parse(readFileSync(file, "utf8"));
+			if (typeof raw !== "object" || raw === null) return { ...DEFAULT_CONFIG };
+			const r = raw as Record<string, unknown>;
+			return {
+				pythonPath: typeof r.pythonPath === "string" && r.pythonPath.length > 0 ? r.pythonPath : undefined,
+				toolboxDir: typeof r.toolboxDir === "string" && r.toolboxDir.length > 0 ? r.toolboxDir : undefined,
+				timeoutMs: num(r.timeoutMs, DEFAULT_CONFIG.timeoutMs),
+				snapshotDebounceMs: num(r.snapshotDebounceMs, DEFAULT_CONFIG.snapshotDebounceMs),
+			};
+		} catch {}
+	}
+	return { ...DEFAULT_CONFIG };
+}