pi-repl-py 0.1.0 → 0.1.1

package/README.md

@@ -33,7 +33,7 @@ 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
+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
@@ -52,7 +52,19 @@ A small set of Python functions is preloaded into every kernel and surfaced to t
 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.
+Set `toolboxDir` to point at your own folder; its functions are loaded **in addition to** the built-ins, and a file there with the **same name** as a built-in overrides it.
+
+Everything the extension keeps lives under one folder in your home directory:
+
+```
+~/.pi/agent/pi-repl/
+  config.json   settings (toolboxDir, pythonPath, timeoutMs)
+  venv/         the Python interpreter + ipykernel
+  functions/    your custom toolbox functions, if any
+  state/        per-session namespace snapshots
+```
+
+These functions are the evaluator's standard file-and-shell surface; the model reaches for them as its builtins and composes its own reusable tools on top.
 
 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
@@ -63,13 +75,13 @@ the kernel also only loads the toolbox 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).
+`~/.pi/agent/pi-repl/config.json` (or `$PI_REPL_CONFIG`) sets `toolboxDir`, `pythonPath`, and timeouts.
+Full keys and path rules: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ## 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
 

package/{ARCHITECTURE.md → docs/ARCHITECTURE.md}

@@ -26,7 +26,7 @@ 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
+~/.pi/agent/pi-repl/venv/bin/python3
 ```
 
 That path is stable across updates because it sits outside the ephemeral
@@ -38,7 +38,7 @@ 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)
+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
@@ -94,7 +94,8 @@ bare kernel still lets the model discover what is loaded.
 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
+session file under `~/.pi/agent/pi-repl/state/<session>/`. 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>`
@@ -125,12 +126,12 @@ Gate: `just check` = biome + bun test (host) + pytest (guest).
 
 ## Configuration reference
 
-Loaded from `~/.pi/agent/pi-repl.json` (or `$PI_REPL_CONFIG`), first-found-wins, never
+Loaded from `~/.pi/agent/pi-repl/config.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. |
+| `toolboxDir` | string, optional | Directory of one-function-per-`.py` files that ADDS to the shipped `src/engine/toolbox` and, when a name collides, overrides that built-in. `~` 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. |

package/docs/how-to-functions.md

@@ -17,15 +17,16 @@ By default the extension ships four (`read`, `write`, `edit`, `bash`) in
 config:
 
 ```jsonc
-// ~/.pi/agent/pi-repl.json
-{ "toolboxDir": "~/.pi/agent/pi-repl-functions" }
+// ~/.pi/agent/pi-repl/config.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.
+every `*.py` there is loaded **in addition to** the shipped `read`/`write`/`edit`/`bash`.
+If a file in your folder has the **same name** as a built-in (e.g. `read.py`), your
+version wins and the built-in is ignored for that name.
 
 ## The file contract
 
@@ -38,7 +39,7 @@ Every toolbox file must:
 A minimal, valid file:
 
 ```python
-# pi-repl-functions/summarize.py
+# pi-repl/functions/summarize.py
 function_description = """Return a first-sentence summary of a text."""
 
 __all__ = ["summarize"]

package/docs/philosophy.md

@@ -57,7 +57,7 @@ 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
+(`~/.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

package/index.ts

@@ -1,6 +1,7 @@
 // --- pi-repl: one execute tool over Python; everything else runs as functions inside it ---
 
 import { basename, join } from "node:path";
