@mono-agent/agent-runtime 0.11.5 → 0.12.0

package/ARCHITECTURE.md

@@ -40,7 +40,7 @@ flowchart TB
   Registry --> PiSDK["Pi SDK bridge<br/>OpenAI, Codex, Gemini, OpenRouter,<br/>Ollama, custom providers"]
   Registry --> CodexApp["Codex app-server CLI bridge"]
 
-  AgentKernel --> Builtins["Read / Write / Edit / Glob / Grep / Bash<br/>WebFetch / WebSearch"]
+  AgentKernel --> Builtins["Read / Write / Edit / Glob / Grep / Bash<br/>NodeRepl / WebFetch / WebSearch"]
   AgentKernel --> MCP["MCP stdio / SSE / HTTP tools"]
   AgentKernel --> Sandbox["Sandbox policy<br/>path/network checks + stdio command wrapping"]
   AgentKernel --> Artifacts["Tool-output bloat guard<br/>host artifact persistence"]
@@ -180,8 +180,9 @@ Key responsibilities by subsystem:
   Real hosts inject `@mono-agent/runtime-adapter`'s sandbox implementation.
 - `agent/compaction.js`: pure helpers consumed by the pi bridge —
   `resolveAgentCompactionPolicy` (derives the context-window compaction trigger +
-  tool-output payload limits from `agent_compaction_*` settings and the running
-  model), `estimateFixedOverheadTokens` (the proactive fixed-overhead correction:
+  adaptive budgets and tool-output payload limits from the typed compaction
+  policy and running model; deprecated `agent_compaction_*` settings remain a
+  compatibility input), `estimateFixedOverheadTokens` (the proactive fixed-overhead correction:
   system prompt + tool schemas + per-turn message), `isLikelyContextTermination`
   (classifies a context-pressure error), and the typed-policy/`settings`-bag shim
   helpers (`resolveRuntimePolicyInputs`, `deprecatedSettingsWarning`) that let a
@@ -255,12 +256,12 @@ provider exposes queue-after-turn), not durability/cost:
 The pi runtime is built on pi-agent-core's native `AgentHarness` (the hand-rolled
 bridge was removed once native reached parity); it owns the session and
 pi-ai-managed retry. `AgentHarness` itself has **no** automatic compaction, so
-the pi bridge drives it directly: before each turn it estimates the running
-model's context usage and calls `AgentHarness.compact()` when near the window
-(proactive), and if a turn still overflows it compacts once and re-prompts
-(reactive recovery). Runs report `context_compaction_applied` as `true` (a
+the pi bridge drives it through a one-shot `session_before_compact` hook: before
+each turn it compares the full request estimate with an adaptive trigger, and if
+a turn still overflows it retries exactly once only after a preview verifies a
+positive reduction. Runs report `context_compaction_applied` as `true` (a
 compaction fired), `false` (enabled but not needed), or `null` (disabled via
-`agent_compaction_enabled: false`).
+`runtime.compaction.enabled: false`).
 
 | Provider | Warm session | Resume across turns | Survives process restart |
 |---|---|---|---|

package/MIGRATION.md

@@ -54,14 +54,16 @@ These were Pi-bridge knobs the native path does not consume.
   overflows the bridge compacts once and re-prompts (reactive recovery).
 - Runs report **`capabilitiesUsed.context_compaction_applied`** as `true` (a
   compaction fired), `false` (enabled but not needed), or `null` (disabled via
-  `agent_compaction_enabled: false`). If you assert on this value, expect this
+  `runtime.compaction.enabled: false`). If you assert on this value, expect this
   tristate on the Pi path.
 - The host **`onCompactionRecorded`** callback now **fires on each automatic
   compaction** on the Pi path (previously inert).
