pi-repl-py 0.1.0 → 0.2.0

package/README.md

@@ -21,7 +21,7 @@ the kernel stayed alive.
 
 ```bash
 # from a clone, one-time setup
-just setup            # npm install + a project-local .venv with the guest deps
+just setup            # npm install + a project-local .venv with ipykernel
 
 # run a session
 pi --repl
@@ -33,48 +33,59 @@ A plain `pi` session is untouched; the extension is dormant until `--repl` is pa
 ## Installing as a pi package
 
 `npm install` runs a `postinstall` that creates the Python venv the evaluator needs, at a stable
-per-user path (`~/.pi/agent/pi-repl-venv`). If `python3` or the network is missing, it prints a
-clear notice. How the interpreter is resolved is in [docs/philosophy.md](docs/philosophy.md).
+per-user path (`~/.pi/agent/pi-repl/venv`). If `python3` or the network is missing, it prints a
+clear notice. How the interpreter is resolved is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ## What you get
 
 - **A persistent namespace.** Variables, functions, imports, and data survive across cells and
   turns; snapshots preserve them across a best-effort restart.
 - **A real `ipython` kernel**, not a hand-rolled `exec` loop.
-- **Shell as values.** `bash("git log --oneline")` returns a `CompletedProcess` you read
-  `.stdout`/`.stderr`/`.returncode` on.
+- **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.
 - **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.
 
-## The toolbox
+## Helpers
 
-A small set of Python functions is preloaded into every kernel and surfaced to the
-model through the `execute` tool's prompt guidance (their signatures + one-line
-summaries are listed there, and `ls()`/`help()` discover them at runtime), so the
-model can call `read`, `write`, `edit`, and `bash` without reimplementing them.
-Set `toolboxDir` to point at your own folder.
+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).
 
-The function list shown to the model is built when the `execute` tool is
-registered, so changing the toolbox (adding/removing a file, renaming one with a
-`_` prefix) needs a **session restart / `/reload`** for the prompt to reflect it —
-the kernel also only loads the toolbox at boot.
+Everything the extension keeps lives under one folder in your home directory:
 
-- Adding a function (the file contract, docstrings, disabling): [docs/how-to-functions.md](docs/how-to-functions.md)
+```
+~/.pi/agent/pi-repl/
+  venv/         the Python interpreter + ipykernel
+  helpers/      your helpers (created empty on install; every *.py loads)
+  state/        per-session namespace snapshots
+```
+
+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
+the kernel execs helpers only at boot.
 
 ## Configuration
 
-`~/.pi/agent/pi-repl.json` (or `$PI_REPL_CONFIG`) sets `toolboxDir`, `pythonPath`, and timeouts.
-Full keys and path rules: [ARCHITECTURE.md](ARCHITECTURE.md).
+There is deliberately no configuration file. Everything is arranged under
+`~/.pi/agent/pi-repl/`: the venv, the fixed helpers dir, and the session state.
+The Python interpreter is auto-resolved (the venv, else `$PYTHON`/`python3`).
 
 ## More
 
 - Why this design: [docs/philosophy.md](docs/philosophy.md)
-- How it works, the venv, config reference: [ARCHITECTURE.md](ARCHITECTURE.md)
+- How it works, the venv, config reference: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 
 ## It is not
 
 - A sandbox. The kernel runs with your permissions; the toolbox trusts you.
-- A subagent framework. There are no `rlm.run` subagents; spawn a process with `bash()`.
+- A subagent framework. There is no `repl.run` API; spawn a process with `subprocess.run`.
 - A pi tool-rack. It is one `execute` tool with functions inside.
 
 ## License

package/docs/ARCHITECTURE.md

@@ -0,0 +1,182 @@
+# Architecture
+
+pi-repl runs in **two processes**: the host lives inside pi and talks the standard Jupyter
+protocol directly to a real `ipykernel` subprocess. There is no middleman and no invented
+framing between them.
+
+```
+pi
+ └─ extension (index.ts)              registers `execute`; dormant until --repl
+     └─ EngineManager (src/engine/index.ts)   venv resolution, lazy spawn,
+         │                                   the call queue, snapshots,
+         │                                   abort grace, teardown
+         └─ KernelClient (src/engine/kernel.ts)   one ipykernel subprocess
+             ├─ ZMTP 3.0 (src/engine/zmtp.ts)     the wire protocol, by hand
+             ├─ Jupyter session (src/engine/session.ts)   framing + HMAC + JSON
+             └─ python -m ipykernel -f <connection-file>   the evaluator
+```
+
+The host is TypeScript; the evaluator is Python in its own process. That split is what makes
+a bad cell survivable: a cell can raise, leak memory, or wedge the kernel without taking pi
+down — and the host, being not the thing that failed, always gets to report what happened.
+
+## Why the host speaks ZMTP itself
+
+The obvious way for a TypeScript host to drive an `ipykernel` is to load a ZMQ client
+library. That does not work here: libzmq's native Node bindings crash `bun`. So an earlier
+design put a Python middleman (`guest.py`) between the host and the kernel, translating a
+private JSON protocol over a file descriptor into the real Jupyter protocol.
+
+The current design removes the middleman. Instead of working around the missing library, the
+host implements the small slice of ZMTP 3.0 a Jupyter client actually needs — a DEALER
+socket for the shell and control channels, a SUB socket for iopub (`src/engine/zmtp.ts`).
+The payoff:
+
+- **one process boundary** instead of two;
+- **one standard protocol** (Jupyter) instead of a private one on top of it;
+- **no invented framing** to maintain;
+- **HMAC signed and verified by the host itself.** The old design carried a nonce scheme to
+  stop a cell from forging its own completion signal; with the host signing every message
+  with the kernel's HMAC key, that concern is moot.
+
+## The Python environment (the venv)
+
+The evaluator is a real `ipykernel` kernel, so it needs a Python environment with
+`ipykernel` installed. That is a hard runtime dependency — you cannot fake it with a script.
+(`jupyter_client` is *not* needed: the host is the client.)
+
+When installed as a pi package, `npm install` runs `postinstall`
+(`scripts/setup-venv.mjs`), which builds a stable per-user venv:
+
+```
+~/.pi/agent/pi-repl/venv/bin/python3
+```
+
+That path is stable across updates because it sits outside the package's own directory,
+which npm replaces on each update. 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` picks the interpreter in this order:
+
+1. the repo's own `.venv` (development)
+2. a venv in the current directory (per-project)
+3. `~/.pi/agent/pi-repl/venv` (package install)
+4. `$PYTHON`, then `python3` (the fallback)
+
+The first one that exists wins. The tool's prompt tells the model it runs in a project-local
+venv, not the system interpreter, so it does not leak the wrong assumption into commands.
+
+## The kernel client
+
+`KernelClient.start` spawns `python -m ipykernel -f <connection-file>` with a per-run
+connection file in the temp directory, connects the three channels as ZMTP sockets, and
+waits for a `kernel_info_reply` before declaring the kernel ready. Cells run as standard
+Jupyter `execute_request`s, routed by `msg_id`:
+
+- **iopub** carries the output — `stream`, `execute_result`, `display_data`, and `error`
+  messages, plus private-MIME payloads that carry snapshot, restore, and namespace data.
+- **shell** carries the authoritative `execute_reply` (status, ename, evalue).
+- **control** carries interrupts (`interrupt_request`) and shutdown.
+
+Two wire subtleties are load-bearing, and both are pinned by the contract tests.
+
+**A cell is not done until two things arrive.** The shell reply and the iopub output stream
+travel on different connections, so a tiny reply can arrive before a large output has
+finished draining on iopub. A cell settles only when **both** the `execute_reply` and the
+matching iopub `status idle` (published after every byte of output) have arrived. Settling
+on the reply alone would drop output that was still in flight.
+
+**Output is capped per channel.** Each channel accumulates output against a character budget
+(`maxOutputChars`). Overflow is flagged per message — a single 10 MB print trips the cap
+within that one message, not only once a later message exhausts the budget — and the host
+appends an explicit truncation marker so the model knows output was cut.
+
+**Cancellation is real.** An abort sends an `interrupt_request` on the control channel,
+which raises a genuine `KeyboardInterrupt` in the running cell; the namespace survives. As a
+backstop for cells wedged in C code (which ignore interrupts), the engine's abort grace then
+kills the kernel after 500 ms, and the next call rebuilds it from the last snapshot.
+
+## Helpers loading
+
+At boot, the kernel and the host both read **one** helpers directory — the fixed
+`~/.pi/agent/pi-repl/helpers`, created empty on install with nothing seeded into it. There is
+no shipped toolbox that merges in.
+
+- **The kernel** execs each `*.py` into its namespace, so the file's functions become
+  callable.
+- **The host** reads the same files to build the helper list shown in the `execute` tool's
+  prompt, so the model sees each `helper_description` verbatim.
+
+Because both sides read the same directory, anything the model is told about is also
+callable, and a file renamed with a `_` prefix is skipped by both. The
+`promptGuidelines` are built once, when the `execute` tool is registered, so a helpers
+change needs a **session restart or `/reload`** to reach the prompt — and the kernel loads
+helpers only at boot anyway.
+
+There are no custom discovery intrinsics (`ls()` / `help()`) injected into a bare kernel.
+The model discovers what is loaded by listing the namespace with ordinary Python:
+
+```python
+[k for k in globals() if not k.startswith('_')]
+```
+
+For the full helper contract — the description, the docstring, disabling — see
+[how-to-functions.md](how-to-functions.md).
+
+## Snapshots & honest resets
+
+After each successful cell, the host schedules a debounced snapshot. A private kernel cell
+pickles the kernel's `globals` (entry by entry, so one value that cannot be pickled costs
+only itself) and publishes the result back over a private MIME payload. The host stores it as
+`namespace.snapshot`, keyed to the session file under
+`~/.pi/agent/pi-repl/state/<session>/`.
+
+When a fresh engine is built, it restores that snapshot. Whatever could not be pickled —
+live handles, some objects — is reported by name. If the evaluator was rebuilt mid-session,
+the result is prefixed with a `<repl_engine_reset>` block that names what was revived and
+what was lost, so the model re-verifies before reusing state that may be gone.
+
+## Failure modes
+
+| Failure | Behaviour |
+| --- | --- |
+| Cell throws | `error` status with traceback; kernel namespace intact |
+| Cell silent or wedged | the watchdog sends an `interrupt_request`; a caller abort then kills the kernel after a 500 ms grace |
+| Kernel dies | the running cell settles with an error; the next call builds a fresh kernel and restores the last snapshot |
+| Host exits | `process.on("exit")` SIGKILLs live kernels (a child does not die with its parent) |
+| Output flood | capped per channel, truncation announced |
+
+## Testing
+
+- **Host (fast):** `test/units.test.ts` covers engine orchestration, rendering, and config;
+  `test/preview-core.test.ts` covers the preview logic.
+- **Contract (slow):** `test/engine.integration.test.ts` boots a real kernel per engine and
+  proves the guarantees the old Python contract pinned: persistence across cells,
+  error-survival, output attribution, helpers loading, snapshot/restore round-trips, output
+  caps, silence timeout, abort, and rebuild-from-snapshot after a dead kernel.
+
+The gate is `just check` — biome (format + lint) plus the host tests. `just integration`
+adds the real-kernel suite.
+
+## The fixed layout
+
+There is no configuration file and no knobs. Everything lives under one directory in the
+user's home, and the default is the only option:
+
+```
+~/.pi/agent/pi-repl/
+  venv/         the Python interpreter + ipykernel
+  helpers/      the helpers directory — every *.py loads into every kernel
+  state/        per-session namespace snapshots
+```
+
+The helpers directory is fixed at `~/.pi/agent/pi-repl/helpers` (matching the kernel's
+`readHelperSources` default), so both sides are guaranteed to read the same directory. The
+venv is built automatically and the interpreter resolved by the order above — no setting
+needed. The per-cell silence watchdog is off by default (`PI_REPL_TIMEOUT_MS=0`: a silent
+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)

