pi-repl-py 0.1.0 → 0.2.0

package/ARCHITECTURE.md

@@ -1,141 +0,0 @@
-# Architecture
-
-Two processes: the host lives inside pi, the guest owns the Python workspace.
-
-```
-pi
- └─ extension (index.ts)        registers `execute`, dormant until --repl
-     └─ EngineManager (src/engine/index.ts)  spawn host: snapshots, teardown
-         │  stdin  ──▶  protocol commands (run / snapshot / restore / ping)
-         │  fd 3   ◀──  stream, done, snapshot_result, ...
-         └─ guest.py ▶ jupyter_client ▶ a real ipython kernel (subprocess)
-```
-
-The host is TypeScript; the evaluator is Python in its own process. Splitting
-them is what makes a bad cell survivable: a cell can raise, leak memory, or
-wedge the guest without taking pi down, and the host, being not the thing
-that failed, always gets to report what happened.
-
-## The Python environment (the venv)
-
-The evaluator is a real `ipython` kernel, so it needs a Python environment with
-`ipykernel` + `jupyter_client`. You cannot fake that with a script; it is a
-hard runtime dependency.
-
-When installed as a pi package, `npm install` runs `postinstall`
-(`scripts/setup-venv.mjs`), which creates a stable per-user venv:
-
-```
-~/.pi/agent/pi-repl-venv/bin/python3
-```
-
-That path is stable across updates because it sits outside the ephemeral
-package dir under `~/.pi/agent/npm`. 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` chooses the interpreter in order:
-
-1. the repo's own `.venv` (development)
-2. a cwd-local `.venv` (project)
-3. `~/.pi/agent/pi-repl-venv` (package install)
-4. `$PYTHON` or `python3`
-
-The first existing one wins. The model is told (via `help()`) that it runs in a
-project-local venv, not the system interpreter, so it does not leak the wrong
-assumption into commands.
-
-## The guest
-
-`src/engine/guest.py` uses `jupyter_client.KernelManager` to start a real
-`ipykernel` subprocess (`python -m ipykernel`), keeps a blocking client
-attached, and stays alive for the whole session. Cells run in that kernel via
-`kc.execute(code)`, so state persists because the kernel process does.
-
-The wire protocol rides two channels, both load-bearing:
-
-*Separation.* Protocol traffic uses a dedicated pipe (fd 3). The guest's real
-stdout/stderr carry only user output, so a cell printing JSON cannot be parsed
-as a protocol message.
-
-*Authentication.* Every frame carries a nonce the host mints at spawn and the
-guest erases from its environment before any cell runs. Code inside a cell
-cannot recover it. Without this, a cell could announce its own completion and
-claim success while failing — an agent that cannot trust its own results has
-nothing.
-
-## Toolbox loading
-
-At boot the guest and the host both read the toolbox directory (default
-`src/engine/toolbox`, overridden by config `toolboxDir` → env `PI_TOOLBOX_DIR`).
-
-- **guest** execs each `*.py` into the kernel namespace, making functions
-  callable.
-- **host** reads the same files to build the functions list on the `execute`
-  tool's `promptGuidelines` (and the tool `description`), so the model sees the
-  real signatures and one-line summaries.
-
-The loader reads each file's `def (...)`: signature (authoritative) and its
-`function_description = """..."""` (one-line summary, optional). Since both
-sides read the same directory, a function in the prompt also exists in the
-kernel. A file renamed with a `_` prefix is skipped by both, so a disabled
-function is never advertised where it does not load. See
-`docs/how-to-functions.md`.
-
-The `promptGuidelines` are built once, when the `execute` tool is registered
-(module load). A toolbox change therefore needs a **session restart / `/reload`**
-to be reflected in the prompt — the kernel also loads the toolbox only at boot.
-
-`ls()` and `help(name)` are built into the kernel (not toolbox files), so a
-bare kernel still lets the model discover what is loaded.
-
-## Snapshots & honest resets
-
-After each successful cell the host schedules a debounced snapshot: it asks
-the guest to pickle the kernel's globals (entry-by-entry so one bad value
-costs only itself), and stores that as `namespace.snapshot` keyed to the
-session file. On a fresh engine it restores, and whatever cannot be pickled
-(live handles, some objects) is reported by name.
-
-If the evaluator restarts, the result is prefixed with a `<rlm_engine_reset>`
-block naming what was revived and what was lost, so the model re-verifies
-before reuse rather than trusting state that is gone.
-
-## Failure modes
-
-| Failure | Behaviour |
-| --- | --- |
-| Cell throws | `done { status: "error" }` with traceback; kernel namespace intact |
-| Kernel wedged | timeout → kill kernel subprocess → spawn fresh → restore snapshot |
-| Guest process dies | pending calls settle; engine reports itself down; later calls reject |
-| Host exits | guest is killed; on abrupt death it self-exits on stdin EOF |
-| Output flood | capped per channel, truncation announced |
-
-## Testing
-
-- **Host (bun):** `test/units.test.ts` (protocol, render, config) +
-  `test/preview-core.test.ts`.
-- **Evaluator (pytest):** `test/guest_contract.py` drives a real guest and
-  asserts persistence, error-survival, output attribution, snapshots, ls/help.
-- **Integration (slow):** `test/engine.integration.test.ts` boots a real
-  engine + guest and proves a variable survives an engine restart.
-
-Gate: `just check` = biome + bun test (host) + pytest (guest).
-`just integration` adds the real-host seam.
-
-## Configuration reference
-
-Loaded from `~/.pi/agent/pi-repl.json` (or `$PI_REPL_CONFIG`), first-found-wins, never
-throws on a missing/malformed file.
-
-| Key | Type / default | Meaning |
-| --- | --- | --- |
-| `toolboxDir` | string, optional | Directory of one-function-per-`.py` files that replaces the shipped `src/engine/toolbox`. `~` is expanded; a bare relative path resolves from the process cwd (not reliable) — prefer an absolute path. |
-| `pythonPath` | string, optional | The interpreter used to spawn the guest. Omit to use `resolvePythonPath` (see venv). |
-| `timeoutMs` | number, 60000 | Per-cell execution timeout in ms. |
-| `snapshotDebounceMs` | number, 1500 | Debounce after an ok cell before snapshot, in ms. |
-
-## Reference documentation
-
-- Philosophy and design rationale: [docs/philosophy.md](docs/philosophy.md)
-- Adding a toolbox function: [docs/how-to-functions.md](docs/how-to-functions.md)

package/src/engine/guest.py

@@ -1,317 +0,0 @@
-"""
-guest.py — the real IPython kernel guest evaluator for pi-repl.
-
-The host spawns this once. It starts a local ipykernel subprocess via
-jupyter_client, keeps it for the session, and bridges the wire protocol to it
-(stdin = commands, fd 3 = results). State survives because the kernel process
-does. Frames carry a nonce the host mints and the guest erases, so agent code
-cannot forge protocol traffic.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import sys
-import time
-
-# --- protocol envelope ---
-ENVELOPE_KEY = "__rlm"
-NONCE_ENV = "PI_RLM_NONCE"
-PROTOCOL_FD = 3
-
-NONCE = os.environ.get(NONCE_ENV, "")
-os.environ.pop(NONCE_ENV, None)
-
-# --- per-cell timeout: 0 = no cap; else a silence watchdog (no output for N seconds) ---
-CELL_TIMEOUT_S = float(os.environ.get("PI_REPL_TIMEOUT_MS", "0") or "0") / 1000.0
-
-# --- snapshot/restore use a fixed window, not the cell silence timer ---
-SNAPSHOT_TIMEOUT_S = 90.0
-
-# --- cap buffered output so a runaway print can't grow guest memory or send one giant frame ---
-MAX_CELL_OUTPUT_CHARS = 1_000_000
-
-# --- fd 3 protocol writer; dup'd so we don't close the caller's fd 3 on exit ---
-_proto = os.fdopen(os.dup(PROTOCOL_FD), "w", buffering=1)
-
-
-def _send(msg):
-    envelope = {ENVELOPE_KEY: 1, **msg}
-    if NONCE:
-        envelope["n"] = NONCE
-    _proto.write(json.dumps(envelope) + "\n")
-    _proto.flush()
-
-
-def _decode(line):
-    if ENVELOPE_KEY not in line:
-        return None
-    try:
-        obj = json.loads(line)
-    except Exception:
-        return None
-    if obj.get(ENVELOPE_KEY) != 1 or not isinstance(obj.get("type"), str):
-        return None
-    if NONCE and obj.get("n") != NONCE:
-        return None
-    return obj
-
-
-# --- toolbox: one function per *.py, exec'd into every kernel (PI_TOOLBOX_DIR) ---
-
-def _toolbox_files(directory):
-    """Return {function_name: source} for each *.py in `directory`."""
-    if not directory:
-        return {}
-    d = os.path.expanduser(directory)
-    if not os.path.isdir(d):
-        return {}
-    names = {}
-    for entry in sorted(os.listdir(d)):
-        if not entry.endswith(".py"):
-            continue
-        name = entry[:-3]
-        if not name.isidentifier() or name.startswith("_"):
-            continue
-        try:
-            with open(os.path.join(d, entry), encoding="utf-8") as f:
-                names[name] = f.read()
-        except OSError:
-            continue
-    return names
-
-DEFAULT_TOOLBOX_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "toolbox")
-TOOLBOX_DIR = os.environ.get("PI_TOOLBOX_DIR", "").strip()
-_TOOLBOX_SRC = _toolbox_files(TOOLBOX_DIR or DEFAULT_TOOLBOX_DIR)
-
-# --- help/ls are part of the evaluator, not the toolbox ---
-INTRINSIC = """
-# --- ls() filters IPython-injected names out of the tool list ---
-_RPL_LS_NOISE = {'exit', 'quit', 'get_ipython', 'open', 'display'}
-
-def ls():
-    return sorted(n for n in globals() if n not in _RPL_LS_NOISE and not n.startswith('_') and callable(globals()[n]))
-
-def help(name=None):
-    if name is None:
-        return ls()
-    fn = globals().get(name)
-    if fn is None or not callable(fn):
-        return f"no such function: {name!r}"
-    return fn.__doc__ or f"{name} (no docstring)"
-"""
-
-
-from jupyter_client import KernelManager
-
-
-class Kernel:
-    """A persistent subprocess ipykernel + blocking client."""
-
-    def __init__(self):
-        self.km = KernelManager(kernel_name="python3")
-        self.km.start_kernel()
-        self.kc = self.km.client()
-        self.kc.start_channels()
-        self.kc.wait_for_ready(timeout=30)
-        self._preload()
-
-    def _preload(self):
-        """Exec every toolbox function + the intrinsic help/ls into the kernel ns."""
-        code = INTRINSIC + "\n"
-        for src in _TOOLBOX_SRC.values():
-            code += src + "\n"
-        if code.strip():
-            self.kc.execute(code)
-            self._drain()
-
-    def _drain(self):
-        try:
-            while True:
-                m = self.kc.get_iopub_msg(timeout=1)
-                if m.get("msg_type") == "status" and m.get("content", {}).get("execution_state") == "idle":
-                    break
-        except Exception:
-            pass
-
-    def _drain_execution(self, code, timeout):
-        """Run `code`; return (stdout, stderr, error_text, result, timed_out).
-
-        `timeout <= 0` means "no cap": a cell runs until it reports idle.
-        `timeout > 0` is a SILENCE watchdog — it trips only once the cell has
-        produced no message for `timeout` seconds. A silent-but-running command
-        (e.g. `find ... | sort`) is allowed to complete; a stalled one (dead
-        kernel, or nothing for the silence window) reports `timed_out=True` so
-        the caller can surface a real hang instead of faking success.
-        """
-        msg_id = self.kc.execute(code)
-        out, err, error, result = [], [], None, None
-        out_len, err_len = 0, 0
-        timed_out = False
-        # --- silence clock only starts once the cell begins (grace for a fresh kernel) ---
-        last_activity: float | None = None
-        while True:
-            if not self.km.is_alive():
-                timed_out = True
-                break
-            if last_activity is not None and timeout and (time.monotonic() - last_activity) >= timeout:
-                timed_out = True
-                break
-            wait = (timeout - (time.monotonic() - last_activity)) if (last_activity is not None and timeout) else 0.25
-            try:
-                m = self.kc.get_iopub_msg(timeout=max(0.01, min(0.25, wait)))
-            except Exception:
-                continue
-            if m.get("parent_header", {}).get("msg_id") != msg_id:
-                continue
-            if last_activity is None:
-                last_activity = time.monotonic()
-            else:
-                last_activity = time.monotonic()
-            mt = m.get("msg_type")
-            c = m.get("content", {})
-            if mt == "stream":
-                is_out = c.get("name") == "stdout"
-                text = c.get("text", "") or ""
-                if is_out:
-                    if out_len < MAX_CELL_OUTPUT_CHARS:
-                        take = text[: MAX_CELL_OUTPUT_CHARS - out_len]
-                        out.append(take)
-                        out_len += len(take)
-                else:
-                    if err_len < MAX_CELL_OUTPUT_CHARS:
-                        take = text[: MAX_CELL_OUTPUT_CHARS - err_len]
-                        err.append(take)
-                        err_len += len(take)
-            elif mt == "execute_result":
-                result = c.get("data", {}).get("text/plain")
-            elif mt == "error":
-                error = "\n".join(c.get("traceback", ["(no traceback)"]))
-            elif mt == "status" and c.get("execution_state") == "idle":
-                break
-        if timed_out:
-            # --- best-effort cancel so the NEXT cell doesn't queue behind this one ---
-            try:
-                self.kc.interrupt_kernel()
-            except Exception:
-                pass
-        return "".join(out), "".join(err), error, result, timed_out
-
-    def execute(self, code):
-        """Idle-sync path used by snapshot/restore; not a user cell."""
-        return self._drain_execution(code, SNAPSHOT_TIMEOUT_S)[:4]
-
-    def run_cell(self, code):
-        """Run a user cell under the per-cell timeout, so the model learns
-        when work did not finish."""
-        return self._drain_execution(code, CELL_TIMEOUT_S)
-
-    def snapshot_globals(self):
-        # --- snapshot only user state (skip toolbox/intrinsic functions and _ names) ---
-        tool_names = sorted(set(_TOOLBOX_SRC) | {"ls", "help", "function_description"})
-        skip_names = json.dumps(tool_names)
-        out, _, _, _ = self.execute(
-            "import pickle as _pk, base64 as _b64, json as _js\n"
-            "__rlm_skip = set(" + skip_names + ") | {'In','Out','get_ipython','exit','quit','open'}\n"
-            "__rlm_v = {}\n__rlm_f = []\n"
-            "for _k, _v in list(globals().items()):\n"
-            "    # skip IPython bookkeeping and names with a leading underscore\n"
-            "    if _k.startswith('__') or _k.startswith('_') or _k in __rlm_skip:\n"
-            "        continue\n"
-            "    try:\n"
-            "        __rlm_v[_k] = _b64.b64encode(_pk.dumps(_v)).decode()\n"
-            "    except Exception as _e:\n"
-            "        __rlm_f.append({'name': _k, 'reason': str(_e)})\n"
-            "print('__RLC_SNAPSHOT__' + _js.dumps({'vars': __rlm_v, 'failed': __rlm_f}))\n"
-        )
-        marker = "__RLC_SNAPSHOT__"
-        if marker not in out:
-            # --- marker never printed: serialization stalled; report incomplete so the host keeps the last good file ---
-            return {}, [], False
-        try:
-            o = json.loads(out.split(marker)[-1])
-            return o.get("vars", {}), o.get("failed", []), True
-        except Exception:
-            return {}, [], False
-
-    def restore_globals(self, vars_):
-        if not vars_:
-            return [], []
-        # --- restore each variable in one atomic kernel call so one failure reports itself ---
-        code2 = (
-            "import pickle as _pk, base64 as _b64, json as _js\n"
-            "__rl_r = {'restored': [], 'failed': []}\n"
-            + "\n".join(
-                "try:\n"
-                f"    globals()[{name!r}] = _pk.loads(_b64.b64decode({b64!r}))\n"
-                f"    __rl_r['restored'].append({name!r})\n"
-                "except Exception as _e:\n"
-                f"    __rl_r['failed'].append({{'name': {name!r}, 'reason': str(_e)}})\n"
-                for name, b64 in vars_.items()
-            )
-            + "\nprint('__RLC_RESTORE__' + _js.dumps(__rl_r))"
-        )
-        out, _, _, _ = self.execute(code2)
-        marker = "__RLC_RESTORE__"
-        if marker not in out:
-            return [], []
-        try:
-            obj = json.loads(out.split(marker)[-1])
-            return obj.get("restored", []), obj.get("failed", [])
-        except Exception:
-            return [], []
-
-
-def _line_error(text):
-    lines = text.split("\n")
-    return {"name": "", "message": text, "stack": lines[:12]}
-
-
-def main():
-    kernel = Kernel()
-    _send({"type": "ready"})
-
-    for line in sys.stdin:
-        msg = _decode(line)
-        if not msg:
-            continue
-        t = msg["type"]
-        if t == "ping":
-            _send({"type": "pong", "id": msg["id"]})
-        elif t == "snapshot":
-            vars_, failed, complete = kernel.snapshot_globals()
-            _send({"type": "snapshot_result", "id": msg["id"], "vars": vars_, "failed": failed, "complete": complete})
-        elif t == "restore":
-            restored, failed = kernel.restore_globals(msg.get("vars", {}))
-            _send({"type": "restore_result", "id": msg["id"], "restored": restored, "failed": failed})
-        elif t == "list_names":
-            names = list(kernel.snapshot_globals()[0].keys())
-            _send({"type": "names_result", "id": msg["id"], "names": names})
-        elif t == "run":
-            cell_id = msg.get("cellId")
-            stdout, stderr, error, result, timed_out = kernel.run_cell(msg.get("code", ""))
-            if stdout:
-                _send({"type": "stream", "cellId": cell_id, "name": "stdout", "chunk": stdout})
-            if stderr:
-                _send({"type": "stream", "cellId": cell_id, "name": "stderr", "chunk": stderr})
-            if timed_out:
-                tmsg = {
-                    "name": "Timeout",
-                    "message": f"cell did not finish within {CELL_TIMEOUT_S:g}s and may still be running",
-                    "stack": ["[cell timed out]"],
-                }
-                _send({"type": "done", "cellId": cell_id, "status": "error", "error": tmsg})
-            elif error:
-                _send({"type": "done", "cellId": cell_id, "status": "error", "error": _line_error(error)})
-            else:
-                _send({"type": "done", "cellId": cell_id, "status": "ok", "result": result})
-        # --- a single-threaded guest can't read 'abort' mid-cell; the host discards+rebuilds ---
-
-
-if __name__ == "__main__":
-    try:
-        main()
-    except Exception as e:
-        _send({"type": "done", "cellId": "", "status": "error", "error": _line_error(str(e))})
-        sys.exit(1)

package/src/engine/protocol.ts

@@ -1,66 +0,0 @@
-// --- 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

@@ -1,72 +0,0 @@
-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

@@ -1,37 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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)"