-- The trigger window auto-tracks the model actually serving the request
-  (`harness.getModel()`) and self-corrects from any real ceiling stated in an
-  overflow error, so a wrong/default `context_window` no longer defeats it.
-  `resolveAgentCompactionPolicy` (`agent_compaction_*` settings) remains exported.
+- The trigger and omitted budgets adapt to the model actually serving the
+  request (`harness.getModel()`). Numeric overflow limits and generic failed
+  request estimates lower a learned process-local ceiling; use
+  `runtime.compaction.contextWindowOverride` for a persistent metadata
+  correction. Deprecated programmatic `agent_compaction_*` settings and
+  `resolveAgentCompactionPolicy` remain compatibility surfaces.
 
 ## 4. Durable Pi session resume: create-on-miss semantics
 
@@ -160,6 +162,9 @@ pass it, so this is a no-op there).
 `resolveAgentCompactionPolicy(settings, model)` stays exported (the canonical
 clamp/mapper both paths route through), and `@mono-agent/runtime-adapter` exposes
 `resolveRuntimePolicies(settings)` to map a legacy bag to the typed objects.
+The migration helper preserves omitted legacy compaction values so adaptive
+defaults are resolved later against the live model rather than frozen at the
+mapper's fallback window.
 **Action:** migrate `settings` → `toolLimits` / `compaction`; until then the shim
 keeps working with one deprecation warning per run.
 

package/README.md

@@ -275,6 +275,7 @@ PROVIDER_ABORT_RE
 RetryableProviderFailureInfo
 classifyFailure
 createStderrTail