package/docs/how-to-functions.md

@@ -1,107 +1,110 @@
-# How to add a toolbox function
+# How to write a helper
 
-A toolbox function is one `.py` file that pi-repl loads into every kernel and
-surfaces to the model through the `execute` tool's prompt guidance (its
-signature + one-line summary appears in `promptGuidelines`). Add a file, and it
-shows up wherever the toolbox is read.
+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.
 
-> **When a change shows up.** The kernel loads the toolbox at boot, and the
-> `execute` tool builds its function list at registration (module load), so a
-> toolbox change (add/remove a file, rename one with a `_` prefix) is picked up
-> by a **session restart / `/reload`** — not mid-session.
+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.
 
-## Where functions live
+## Prerequisites
 
-By default the extension ships four (`read`, `write`, `edit`, `bash`) in
-`src/engine/toolbox/`. To use your **own** set, set `toolboxDir` in your
-config:
+- A working `pi --repl` session (the extension is installed — see the README).
+- The helpers folder, `~/.pi/agent/pi-repl/helpers/`. It is created empty on install.
 
-```jsonc
-// ~/.pi/agent/pi-repl.json
-{ "toolboxDir": "~/.pi/agent/pi-repl-functions" }
-```
-
-Use an absolute path or a `~`-prefixed one (`~` expands to your home). A bare relative
-path resolves from the process working directory, which is not reliable, so prefer
-an absolute path for a stable per-user folder. Point `toolboxDir` at a directory and
-every `*.py` there is loaded. Note: it **replaces** the shipped defaults; you do not
-get built-ins plus yours, unless you copy the built-ins into your folder too.
+## The smallest helper
 
