pi-repl-py 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,141 @@
+# 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shift Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# pi-repl
+
+A [pi](https://pi.dev) extension that gives the agent a single `execute` tool backed by a
+**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.
+
+```
+✓ repl · data = load_json("records.json")       · done
+✓ repl · avg = sum(v["score"] for v in data)/len(data)
+✓ repl · print("mean score:", round(avg, 2))    · mean score: 41.7
+```
+
+`data` is still there in cell three. Nothing was re-read, nothing re-derived from output, because
+the kernel stayed alive.
+
+## Quick start
+
+```bash
+# from a clone, one-time setup
+just setup            # npm install + a project-local .venv with the guest deps
+
+# run a session
+pi --repl
+```
+
+A plain `pi` session is untouched; the extension is dormant until `--repl` is passed (or
+`PI_REPL_FORCE=1`).
+
+## 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).
+
+## 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.
+- **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
+
+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.
+
+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.
+
+- Adding a function (the file contract, docstrings, disabling): [docs/how-to-functions.md](docs/how-to-functions.md)
+
+## Configuration
+
+`~/.pi/agent/pi-repl.json` (or `$PI_REPL_CONFIG`) sets `toolboxDir`, `pythonPath`, and timeouts.
+Full keys and path rules: [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## More
+
+- Why this design: [docs/philosophy.md](docs/philosophy.md)
+- How it works, the venv, config reference: [ARCHITECTURE.md](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 pi tool-rack. It is one `execute` tool with functions inside.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/docs/how-to-functions.md

@@ -0,0 +1,107 @@
+# How to add a toolbox function
+
+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.
+
+> **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.
+
+## Where functions live
+
+By default the extension ships four (`read`, `write`, `edit`, `bash`) in
+`src/engine/toolbox/`. To use your **own** set, set `toolboxDir` in your
+config:
+
+```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 file contract
+
+Every toolbox file must:
+
+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).
+
+A minimal, valid file:
+
+```python
+# pi-repl-functions/summarize.py
+function_description = """Return a first-sentence summary of a text."""
+
+__all__ = ["summarize"]
+
+def summarize(text, limit=1):
+    return ". ".join(text.split(". ")[:limit]) + "."
+```
+
+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.
+
+## The two pieces the loader reads
+
+**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.
+
+**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.
+
+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.
+
+## How much to document
+
+`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").
+
+## Disabling a file without deleting it
+
+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.
+
+## Good practice
+
+- 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.
+
+## Confirming it worked
+
+At a `pi --repl` prompt, run a cell:
+
+```python
+print(ls())           # list what's loaded
+print(help('summarize'))  # signature + full docstring details
+```
+
+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.

package/docs/philosophy.md

@@ -0,0 +1,88 @@
+# Philosophy: why a persistent Python workspace
+
+## 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.
+
+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.
+
+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.
+
+## 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.
+
+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 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.
+
+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.
+
+## 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:
+
+- 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`.
+
+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`.
+
+## 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.
+
+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.
+
+## 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.
+
+## 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.
+
+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.

package/index.ts

@@ -0,0 +1,220 @@
+// --- pi-repl: one execute tool over Python; everything else runs as functions inside it ---
+
+import { basename, join } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { EngineBusyError, EngineManager } from "./src/engine/index.js";
+import { loadConfig } from "./src/extension/config.js";
+import { ExecuteCellComponent, type ExecuteDetails, type ExecuteRenderState } from "./src/extension/render.js";
+import { EngineLifecycle, summarizeNames } from "./src/extension/session-engine.js";
+import { EXECUTE_DESCRIPTION, buildExecutePromptGuidelines, EXECUTE_PROMPT_SNIPPET } from "./src/extension/tool-meta.js";
+
+const executeSchema = Type.Object({
+	code: Type.String({
+		description: "Python to execute in the persistent evaluator.",
+	}),
+});
+
+function syncRenderState(
+	state: Partial<ExecuteRenderState>,
+	context: {
+		args?: { code?: string };
+		isPartial: boolean;
+		isError: boolean;
+		expanded: boolean;
+		executionStarted: boolean;
+	},
+): ExecuteRenderState {
+	state.code = context.args?.code ?? state.code ?? "";
+	state.isPartial = context.isPartial;
+	state.isError = context.isError;
+	state.expanded = context.expanded;
+	state.executionStarted = context.executionStarted;
+	state.hasResult = state.hasResult ?? false;
+	return state as ExecuteRenderState;
+}
+
+/** Stack lines kept when surfacing a cell error to the model. */
+const ERROR_STACK_LINES = 10;
+
+/** Header plus stack — without repeating the header when the stack already starts with it. */
+function composeErrorLines(error: { name: string; message: string; stack: string[] }): string[] {
+	const header = `${error.name}: ${error.message}`;
+	const stack = error.stack.slice(0, ERROR_STACK_LINES);
+	return stack[0]?.trim() === header ? stack : [header, ...stack];
+}
+
+const CFG = loadConfig();
+
+export default function (pi: ExtensionAPI) {
+	pi.registerFlag("repl", {
+		type: "boolean",
+		description: "Single execute tool backed by a persistent Python evaluator; replaces the default tool surface",
+	});
+	// Flag only lands post-factory; gate per event. PI_REPL_FORCE is the dev escape.
+	const active = () => pi.getFlag("repl") === true || process.env.PI_REPL_FORCE === "1";
+
+	let location = { cwd: process.cwd(), sessionFile: undefined as string | undefined };
+	// Pi rebuilds thrown errors as bare text; stash details to re-attach in tool_result.
+	const pendingErrorResults = new Map<string, { details: ExecuteDetails }>();
+
+	const lifecycle = new EngineLifecycle<EngineManager>({
+		create() {
+			const { cwd, sessionFile } = location;
+			const sessionKey = sessionFile ? basename(sessionFile).replace(/\.jsonl$/, "") : undefined;
+			const stateDir = join(cwd, ".pi-repl", sessionKey ?? "ephemeral");
+			return new EngineManager({
+				cwd,
+				pythonPath: CFG.pythonPath,
+				timeoutMs: CFG.timeoutMs,
+				toolboxDir: CFG.toolboxDir,
+				// --- snapshots are keyed to a session file; ephemeral sessions get none ---
+				snapshot: sessionKey ? { path: join(stateDir, "namespace.snapshot") } : undefined,
+			});
+		},
+		async dispose(engine) {
+			await engine.dispose();
+		},
+		// --- a wedged guest can't answer dispose; kill and rely on the last snapshot ---
+		async discard(engine) {
+			await engine.kill();
+		},
+	});
+
+	// --- no custom prompt: pi's default prompt stands. session_start collapses
+	//     the active set to just `execute`, so the default prompt's built-in
+	//     read/bash/edit/write never appear. All REPL knowledge (description,
+	//     promptSnippet, promptGuidelines) lives on the tool itself, not in a
+	//     prompt builder. ---
+
+	pi.on("session_start", async (_event, ctx) => {
+		if (!active()) {
+			// --- drop execute so a stock session stays stock ---
+			pi.setActiveTools(pi.getActiveTools().filter((name) => name !== "execute"));
+			return;
+		}
+		// --- active: the whole surface collapses to the one tool ---
+		pi.setActiveTools(["execute"]);
+		// --- revive the previous run; the engine also self-revives if session_start was skipped ---
+		location = { cwd: ctx.cwd, sessionFile: ctx.sessionManager.getSessionFile() ?? undefined };
+		const { restore } = await lifecycle.acquire("startup");
+		if (restore && restore.restored.length > 0) {
+			pi.sendMessage({
+				customType: "pi-repl-restore",
+				content: `Revived ${restore.restored.length} variable(s) from the previous run: ${summarizeNames(restore.restored, 8)}${
+					restore.failed.length > 0
+						? `. Failed: ${summarizeNames(
+								restore.failed.map((f) => f.name),
+								8,
+							)}`
+						: ""
+				}`,
+				display: true,
+			});
+		}
+	});
+
+	pi.on("session_shutdown", async () => {
+		await lifecycle.shutdown();
+	});
+
+	pi.on("tool_result", async (event) => {
+		if (event.toolName !== "execute") return undefined;
+		const stashed = pendingErrorResults.get(event.toolCallId);
+		pendingErrorResults.delete(event.toolCallId);
+		if (!stashed || !event.isError) return undefined;
+		// --- restore the collapsed details an errored cell lost ---
+		return { content: event.content, details: stashed.details, isError: true };
+	});
+
+	pi.registerTool<typeof executeSchema, ExecuteDetails, Partial<ExecuteRenderState>>({
+		name: "execute",
+		label: "execute",
+		description: EXECUTE_DESCRIPTION,
+		promptSnippet: EXECUTE_PROMPT_SNIPPET,
+		promptGuidelines: buildExecutePromptGuidelines(CFG.toolboxDir),
+		parameters: executeSchema,
+		renderShell: "self",
+		renderCall(args, theme, context) {
+			const state = syncRenderState(context.state, { ...context, args });
+			// --- compact header lives in the call slot ---
+			return new ExecuteCellComponent(state, theme, "header");
+		},
+		renderResult(result, options, _theme, context) {
+			const state = syncRenderState(context.state, context);
+			state.hasResult = true;
+			state.isPartial = options.isPartial;
+			state.expanded = options.expanded;
+			state.details = (result.details as ExecuteDetails | undefined) ?? state.details;
+			state.contentText = result.content
+				?.filter((block): block is { type: "text"; text: string } => block.type === "text")
+				.map((block) => block.text)
+				.join("\n");
+			// --- body (code + output) lives in the result slot; Ctrl+O expands it ---
+			return new ExecuteCellComponent(state, _theme, "body");
+		},
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			if (!active()) {
+				throw new Error("pi-repl is dormant in this session. Start pi with --repl (or PI_REPL_FORCE=1) to use execute.");
+			}
+			if (ctx?.cwd) location = { cwd: ctx.cwd, sessionFile: ctx.sessionManager?.getSessionFile?.() ?? undefined };
+			// --- previous engine died mid-session; acquire revives it ---
+			const { engine: m } = await lifecycle.acquire("cell");
+			try {
+				// --- accumulate partial updates so the row height doesn't oscillate ---
+				let streamed = "";
+				const r = await m.execute(params.code, {
+					signal,
+					onStream: (chunk) => {
+						streamed += chunk;
+						onUpdate?.({ content: [{ type: "text", text: streamed }], details: {} });
+					},
+				});
+				// --- reset notice leads so the model reads that its namespace was rebuilt ---
+				const sections = [lifecycle.takeResetNotice(), r.stdout, r.stderr, r.result];
+				const errorLines = r.error ? composeErrorLines(r.error) : undefined;
+				if (r.status === "error" && errorLines) sections.push(errorLines.join("\n"));
+				if (r.status === "aborted") sections.push("[cell aborted]");
+			const text = sections.filter((section) => section !== undefined && section !== "").join("\n");
+
+			const details: ExecuteDetails = {
+				status: r.status,
+				durationMs: r.durationMs,
+				errorName: r.error?.name,
+				stdout: r.stdout || undefined,
+				stderr: r.stderr || undefined,
+				result: r.result,
+				errorStack: errorLines,
+			};
+			const result = { content: [{ type: "text" as const, text: text || "(no output)" }], details };
+			if (r.status === "error") {
+				pendingErrorResults.set(toolCallId, { details });
+				throw new Error(text || "(no output)");
+			}
+			if (r.status === "aborted") {
+				// A cancelled cell's kernel may still be executing work the guest
+				// single-threaded loop can't interrupt. Discard the engine so the
+				// NEXT run gets a fresh kernel instead of queuing behind the
+				// still-busy one (same class as the stalled-timeout recovery).
+				await lifecycle.discard();
+			}
+			return result;
+		} catch (error) {
+			if (error instanceof EngineBusyError) {
+				// --- discard the wedged engine; the next cell revives from the last snapshot ---
+				await lifecycle.discard();
+				throw new Error(
+					"The evaluator was wedged by a previously interrupted cell and has been killed. " +
+						"Run the next cell to get a fresh evaluator revived from the last snapshot; " +
+						"anything newer than that snapshot is gone, so re-verify variables before reusing them.",
+				);
+			}
+			// --- a guest that died leaves the engine shutdown; drop it so the next cell rebuilds fresh ---
+			if (m.isRunning === false) {
+				await lifecycle.discard();
+			}
+			throw error;
+		}
+		},
+	});
+}