+isContextLimitFailureText
 isProviderAuthFailureText
 retryableProviderFailureInfo
 ```
@@ -478,7 +479,7 @@ console.log(result.text);
 `@mono-agent/agent-runtime` is purpose-built for **autonomous, long-running agent work** with provider portability and operational resilience as first-class concerns. It is *not* a streaming-chat UI kit. Where each peer fits:
 
 - **Vercel AI SDK** — best when you're building a chat / generative-UI experience inside a React or Next.js app. `useChat`, `useCompletion`, streaming server components, and edge-runtime compatibility are their strengths. Their provider list is curated (Anthropic, OpenAI, Google, etc., via `@ai-sdk/*` packages); there's no Pi gateway, no Claude Code CLI, no Codex CLI app-server, and no per-call provider fallback. If you're rendering a streaming chat into a browser, use them. If you're orchestrating multi-turn autonomous work that must survive a rate-limited primary provider, use us.
-- **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — first-party Anthropic SDK. Tight integration with Claude features (canUseTool, sub-agents, hooks, MCP). We *wrap* it as one of our five bridges and add transcript-resume across provider drops, a 22-kind failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Context/window handling stays with the provider — the runtime does not run its own in-loop summarization pass. Reach for the bare Anthropic SDK when you only ever talk to Claude and don't need cross-provider portability or resume.
+- **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — first-party Anthropic SDK. Tight integration with Claude features (canUseTool, sub-agents, hooks, MCP). We *wrap* it as one of our five bridges and add transcript-resume across provider drops, a structured failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Context/window handling remains bridge-specific; the pi-native bridge drives its own compaction recovery. Reach for the bare Anthropic SDK when you only ever talk to Claude and don't need cross-provider portability or resume.
 - **Mastra** — a workflow engine + memory + RAG stack. Different category: it's the layer *above* a runtime. You can layer Mastra workflows on top of `@mono-agent/agent-runtime` if you want both.
 - **OpenAI Agents SDK** — first-party OpenAI SDK. Same trade-off as the Claude Agent SDK: tight integration with OpenAI, no other providers. Pi providers in our runtime cover OpenAI plus a dozen others through a single API.
 - **LangChain.js** — kitchen sink with deep abstraction stacks. We're deliberately lean; if you want chains, agents, vector stores, and parsers under one umbrella, LangChain is built for that. If you want a focused runtime kernel, use us.
@@ -674,12 +675,14 @@ Returns:
 
 ## Built-in tools
 
-The agent kernel ships with: `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`, `WebFetch`, `WebSearch`. You select via `allowedTools`. Tool implementations honor:
+The agent kernel's managed tools are `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`, `NodeRepl`, `WebFetch`, and `WebSearch`. `NodeRepl({ code })` is backed by one lazily started Node.js REPL child per run. You select them via `allowedTools`. Tool implementations honor:
 
 - `cwd` (required for path-based tools)
 - The runtime context's `workspace` / `repoRoot` allow-list (paths outside both, plus `/tmp` and `process.cwd()`, are rejected)
 - Output truncation with optional artifact persistence (`{toolArtifactDir}/tool-output/{runId}/...` when `toolArtifactDir` is configured)
 
+`NodeRepl` uses Node's default `node:repl` evaluator, so variables, `_`, `_error`, and loaded modules persist across calls in the same run. It supports multiline input and top-level `await`, resolves workspace-installed packages, and is closed with the run. Its child is prepared through the same sandbox seam as `Bash`; abort, the fixed 120-second timeout, child exit, or hard output overflow resets the session. It deliberately has no session ids, persistent history, terminal commands, or package-install surface.
+
 Override or extend the tool surface by passing `mcpServers` for MCP-backed tools.
 
 ## Structured output
@@ -713,6 +716,7 @@ Behaviour:
 
 - Successful run on entry N → returns the result with `failoverHistory` set to attempts 0..N-1.
 - Retryable provider failure → emits `provider_failover_started`, builds a transcript snapshot, and retries on the next entry.
+- Context-window failure after bridge compaction recovery → preserves `failureKind: "context_limit"` in `failoverHistory` and tries the next entry; quota/output/max-turn `usage_limit` remains terminal.
 - Provider auth failure → retries the next chain entry and preserves `failureKind: "provider_auth"` in `failoverHistory` for the failed attempt.
 - Malformed request/config/billing-type non-retryable failure → returns immediately with `failoverHistory` containing the one attempt.
 - Cancellation → returns immediately.
@@ -823,17 +827,34 @@ Hosts that don't supply `persistArtifact` get the truncation summary but no on-d
 The sole pi bridge runs on pi-agent-core's native `AgentHarness`. pi performs **no**
 automatic in-loop compaction, so the bridge drives it: before each turn it estimates the
 running model's context usage and calls `AgentHarness.compact()` when near the window
-(proactive), and if a turn still overflows it compacts once and re-prompts (reactive
-recovery). The context window auto-tracks the model actually serving the request
-(`harness.getModel()`), self-correcting from any real ceiling stated in an overflow error.
+(proactive), and if a turn still overflows it compacts once and re-prompts exactly once
+only after a rebuilt-context preview proves positive reduction (reactive recovery).
+The bridge installs a one-shot `session_before_compact` hook around the public harness
+operation, using Pi's public `prepareCompaction()` and `compact()` primitives so the
+harness still owns phase changes, persistence, and events. Non-reducing previews and
+proactive savings below policy are cancelled before persistence.
+
+The context window auto-tracks the model actually serving the request
+(`harness.getModel()`). Numeric provider limits become learned ceilings; generic
+overflow temporarily lowers the process-local ceiling to 90% of the failed request
+estimate. A configured `contextWindowOverride` provides a persistent metadata
+correction, while learned evidence may still lower it.
 Runs report `context_compaction_applied: true` (fired), `false` (enabled but not needed),
-or `null` (disabled). The other backends manage their windows per their own behavior.
+or `null` (disabled), plus request-estimate, fixed-overhead, reactive-attempted,
+tokens-after, and reduced diagnostics.
+Persistent overflow is classified as `context_limit`, allowing the fallback router to
+try the next configured model. The other backends manage their windows per their own behavior.
 (`docs/reference/feature-registry.md` is the source of truth for this row.)
 
-`resolveAgentCompactionPolicy(...)` (the `agent_compaction_*` settings: trigger ratio,
-keep-recent, enable/disable) and the `onCompactionRecorded(record)` host callback (fired
-on each automatic compaction) are exported from
-`@mono-agent/agent-runtime/agent/compaction.js` and consumed by the pi bridge.
+Hosts pass the typed `RuntimeCompactionPolicy` through `runOptions.compaction`; the
+deprecated programmatic `agent_compaction_*` settings remain a compatibility fallback.
+The config-first host exposes this as `runtime.compaction.*` plus matching
+`MONO_AGENT_COMPACTION_*` variables. Omitted values resolve against effective window
+`W`: trigger ratio `0.70`; safety headroom `clamp(floor(W × 0.25), 16000, 96000)`;
+retained context and minimum proactive savings `clamp(floor(W × 0.10), 4000, 20000)`;
+summary output `clamp(floor(W × 0.04), 2000, 12000)`. Explicit values retain their
+scalar validation bounds. `onCompactionRecorded(record)` fires only for accepted,
+persisted automatic compactions.
 
 ## Advanced exports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.11.5",
+  "version": "0.12.0",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, and Pi SDK bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",

package/src/agent/compaction.js

@@ -35,10 +35,7 @@
  */
 
 const DEFAULT_CONTEXT_WINDOW = 128000;