-## The file contract
+Create this file:
 
-Every toolbox file must:
+```python
+# ~/.pi/agent/pi-repl/helpers/double.py
+helper_description = """double(x) — multiply a value by two."""
 
-1. have a `def` whose signature is the real call an agent would use, and
-2. may declare `function_description` (a short one-line summary shown in the
-   prompt).
+def double(x):
+    """Return x * 2. Works on ints, floats, and lists."""
+    return x * 2
+```
 
-A minimal, valid file:
+Restart the session (`/reload`, or relaunch `pi --repl`), then check it loaded:
 
 ```python
-# pi-repl-functions/summarize.py
-function_description = """Return a first-sentence summary of a text."""
-
-__all__ = ["summarize"]
+print([k for k in globals() if not k.startswith('_')])
+# ['double', ...]
 
-def summarize(text, limit=1):
-    return ". ".join(text.split(". ")[:limit]) + "."
+print(double(21))
+# 42
 ```
 
-That is everything. `summarize` loads into the kernel and the `execute` tool's
-prompt guidance shows `summarize(text, limit=1)` after the next session restart.
+If `double` appears in the namespace and runs, it's loaded. That is the whole loop: write
+the file, restart, use it.
 
-## The two pieces the loader reads
+## How it actually works
 
-**1. The signature comes from the `def`, not the description.**
-Arguments are read from the actual `def` line rather than hand-copied into a
-docstring, so the signature the model sees tracks the code for a normal
-single-line signature. Change `def summarize(text,
-limit=1):` to `limit=200`, and after the next session restart the prompt
-updates to match.
+Two things happen with the file you wrote:
 
