pi-repl-py 0.2.2 → 0.2.5

package/README.md

@@ -4,9 +4,9 @@ A [pi](https://pi.dev) extension that gives the agent a single `execute` tool ba
 **persistent Python evaluator**: a real `ipython` kernel that keeps variables, functions, imports,
 and data alive across every call and turn.
 
-There is no interactive shell. The agent batches code into a Python workspace that lives for the
-whole session, and only the printed result comes back. That is the part of a REPL an agent wants:
-lasting state and code-as-a-workspace, without the interactive loop in the way.
+There is no interactive shell. The agent sends batches of Python code to a workspace that stays
+alive for the session. Only the output comes back to the conversation. This keeps state in Python
+without requiring an interactive prompt.
 
 ```
 ✓ repl · data = load_json("records.json")       · done
@@ -36,16 +36,21 @@ A plain `pi` session is untouched; the extension is dormant until `--repl` is pa
 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).
 
+### Termux / Android
+
+On **Termux (Android)**, the `postinstall` venv build can fail because `ipykernel` depends on
+`psutil`, and PyPI does not provide a compatible Android wheel. The [Termux / Android setup guide](docs/termux.md) shows how to build `psutil` from source and finish the installation.
+
 ## 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 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.
+- **Shell and file IO as plain Python.** Use `!cmd` or `%%bash` for shell commands. Use
+  `subprocess.run(...)` when you need the result in a variable, and use `open()` or `pathlib`
+  for files. There is no extra wrapper API to learn.
 - **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.
+- **Explicit recovery.** If it restarts, pi-repl reports which state it restored and which state it lost.
 
 ## Helpers
 
@@ -80,8 +85,10 @@ 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: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Why this design: [docs/design.md](docs/design.md)
+- How it works, the venv, and the kernel: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- How to write and load helpers: [docs/helpers.md](docs/helpers.md)
+- Termux / Android installation: [docs/termux.md](docs/termux.md)
 
 ## It is not
 

package/docs/ARCHITECTURE.md

@@ -1,8 +1,8 @@
 # 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-repl runs in **two processes**. pi hosts the TypeScript extension, and the extension manages a
+separate Python `ipykernel` process where user code runs. The host talks to that kernel using the
+standard Jupyter protocol. There is no Python middleman and no private framing layer between them.
 
 ```
 pi
@@ -16,9 +16,9 @@ pi
              └─ 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.
+The host is TypeScript, and the evaluator is Python in a separate process. This means a cell can
+raise an exception or make the kernel unusable without taking pi down. The host can still report
+what happened.
 
 ## Why the host speaks ZMTP itself
 
@@ -28,21 +28,22 @@ design put a Python middleman (`guest.py`) between the host and the kernel, tran
 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`).
+host implements the small slice of ZMTP 3.0 that a Jupyter client needs. ZMTP is the socket
+protocol used by Jupyter's channels: the host uses a DEALER socket for shell and control, and 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.
+- **Messages are authenticated with HMAC.** The host signs and verifies Jupyter messages with
+  the kernel's HMAC key. The earlier design used a nonce to prevent false completion messages;
+  the standard message signature now provides that check.
 
 ## 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.
+`ipykernel` installed. This is a hard runtime dependency. A script cannot replace it.
 (`jupyter_client` is *not* needed: the host is the client.)
 
 When installed as a pi package, `npm install` runs `postinstall`
@@ -73,23 +74,23 @@ connection file in the temp directory, connects the three channels as ZMTP socke
 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.
+- **iopub** carries output messages such as `stream`, `execute_result`, `display_data`, and
+  `error`. It also carries private-MIME payloads for 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.
+Two details of this protocol are important enough to have dedicated contract tests.
 
-**A cell is not done until two things arrive.** The shell reply and the iopub output stream
+**A cell is not complete until two messages 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.
+(`maxOutputChars`). Overflow is checked within each message. A single 10 MB print trips the
+cap immediately instead of waiting for a later message to exhaust the budget. 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
@@ -98,20 +99,19 @@ kills the kernel after 500 ms, and the next call rebuilds it from the last snaps
 
 ## 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.
+At boot, the kernel and the host both read the same helpers directory:
+`~/.pi/agent/pi-repl/helpers`. It is created empty on install. No shipped toolbox is merged in.
 
-- **The kernel** execs each `*.py` into its namespace, so the file's functions become
-  callable.
+- **The kernel** executes each eligible `*.py` file in its namespace, so the file's definitions
+  and imports become available.
 - **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
+Both sides read the same directory, so the names described to the model come from files the
+kernel also loads. A file renamed with a `_` prefix is skipped by both sides. 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.
+change needs a **session restart or `/reload`** to reach the prompt. The kernel also loads
+helpers only at boot.
 
 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:
@@ -120,7 +120,7 @@ The model discovers what is loaded by listing the namespace with ordinary Python
 [k for k in globals() if not k.startswith('_')]
 ```
 
-For the full helper contract — the description, the docstring, disabling — see
+For the full helper contract, including descriptions, docstrings, and disabling, see
 [helpers.md](helpers.md).
 
 ## Snapshots & honest resets
@@ -131,8 +131,8 @@ only itself) and publishes the result back over a private MIME payload. The host
 `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,
+When a fresh engine is built, it restores that snapshot. It reports the names of values that
+could not be pickled, such as live handles and some runtime objects. 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.
 
@@ -151,32 +151,33 @@ what was lost, so the model re-verifies before reusing state that may be gone.
 - **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.
+  verifies persistence across cells, error survival, output attribution, helper loading,
+  snapshot/restore round-trips, output caps, silence timeout, abort, and rebuilding from a
+  snapshot after the kernel dies.
 
-The gate is `just check` — biome (format + lint) plus the host tests. `just integration`
-adds the real-kernel suite.
+The gate is `just check`. It runs Biome formatting and linting, dead-code checks, and 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:
+There is no configuration file. Most state lives under one directory in the user's home. A
+small number of environment variables can still change runtime behavior, such as the silence
+watchdog timeout.
 
 ```
 ~/.pi/agent/pi-repl/
   venv/         the Python interpreter + ipykernel