-const DEFAULT_TRIGGER_RATIO = 0.85;
-const DEFAULT_KEEP_RECENT_TOKENS = 24000;
-const DEFAULT_SUMMARY_MAX_TOKENS = 16000;
-const DEFAULT_MIN_SAVINGS_TOKENS = 20000;
+const DEFAULT_TRIGGER_RATIO = 0.70;
 const DEFAULT_TOOL_PAYLOAD_COMPACTION_TRIGGER_CHARS = 0;
 const DEFAULT_TOOL_PRUNE_TRIGGER_TOKENS = 40000;
 // intelligence-ramp Phase 3: lifted from 16K/20K/12K. Mid-task tool reads
@@ -100,22 +97,43 @@ export function resolveAgentCompactionPolicy(settings = {}, model = {}) {
     0.2,
     0.95,
   );
-  const reserveTokens = Math.max(16000, Math.min(64000, Math.floor(contextWindow * 0.25)));
-  const ratioTrigger = Math.floor(contextWindow * triggerRatio);
-  const reserveTrigger = Math.max(1, contextWindow - reserveTokens);
+  const safetyHeadroom = clampInteger(contextWindow * 0.25, 16000, 16000, 96000);
+  // Add a tiny scale-aware epsilon before flooring so decimal ratios such as
+  // 0.70 do not lose a token to IEEE-754 representation (372000 * 0.70 is
+  // otherwise 260399.99999999997 in JavaScript).
+  const ratioTrigger = Math.floor((contextWindow * triggerRatio) + (Number.EPSILON * contextWindow));
+  const reserveTrigger = Math.max(1, contextWindow - safetyHeadroom);
+  const adaptiveKeepRecentTokens = clampInteger(contextWindow * 0.10, 4000, 4000, 20000);
+  const adaptiveSummaryMaxTokens = clampInteger(contextWindow * 0.04, 2000, 2000, 12000);
+  const adaptiveMinSavingsTokens = clampInteger(contextWindow * 0.10, 4000, 4000, 20000);
   return {
     enabled: settings.agent_compaction_enabled !== false,
     contextWindow,
     triggerRatio,
     triggerTokens: Math.min(ratioTrigger, reserveTrigger),
-    keepRecentTokens: clampInteger(settings.agent_compaction_keep_recent_tokens, DEFAULT_KEEP_RECENT_TOKENS, 4000, 200000),
-    summaryMaxTokens: clampInteger(settings.agent_compaction_summary_max_tokens, DEFAULT_SUMMARY_MAX_TOKENS, 1000, 64000),
+    keepRecentTokens: clampInteger(
+      settings.agent_compaction_keep_recent_tokens,
+      adaptiveKeepRecentTokens,
+      4000,
+      200000,
+    ),
+    summaryMaxTokens: clampInteger(
+      settings.agent_compaction_summary_max_tokens,
+      adaptiveSummaryMaxTokens,
+      1000,
+      64000,
+    ),
     // ON by default; the proactive fixed-overhead correction (system prompt +
     // tool schemas + per-turn message) is disabled only when explicitly false.
     // Read by the compaction driver off the resolved policy so it never has to
     // re-sniff the raw settings/policy inputs.
     fixedOverheadEnabled: settings.agent_compaction_fixed_overhead_enabled !== false,
-    compactionMinSavingsTokens: clampInteger(settings.agent_compaction_min_savings_tokens, DEFAULT_MIN_SAVINGS_TOKENS, 0, 500000),
+    compactionMinSavingsTokens: clampInteger(
+      settings.agent_compaction_min_savings_tokens,
+      adaptiveMinSavingsTokens,
+      0,
+      500000,
+    ),
     toolPayloadCompactionTriggerChars: clampInteger(
       settings.agent_tool_payload_compaction_trigger_chars,
       DEFAULT_TOOL_PAYLOAD_COMPACTION_TRIGGER_CHARS,

package/src/agent/tools/node-repl.js

@@ -0,0 +1,406 @@
+// @ts-check
+
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { passthroughSandbox } from "../sandbox-seam.js";
+import { capChars } from "./shared/output-truncation.js";
+import { readToolRuntime } from "./shared/runtime-context.js";
+import { resolveSandboxPolicy } from "./shared/tool-context.js";
+
+const DEFAULT_NODE_REPL_TIMEOUT_MS = 120_000;
+const NODE_REPL_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+const KILL_GRACE_MS = 1_000;
+
+// Kept self-contained so the sandboxed child can start from `node --eval`
+// without needing read access to agent-runtime's installed package directory.
+function nodeReplWorkerMain() {
+  const repl = require("node:repl");
+  const { PassThrough } = require("node:stream");
+  const MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+  const input = new PassThrough();
+  const output = new PassThrough();
+  const server = repl.start({
+    input,
+    output,
+    prompt: "",
+    terminal: false,
+    useGlobal: false,
+  });
+  const replServer = /** @type {any} */ (server);
+  let active = null;
+
+  function send(message) {
+    try {
+      process.send?.(message);
+    } catch {
+      process.exit(1);
+    }
+  }
+
+  function errorText(error) {
+    const cause = error?.err ?? error;
+    return String(cause?.stack || cause?.message || cause || "Node REPL evaluation failed.");
+  }
+
+  function finish(ok, text, reset = false) {
+    const request = active;
+    if (!request) return;
+    active = null;
+    const value = String(text || "");
+    const responseBytes = Buffer.byteLength(value, "utf8")
+      + Buffer.byteLength(request.stdout, "utf8")
+      + Buffer.byteLength(request.stderr, "utf8");
+    if (responseBytes > MAX_BUFFER_BYTES) {
+      send({
+        type: "result",
+        id: request.id,
+        ok: false,
+        reset: true,
+        text: `Node REPL output exceeded ${MAX_BUFFER_BYTES} bytes.`,
+        stdout: request.stdout,
+        stderr: request.stderr,
+      });
+      setImmediate(() => process.exit(1));
+      return;
+    }
+    send({
+      type: "result",
+      id: request.id,
+      ok,
+      reset,
+      text: value,
+      stdout: request.stdout,
+      stderr: request.stderr,
+    });
+  }
+
+  function captureProcessWrite(field, originalWrite) {
+    return function capturedWrite(chunk, encoding, callback) {
+      if (!active) return originalWrite(chunk, encoding, callback);
+      const resolvedEncoding = typeof encoding === "string" ? encoding : "utf8";
+      const resolvedCallback = typeof encoding === "function" ? encoding : callback;
+      const buffer = typeof chunk === "string"
+        ? Buffer.from(chunk, /** @type {any} */ (resolvedEncoding))
+        : Buffer.from(/** @type {any} */ (chunk));
+      active.bytes += buffer.length;
+      if (active.bytes > MAX_BUFFER_BYTES) {
+        finish(false, `Node REPL output exceeded ${MAX_BUFFER_BYTES} bytes.`, true);
+        setImmediate(() => process.exit(1));
+        return false;
+      }
+      active[field] += buffer.toString("utf8");
+      if (typeof resolvedCallback === "function") queueMicrotask(resolvedCallback);
+      return true;
+    };
+  }
+
+  process.stdout.write = captureProcessWrite("stdout", process.stdout.write.bind(process.stdout));
+  process.stderr.write = captureProcessWrite("stderr", process.stderr.write.bind(process.stderr));
+
+  output.on("data", (chunk) => {
+    if (!active) return;
+    active.bytes += chunk.length;
+    if (active.bytes > MAX_BUFFER_BYTES) {
+      finish(false, `Node REPL output exceeded ${MAX_BUFFER_BYTES} bytes.`, true);
+      setImmediate(() => process.exit(1));
+      return;
+    }
+    active.output += chunk.toString("utf8");
+  });
+
+  // Runtime exceptions from the default evaluator are printed through the
+  // REPL output stream and completed by displayPrompt(), rather than passed to
+  // eval's callback. Intercept that public completion point while retaining the
+  // default evaluator's `_error` behavior.
+  replServer.displayPrompt = () => {
+    if (!active) return;
+    finish(false, active.output.trimEnd() || "Node REPL evaluation failed.");
+  };
+
+  process.on("message", (message) => {
+    const requestMessage = /** @type {any} */ (message);
+    if (!requestMessage || requestMessage.type !== "evaluate") return;
+    if (active) {
+      send({ type: "result", id: requestMessage.id, ok: false, text: "Node REPL is already evaluating code." });
+      return;
+    }
+    if (typeof requestMessage.code !== "string" || requestMessage.code.trim().length === 0) {
+      send({ type: "result", id: requestMessage.id, ok: false, text: "Node REPL code must not be empty." });
+      return;
+    }
+    active = { id: requestMessage.id, output: "", stdout: "", stderr: "", bytes: 0 };
+    try {
+      replServer.eval(requestMessage.code, replServer.context, "<mono-agent-node-repl>", (error, value) => {
+        if (!active || active.id !== requestMessage.id) return;
+        if (error) {
+          if (!replServer.underscoreErrAssigned) replServer.lastError = error;
+          finish(false, [active.output.trimEnd(), errorText(error)].filter(Boolean).join("\n"));
+          return;
+        }
+        if (!replServer.underscoreAssigned) replServer.last = value;
+        let rendered;
+        try {
+          rendered = replServer.writer(value);
+        } catch (writerError) {
+          finish(false, [active.output.trimEnd(), errorText(writerError)].filter(Boolean).join("\n"));
+          return;
+        }
+        finish(true, `${active.output}${rendered}`.trimEnd());
+      });
+    } catch (error) {
+      finish(false, [active.output.trimEnd(), errorText(error)].filter(Boolean).join("\n"));
+    }
+  });
+
+  process.on("disconnect", () => {
+    server.close();
+    process.exit(0);
+  });
+}
+
+const NODE_REPL_WORKER_SOURCE = `(${nodeReplWorkerMain.toString()})();`;
+
+function killProcessGroup(child, signal) {
+  if (!child?.pid) return;
+  try {
+    process.kill(process.platform === "win32" ? child.pid : -child.pid, signal);
+  } catch {
+    try { process.kill(child.pid, signal); } catch { /* already gone */ }
+  }
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function appendChunk(record, target, chunk) {
+  record.directOutputBytes += chunk.length;
+  if (record.directOutputBytes > NODE_REPL_MAX_BUFFER_BYTES) {
+    record.failureReason = `Node REPL output exceeded ${NODE_REPL_MAX_BUFFER_BYTES} bytes.`;
+    void terminateRecord(record);
+    return;
+  }
+  target.push(chunk);
+}
+
+function directOutput(record, capturedStdout = "", capturedStderr = "") {
+  const sections = [];
+  const stdout = `${capturedStdout}${Buffer.concat(record.stdout).toString("utf8")}`.trimEnd();
+  const stderr = `${capturedStderr}${Buffer.concat(record.stderr).toString("utf8")}`.trimEnd();
+  if (stdout) sections.push(`STDOUT:\n${stdout}`);
+  if (stderr) sections.push(`STDERR:\n${stderr}`);
+  return sections.join("\n");
+}
+
+function clearRequestOutput(record) {
+  record.stdout = [];
+  record.stderr = [];
+  record.directOutputBytes = 0;
+  record.failureReason = null;
+}
+
+function resultText(record, text, stdout, stderr) {
+  return [directOutput(record, stdout, stderr), String(text || "").trimEnd()].filter(Boolean).join("\n");
+}
+
+async function cleanupPrepared(record) {
+  if (record.cleaned) return;
+  record.cleaned = true;
+  try { await record.prepared.cleanup?.(); } catch { /* best-effort teardown */ }
+}
+
+async function terminateRecord(record) {
+  if (record.closed) {
+    await record.done;
+    return;
+  }
+  killProcessGroup(record.child, "SIGTERM");
+  if (!record.killTimer) {
+    record.killTimer = setTimeout(() => killProcessGroup(record.child, "SIGKILL"), KILL_GRACE_MS);
+    record.killTimer.unref?.();
+  }
+  await record.done;
+}
+
+/**
+ * One lazy Node REPL process owned by a single Pi run.
+ * @param {{cwd?: string, maxOutputChars?: number, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ */
+export function createNodeReplController({
+  cwd,
+  maxOutputChars,
+  sandboxPolicy,
+  sandboxEngine,
+  ctx,
+} = {}) {
+  const resolvedCtx = ctx ?? readToolRuntime();
+  const sandbox = resolvedCtx.sandbox ?? passthroughSandbox;
+  const policy = resolveSandboxPolicy(resolvedCtx, sandboxPolicy);
+  const workdir = resolve(cwd || resolvedCtx.workspace || process.cwd());
+  let current = null;
+  let starting = null;
+  let permanentlyClosed = false;
+  let nextRequestId = 0;
+
+  async function startChild() {
+    const prepared = await sandbox.prepareCommand({
+      policy,
+      engine: sandboxEngine ?? resolvedCtx.sandboxEngine ?? undefined,
+      command: {
+        command: process.execPath,
+        args: ["--eval", NODE_REPL_WORKER_SOURCE],
+        cwd: workdir,
+      },
+    });
+    if (permanentlyClosed) {
+      await prepared.cleanup?.();
+      throw new Error("Node REPL run has already ended.");
+    }
+
+    let child;
+    try {
+      child = spawn(prepared.command, prepared.args || [], {
+        cwd: prepared.cwd,
+        detached: true,
+        env: prepared.env ? { ...process.env, ...prepared.env } : process.env,
+        stdio: ["ignore", "pipe", "pipe", "ipc"],
+      });
+    } catch (error) {
+      await prepared.cleanup?.();
+      throw error;
+    }
+
+    let resolveDone = () => {};
+    const done = new Promise((resolveDonePromise) => { resolveDone = () => resolveDonePromise(); });
+    const record = {
+      child,
+      prepared,
+      done,
+      resolveDone,
+      closed: false,
+      cleaned: false,
+      killTimer: null,
+      spawnError: null,
+      failureReason: null,
+      pending: null,
+      stdout: [],
+      stderr: [],
+      directOutputBytes: 0,
+    };
+    current = record;
+
+    child.stdout?.on("data", (chunk) => appendChunk(record, record.stdout, chunk));
+    child.stderr?.on("data", (chunk) => appendChunk(record, record.stderr, chunk));
+    child.once("error", (error) => { record.spawnError = error; });
+    child.on("message", (message) => {
+      const result = /** @type {any} */ (message);
+      const pending = record.pending;
+      if (!pending || !result || result.type !== "result" || result.id !== pending.id) return;
+      record.pending = null;
+      clearTimeout(pending.timeoutTimer);
+      pending.signal?.removeEventListener?.("abort", pending.onAbort);
+      setImmediate(async () => {
+        const text = resultText(record, result.text, result.stdout, result.stderr);
+        if (result.reset) await terminateRecord(record);
+        if (result.ok) {
+          pending.resolve(capChars(text || "(no output)", {
+            label: "NodeRepl",
+            maxChars: maxOutputChars,
+            strategy: "head_tail",
+            ctx: resolvedCtx,
+          }));
+        } else {
+          pending.reject(new Error(text || "Node REPL evaluation failed."));
+        }
+      });
+    });
+    child.once("close", (code, closeSignal) => {
+      record.closed = true;
+      if (record.killTimer) clearTimeout(record.killTimer);
+      if (current === record) current = null;
+      const pending = record.pending;
+      record.pending = null;
+      if (pending) {
+        clearTimeout(pending.timeoutTimer);
+        pending.signal?.removeEventListener?.("abort", pending.onAbort);
+        const reason = record.failureReason
+          || (record.spawnError ? errorMessage(record.spawnError) : null)
+          || `Node REPL process exited before evaluation completed${closeSignal ? ` (${closeSignal})` : ` (code ${code ?? "unknown"})`}.`;
+        pending.reject(new Error(`${reason} Session state was reset.`));
+      }
+      void cleanupPrepared(record).finally(() => record.resolveDone());
+    });
+    return record;
+  }
+
+  async function ensureChild() {
+    if (permanentlyClosed) throw new Error("Node REPL run has already ended.");
+    if (current && !current.closed) return current;
+    starting ??= startChild().finally(() => { starting = null; });
+    return await starting;
+  }
+
+  async function resetForFailure(record, pending, message) {
+    if (record.pending === pending) record.pending = null;
+    clearTimeout(pending.timeoutTimer);
+    pending.signal?.removeEventListener?.("abort", pending.onAbort);
+    await terminateRecord(record);
+    pending.reject(new Error(`${message} Session state was reset.`));
+  }
+
+  return {
+    /** @param {{code: string}} params @param {{signal?: AbortSignal}} [execution] */
+    async execute({ code }, { signal } = {}) {
+      if (typeof code !== "string" || code.trim().length === 0) {
+        throw new Error("Node REPL code must not be empty.");
+      }
+      if (signal?.aborted) throw new Error("Node REPL execution aborted.");
+      const record = await ensureChild();
+      if (signal?.aborted) {
+        await terminateRecord(record);
+        throw new Error("Node REPL execution aborted. Session state was reset.");
+      }
+      if (record.pending) throw new Error("Node REPL is already evaluating code.");
+      clearRequestOutput(record);
+      const id = `node-repl-${++nextRequestId}`;
+
+      return await new Promise((resolveResult, rejectResult) => {
+        const pending = {
+          id,
+          resolve: resolveResult,
+          reject: rejectResult,
+          signal,
+          onAbort: null,
+          timeoutTimer: null,
+        };
+        pending.onAbort = () => {
+          void resetForFailure(record, pending, "Node REPL execution aborted.");
+        };
+        pending.timeoutTimer = setTimeout(() => {
+          void resetForFailure(
+            record,
+            pending,
+            `Node REPL execution timed out after ${DEFAULT_NODE_REPL_TIMEOUT_MS}ms.`,
+          );
+        }, DEFAULT_NODE_REPL_TIMEOUT_MS);
+        pending.timeoutTimer.unref?.();
+        record.pending = pending;
+        signal?.addEventListener?.("abort", pending.onAbort, { once: true });
+        record.child.send({ type: "evaluate", id, code }, (error) => {
+          if (error && record.pending === pending) {
+            void resetForFailure(record, pending, `Node REPL IPC failed: ${errorMessage(error)}.`);
+          }
+        });
+      });
+    },
+
+    async close() {
+      if (permanentlyClosed) return;
+      permanentlyClosed = true;
+      if (starting) {
+        try { await starting; } catch { /* start failure already surfaced */ }
+      }
+      if (current) await terminateRecord(current);
+    },
+  };
+}