acuvo-code 0.2.0

package/lib/repl-driver.mjs

@@ -0,0 +1,264 @@
+/**
+ * ── THE PROCESS THAT HOLDS THE STATE ───────────────────────────────────────
+ *
+ * Spawned once per REPL session and talked to over stdin/stdout in JSON lines.
+ * It is deliberately NOT `node -i`: the interactive REPL is built for a human,
+ * so its output is prompts, echoes and continuation state, and every agent that
+ * has tried to drive one ends up writing a parser for `> ` that breaks on the
+ * first multi-line paste. A protocol we own is smaller than that parser, and
+ * cannot be confused by output that happens to contain a prompt character.
+ *
+ * ⚠️ IT RUNS IN THE WORKSPACE, so `await import('./lib/thing.mjs')` reaches the
+ * project being worked on. A REPL that cannot open the project it is sitting in
+ * is a calculator.
+ *
+ * Protocol, one JSON object per line each way:
+ *   in   { id, code, timeoutMs }
+ *   out  { id, ok, value, error, logs, ms, defined }
+ */
+
+import { createInterface } from 'node:readline';
+import { inspect } from 'node:util';
+import { Script, constants as vmConstants } from 'node:vm';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const MAX_VALUE_CHARS = 4_000;
+const MAX_LOG_CHARS = 4_000;
+
+/** Names this session is carrying, so the model never has to guess its own state. */
+const defined = new Set();
+
+/**
+ * ⚠️⚠️ DECLARATIONS BECOME ASSIGNMENTS, AND THE FIRST VERSION DID NOT DO THIS.
+ *
+ * It wrapped each submission in an AsyncFunction body. Measured immediately:
+ * `const a = 21` then `a * 2` gave **"a is not defined"** — a `const` inside a
+ * function body dies with the call, so the one property this tool exists for was
+ * the one it did not have. A stateful REPL that forgets is `evaluate` with extra
+ * moving parts.
+ *
+ * Top-level await forces a wrapper, and a wrapper re-introduces that scope
+ * problem, so a leading declaration is rewritten onto `globalThis` instead.
+ *
+ * ⚠️ DELIBERATELY CONSERVATIVE: simple `const x =`, `let x =`, `function f`,
+ * `class C`. Destructuring (`const { a, b } = …`) is left alone and therefore
+ * does NOT persist — said plainly in the tool description rather than
+ * half-handled, because a transform that is wrong about `const [a, ...rest] = x`
+ * would corrupt the user's code rather than fail it.
+ */
+function liftDeclarations(src) {
+  const names = [];
+  const out = src
+    .replace(/^[ \t]*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/gm, (_m, name) => {
+      names.push(name);
+      return `globalThis.${name} =`;
+    })
+    .replace(/^[ \t]*(function|class)\s+([A-Za-z_$][\w$]*)/gm, (_m, kind, name) => {
+      names.push(name);
+      return `globalThis.${name} = ${kind} ${name}`;
+    });
+  return { code: out, names };
+}
+
+/**
+ * ⚠️ RELATIVE IMPORTS RESOLVE AGAINST THIS FILE, NOT THE WORKSPACE. Measured:
+ * `await import("./lib/budget.mjs")` returned ERR_MODULE_NOT_FOUND pointing at
+ * this driver's own directory. The specifier is rewritten to an absolute file
+ * URL from the working directory, which IS the workspace.
+ */
+function absolutiseImports(src) {
+  return src.replace(/\bimport\(\s*(['"])(\.[^'"]*)\1\s*\)/g, (_m, q, spec) => {
+    const url = pathToFileURL(resolve(process.cwd(), spec)).href;
+    return `import(${q}${url}${q})`;
+  });
+}
+
+function render(value) {
+  if (value === undefined) return 'undefined';
+  try {
+    const text = typeof value === 'string'
+      ? value
+      : inspect(value, { depth: 3, maxArrayLength: 50, breakLength: 100 });
+    return text.length > MAX_VALUE_CHARS ? `${text.slice(0, MAX_VALUE_CHARS)}\n… (truncated)` : text;
+  } catch (e) {
+    return `[unrenderable: ${e?.message ?? e}]`;
+  }
+}
+
+/**
+ * ⭐ THE LAST EXPRESSION IS RETURNED. `const x = 2` yielding undefined is
+ * correct; `x * 3` yielding nothing would make the tool write-only. Same
+ * heuristic every REPL uses — a lone expression is returned, anything that
+ * starts with a statement keyword runs as a block.
+ */
+function looksLikeExpression(src) {
+  const t = src.trim();
+  if (t === '') return false;
+  if (/^(const|let|var|function|class|import|export|return|if|for|while|switch|try|throw|do|globalThis\.)/.test(t)) return false;
+  if (/;\s*\S/.test(t)) return false;
+  if (t.includes('\n')) return false;
+  return true;
+}
+
+const SCRIPT_OPTIONS = {
+  filename: 'repl',
+  /**
+   * ⚠️ WITHOUT THIS, `await import(...)` THROWS
+   * ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING — code compiled through `vm` has no
+   * module loader attached, so the single most valuable thing this REPL does
+   * (open the project) failed while everything else worked.
+   * `USE_MAIN_CONTEXT_DEFAULT_LOADER` borrows the real one, so imports resolve
+   * exactly as they would in any other file, with no flags.
+   */
+  importModuleDynamically: vmConstants.USE_MAIN_CONTEXT_DEFAULT_LOADER,
+};
+
+/**
+ * ── ⭐⭐ SEVERAL STATEMENTS NOW RETURN THE LAST ONE'S VALUE ──────────────────
+ *
+ * `const z = 5; z*2` used to answer `undefined`. Documented, not broken — but
+ * ROUNDS ARE THE UNIT OF COST HERE, and it cost the model a whole extra round to
+ * fetch a value it had already computed. That is the most expensive kind of
+ * "documented".
+ *
+ * ⭐ AND THE FIX NEEDS NO PARSER, WHICH IS THE ONLY REASON IT IS SAFE. The
+ * obvious implementation — find the last statement and prefix it with `return` —
+ * is string surgery on JavaScript, and it corrupts the user's code the first
+ * time a `;` appears inside a string literal or a submission ends in a `//`
+ * comment. **V8 already computes this**: it is the completion value of a Script,
+ * the exact thing `node -i` prints, and asking for it is free.
+ *
+ * ⚠️ WRAPPED IN A BLOCK, NOT RUN BARE, AND THAT BRACE IS LOAD-BEARING. MEASURED
+ * both ways: run bare, a script-level `const` becomes a GLOBAL LEXICAL binding,
+ * so the second submission of `const {q,w} = {q:1,w:2}` dies with "Identifier
+ * 'q' has already been declared" — a stateful tool poisoned by its own history.
+ * Inside a block those declarations are block-scoped and die with the
+ * submission, exactly as they do inside today's function wrapper, and the
+ * completion value still propagates out. Measured: bare 1st=3 2nd=THREW;
+ * block 1st=3 2nd=3.
+ *
+ * ⚠️⚠️ THE FALLBACK IS COMPILE-ONLY, AND THAT IS THE SAFETY PROPERTY. Some
+ * submissions are legal in a function body and illegal in a block — `return 9`
+ * is the common one. Those are caught HERE, at `new Script`, before a single
+ * byte of user code has run, so re-compiling them the old way cannot repeat a
+ * side effect. VERIFIED by counting: a fallback submission that increments a
+ * counter leaves it at 1, not 2. Anything that worked before still works, and
+ * the failure direction is "behaves exactly as it did yesterday".
+ *
+ * ⚠️ `await` KEEPS THE WRAPPER, so a submission containing one still answers
+ * `undefined` unless it says `return`. A completion value does not exist inside
+ * a function body, and top-level await does not exist outside one; there is no
+ * arrangement that gives both. The tool description says `return` out loud
+ * instead of pretending otherwise.
+ *
+ * ⭐ FREE BUG FIX ON THE WAY PAST: today's wrapper is built on ONE LINE, so
+ * `const p = 2\n// trailing comment` compiled to `(async () => { globalThis.p =
+ * 2\n// trailing comment })()` — the closing brace landed INSIDE the comment and
+ * the submission died with "Unexpected end of input", an error with nothing to
+ * do with the user's code. Both forms now put the braces on their own lines.
+ */
+/**
+ * ⚠️ THE NARROWING THAT KEEPS EVERY SINGLE-STATEMENT ANSWER EXACTLY AS IT WAS.
+ *
+ * These are the same two clauses `looksLikeExpression` uses to REJECT — a `;`
+ * with something after it, or a newline — so between them the two functions
+ * partition submissions into three cases with no overlap and no gap: one
+ * expression, one statement, several statements. Only the third case changes.
+ *
+ * ⭐ IT IS ALSO THE CASE THE DEFECT NAMED: "one expression returns its value;
+ * several statements run as a block". So `const q = 2` still answers
+ * `undefined` — a lone declaration, and the answer the existing test pins — and
+ * it stays cheap: a single `const big = readFileSync(…)` does not start dumping
+ * a file into the reply as its assignment value.
+ */
+function looksMultiStatement(src) {
+  const t = src.trim();
+  return /;\s*\S/.test(t) || t.includes('\n');
+}
+
+function compileSubmission(src) {
+  if (!looksLikeExpression(src) && looksMultiStatement(src)) {
+    try {
+      return { script: new Script(`{\n${src}\n}`, SCRIPT_OPTIONS), completion: true };
+    } catch {
+      /* not legal as a block — fall through to the wrapper, having run nothing */
+    }
+  }
+  const body = looksLikeExpression(src) ? `return (${src});` : src;
+  return { script: new Script(`(async () => {\n${body}\n})()`, SCRIPT_OPTIONS), completion: false };
+}
+
+async function run(code, timeoutMs) {
+  const logs = [];
+  const original = { log: console.log, error: console.error, warn: console.warn };
+  const capture = (...args) => {
+    logs.push(args.map((a) => (typeof a === 'string' ? a : render(a))).join(' '));
+  };
+  console.log = capture;
+  console.error = capture;
+  console.warn = capture;
+
+  const started = Date.now();
+  try {
+    const lifted = liftDeclarations(absolutiseImports(code));
+    for (const n of lifted.names) defined.add(n);
+
+    /**
+     * ⭐ RUN IN *THIS* CONTEXT, either way. The real global is shared — so
+     * `process`, `fetch` and timers behave exactly as they do in the code under
+     * test — and the lifted declarations are already `globalThis.x =`, so they
+     * outlive whichever wrapper was chosen.
+     *
+     * ⚠️ `vm.createContext` would also persist state and would quietly DIFFER:
+     * a different global means a different `process`, and the value of this tool
+     * is that what happens here is what happens there.
+     */
+    const compiled = compileSubmission(lifted.code);
+    const result = await Promise.race([
+      compiled.script.runInThisContext(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs)),
+    ]);
+
+    return { ok: true, value: render(result), logs, ms: Date.now() - started };
+  } catch (e) {
+    /**
+     * ⚠️ THE STACK IS KEPT. Returning only `e.message` for a TypeError deep in
+     * the project makes debugging harder than a console.log would have been.
+     */
+    return {
+      ok: false,
+      error: String(e?.stack ?? e ?? 'unknown error').slice(0, MAX_VALUE_CHARS),
+      logs,
+      ms: Date.now() - started,
+    };
+  } finally {
+    console.log = original.log;
+    console.error = original.error;
+    console.warn = original.warn;
+  }
+}
+
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+rl.on('line', async (line) => {
+  const text = line.trim();
+  if (text === '') return;
+  let msg;
+  try { msg = JSON.parse(text); } catch { return; }
+  if (msg?.code === undefined) return;
+
+  const out = await run(String(msg.code), Number(msg.timeoutMs) || 15_000);
+  out.id = msg.id;
+  out.defined = [...defined];
+  const joined = (out.logs ?? []).join('\n');
+  out.logs = joined.length > MAX_LOG_CHARS ? `${joined.slice(0, MAX_LOG_CHARS)}\n… (truncated)` : joined;
+  process.stdout.write(`${JSON.stringify(out)}\n`);
+});
+
+/**
+ * ⚠️ A CLOSED STDIN MEANS THE PARENT IS GONE. Exit rather than linger as an
+ * orphan holding the workspace open — the failure this repo has already paid for
+ * twice, once with a pid that ran until reboot.
+ */
+rl.on('close', () => process.exit(0));

package/lib/repl.mjs

@@ -0,0 +1,324 @@
+/**
+ * ── ⭐⭐ A REPL THE AGENT CONVERSES WITH — AND NOBODY ELSE HAS ONE ───────────
+ *
+ * `evaluate` writes a snippet to a file and runs it in a fresh process. So does
+ * every other terminal coding agent: Claude Code, Cursor, Codex and Aider all
+ * execute statelessly, and none of them can hold a value between two thoughts.
+ *
+ * ⚠️ THAT IS NOT HOW ANYBODY DEBUGS. A human loads the module, looks at a value,
+ * pokes the object, tries the fix on the live thing. Statelessly, the agent must
+ * RE-DERIVE THE ENTIRE SETUP to check one field — which is exactly why models
+ * rewrite a whole script to answer a question a single expression would settle,
+ * and why each of those rewrites is another paid round.
+ *
+ * Measured shape of the win: reading a config, parsing it, and inspecting one
+ * nested key is three `evaluate` calls that each re-read and re-parse, or three
+ * lines in one REPL session where line 2 can see line 1.
+ *
+ * ── WHY THIS IS RARE RATHER THAN MERELY MISSING ─────────────────────────────
+ *
+ * It is rare because it is annoying: `node -i` is built for a human, so driving
+ * it means parsing prompts, echoes and continuation state, and that parser
+ * breaks on the first multi-line paste. `repl-driver.mjs` sidesteps all of it
+ * with a JSON-lines protocol we own — which is less code than the parser would
+ * have been, and cannot be confused by output that happens to contain `> `.
+ *
+ * ⚠️ SAME GOVERNANCE AS EVERY OTHER PROCESS. `--no-run` withholds it, a dry run
+ * refuses it, it is killed on exit and on Ctrl-C with the whole tree, and there
+ * is a hard cap on how long one expression may run. A stateful process is more
+ * useful than a stateless one and exactly as dangerous, so it gets exactly the
+ * same locks.
+ */
+
+import { spawn } from 'node:child_process';
+import { exitIsDeferred } from './interrupt.mjs';
+import { fileURLToPath } from 'node:url';
+import { detachChild, deleteIfCurrent } from './child-lifetime.mjs';
+
+import { killProcessTree, childEnvironment } from './command.mjs';
+
+const DRIVER = fileURLToPath(new URL('./repl-driver.mjs', import.meta.url));
+
+/** One expression should not be able to hang the run. */
+export const DEFAULT_EVAL_TIMEOUT_MS = 15_000;
+export const MAX_EVAL_TIMEOUT_MS = 60_000;
+
+/** Source cap, matching `evaluate` — past this, it belongs in a file. */
+export const MAX_CODE_CHARS = 4_000;
+
+/** ⚠️ ONE SESSION PER WORKSPACE. Two would mean two truths about the same state. */
+const sessions = new Map();
+let hooked = false;
+
+function installExitHooks() {
+  if (hooked) return;
+  hooked = true;
+  const killAll = () => {
+    for (const s of sessions.values()) releaseSession(s);
+    sessions.clear();
+  };
+  process.once('exit', killAll);
+  for (const [sig, code] of [['SIGINT', 130], ['SIGTERM', 143], ['SIGBREAK', 149]]) {
+    try { process.once(sig, () => { killAll(); if (!exitIsDeferred()) process.exit(code); }); } catch { /* no SIGBREAK off Windows */ }
+  }
+}
+
+function start(root, { spawnImpl = spawn, env = process.env } = {}) {
+  const child = spawnImpl(process.execPath, [DRIVER], {
+    cwd: root,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+    detached: process.platform !== 'win32',
+    /**
+     * ── ⚠️⚠️⚠️ THIS SPAWN HAD NO `env`, SO IT INHERITED EVERY SECRET ────────
+     *
+     * Without an `env` option the child gets `process.env` whole — the
+     * OpenRouter key, the Acuvo account token, AWS credentials, everything on
+     * the machine. And the repl exists to run **model-written JavaScript**, so
+     * one `repl` call could read them all back out. That bypassed the entire
+     * `run_command` allowlist, which is the control this package leans on
+     * hardest: a program the model may not run is irrelevant if it can just
+     * `process.env` its way past it.
+     *
+     * ⭐ EVERY SIBLING SPAWNER ALREADY DID THIS RIGHT — `evaluate.mjs:224`,
+     * `background.mjs`, `command.mjs` all pass `childEnvironment(...)`. The repl
+     * was the one that did not, which is exactly how a security control with
+     * one uncovered door reads as present while being absent.
+     *
+     * `childEnvironment` scrubs secret-shaped names and sets
+     * `npm_config_ignore_scripts` unless npm is genuinely the program.
+     */
+    env: childEnvironment({ file: process.execPath, args: [DRIVER] }, env),
+  });
+
+  const session = { child, root, buffer: '', pending: new Map(), seq: 0, defined: [] };
+
+  child.stdout?.setEncoding?.('utf8');
+  child.stdout?.on?.('data', (chunk) => {
+    session.buffer += chunk;
+    let nl;
+    while ((nl = session.buffer.indexOf('\n')) !== -1) {
+      const line = session.buffer.slice(0, nl);
+      session.buffer = session.buffer.slice(nl + 1);
+      if (!line.trim()) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      const entry = session.pending.get(msg.id);
+      if (entry) { session.pending.delete(msg.id); clearTimeout(entry.timer); entry.resolve(msg); }
+    }
+  });
+
+  child.stderr?.setEncoding?.('utf8');
+  child.stderr?.on?.('data', () => { /* the driver reports errors as data, not on stderr */ });
+
+  /**
+   * ⚠️⚠️ A DEAD CHILD MUST NOT EVICT ITS OWN SUCCESSOR.
+   *
+   * `exit` arrives asynchronously — after `replReset` has already deleted this
+   * entry and, very often, after a later `replEval` has registered a REPLACEMENT
+   * session under the same root. An unconditional `sessions.delete(root)` then
+   * removes the LIVE session's entry, so the next `replReset` reports "no REPL
+   * was running" and nothing ever releases that child. It holds the event loop
+   * open for the life of the process.
+   *
+   * Measured 2026-08-12: reset → eval → reset hangs forever; a single reset
+   * exits in 0.4s. It is what hung the suite.
+   */
+  child.on?.('exit', () => {
+    for (const [, e] of session.pending) {
+      clearTimeout(e.timer);
+      e.resolve({ ok: false, error: 'the REPL process exited — its state is gone. The next repl call starts a fresh one.' });
+    }
+    session.pending.clear();
+    deleteIfCurrent(sessions, root, session);
+  });
+
+  /**
+   * ⭐ A REPL CHILD MUST NEVER DECIDE WHEN ITS OWNER EXITS. Without this, a
+   * process that started a REPL and never reset it can never exit, and
+   * `installExitHooks`'s cleanup deadlocks: it runs on 'exit', which cannot fire.
+   */
+  detachChild(child);
+
+  installExitHooks();
+  sessions.set(root, session);
+  return session;
+}
+
+/**
+ * Evaluate one expression or block, keeping everything it defines.
+ *
+ * @returns {Promise<object>}
+ */
+export async function replEval(root, code, { timeoutMs = DEFAULT_EVAL_TIMEOUT_MS, dryRun = false, spawnImpl } = {}) {
+  if (dryRun) {
+    return { ok: false, error: 'this is a --dry-run, so nothing is evaluated (a REPL runs your code for real)' };
+  }
+  if (typeof code !== 'string' || code.trim() === '') {
+    return { ok: false, error: 'code is required — the JavaScript to evaluate' };
+  }
+  if (code.length > MAX_CODE_CHARS) {
+    return {
+      ok: false,
+      error: `the code is ${code.length} characters, over the ${MAX_CODE_CHARS} limit — write it to a real file and import it here instead`,
+    };
+  }
+
+  const bounded = Math.min(Math.max(500, timeoutMs), MAX_EVAL_TIMEOUT_MS);
+  const session = sessions.get(root) ?? start(root, { spawnImpl });
+  const fresh = session.seq === 0;
+  session.seq += 1;
+  const id = session.seq;
+
+  const reply = await new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      session.pending.delete(id);
+      /**
+       * ⚠️ A TIMEOUT KILLS THE SESSION, and it has to. The driver is
+       * single-threaded, so an expression stuck in a loop means every later
+       * call would queue behind it forever — a REPL that answers nothing is
+       * worse than no REPL, because the model keeps waiting instead of trying
+       * something else.
+       */
+      try { killProcessTree(session.child); } catch { /* gone */ }
+      sessions.delete(root);
+      resolve({
+        ok: false,
+        error: `the expression did not finish within ${bounded}ms, so the REPL was stopped and its state discarded. `
+          + 'An infinite loop or a hanging await is the usual cause.',
+      });
+    }, bounded + 500);
+    session.pending.set(id, { resolve, timer });
+    try {
+      session.child.stdin.write(`${JSON.stringify({ id, code, timeoutMs: bounded })}\n`);
+    } catch (e) {
+      clearTimeout(timer);
+      session.pending.delete(id);
+      resolve({ ok: false, error: `could not reach the REPL: ${e?.message ?? e}` });
+    }
+  });
+
+  if (reply.defined) session.defined = reply.defined;
+  return {
+    ...reply,
+    /**
+     * ⭐ THE NAMES IT IS CARRYING, returned every time. The one thing a model
+     * cannot know about a stateful tool is what state it is in, and guessing is
+     * how it re-declares a const and gets a confusing error.
+     */
+    defined: session.defined,
+    startedFresh: fresh,
+  };
+}
+
+/**
+ * ── ⚠️⚠️ STOPPING MUST NOT BE A RACE ────────────────────────────────────────
+ *
+ * `killProcessTree` is ASYNCHRONOUS on Windows: it spawns `taskkill /T /F` and
+ * returns before the child is gone. Killing alone is therefore not enough to
+ * let THIS process exit — we opened three pipes to that child, and Node keeps
+ * an event loop alive for them. A process with no work left still cannot die.
+ *
+ * ⭐ That is not a theoretical window. It hung the full suite on 2026-08-12
+ * with every test already passed, and it only bites under load — when the
+ * machine is busy, the reaper is slow, which is exactly when the suite is
+ * slowest and a hang is least distinguishable from work.
+ *
+ * ⚠️ AND KILLING FIRST IS BACKWARDS. `taskkill` guts the child mid-flight and
+ * leaves this side's pipes half-open, so destroying them afterwards does not
+ * return the libuv handles. Measured: `replReset` alone leaves one ProcessWrap
+ * and five PipeWrap behind, and that one test hangs its own file.
+ *
+ * ⭐ THE DRIVER ALREADY KNOWS HOW TO DIE. `repl-driver.mjs` ends with
+ * `rl.on('close', () => process.exit(0))` — closing its stdin IS the shutdown
+ * signal. Ask nicely, unref so we never wait, and keep the reaper only as a
+ * fallback for a driver wedged so badly it stopped reading stdin. Cooperative
+ * shutdown is what actually releases the handles; the kill is insurance.
+ */
+const STOP_GRACE_MS = 2_000;
+
+function releaseSession(session) {
+  const child = session.child;
+  // 1. The shutdown signal the driver is already listening for.
+  try { child?.stdin?.end?.(); } catch { /* already closed */ }
+  // 2. Never let a child we have finished with hold this process open.
+  try { child?.unref?.(); } catch { /* a stubbed child in a test */ }
+  // 3. Insurance only. Unref'd, so if we are exiting anyway it never fires and
+  //    the OS reaps the child — nothing waits on this.
+  try {
+    const t = setTimeout(() => {
+      try { killProcessTree(child); } catch { /* already gone */ }
+    }, STOP_GRACE_MS);
+    t.unref?.();
+  } catch { /* no timers in this context */ }
+}
+
+/** Throw the session away. Idempotent — resetting nothing is a success. */
+export function replReset(root) {
+  const session = sessions.get(root);
+  if (!session) return { ok: true, reset: false, note: 'no REPL was running, so there was nothing to clear' };
+  releaseSession(session);
+  sessions.delete(root);
+  return { ok: true, reset: true, note: 'the REPL was stopped and every variable it held is gone' };
+}
+
+/** For tests and teardown. */
+export function replStopAll() {
+  for (const s of sessions.values()) releaseSession(s);
+  sessions.clear();
+}
+
+export const REPL_TOOL_NAMES = ['repl', 'repl_reset'];
+
+export function replToolSchemas() {
+  return [
+    {
+      type: 'function',
+      function: {
+        name: 'repl',
+        description: [
+          'Evaluate JavaScript in a session that REMEMBERS what you defined — the next call can see it.',
+          'Top-level await works, so `const m = await import("./lib/thing.mjs")` then `m.parse("x")` on the next call',
+          'is two lines instead of two whole scripts.',
+          'Use this to INVESTIGATE: load a module, look at a real value, poke an object, try the fix on the live thing',
+          'before you write it to a file. It runs in the workspace, so relative imports reach the project.',
+          'You get the value of the LAST expression back, so `const z = 5; z*2` answers 10 — do the work and read',
+          'the answer in ONE call rather than spending a second round fetching a value you already computed.',
+          'The one exception is a submission that uses await: say `return` for the value you want',
+          '(`const m = await import("./lib/x.mjs"); return m.parse("a")`).',
+        ].join(' '),
+        parameters: {
+          type: 'object',
+          properties: {
+            /**
+             * ⚠️ THE `await` CAVEAT IS ON THE PARAMETER TOO, not only in the
+             * description. A model reading one and not the other is the reason a
+             * documented-but-surprising behaviour costs a round.
+             */
+            code: { type: 'string', description: 'JavaScript. The last expression\'s value comes back — `const z = 5; z*2` answers 10. If the code uses await, write `return <expression>` for the value you want.' },
+          },
+          required: ['code'],
+        },
+      },
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'repl_reset',
+        description: 'Throw away the REPL session and everything it holds. Use it when the state has become confusing, or after changing a file you already imported — imports are cached, so a stale module is the one real trap here.',
+        parameters: { type: 'object', properties: {} },
+      },
+    },
+  ];
+}
+
+export async function runReplTool(name, args = {}, { executor } = {}) {
+  switch (name) {
+    case 'repl':
+      return replEval(executor.root, String(args.code ?? ''), { dryRun: executor.dryRun });
+    case 'repl_reset':
+      return replReset(executor.root);
+    default:
+      return { ok: false, error: `"${name}" is not a repl tool` };
+  }
+}