-  helpers/      the helpers directory — every *.py loads into every kernel
+  helpers/      the helpers directory; every eligible *.py loads into each 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
+venv is built automatically, and the interpreter follows the order above. No setting is
 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)
+- Design rationale: [design.md](design.md)
 - Adding a helper: [helpers.md](helpers.md)

package/docs/{philosophy.md → design.md}

@@ -1,4 +1,4 @@
-# Philosophy: why a persistent Python workspace
+# Design rationale: why a persistent Python workspace
 
 ## The bet
 
@@ -7,13 +7,12 @@ a search tool, each with its own schema, its own failure modes, and its own toke
 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.** 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.
+pi-repl makes the opposite choice: **give the model one persistent Python workspace and let it
+compose the work there.** Reading, running, searching, and editing happen in code inside one
+namespace. The interface stays small while the code changes to fit the task.
 
-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.
+This project assumes an agent benefits from a REPL that keeps working state alive. It is not an
+interactive prompt for a person to type into; it is long-lived working memory for the model.
 
 ## What persistence buys
 
@@ -26,10 +25,9 @@ In a persistent kernel that work happens once and stays put:
 - 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;
 - `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 agent can branch on with normal code. It does not need to re-parse tool output.
 
-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,
+Holding a whole file in context just to avoid re-reading it is expensive 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
@@ -38,12 +36,12 @@ pi-repl does not hand-roll an `exec` loop. It drives a genuine `ipython` kernel
 separate process. That buys four things a script string passed to `exec` cannot give:
 
 - **rich, real tracebacks** instead of a wrapped `except`;
-- **real interrupts** — a stuck cell can be interrupted mid-run without losing the session;
+- **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.
+- **a namespace that survives errors:** a cell that throws leaves the kernel and everything
+  defined before it intact.
 
-It is also an honest isolation boundary. The kernel is its own process, not part of pi. A
+The kernel is a separate process, not part of pi. This is a process boundary, not a security sandbox. 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.
@@ -56,31 +54,22 @@ revived and what it lost, so the model re-verifies before trusting state that ma
 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 per-user path
+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.
+The host has a fallback order for finding Python, with the project and installed environments
+preferred over the system interpreter. The exact order and the reasons for it are documented in
+[ARCHITECTURE.md](ARCHITECTURE.md). This keeps the design rationale here focused on why the
+venv is persistent rather than on runtime lookup details.
 
 ## 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 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.
+against an untrusted model, this is the wrong tool. Use a real sandbox for untrusted code. The design favors a clear limitation over a false promise of safety.
 
 ## What it isn't
 

package/docs/helpers.md

@@ -1,110 +1,185 @@
-# How to write a helper
+# Helpers
 
-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.
+Helpers are optional Python files that pi-repl loads into the persistent workspace. Use one when
+code is worth reusing. A helper can also give the model a reliable wrapper instead of making it
+rebuild the same plumbing in every cell.
 
-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.
+A helper can define a function, class, constant, import, or configured object. The filename labels the helper entry shown in the prompt. It does not have to match a function
+name or any other public name in the file.
 
-## Prerequisites
+## Where helpers live
 
-- 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.
+```text
+~/.pi/agent/pi-repl/helpers/
+```
+
+The directory is created empty when pi-repl is installed. Every `.py` file in it is loaded when the evaluator starts. Files whose names begin with `_` are ignored.
 
-## The smallest helper
+After adding, changing, renaming, or disabling a helper, run `/reload` or start a new `pi --repl` session. The running evaluator does not watch the directory for changes.
 
-Create this file:
+## A small function helper
+
+Create `double.py`:
 
 ```python