-**2. The description, from `function_description`, optional.**
-Used as the one-line summary in the `execute` tool's prompt guidance. If you
-omit it, the function is still advertised (by signature), just without a
-one-liner.
+1. **The kernel execs it at boot.** The file's source runs in the kernel before the first
+   cell, so `def double` defines a callable `double` in the workspace. Separately, the
+   filename sets the label the prompt uses to advertise it — `double.py` is listed as
+   `double`. Keep the two identical (see *Common mistakes*).
 
-Each file should also give the function a real docstring (the text under
-`def`). That docstring is shown by `help(name)` in the kernel and carries the
-deeper usage and gotchas. It does not go into the execute tool's prompt
-guidance (only the one-line `function_description` does). Keep it for
-details, the venv note, and edge cases.
+2. **The model sees the description.** The `execute` tool's prompt lists each helper's
+   `helper_description`, rendered **verbatim**. Nothing is parsed: the text you put between
+   the triple-quotes is exactly what the model reads.
 
-## How much to document
+Shell and file IO are not helpers — they are already ordinary Python
+(`subprocess.run`, `!cmd`, `%%bash`, `open`, `pathlib`). A helper is only worth writing for
+the fragile or opaque part the model can't reliably reconstruct on its own: a `web_search`
+with provider failover, a client wrapper, a conversion it keeps getting wrong.
 