+import { homedir } from "node:os";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import { EngineBusyError, EngineManager } from "./src/engine/index.js";
@@ -62,7 +63,8 @@ export default function (pi: ExtensionAPI) {
 		create() {
 			const { cwd, sessionFile } = location;
 			const sessionKey = sessionFile ? basename(sessionFile).replace(/\.jsonl$/, "") : undefined;
-			const stateDir = join(cwd, ".pi-repl", sessionKey ?? "ephemeral");
+			// --- kernel namespace state lives under ~/.pi/agent/pi-repl, keyed by session, so it never clutters the project ---
+			const stateDir = join(homedir(), ".pi", "agent", "pi-repl", "state", sessionKey ?? "ephemeral");
 			return new EngineManager({
 				cwd,
 				pythonPath: CFG.pythonPath,
@@ -81,11 +83,7 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	// --- 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. ---
+	// --- no custom prompt: pi's default prompt stands; active tools collapse to execute, so REPL knowledge lives on the tool ---
 
 	pi.on("session_start", async (_event, ctx) => {
 		if (!active()) {
@@ -192,10 +190,7 @@ export default function (pi: ExtensionAPI) {
 				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).
+				// --- a busy kernel can't be interrupted mid-cell; discard+rebuild so the next run doesn't queue ---
 				await lifecycle.discard();
 			}
 			return result;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"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": [
@@ -11,6 +11,14 @@
 		"repl"
 	],
 	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/k3-2o/pi-repl-py.git"
+	},
+	"homepage": "https://github.com/k3-2o/pi-repl-py",
+	"bugs": {
+		"url": "https://github.com/k3-2o/pi-repl-py/issues"
+	},
 	"pi": {
 		"extensions": [
 			"./index.ts"
@@ -22,7 +30,6 @@
 		"docs",
 		"index.ts",
 		"README.md",
-		"ARCHITECTURE.md",
 		"LICENSE"
 	],
 	"engines": {

package/scripts/setup-venv.mjs

@@ -8,7 +8,7 @@
  * and excluded from the npm tarball), so we create one at a stable path that
  * the engine also knows about:
  *
- *   ~/.pi/agent/pi-repl-venv/bin/python3
+ *   ~/.pi/agent/pi-repl/venv/bin/python3
  *
  * Failures are non-fatal: if there's no system python3 or no network, we print
  * a clear notice and let the engine fall back to '$PYTHON' or 'python3' at
@@ -20,7 +20,7 @@ import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-const VENV_DIR = join(homedir(), ".pi", "agent", "pi-repl-venv");
+const VENV_DIR = join(homedir(), ".pi", "agent", "pi-repl", "venv");
 const PY = join(VENV_DIR, "bin", "python3");
 const DEPS = ["ipykernel", "jupyter_client"];
 

package/src/engine/guest.py

@@ -83,7 +83,10 @@ def _toolbox_files(directory):
 
 DEFAULT_TOOLBOX_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "toolbox")
 TOOLBOX_DIR = os.environ.get("PI_TOOLBOX_DIR", "").strip()
-_TOOLBOX_SRC = _toolbox_files(TOOLBOX_DIR or DEFAULT_TOOLBOX_DIR)
+# --- Merge: built-ins are supreme; a config toolboxDir adds others and overrides on name ---
+_TOOLBOX_SRC = _toolbox_files(DEFAULT_TOOLBOX_DIR)
+if TOOLBOX_DIR and os.path.expanduser(TOOLBOX_DIR) != DEFAULT_TOOLBOX_DIR:
+    _TOOLBOX_SRC.update(_toolbox_files(TOOLBOX_DIR))
 
 # --- help/ls are part of the evaluator, not the toolbox ---
 INTRINSIC = """

package/src/engine/index.ts

@@ -20,7 +20,7 @@ const GUEST_PATH = fileURLToPath(new URL("./guest.py", import.meta.url));
 
 // --- venv created by the package postinstall ---
 function installVenvPython(): string {
-	return join(homedir(), ".pi", "agent", "pi-repl-venv", "bin", "python3");
+	return join(homedir(), ".pi", "agent", "pi-repl", "venv", "bin", "python3");
 }
 
 // --- prefer a venv with ipykernel; else PYTHON or python3 ---
@@ -134,8 +134,7 @@ interface ActiveExecution {
 	reject(error: Error): void;
 }
 
-// ── process-wide cleanup ─────────────────────────────────────────────────────
-// Guests are killed on host exit; the guest also self-exits on stdin EOF.
+// --- process-wide cleanup: guests killed on exit; the guest self-exits on stdin EOF ---
 
 const liveEngines = new Set<EngineManager>();
 let cleanupHandlersInstalled = false;
@@ -190,7 +189,7 @@ export class EngineManager {
 		return this.state === "running";
 	}
 
-	// ── lifecycle ──────────────────────────────────────────────────────────────
+	//--- lifecycle ---
 
 	async start(): Promise<void> {
 		if (this.state === "shutdown") throw new Error("Engine has been shut down");
@@ -220,7 +219,7 @@ export class EngineManager {
 				PI_REPL_TIMEOUT_MS: String(this.timeoutMs),
 				PI_TOOLBOX_DIR: this.toolboxDir ?? "",
 			},
-			// fd 3 carries protocol; stdout/stderr stay user output.
+			// --- fd 3 is the protocol pipe; stdout/stderr stay user output ---
 			stdio: ["pipe", "pipe", "pipe", "pipe"],
 		});
 		this.child = child;
@@ -247,8 +246,7 @@ export class EngineManager {
 		}
 		this.protocolReader = createInterface({ input: protocolStream });
 		this.protocolReader.on("line", (line) => this.handleGuestLine(line));
-		// Anything the guest writes to the real stdout/stderr fds is subprocess
-		// output (Bun.$ without .quiet()); attribute it to the running cell.
+		// --- guest stdout/stderr are subprocess output; attach to the running cell ---
 		child.stdout!.on("data", (buffer: Buffer) => this.appendActiveOutput("stdout", buffer.toString()));
 		child.stderr!.on("data", (buffer: Buffer) => {
 			const text = buffer.toString();
@@ -262,7 +260,7 @@ export class EngineManager {
 				(error as NodeJS.ErrnoException).code === "ENOENT"
 					? "Engine process failed: '" +
 						pythonPath +
-						"' was not found on PATH. pi-repl runs its evaluator in Python; ensure it is installed and on your PATH, or set the pythonPath in ~/.pi/agent/pi-repl.json."
+						"' was not found on PATH. pi-repl runs its evaluator in Python; ensure it is installed and on your PATH, or set the pythonPath in ~/.pi/agent/pi-repl/config.json."
 					: `Engine process failed: ${error.message}`;
 			this.failAllPending(new Error(message));
 			this.transitionToShutdown(message);
@@ -280,8 +278,7 @@ export class EngineManager {
 			}
 		});
 
-		// On a boot timeout the child must be torn down and the state reset to
-		// idle, or a retried start() orphans the previous child and its fd3 pipe.
+		// --- on a boot timeout tear down the child and reset state, or a retried start orphans it ---
 		await ready.catch((error) => {
 			if (this.child === child) this.child = undefined;
 			this.protocolReader?.close();
@@ -348,7 +345,7 @@ export class EngineManager {
 		await this.kill();
 	}
 
-	// ── guest messaging ────────────────────────────────────────────────────────
+	//--- guest messaging ---
 
 	private sendToGuest(message: HostToGuestMessage): void {
 		// --- a write into a dying child can throw; callers learn via the exit path ---
@@ -373,7 +370,7 @@ export class EngineManager {
 	}
 
 	private handleGuestLine(line: string): void {
-		// fd 3 is protocol-only; a line that fails to decode is discarded.
+		// --- fd 3 is protocol-only; undecodable lines are discarded ---
 		const message = decodeMessage<GuestToHostMessage>(line, this.nonce);
 		if (!message) return;
 		switch (message.type) {
@@ -427,7 +424,7 @@ export class EngineManager {
 		pending.resolve(message);
 	}
 
-	// ── output accumulation ────────────────────────────────────────────────────
+	//--- output accumulation ---
 
 	private appendActiveOutput(name: "stdout" | "stderr", text: string): void {
 		const active = this.activeExecution;
@@ -448,15 +445,14 @@ export class EngineManager {
 		} else {
 			active[truncatedKey] = true;
 		}
-		// --- cap the live stream feed too, so index.ts's accumulated partial
-		//     content cannot grow past the same budget the final output is capped at ---
+		// --- cap the live stream feed, so partial content can't grow past the output budget ---
 		const room = active.maxChars - active.streamedChars;
 		const forward = Math.min(text.length, Math.max(0, room));
 		if (forward > 0) active.opts.onStream?.(text.slice(0, forward), name);
 		active.streamedChars += forward;
 	}
 
-	// ── execute ────────────────────────────────────────────────────────────────
+	//--- execute ---
 
 	async execute(code: string, opts: ExecuteOptions = {}): Promise<ExecuteResult> {
 		// --- claim the queue slot synchronously so order == submission order ---
@@ -565,8 +561,7 @@ export class EngineManager {
 		active.settled = true;
 		if (this.activeExecution === active) this.activeExecution = undefined;
 
-		// A cancelled cell reports "aborted" even if it finished first:
-		// the caller withdrew interest, so the value is not theirs to consume.
+		// --- a cancelled cell reports "aborted" even if it finished first (caller withdrew) ---
 		let status = active.status;
 		if (active.opts.signal?.aborted) status = "aborted";
 		if (status !== "aborted") this.maybeWedged = false;
@@ -588,7 +583,7 @@ export class EngineManager {
 		});
 	}
 
-	// ── snapshot / restore / names ─────────────────────────────────────────────
+	//--- snapshot / restore / names ---
 
 	async snapshotState(): Promise<SnapshotResult | null> {
 		const config = this.options.snapshot;
@@ -596,9 +591,7 @@ export class EngineManager {
 		try {
 			const reply = await this.request({ type: "snapshot", id: randomUUID() }, SNAPSHOT_REQUEST_TIMEOUT_MS);
 			if (reply.type !== "snapshot_result") return null;
-			// An incomplete snapshot (the guest stalled mid-serialization) must
-			// NOT overwrite the last good file — a failed snapshot should cost a
-			// throwaway run, never the durable memory.
+			// --- an incomplete snapshot must not overwrite the last good file ---
 			if (reply.complete === false) return null;
 			mkdirSync(dirname(config.path), { recursive: true });
 			writeFileSync(config.path, JSON.stringify({ version: 1, vars: reply.vars, failed: reply.failed }));

package/src/engine/toolbox/edit.py

@@ -16,7 +16,7 @@ def edit(path, old_text, new_text):
 
     Environment:
       This evaluator runs in a project-local Python venv, not the system
-      interpreter. For a package install that is ~/.pi/agent/pi-repl-venv; for a
+      interpreter. For a package install that is ~/.pi/agent/pi-repl/venv; for a
       repo checkout it is .venv/. The file edited is a real file on disk.
     """
     with open(path, encoding="utf-8") as f:

package/src/engine/toolbox/read.py

@@ -15,7 +15,7 @@ def read(path, offset=1, limit=None):
 
     Environment:
       This evaluator runs in a project-local Python venv, not the system
-      interpreter. For a package install that is ~/.pi/agent/pi-repl-venv; for a
+      interpreter. For a package install that is ~/.pi/agent/pi-repl/venv; for a
       repo checkout it is .venv/. python / pip on PATH may point elsewhere, so
       do not assume the system python is what's running.
     """

package/src/engine/toolbox/write.py

@@ -14,7 +14,7 @@ def write(path, content):
 
     Environment:
       This evaluator runs in a project-local Python venv, not the system
-      interpreter. For a package install that is ~/.pi/agent/pi-repl-venv; for a
+      interpreter. For a package install that is ~/.pi/agent/pi-repl/venv; for a
       repo checkout it is .venv/. Files you write are real files on disk in the
       working directory, visible to the host and other processes.
     """

package/src/extension/config.ts

@@ -5,7 +5,7 @@
  * configured. First-found-wins, never throws on a missing/malformed file.
  *
  *   $PI_REPL_CONFIG            explicit env override
- *   ~/.pi/agent/pi-repl.json   user-global (same dir as pi's settings.json)
+ *   ~/.pi/agent/pi-repl/config.json   user-global
  *
  * The loadable function set is the toolbox directory (see engine/toolbox/);
  * there is no separate helpers list. The extension ships with the four default
@@ -29,8 +29,7 @@ export interface ReplConfig {
 }
 
 const DEFAULT_CONFIG: ReplConfig = {
-	// 0 = no stall provecap: cells run until they finish. A nonzero value is a
-	// SILENCE watchdog (no output for N ms), not a wall-clock deadline.
+	// --- timeoutMs: 0 = no cap; nonzero = silence watchdog (no output for N ms) ---
 	timeoutMs: 0,
 	snapshotDebounceMs: 1500,
 };
@@ -41,7 +40,7 @@ function num(v: unknown, dflt: number): number {
 
 function configCandidates(): string[] {
 	const env = process.env.PI_REPL_CONFIG;
-	const user = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".pi", "agent"), "pi-repl.json");
+	const user = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".pi", "agent", "pi-repl"), "config.json");
 	return [env, user].filter((p): p is string => !!p && p.length > 0);
 }
 

package/src/extension/preview/candidates.ts

@@ -0,0 +1,205 @@
+// --- candidates: the five detectors that name a cell's intent, plus generic scoring ---
+
+import { descriptor } from "./descriptor.js";
+import { maskSpan, scanTemplate, substituteVars } from "./scan.js";
+import { previewShellCommand, previewShellCommandScored, SHELL_SETUP_WORDS, shellWords } from "./shell.js";
+import { BACKTICK, type Candidate } from "./types.js";
+
+const SHELL_OPEN_PATTERN = new RegExp("Bun\\s*\\.\\s*\\$\\s*(?:\\([^)]*\\)\\s*)?" + BACKTICK, "g");
+
+export function shellCandidates(
+	source: string,
+	vars: ReadonlyMap<string, string>,
+): { candidates: Candidate[]; masked: string } {
+	const candidates: Candidate[] = [];
+	let masked = source;
+	SHELL_OPEN_PATTERN.lastIndex = 0;
+	let match = SHELL_OPEN_PATTERN.exec(masked);
+	while (match) {
+		const span = scanTemplate(masked, match.index + match[0].length - 1);
+		const command = previewShellCommandScored(substituteVars(span.body, vars));
+		// --- the command's own strength breaks ties; setup-only drops lower ---
+		if (command.text) {
+			const setupOnly = SHELL_SETUP_WORDS.has(shellWords(command.text)[0] ?? "");
+			const score = setupOnly ? 72 : 90 + Math.min(command.strength, 200) / 25;
+			candidates.push({ kind: "shell", text: command.text, score });
+		}
+		masked = maskSpan(masked, span);
+		SHELL_OPEN_PATTERN.lastIndex = span.end;
+		match = SHELL_OPEN_PATTERN.exec(masked);
+	}
+	return { candidates, masked };
+}
+
+const STRING_ARG_PATTERN = /^\s*(?:"([^"]*)"|'([^']*)')/;
+
+export function agentCandidates(
+	source: string,
+	vars: ReadonlyMap<string, string>,
+): { candidates: Candidate[]; masked: string } {
+	const tasks: string[] = [];
+	let masked = source;
+	const pattern = /rlm\s*\.\s*run\s*\(/g;
+	let match = pattern.exec(masked);
+	while (match) {
+		const argsStart = match.index + match[0].length;
+		let task: string | undefined;
+		const rest = masked.slice(argsStart);
+		const literal = rest.match(STRING_ARG_PATTERN);
+		if (literal) {
+			task = literal[1] ?? literal[2];
+		} else if (rest.trimStart().startsWith(BACKTICK)) {
+			const tickIndex = argsStart + rest.indexOf(BACKTICK);
+			const span = scanTemplate(masked, tickIndex);
+			task = substituteVars(span.body, vars);
+			masked = maskSpan(masked, span);
+		} else {
+			const identifier = rest.match(/^\s*([A-Za-z_$][\w$]*)/)?.[1];
+			task = identifier ? (vars.get(identifier) ?? identifier) : undefined;
+		}
+		// --- a chosen child name is identity; lead with it ---
+		const name = masked.slice(argsStart).match(/name\s*:\s*(?:"([^"]*)"|'([^']*)')/);
+		const label = name?.[1] ?? name?.[2];
+		tasks.push(label && task ? label + ": " + task : (label ?? task ?? "subagent"));
+		pattern.lastIndex = argsStart;
+		match = pattern.exec(masked);
+	}
+	const candidates: Candidate[] =
+		tasks.length === 0
+			? []
+			: [
+					{
+						kind: "agent",
+						text: descriptor(tasks.length === 1 ? (tasks[0] ?? "") : tasks[0] + " (+" + (tasks.length - 1) + " more)"),
+						score: 100,
+					},
+				];
+	return { candidates, masked };
+}
+
+const FILE_EFFECT_PATTERN =
+	/(?:Bun\.write|\b(?:fs|fsp|promises)\.(?:writeFileSync|writeFile|appendFileSync|appendFile|mkdirSync|mkdir|rmSync|rmdirSync|unlinkSync|unlink|renameSync|rename|copyFileSync|copyFile|cpSync|cp)|\b(?:writeFileSync|writeFile|appendFileSync|mkdirSync|rmSync|unlinkSync|renameSync|copyFileSync))\s*\(\s*([^,)\n]+)/g;
+
+const FILE_EFFECT_VERBS: ReadonlyArray<[string, string]> = [
+	["Bun.write", "write"],
+	["writeFileSync", "write"],
+	["writeFile", "write"],
+	["appendFileSync", "append"],
+	["appendFile", "append"],
+	["mkdirSync", "mkdir"],
+	["mkdir", "mkdir"],
+	["rmdirSync", "delete"],
+	["rmSync", "delete"],
+	["rm", "delete"],
+	["unlinkSync", "delete"],
+	["unlink", "delete"],
+	["renameSync", "rename"],
+	["rename", "rename"],
+	["copyFileSync", "copy"],
+	["copyFile", "copy"],
+	["cpSync", "copy"],
+	["cp", "copy"],
+];
+
+// --- resolve a quoted literal, a known const, or an interpolated template into a plain string ---
+function resolveArgText(arg: string, vars: ReadonlyMap<string, string>): string | undefined {
+	const trimmed = arg.trim();
+	const literalPattern = new RegExp("^[\"'" + BACKTICK + "]([^\"'" + BACKTICK + "]*)[\"'" + BACKTICK + "]$");
+	const literal = trimmed.match(literalPattern);
+	if (literal?.[1]) return literal[1];
+	if (/^[A-Za-z_$][\w$]*$/.test(trimmed)) return vars.get(trimmed);
+	if (trimmed.startsWith(BACKTICK)) return substituteVars(trimmed.slice(1, -1), vars);
+	return undefined;
+}
+
+const FILE_READ_PATTERN = /Bun\.file\s*\(\s*([^,)\n]+?)\s*\)\s*\.\s*(?:text|json|arrayBuffer|bytes|stream)\s*\(/g;
+
+export function fileCandidates(source: string, vars: ReadonlyMap<string, string>): Candidate[] {
+	const candidates: Candidate[] = [];
+	for (const match of source.matchAll(FILE_EFFECT_PATTERN)) {
+		const call = match[0];
+		const verb = FILE_EFFECT_VERBS.find(([name]) => call.includes(name))?.[1];
+		if (!verb) continue;
+		const path = resolveArgText(match[1] ?? "", vars);
+		if (path) candidates.push({ kind: "ts", text: descriptor(verb + " " + path), score: 95 });
+	}
+	for (const match of source.matchAll(FILE_READ_PATTERN)) {
+		const path = resolveArgText(match[1] ?? "", vars);
+		if (path) candidates.push({ kind: "ts", text: descriptor("read " + path), score: 70 });
+	}
+	for (const match of source.matchAll(/\bfetch\s*\(\s*([^,)\n]+)/g)) {
+		const url = resolveArgText(match[1] ?? "", vars);
+		if (url) candidates.push({ kind: "ts", text: descriptor("fetch " + url), score: 75 });
+	}
+	return candidates;
+}
+
+// --- per-tool: which arg names the target, the verb shown, and its scoring band ---
+const BRIDGED_TOOLS: Record<string, { arg: string; verb: string; score: number }> = {
+	read: { arg: "path", verb: "read", score: 70 },
+	bash: { arg: "command", verb: "", score: 88 },
+	edit: { arg: "path", verb: "edit", score: 95 },
+	write: { arg: "path", verb: "write", score: 95 },
+	grep: { arg: "pattern", verb: "grep", score: 68 },
+	find: { arg: "pattern", verb: "find", score: 68 },
+	ls: { arg: "path", verb: "ls", score: 68 },
+};
+
+export function bridgedToolCandidates(source: string, vars: ReadonlyMap<string, string>): Candidate[] {
+	const candidates: Candidate[] = [];
+	for (const match of source.matchAll(/\btools\.(\w+)\s*\(\s*\{([^}]*)\}/g)) {
+		const spec = BRIDGED_TOOLS[match[1] ?? ""];
+		if (!spec) continue;
+		const props = match[2] ?? "";
+		const argMatch = props.match(new RegExp(spec.arg + "\\s*:\\s*([^,}]+)"));
+		const target = argMatch ? resolveArgText(argMatch[1] ?? "", vars) : undefined;
+		if (!target) continue;
+		// --- a bridged bash call is a command like any other ---
+		const text = spec.verb ? spec.verb + " " + target : previewShellCommand(target) || target;
+		candidates.push({ kind: "ts", text: descriptor(text), score: spec.score });
+	}
+	return candidates;
+}
+
+const SKIP_LINE_PATTERN = /^(?:$|\/\/|\/\*|\*|import\s|export\s+(?:type\s|\{)|[})\];,]+$)/;
+const DEFINITION_PATTERN = /^(?:export\s+)?(?:async\s+)?(?:function\s|class\s|interface\s|type\s+\w+\s*=)/;
+const ARROW_DEFINITION_PATTERN = /^(?:const|let)\s+[A-Za-z_$][\w$]*\s*=\s*(?:async\s*)?\(?[^)=]*\)?\s*=>/;
+const CONTROL_PATTERN = /^(?:if|for|while|switch|try|do)\b/;
+const CALL_STATEMENT_PATTERN = /^(?:await\s+)?[A-Za-z_$][\w$.]*\s*\(/;
+const ASSIGNMENT_CALL_PATTERN = /^(?:const|let|var)\s+[^=]{1,60}=\s*(?:await\s+)?(?:new\s+)?[A-Za-z_$][\w$.]*\s*\(/;
+const LOW_SIGNAL_CALL_PATTERN =
+	/^(?:await\s+)?(?:console\.\w+|String|Number|Boolean|JSON\.stringify|JSON\.parse|structuredClone)\s*\(/;
+const LOW_SIGNAL_ASSIGNMENT_PATTERN =
+	/=\s*(?:await\s+)?(?:JSON\.parse|JSON\.stringify|String|Number|Boolean|Object\.keys|Object\.entries)\s*\(/;
+
+function consoleInnerCall(line: string): string | undefined {
+	const inner = line.match(/^console\.\w+\(\s*(.+)\)\s*;?\s*$/)?.[1]?.trim();
+	return inner && CALL_STATEMENT_PATTERN.test(inner) && !LOW_SIGNAL_CALL_PATTERN.test(inner) ? inner : undefined;
+}
+
+function genericLineScore(line: string): number {
+	if (SKIP_LINE_PATTERN.test(line)) return -1;
+	if (LOW_SIGNAL_ASSIGNMENT_PATTERN.test(line)) return 25;
+	if (consoleInnerCall(line)) return 55;
+	if (LOW_SIGNAL_CALL_PATTERN.test(line)) return 15;
+	if (DEFINITION_PATTERN.test(line) || ARROW_DEFINITION_PATTERN.test(line)) return 50;
+	if (CONTROL_PATTERN.test(line)) return 20;
+	if (/^(?:return|throw)\b/.test(line)) return 45;
+	if (ASSIGNMENT_CALL_PATTERN.test(line)) return 60;
+	if (CALL_STATEMENT_PATTERN.test(line)) return 65;
+	if (/^(?:const|let|var)\s/.test(line)) return 22;
+	return 30;
+}
+
+export function genericCandidates(masked: string): Candidate[] {
+	const candidates: Candidate[] = [];
+	for (const [index, rawLine] of masked.split("\n").entries()) {
+		const line = rawLine.trim();
+		const score = genericLineScore(line);
+		if (score < 0) continue;
+		const text = consoleInnerCall(line) ?? line;
+		// --- later lines win ties: cells read as setup-then-act, and the act is the story ---
+		candidates.push({ kind: "ts", text: descriptor(text), score: score + Math.min(index, 90) / 100 });
+	}
+	return candidates;
+}