-# ~/.pi/agent/pi-repl/helpers/double.py
 helper_description = """double(x) — multiply a value by two."""
 
+
 def double(x):
     """Return x * 2. Works on ints, floats, and lists."""
     return x * 2
 ```
 
-Restart the session (`/reload`, or relaunch `pi --repl`), then check it loaded:
+Reload pi, then call it from `execute`:
 
 ```python
-print([k for k in globals() if not k.startswith('_')])
-# ['double', ...]
-
 print(double(21))
 # 42
 ```
 
-If `double` appears in the namespace and runs, it's loaded. That is the whole loop: write
-the file, restart, use it.
+The evaluator runs the file in its global namespace, so `double` is directly available. You do not register or separately install an individual helper.
 
-## How it actually works
+## A helper can expose an object
 
-Two things happen with the file you wrote:
+A helper does not need to expose a function with the same name as its file. For example, `web.py` can create a configured `web` object:
 
-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*).
+```python
+helper_description = """web — search, read, and map websites."""
 
-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.
 
-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.
+class Web:
+    def search(self, query):
+        """Search the web and return normalized results."""
+        raise NotImplementedError
 
-## The three parts of a helper file
 
-| 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 |
+web = Web()
+```
 
-**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.
+The model calls `web.search(...)`, not `web(...)`. See [`example/helper/web.py`](../example/helper/web.py) for the full provider-backed example.
 
-**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):
+## What the model sees
 
-- 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.`
+A helper may define `helper_description`:
 