-`function_description` is the summary; the `def` docstring is the detail. A
-good `function_description` is one line ("Run a shell command and return its
-result."). A good docstring explains arguments, return value, and any
-non-obvious behavior, including environment facts the model needs
-("the evaluator runs in a project-local venv, not the system python").
+## The three parts of a helper file
 
-## Disabling a file without deleting it
+| Part | Required? | What it does | Who sees it |
+|---|---|---|---|
+| `def name(...)` | yes | the implementation | runs in the kernel |
+| `helper_description` | no | one line the model reads first | the prompt, verbatim |
+| a docstring | no | the full detail | `print(name.__doc__)` on demand |
 
-Rename the file to start with an underscore: `_test_helper.py`. The loader
-**(and the execute tool's prompt guidance)** skip underscore-prefixed files, so
-it never reaches the kernel or the model. Use this for scratch or internal
-helpers.
+**The function** is the implementation. Its public name must match the filename: `double.py`
+exposes `double`. Keep the `def` name identical so callers and the namespace agree.
 
-## Good practice
+**The description** is the model's first impression. It is the only part that reaches the
+prompt, and it is billed into context every turn, so it wants to be short. Two habits help
+(not requirements — the loader parses nothing):
 
-- One function per file, name matches the function.
-- Keep `function_description` one line. Everything else goes in the docstring.
-- Let the signature carry the truth; the description says what it's *for*.
-- A function that can hang (a shell call, network) should say so in its
-  docstring so the model knows the trade-off.
+- Start with the call shape: `double(x) — multiply a value by two.`
+- Add an "Instead of:" line naming the hand-rolled code it replaces, so the model reaches
+  for the helper rather than rewriting the raw call. *Good:* `Instead of: subprocess.run
+  with a hand-rolled kill-on-timeout.` *Weak:* `Instead of: doing it manually.`
 
-## Confirming it worked
+**The docstring** holds the depth — argument types and defaults, return value, error
+behaviour, environment facts ("this runs in a project-local venv, not the system Python").
+It never enters the prompt. The model reads it on demand with `print(name.__doc__)` or
+`help(name)` when the description is not enough.
 
-At a `pi --repl` prompt, run a cell:
+## Common mistakes
 
-```python
-print(ls())           # list what's loaded
-print(help('summarize'))  # signature + full docstring details
-```
+- **Description buried in detail.** Move anything beyond the call shape and one consequence
+  into the docstring. A long description bills into every turn.
+- **The helper decides too much.** A helper should own the murky part (the call, the
+  parsing), not the decision. If it picks the command, the routing, or the judgement, the
+  model stops reasoning.
+- **No docstring.** Without one, the model sees only a signature and the gotchas vanish.
+- **Top-level side effects.** The file runs at boot in every kernel. Keep module-level code
+  to definitions — no prints, no network, no slow imports at module scope.
+- **Filename and `def` name differ.** `helpers/foo.py` exposing `def bar` confuses callers
+  and the prompt. Keep them identical.
+
+## Disable a file without deleting it
+
+Rename it with a leading underscore (`_scratch.py`). The loader skips any file whose name
+starts with `_`, so it never reaches the kernel or the prompt. Handy for scratch work.
+
+## Checklist
 
-If `summarize` shows up in `ls()` and `help`, it loaded. The `execute` tool's
-prompt guidance also lists it (same first-line summary) after the next session
-restart.
+- [ ] Filename matches the public `def` name
+- [ ] `helper_description` is short and starts with the call shape
+- [ ] Depth lives in the docstring, not the description
+- [ ] No top-level side effects
+- [ ] Session restarted or `/reload`-ed
+- [ ] Name appears in `globals()` and the function runs

package/docs/philosophy.md

@@ -2,87 +2,95 @@
 
 ## The bet
 
-Most coding agents are a pile of point tools. A read tool, a bash tool, an edit
-tool, a find tool, each with its own schema, its own failure modes, its own
-token cost to describe. The model spends context deciding *which* tool, then
-*how* the output should be threaded into the next one.
+Most coding agents carry a toolbox of point tools: a read tool, a bash tool, an edit tool,
+a search tool, each with its own schema, its own failure modes, and its own token cost to
+describe. The model spends context deciding *which* tool to call, then *how* to thread one
+tool's output into the next.
 
-pi-repl makes the opposite bet: **give the model one persistent Python
-workspace and let it write the composition itself.** Configuration, state, and
-file access all happen in code, in one living namespace. The model's interface
-to the world never grows — the *code* it writes adapts instead.
+pi-repl makes the opposite bet: **give the model one persistent Python workspace, and let it
+write the composition itself.** Reading, running, searching, and editing all happen in code,
+in a single living namespace. The model's interface to the world never grows — the *code* it
+writes adapts instead.
 
-That is a "REPL" the way an agent actually wants one. Not an interactive
-lozenge to type into, but a long-lived working memory the model owns.
+This is what an agent actually wants from a "REPL". Not an interactive prompt to type into,
+but long-lived working memory the model owns.
 
 ## What persistence buys
 
-A separate-tool loop re-parses text every step. `read` returns a string, the
-agent pastes it, `grep` returns lines, the agent re-reads them. Every
-transformation is round-tripped through the transcript and billed as tokens.
+A point-tool loop re-parses text at every step. The `read` tool returns a string, so the
+agent pastes it back into context. The `grep` tool returns lines, so the agent re-reads
+them. Every transformation is round-tripped through the transcript and billed as tokens.
 
-In a persistent kernel, that work happens once and stays put:
+In a persistent kernel that work happens once and stays put:
 
-- a variable assigned in one cell is there in the next, and the next turn;
+- a variable assigned in one cell is still there in the next cell, and the next turn;
 - a function defined once is reusable for the whole session;
-- `bash()` returns a real `subprocess.CompletedProcess`, not a transcript
-  snippet, so the agent branches on `.returncode` and slices `.stdout` with
-  normal code.
+- `subprocess.run(...)` returns a structured result (`.returncode`, `.stdout`, `.stderr`)
+  the agent branches on with normal code — no re-parsing a tool's text output.
 
-The savings compound harder for small models. Holding a whole file in context
-to avoid re-reading it is expensive precisely when context is scarce; the
-kernel lets the model aggregate, filter, and store in code, printing only what
-the current step needs.
+The savings compound for small models. Holding a whole file in context to avoid re-reading
+it is expensive precisely when context is scarce. The kernel lets the model load, filter,
+and store in code, printing only what the current step needs.
 
 ## Why a real kernel
 
-pi-repl does not hand-roll an `exec` loop. It drives a genuine `ipython`
-kernel in a subprocess via `jupyter_client`. That buys:
+pi-repl does not hand-roll an `exec` loop. It drives a genuine `ipython` kernel in a
+separate process. That buys four things a script string passed to `exec` cannot give:
 
-- rich, real tracebacks instead of a wrapped `except`;
-- the full standard library and real `import` semantics;
-- last-expression capture;
-- a namespace that genuinely survives errors, instead of a script string passed
-to `exec`.
+- **rich, real tracebacks** instead of a wrapped `except`;
+- **real interrupts** — a stuck cell can be interrupted mid-run without losing the session;
+- **last-expression capture** (a cell's final expression becomes its result);
+- **a namespace that survives errors** — a cell that throws leaves the kernel, and
+  everything defined before it, intact.
 
-And it is an honest isolation boundary: the kernel is a separate process from
-pi. A cell can raise, or consume memory, or spin, and pi keeps answering because
-pi is not the process that failed. The host restores from the last completed
-snapshot and tells the model exactly what came back in a `<rlm_engine_reset>`
-notice. More in `ARCHITECTURE.md`.
+It is also an honest isolation boundary. The kernel is its own process, not part of pi. A
+cell that raises leaves pi answering and the namespace intact, because pi is not the process
+that failed. A cell that wedges the *whole* kernel instead stops cells from running until
+the next call notices the dead kernel and rebuilds it from the last completed snapshot.
+Either way the result carries a `<repl_engine_reset>` notice that names what the rebuild
+revived and what it lost, so the model re-verifies before trusting state that may be gone.
+(How that machinery works is in `ARCHITECTURE.md`.)
 
 ## The venv as part of the design
 
-Because the evaluator is real Python, it needs a real Python environment with
-`ipykernel` + `jupyter_client`. You cannot conjure that from nothing.
+Because the evaluator is real Python, it needs a real Python environment with `ipykernel`.
+You cannot conjure that from a script; it is a hard runtime dependency.
 
-The package's `postinstall` creates it once, at a stable user path
-(`~/.pi/agent/pi-repl-venv`), so a `pi install` ends with a working evaluator
-and updates do not lose it (the venv is outside the ephemeral package dir
-where it would vanish). At runtime the host resolves the interpreter in a
-short deterministic order (repo venv, cwd venv, the install venv, then
-`$PYTHON`/`python3`). The system interpreter is the fallback, never the
-assumption, because the whole tool quietly breaks if it silently runs in the
-wrong environment. This is a fact the toolbox functions' test in `help()`
-exist to keep visible.
+The package's `postinstall` creates it once, at a stable per-user path
+(`~/.pi/agent/pi-repl/venv`), so a `pi install` normally ends with a working evaluator. If
+`python3` or the network is missing at install time, `postinstall` prints a clear notice and
+the host falls back to `$PYTHON` or `python3` at runtime. Updates never lose it, because the
+venv lives outside the ephemeral package directory where it would vanish on every update.
+
+At runtime the host resolves the interpreter in a short, fixed order:
+
+1. the repo's own `.venv` (development)
+2. a venv in the current directory (per-project)
+3. the install venv at `~/.pi/agent/pi-repl/venv`
+4. `$PYTHON`, then `python3` (the fallback)
+
+The first one that exists wins. The system interpreter is the fallback, never the
+assumption, because the whole tool quietly breaks if it silently runs in the wrong
+environment. The tool's prompt tells the model this, so it does not leak the wrong
+assumption into commands.
 
 ## Trust, not a sandbox
 
-This is deliberately **not** a sandbox. The kernel runs with your user's
-permissions, can read and write anywhere you can, and the toolbox is trusted
-as written. If you need to guard against an untrusted model, this is the wrong
-tool: reach for a real sandbox the way you would for any untrusted user code.
-The philosophy prefers a sharp, honest tool over a pretend-safe one.
+This is deliberately **not a sandbox.** The kernel runs with your user's permissions, can
+read and write anywhere you can, and helpers are trusted as written. If you need to guard
+against an untrusted model, this is the wrong tool — reach for a real sandbox the way you
+would for any untrusted code. The philosophy here prefers a sharp, honest tool over a
+pretend-safe one.
 
 ## What it isn't
 
-- A subagent framework. There is no `rlm.run`. To delegate, the model spawns
-  a process with `bash()`.
-- A drop-in pi-tool parcel. It exposes one `execute` tool; everything else is
-  inside that workspace.
-- A replacement for your own editing/browsing tools required. It is there
-  when the working style above is worth it, dormant otherwise.
+- **A subagent framework.** There is no `repl.run`. To delegate, the model spawns a process
+  with `subprocess.run` (or `!cmd` / `%%bash`).
+- **A pi tool-rack.** It exposes one `execute` tool; everything else lives inside that
+  workspace.
+- **A replacement for your own editing and browsing tools.** It is there when the working
+  style above is worth it, and dormant otherwise.
 
-The trade-off is real and accepted: the agent pays a little more per-call to
-hold a heavier environment, and it gets back far fewer re-reads, fewer
-transcript round-trips, and sharper small-model behavior.
+The trade-off is real and accepted: the agent pays a little more per call to hold a heavier
+environment, and gets back far fewer re-reads, fewer transcript round-trips, and sharper
+small-model behaviour.