-**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.
+```python
+helper_description = """double(x) — multiply a value by two."""
+```
+
+The host reads this value and puts it in the `execute` tool description verbatim. It is guidance for the model, not a registration mechanism or generated API. Keep it short: it
+is included in the model's context on every turn.
+
+A useful description answers three questions:
+
+1. What does this helper provide?
+2. How should the model call it?
+3. What important behavior or limitation should it know before calling it?
+
+For a helper that replaces hand-written plumbing, an `Instead of:` line can be useful:
+
+```python
+helper_description = """web — search, read, and map websites.
+Use web.search(query), web.read(url), and web.map(url).
+Instead of: writing provider requests and parsing each response by hand."""
+```
+
+Do not put the complete API contract in the description. Long explanations consume context on every call. Put detailed behavior in docstrings instead.
+
+## Docstrings are on-demand detail
+
+Docstrings stay in the Python workspace and do not appear in the tool description automatically:
+
+```python
+def double(x):
+    """Return x * 2.
+
+    Accepts numbers and lists. Raises no custom exceptions.
+    """
+    return x * 2
+```
+
+When the description is not enough, inspect the helper in the workspace:
+
+```python
+help(double)
+print(double.__doc__)
+```
+
+Use docstrings for argument details, defaults, return values, errors, environment requirements, and side effects.
+
+## How loading works
+
+At startup, two parts of pi-repl read the same helper directory:
+
+1. The kernel executes each eligible `.py` file. Its definitions become names in the Python workspace.
+2. The host reads `helper_description` to build the helper guidance shown to the model.
+
+The host does not inspect `def` lines or infer signatures from filenames. A helper does not need to define one particular symbol. The file is the unit of loading; its public names are the names it defines or imports for use in
+the workspace.
+
+Because helpers execute at kernel startup, top-level code has consequences. Definitions are fine; imports should be reasonable; network calls, prints, subprocesses, and expensive work should usually happen inside an explicit function or method call.
+
+## Choosing what belongs in a helper
+
+Write a helper when it owns a part of the work that is easy to get wrong or tedious to repeat:
+
+- a web client that handles authentication, fallback, and response normalization;
+- a conversion with awkward edge cases;
+- a project-specific API client;
+- a small collection of related operations with shared configuration.
+
+Do not make a helper for ordinary Python that the model can write clearly in one cell. File access and subprocess work are already available through normal Python:
+
+```python
+from pathlib import Path
+import subprocess
+
+text = Path("notes.txt").read_text()
+result = subprocess.run(["git", "status", "--short"], capture_output=True, text=True, check=False)
+```
+
+The helper should handle the plumbing. The model should still decide what to inspect, which sources matter, and what the evidence supports.
 
 ## Common mistakes
 
-- **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.
+### Description too long
+
+The description is repeated in the tool prompt. Put the call shape and the few facts needed to choose the helper there; put examples and edge cases in docstrings.
+
+### Public names are unclear
+
+If `web.py` exposes `web`, document `web.search()` and `web.read()`. Do not describe it as `web()` unless the file actually defines a callable named `web`.
+
+### Side effects happen during loading
+
+The file is executed before the first cell. A top-level print pollutes every new session, and a top-level network request can make startup slow or fail before the model calls anything. Constructing a lightweight object is usually fine; defer expensive work to a method.
 
-## Disable a file without deleting it
+### A changed helper is not visible
+
+The prompt guidance and kernel namespace are established during startup. Run `/reload` after editing the file.
+
+### A helper hides the decision
+
+A helper can normalize responses or manage retries. For example, the web helper can hide
+provider authentication and fallback. It should not silently decide which source proves a claim
+or which file should be edited; those decisions belong to the model.
+
+## Disable a helper without deleting it
+
+Rename the file with a leading underscore:
+
+```text
+web.py → _web.py
+```
 
-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.
+The loader skips it. Rename it back and reload when you want it again.
 
 ## Checklist
 
-- [ ] 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
+- [ ] The file is in `~/.pi/agent/pi-repl/helpers/`.
+- [ ] Its public names and call shapes are clear.
+- [ ] `helper_description` is short enough for every-turn context.
+- [ ] Detailed behavior is in docstrings.
+- [ ] Top-level code has no unnecessary side effects.
+- [ ] The helper keeps plumbing separate from model judgment.
+- [ ] Pi was reloaded after the file changed.

package/docs/termux.md

@@ -0,0 +1,49 @@
+# Termux / Android setup
+
+On **Termux (Android)**, the `postinstall` venv build can fail because `ipykernel` depends on
+`psutil`, and PyPI does not provide a compatible Android wheel. Two common alternatives do not
+solve the problem:
+
+- `pkg install python-psutil`: Termux's `.deb` post-install runs the same failing `pip install
+  psutil`, so no usable psutil is left.
+- `pip install psutil-android`: the prebuilt `.so` links `libpython3.14.so`; on an older
+  Termux Python it fails with `dlopen failed: library "libpython3.14.so" not found`. It works
+  only when Termux's Python matches the wheel's ABI (currently 3.14).
+
+The reliable route is to build the documented `psutil` release from source with a small
+Android-specific change, then install the evaluator venv. Run these commands from a writable
+working directory. If the release changes, update the source URL, version numbers, and patch
+before running them:
+
+```bash
+# 1. show a compiler + Python headers
+pkg install clang python
+
+# 2. fetch and patch the psutil source so Android counts as Linux
+curl -sL -o psutil.tar.gz https://files.pythonhosted.org/packages/source/p/psutil/psutil-7.2.2.tar.gz && tar -xzf psutil.tar.gz
+cd psutil-7.2.2
+sed -i 's/LINUX = sys.platform.startswith("linux")/LINUX = sys.platform.startswith(("linux", "android"))/' psutil/_common.py
+python3 setup.py bdist_wheel
+# If this reports that wheel is missing:
+python3 -m pip install wheel
+
+# 3. (re)build the evaluator venv and install the patched wheel first
+python3 -m venv --clear ~/.pi/agent/pi-repl/venv
+~/.pi/agent/pi-repl/venv/bin/pip install dist/psutil-7.2.2-*.whl
+~/.pi/agent/pi-repl/venv/bin/pip install ipykernel
+
+# 4. finish the package install
+pi install npm:pi-repl-py
+
+# 5. verify
+~/.pi/agent/pi-repl/venv/bin/python3 -c "import psutil, ipykernel; print(psutil.__version__, ipykernel.__version__)"
+```
+
+The final command checks that both packages import successfully. Then start pi-repl:
+
+```bash
+pi --repl
+```
+
+The venv already contains the working `ipykernel` that the evaluator needs.
+

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.2.2",
+	"version": "0.2.5",
 	"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/src/extension/prompt.ts

@@ -1,76 +1,70 @@
 // --- prompt: the execute tool's model-facing contract (pure, no pi/helper dep) ---
+//
+// Verbatim clauses from CodeAct (arXiv 2402.01030) and RLM (arXiv 2512.24601)
+// are trimmed to what pi-repl actually has — no sub-LLMs, no recursion, no
+// context variable — and the rest is stripped for lean context. Less prose,
+// more signal; the machine reads every line every turn.
 
 export const executeToolDescription =
 	"You have one tool: a persistent Python workspace backed by a real `ipython` kernel. " +
-	"Variables, imports, functions, and data survive across cells and turns. Use this tool to read files, " +
-	"run shell commands, search code, transform data, and build up solutions — all inside Python. " +
-	"Helpers in `~/.pi/agent/pi-repl/helpers/` are loaded at boot as functions; see what's loaded with " +
-	"`[k for k in globals() if not k.startswith('_')]`. A cell returns its final expression; printed output " +
-	"is captured separately.";
+	"Variables, imports, and definitions survive across cells and turns — it is your working memory and action " +
+	"language. " +
+	"Helpers in `~/.pi/agent/pi-repl/helpers/` load at boot; list them with " +
+	"`[k for k in globals() if not k.startswith('_')]`. A cell returns its final expression; printed output is " +
+	"captured separately.";
 
 export const executePromptSnippet =
-	"Use the Python workspace: keep state in variables, batch independent reads/searches in one cell, " +
-	"edit files safely, and iterate in small cells.";
+	"Work in the workspace: keep artifacts in variables, compose related actions in Python, print only what " +
+	"the next step needs, and revise from what you observe.";
 
 // --- the workspace doctrine riding the execute tool ---
 export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
-		"## This workspace is your only tool",
-		"In `--repl` mode, `execute` is the only callable tool. Read files, run shell, search, and edit " +
-			"all happen inside Python.",
+		"## Your only workspace",
+		"`execute` is the only callable tool. Python replaces a read, shell, search, and edit tool rack. State " +
+			"persists across cells and turns.",
 		"",
-		"## The loop is generate → execute → observe → iterate",
-		"Write a cell, run it, observe the result, then write the next cell. Build solutions incrementally.",
+		"## Work in the workspace, not the transcript",
+		"Load files, command results, search hits, and computed artifacts into variables once; filter, compare, " +
+			"branch, edit, and verify them in later cells. Do not re-read or paste raw material back. Print only the " +
+			"small observation needed for the next decision; keep the full artifact in a variable.",
 		"",
-		"## State persists",
-		"Variables, imports, and functions survive across cells and turns. Assign read/search results to " +
-			"named variables and reuse them.",
+		"## A cell is a small program",
+		"Compose filesystem access, shell commands, searches, transforms, checks, and edits in ordinary Python " +
+			"when they belong to the same step.",
 		"",
-		"## Chain big tasks into verifiable steps",
-		"Break ambitious requests into independently checkable steps. Confirm assumptions before writing " +
-			"code that depends on them.",
+		"## Revise on observations",
+		"Revise prior actions or emit new actions upon new observations.", // CodeAct core
 		"",
-		"## Shell & files are plain Python",
-		"`!cmd` / `%%bash` for fire-and-forget shell; `subprocess.run(..., timeout=...)` when you need the result back " +
-			"as a value — always set a `timeout` on anything that could hang (the evaluator does not kill a " +
-			"silent cell automatically). `open()` / `pathlib` read and write files. For safe edits: read the full " +
-			"file, modify in memory, write once, then re-read to verify.",
+		"## Probe, then build",
+		"Inspect what is present — count, print a few lines, list what is loaded — before committing. Build one " +
+			"step, run it, and use its output to choose the next.",
 		"",
-		"## Batch independent work, keep exploratory cells small",
-		"Batch independent reads, searches, and setup steps in one cell to reduce round-trips. Keep " +
-			"exploratory/iterative cells small so you can observe and adjust.",
-		"",
-		"## Search efficiently",
-		"Use `rg`, `fd`, `grep`, `find` via `subprocess.run` for deep searches, not Python loops.",
+		"## Batch and print sparingly",
+		"Batch as much independent work as reasonably possible into one call. Keep large values in variables; " +
+			"print slices, counts, and summaries.",
 		"",
 		...(preloaded.length
 			? [
 					"## Helpers",
-					"User helpers load from `~/.pi/agent/pi-repl/helpers/`. Their descriptions appear below. " +
-						"List what's loaded with `[k for k in globals() if not k.startswith('_')]`.",
+					"User helpers load from `~/.pi/agent/pi-repl/helpers/` as workspace definitions. Their descriptions " +
+						"appear below. List what is loaded with `[k for k in globals() if not k.startswith('_')]`.",
 					"",
 					...preloaded,
 					"",
 				]
 			: []),
-		"## Compose and reuse",
-		"If the same pattern appears more than once, wrap it in a `def` and reuse it.",
-		"",
-		"## Output discipline",
-		"Printing is a context cost: everything a cell prints stays in the transcript. Print slices, " +
-			"counts, and summaries. Keep large values in variables. End a cell with `;` to suppress the " +
-			"last-expression echo.",
+		"## Shell and search",
+		"`subprocess.run(..., timeout=...)` when you need a result — always set a `timeout`, the evaluator does not " +
+			"kill a silent cell. Use `rg`/`grep`/`find` via `subprocess.run` for deep searches, not Python loops.",
 		"",
 		"## Environment boundary",
 		"The evaluator runs in a project-local venv, not the system Python. Do not install a target project's " +
-			"dependencies into the evaluator just to make that project run there. Run external projects " +
-			"through their own interface and normal commands.",
+			"dependencies into the evaluator. Run external projects through their own interface and normal commands.",
 		"",
 		"## Engine reset guard",
-		"If the output begins with `<repl_engine_reset>`, the kernel was rebuilt from the last snapshot. " +
-			"Some variables may be revived, some lost, and anything defined after the snapshot is gone. " +
-			"Re-verify variables before reusing them — never interpolate a restored variable into a shell " +
-			"command until you have confirmed it still holds what you expect. Functions, classes, and live " +
-			"handles cannot be snapshotted and must be redefined.",
+		"If output begins with `<repl_engine_reset>`, the kernel was rebuilt from the last snapshot. Re-verify a " +
+			"revived variable before reusing it — especially in a shell command. Functions, classes, and live handles " +
+			"are not snapshotted and must be redefined.",
 	];
 }