bare-agent 0.14.0 → 0.16.0

package/README.md

@@ -66,8 +66,9 @@ Every piece works alone — take what you need, ignore the rest.
 
 | Component | What it does |
 |---|---|
-| **Loop** | Think → act → observe → repeat. Calls any LLM, executes your tools, loops until done. Returns estimated USD cost per run. Governance via `Loop({ policy })` — wire bareguard's `Gate` through `wireGate(gate)` and every tool call (native, MCP, browsing, mobile) traverses one chokepoint with per-caller `ctx` routing. Bareguard owns the audit log, budget caps, and halt decisions; Loop respects the verdict. Context engineering via `Loop({ assemble })` — a per-round `assemble(msgs, ctx)` chokepoint to recall/compress/trim the window sent to the model (the seam litectx plugs into); returns a view, the canonical transcript stays intact, fail-open. The exported `unitAssembler`/`toUnits`/`fromUnits` adapter lets a consumer work over a neutral unit `{id, role, content, kind, pinned, atomic, tokensApprox}` — bareagent owns the grammar (atomic tool-pair bundling, pinned system/task, a pairing seatbelt), the consumer owns content + relevance. The CE function reads its inputs from the per-run `ctx` — litectx's budget-fitter uses `ctx.budget` (and `ctx.task`), so you **must** populate it via `run(msgs, tools, { ctx })`: an unset `ctx.budget` means the fitter has no budget, keeps everything, and returns the window unchanged — a silent no-op, not a bug (see `examples/litectx-assemble.mjs`). For summary-window compaction the Loop also lends a provider-bound `ctx.summarize(excerpt) => Promise<string>` (R-C6): the consumer owns when/what to summarize and the splice, bareagent makes the one model call (counted against the budget via `onLlmResult`, tagged `kind:'summarize'`). `onError` + `loop:error` surface every silent-ish failure (callback throw, Checkpoint timeout) |
+| **Loop** | Think → act → observe → repeat. Calls any LLM, executes your tools, loops until done. Returns estimated USD cost per run. Governance via `Loop({ policy })` — wire bareguard's `Gate` through `wireGate(gate)` and every tool call (native, MCP, browsing, mobile) traverses one chokepoint with per-caller `ctx` routing. Bareguard owns the audit log, budget caps, and halt decisions; Loop respects the verdict. Context engineering via `Loop({ assemble })` — a per-round `assemble(msgs, ctx)` chokepoint to recall/compress/trim the window sent to the model (the seam litectx plugs into); returns a view, the canonical transcript stays intact, fail-open. The exported `unitAssembler`/`toUnits`/`fromUnits` adapter lets a consumer work over a neutral unit `{id, role, content, kind, pinned, atomic, tokensApprox}` — bareagent owns the grammar (atomic tool-pair bundling, pinned system/task, a pairing seatbelt), the consumer owns content + relevance. The CE function reads its inputs from the per-run `ctx` — litectx's budget-fitter uses `ctx.budget` (and `ctx.task`), so you **must** populate it via `run(msgs, tools, { ctx })`: an unset `ctx.budget` means the fitter has no budget, keeps everything, and returns the window unchanged — a silent no-op, not a bug (see `examples/litectx-assemble.mjs`). For summary-window compaction the Loop also lends a provider-bound `ctx.summarize(excerpt) => Promise<string>` (R-C6): the consumer owns when/what to summarize and the splice, bareagent makes the one model call (counted against the budget via `onLlmResult`, tagged `kind:'summarize'`). For an unbounded long-running agent there's the **destructive** counterpart `Loop({ trim })` (RT-2) — a per-round bound on the canonical transcript that evicts old turns *after* harvesting them; wire it with the exported `unitTrimmer({ trim, onHarvest, policy })` over litectx's `trim` verb (harvest-before-evict, fail-open; `harvestKey` gives the stable upsert id), opt-in (requires a consumer on litectx ≥ 0.16.0). `onError` + `loop:error` surface every silent-ish failure (callback throw, Checkpoint timeout) |
 | **Planner** | Break a goal into a step DAG via LLM. Built-in caching (`cacheTTL`) |
+| **assessComplexity** | Pure-code pre-planner (no LLM): rates a goal `simple`/`medium`/`complex`/`critical` from its text via keyword scoring + a critical safety override. `needsPlanning` gates whether to spend a Planner pass; `critical` flags security/production/compliance work for extra scrutiny. Free, instant, debuggable via `signals` |
 | **runPlan** | Execute steps in parallel waves. Dependency-aware, failure propagation, per-step retry |
 | **Retry** | Exponential/linear backoff with jitter. Respects `err.retryable` |
 | **CircuitBreaker** | Fail fast after N errors. Auto-recovers after cooldown. Per-key isolation |
@@ -83,7 +84,7 @@ Every piece works alone — take what you need, ignore the rest.
 | **Mobile** | Android + iOS device control via `baremobile`. Same two modes: library tools (`createMobileTools` — action tools auto-return snapshots) or CLI session (`baremobile` CLI — disk-based snapshots) |
 | **Shell** | Cross-platform `shell_read`, `shell_grep`, `shell_run` (argv, no shell), `shell_exec` (raw shell). Pure Node — no `grep`/`rg`/`findstr` dependency. Injection-proof `shell_run` for policy-gated use |
 | **MCP Bridge** | Auto-discover MCP servers from IDE configs (Claude Code, Cursor, etc.), expose as bareagent tools. Static allow/deny via `.mcp-bridge.json`, `systemContext` for LLM awareness. Runtime policy lives in `Loop({ policy })` — one hook for MCP + native tools alike. Returns both bulk `tools` (one per MCP tool) and `metaTools` (`mcp_discover` + `mcp_invoke` for token-thrifty access to large catalogs). Connecting runs a server's `command` (which may come from a cwd `.mcp.json`): pass `confirmServer` to vet each before it spawns — otherwise the bridge warns naming every command it runs. Every RPC is time-bounded (`timeout` for the handshake, `callTimeout` for `tools/call`), and a server that breaks its stdin pipe fails the connection instead of crashing the host. Zero deps |
-| **Spawn** | Fork a child bareagent process as a specialist agent. LLM-callable form blocks until child exits; library form returns a handle (`wait`, `onLine`, `kill`). One JSONL channel per child — child stderr captured and re-emitted as `child:stderr` events on the parent stream. Threads `BAREGUARD_AUDIT_PATH` / `BAREGUARD_PARENT_RUN_ID` / `BAREGUARD_BUDGET_FILE` / `BAREGUARD_SPAWN_DEPTH` so the family stitches into one audit + budget. `bareguard ^0.2.0` adds `spawn.ratePerMinute` + `limits.maxDepth` per-family caps |
+| **Spawn** | Fork a child bareagent process as a specialist agent. LLM-callable form blocks until child exits; library form returns a handle (`wait`, `onLine`, `kill`). One JSONL channel per child — child stderr captured and re-emitted as `child:stderr` events on the parent stream. Threads `BAREGUARD_AUDIT_PATH` / `BAREGUARD_PARENT_RUN_ID` / `BAREGUARD_BUDGET_FILE` / `BAREGUARD_SPAWN_DEPTH` so the family stitches into one audit + budget. `bareguard ^0.2.0` adds `spawn.ratePerMinute` + `limits.maxDepth` per-family caps. `timeoutMs` is the wall-clock ceiling; opt-in `idleTimeoutMs` is a heartbeat watchdog that kills a child gone silent on both stdio streams (resets on each line, so slow-but-working children survive; result carries `idleKilled`) |
 | **Defer** | Append a `{action, when}` record to a JSONL queue for a separate waker (cron / systemd timer / `examples/wake.sh`) to fire later. Two-phase governance: emit-time `gate.check` on the `defer` action; fire-time `gate.check` on the inner action when the waker re-invokes. `bareguard ^0.2.0` adds `defer.ratePerMinute` family-wide cap |
 
 **Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Ollama, CLIPipe (any CLI tool via stdin/stdout with real-time streaming), Fallback, or bring your own (one method: `generate`). All return the same shape — swap freely. The OpenAI provider warns if it would send your key over plaintext `http://` to a non-loopback host (use `https`, or drop `apiKey` for keyless local endpoints).
@@ -240,17 +241,20 @@ For wiring recipes and API details, see the **[Integration Guide](bareagent.cont
 
 ## The bare ecosystem
 
-Four vanilla JS modules. Zero deps where possible (bareguard has one). Same API patterns.
+Local-first, composable agent infrastructure. Same API patterns throughout —
+mix and match, each module works standalone.
 
-| | [**bareagent**](https://npmjs.com/package/bare-agent) | [**barebrowse**](https://npmjs.com/package/barebrowse) | [**baremobile**](https://npmjs.com/package/baremobile) | [**bareguard**](https://npmjs.com/package/bareguard) |
-|---|---|---|---|---|
-| **Does** | Gives agents a think→act loop | Gives agents a real browser | Gives agents Android + iOS devices | Gates everything an agent does |
-| **How** | Goal in → coordinated actions out | URL in → pruned snapshot out | Screen in → pruned snapshot out | Action in → allow / deny / human-asked out |
-| **Replaces** | LangChain, CrewAI, AutoGen | Playwright, Selenium, Puppeteer | Appium, Espresso, XCUITest | Hand-rolled allowlists, scattered policy code |
-| **Interfaces** | Library · CLI · subprocess | Library · CLI · MCP | Library · CLI · MCP | Library |
-| **Solo or together** | Orchestrates the others as tools | Works standalone | Works standalone | Embedded in bareagent's loop; usable by any runner |
+**Core** — the brain, the gate, the memory.
 
-> **Reach 50+ messengers with one Docker container via [beeperbox](https://github.com/hamr0/beeperbox)** — a headless Beeper Desktop that exposes WhatsApp, iMessage, Signal, Telegram, Slack, Discord, RCS, SMS and more as a single MCP server. Wire it through bareagent's MCP bridge; bareguard policies the invocations like any other tool (per-chat allowlists, ask patterns on destructive sends, all the usual layered defense).
+- **[bareagent](https://npmjs.com/package/bare-agent)** — the think→act→observe loop. *Goal in → coordinated actions out.* Replaces LangChain, CrewAI, AutoGen.
+- **[bareguard](https://npmjs.com/package/bareguard)** — the single gate every action passes through. *Action in → allow / deny / ask-a-human out.* Replaces hand-rolled allowlists and scattered policy code.
+- **[litectx](https://npmjs.com/package/litectx)** — tree-sitter code + memory graph with activation decay, plus lightweight context engineering (write · select · compress · isolate). *Query in → ranked context out.*
+
+**Optional reach** — give the agent hands.
+
+- **[barebrowse](https://npmjs.com/package/barebrowse)** — a real browser for agents. *URL in → pruned snapshot out.* Replaces Playwright, Selenium, Puppeteer.
+- **[baremobile](https://npmjs.com/package/baremobile)** — Android + iOS device control. *Screen in → pruned snapshot out.* Replaces Appium, Espresso, XCUITest.
+- **[beeperbox](https://github.com/hamr0/beeperbox)** — 50+ messaging networks via one MCP server (headless Beeper Desktop in Docker). *Chat in → unified message stream out.* Replaces Twilio, per-platform bot APIs.
 
 **What you can build:**
 

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.14.0 | Node.js >= 18 | one required dep (`bareguard ^0.4.2`) | Apache 2.0
+> v0.16.0 | Node.js >= 18 | one required dep (`bareguard ^0.4.2`) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -14,7 +14,7 @@ npm install bare-agent
 ```
 
 Eight entry points:
-- `require('bare-agent')` — Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, **toUnits, fromUnits, unitAssembler** (the `assemble` context-units adapter, v0.13+), BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, **HaltError**
+- `require('bare-agent')` — Loop, Planner, **assessComplexity** (pure-code no-LLM pre-planner → `{level, score, needsPlanning, signals}`), StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, **toUnits, fromUnits, unitAssembler** (the `assemble` context-units adapter, v0.13+), **unitTrimmer, harvestKey** (the destructive `trim` seam adapter — RT-2 harvest-before-evict, needs a consumer on litectx ≥ 0.16.0), BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, **HaltError**
 - `require('bare-agent/errors')` — same error classes via a stable subpath (v0.10.1+) for adopters who want to import only the error surface
 - `require('bare-agent/providers')` — OpenAI, Anthropic, Ollama, CLIPipe, Fallback (the canonical short names; `*Provider` aliases — `OpenAIProvider`, `AnthropicProvider`, etc. — are also exported and match the class names, so either destructure works, v0.12.1+)
 - `require('bare-agent/stores')` — SQLite (FTS5), JsonFile
@@ -31,6 +31,8 @@ Eight entry points:
 |---|---|
 | Call an LLM with tools and get a result | Loop + a Provider |
 | Break a goal into steps | Planner + a Provider |
+| Size a goal before planning (no LLM) | assessComplexity — `needsPlanning` gates a Planner pass |
+| Kill a spawned child that hangs silently | createSpawnTool / spawnChild `{ idleTimeoutMs }` |
 | Execute a step DAG with parallelism | runPlan + executeFn |
 | Track task state (pending/running/done/failed) | StateMachine |
 | Run agent turns on a schedule (cron, timers) | Scheduler |

package/index.d.ts

@@ -1,5 +1,6 @@
 import { Loop } from "./src/loop";
 import { Planner } from "./src/planner";
+import { assessComplexity } from "./src/complexity";
 import { StateMachine } from "./src/state";
 import { Scheduler } from "./src/scheduler";
 import { Checkpoint } from "./src/checkpoint";
@@ -13,6 +14,8 @@ import { defaultActionTranslator } from "./src/bareguard-adapter";
 import { toUnits } from "./src/context-units";
 import { fromUnits } from "./src/context-units";
 import { unitAssembler } from "./src/context-units";
+import { unitTrimmer } from "./src/context-units";
+import { harvestKey } from "./src/context-units";
 import { BareAgentError } from "./src/errors";
 import { ProviderError } from "./src/errors";
 import { ToolError } from "./src/errors";
@@ -20,4 +23,4 @@ import { TimeoutError } from "./src/errors";
 import { ValidationError } from "./src/errors";
 import { CircuitOpenError } from "./src/errors";
 import { HaltError } from "./src/errors";
-export { Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, toUnits, fromUnits, unitAssembler, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };
+export { Loop, Planner, assessComplexity, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };

package/index.js

@@ -2,6 +2,7 @@
 
 const { Loop } = require('./src/loop');
 const { Planner } = require('./src/planner');
+const { assessComplexity } = require('./src/complexity');
 const { StateMachine } = require('./src/state');
 const { Scheduler } = require('./src/scheduler');
 const { Checkpoint } = require('./src/checkpoint');
@@ -11,7 +12,7 @@ const { Retry } = require('./src/retry');
 const { runPlan } = require('./src/run-plan');
 const { CircuitBreaker } = require('./src/circuit-breaker');
 const { wireGate, defaultActionTranslator } = require('./src/bareguard-adapter');
-const { toUnits, fromUnits, unitAssembler } = require('./src/context-units');
+const { toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey } = require('./src/context-units');
 const {
   BareAgentError,
   ProviderError,
@@ -25,6 +26,7 @@ const {
 module.exports = {
   Loop,
   Planner,
+  assessComplexity,
   StateMachine,
   Scheduler,
   Checkpoint,
@@ -38,6 +40,8 @@ module.exports = {
   toUnits,
   fromUnits,
   unitAssembler,
+  unitTrimmer,
+  harvestKey,
   BareAgentError,
   ProviderError,
   ToolError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "files": [
     "index.js",
     "index.d.ts",
@@ -99,7 +99,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
-    "litectx": "^0.13.0",
+    "litectx": "^0.16.0",
     "typescript": "^5.7.0"
   }
 }

package/src/complexity.d.ts

@@ -0,0 +1,31 @@
+export type ComplexityResult = {
+    /**
+     * - Assessed complexity tier.
+     */
+    level: "simple" | "medium" | "complex" | "critical";
+    /**
+     * - Raw heuristic score (100 for a critical override).
+     */
+    score: number;
+    /**
+     * - false for `simple`, true otherwise — the routing hint.
+     */
+    needsPlanning: boolean;
+    /**
+     * - Which signals fired, for transparency/debugging.
+     */
+    signals: string[];
+};
+/**
+ * @typedef {object} ComplexityResult
+ * @property {'simple'|'medium'|'complex'|'critical'} level - Assessed complexity tier.
+ * @property {number} score - Raw heuristic score (100 for a critical override).
+ * @property {boolean} needsPlanning - false for `simple`, true otherwise — the routing hint.
+ * @property {string[]} signals - Which signals fired, for transparency/debugging.
+ */
+/**
+ * Assess the complexity of a goal/prompt from its text alone (no LLM).
+ * @param {string} prompt - The goal to classify.
+ * @returns {ComplexityResult}
+ */
+export function assessComplexity(prompt: string): ComplexityResult;

package/src/complexity.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * Keyword complexity assessor — a fast, pure-code "pre-planner" that classifies a goal as
+ * simple / medium / complex / critical from its text alone, with NO LLM call. Ported (concept,
+ * not line-for-line) from Aurora's SOAR keyword assessor. It exists to drive a routing decision:
+ * a `simple` goal can run single-shot; `medium`+ warrants a Planner pass; `critical` (security,
+ * production, compliance, financial) flags work that deserves extra scrutiny (e.g. a checkpoint /
+ * adversarial verification) before acting.
+ *
+ *   const { level, needsPlanning } = assessComplexity(goal);
+ *   const steps = needsPlanning ? await planner.plan(goal) : [{ id: 's1', action: goal }];
+ *
+ * Concept, deliberately lightweight: a critical-keyword override, tiered action-verb scoring
+ * (simple verbs subtract, complex verbs add the most), feature nouns + scope + structure signals,
+ * and two calibrated thresholds. It is a heuristic — transparent and debuggable via `signals`, not
+ * a model. On the upstream validation corpus it lands ~89% (the fuller LLM-free original ~95%);
+ * the gap is long-tail ambiguity ("add a button" is genuinely context-dependent).
+ */
+
+const has = (/** @type {Set<string>} */ words, /** @type {Set<string>} */ set) =>
+  [...set].filter(w => words.has(w));
+const wordSet = (/** @type {string} */ s) => new Set(s.match(/\b\w+\b/g) || []);
+// Escape regex metacharacters so a keyword can't break (or alter) the word-boundary match — the
+// lists below are plain words today, but a future entry like "c++" or ".net" must stay literal.
+const esc = (/** @type {string} */ k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const hasAny = (/** @type {string} */ s, /** @type {string[]} */ list) =>
+  list.some(k => new RegExp(`\\b${esc(k)}\\b`).test(s));
+
+// --- critical safety override: high-stakes work jumps straight to the top tier ---
+const CRIT_INCIDENT = ['emergency', 'outage', 'breach', 'vulnerability', 'exploit', 'corruption', 'data loss', 'incident', 'penetration'];
+const CRIT_COMPLIANCE = ['gdpr', 'hipaa', 'pci', 'compliance', 'regulation'];
+const SEC_CONTEXT = ['security', 'production', 'authentication', 'authorization'];
+const CRIT_ACTIONS = ['fix', 'patch', 'investigate', 'secure', 'protect', 'mitigate', 'prevent', 'respond', 'handle'];
+const FINANCIAL = ['payment', 'transaction', 'billing', 'financial'];
+const SECURE_ACTS = ['encrypt', 'secure', 'protect', 'audit'];
+
+/** @param {string} s lowercased prompt */
+function isCritical(s) {
+  if (hasAny(s, CRIT_INCIDENT) || hasAny(s, CRIT_COMPLIANCE)) return true;
+  if (hasAny(s, SEC_CONTEXT) && hasAny(s, CRIT_ACTIONS)) return true;     // e.g. "fix security ..."
+  if (hasAny(s, FINANCIAL) && hasAny(s, SECURE_ACTS)) return true;        // e.g. "encrypt payment ..."
+  return false;
+}
+
+// --- tiered keyword scoring: verb "weight" reflects how much work the ask implies ---
+const COMPLEX_VERBS = new Set(['implement', 'design', 'architect', 'refactor', 'integrate', 'migrate', 'build', 'create', 'develop', 'construct', 'engineer', 'establish', 'transform', 'overhaul', 'rewrite', 'restructure', 'optimize']);
+const ANALYSIS_VERBS = new Set(['explain', 'compare', 'analyze', 'debug', 'understand', 'investigate', 'describe', 'evaluate', 'review', 'examine', 'diagnose', 'trace', 'why', 'difference']);
+const MEDIUM_VERBS = new Set(['add', 'update', 'fix', 'write', 'change', 'modify', 'remove', 'delete', 'improve', 'enhance', 'extend', 'convert', 'rename', 'move', 'test', 'configure', 'setup', 'set', 'enable', 'disable']);
+const SIMPLE_VERBS = new Set(['what', 'show', 'list', 'get', 'find', 'print', 'check', 'read', 'open', 'run', 'where', 'which', 'display', 'view', 'see', 'tell', 'give', 'name', 'count', 'who', 'when', 'is']);
+const SCOPE = new Set(['all', 'every', 'entire', 'across', 'comprehensive', 'complete', 'codebase', 'project', 'system', 'application', 'full', 'whole', 'everything', 'throughout']);
+const DOMAINS = new Set(['security', 'performance', 'scalability', 'reliability', 'testing', 'authentication', 'authorization', 'caching', 'logging', 'monitoring', 'database', 'api', 'frontend', 'backend', 'infrastructure', 'deployment', 'docker', 'kubernetes', 'microservices', 'distributed']);
+// Feature/system nouns: paired with an action verb they signal a real feature, not a one-liner.
+const COMPLEX_NOUNS = new Set(['authentication', 'authorization', 'oauth', 'jwt', 'session', 'sessions', 'pipeline', 'workflow', 'notification', 'notifications', 'dashboard', 'crud', 'plugin', 'framework', 'websocket', 'websockets', 'realtime', 'pagination', 'search', 'validation', 'migration', 'schema', 'registration']);
+const SEQUENCE = ['first', 'then', 'after that', 'finally', 'next', 'afterwards', 'subsequently', 'step by step', 'and then', 'as well as', 'additionally', 'along with'];
+const CONSTRAINTS = ['without breaking', 'without changing', 'maintaining', 'ensuring', 'backward compatible', 'backwards compatible', 'must not', 'should not', 'preserve', 'without affecting'];
+
+const SIMPLE_THRESHOLD = 11;
+const MEDIUM_THRESHOLD = 28;
+
+// Bound the text the assessor scans. Several signal patterns contain `.*`, which can backtrack
+// quadratically on adversarial input (e.g. "integrate "×N with no "with" — O(n²)). Complexity is
+// fully determined by the opening of a goal, so capping the working string makes every scan
+// linear-bounded and removes the DoS surface for callers that pass untrusted end-user text.
+const MAX_ASSESS_LEN = 4000;
+
+/**
+ * @typedef {object} ComplexityResult
+ * @property {'simple'|'medium'|'complex'|'critical'} level - Assessed complexity tier.
+ * @property {number} score - Raw heuristic score (100 for a critical override).
+ * @property {boolean} needsPlanning - false for `simple`, true otherwise — the routing hint.
+ * @property {string[]} signals - Which signals fired, for transparency/debugging.
+ */
+
+/**
+ * Assess the complexity of a goal/prompt from its text alone (no LLM).
+ * @param {string} prompt - The goal to classify.
+ * @returns {ComplexityResult}
+ */
+function assessComplexity(prompt) {
+  if (typeof prompt !== 'string' || !prompt.trim()) {
+    return { level: 'simple', score: 0, needsPlanning: false, signals: ['empty'] };
+  }
+  const text = prompt.trim().slice(0, MAX_ASSESS_LEN);
+  const lower = text.toLowerCase();
+  if (isCritical(lower)) {
+    return { level: 'critical', score: 100, needsPlanning: true, signals: ['critical_override'] };
+  }
+
+  const words = wordSet(lower);
+  const wc = text.split(/\s+/).length;
+  /** @type {string[]} */
+  const signals = [];
+  let score = 0;
+  /** @param {number} n @param {string} [sig] */
+  const add = (n, sig) => { score += n; if (sig) signals.push(sig); };
+
+  const complex = has(words, COMPLEX_VERBS);
+  const analysis = has(words, ANALYSIS_VERBS);
+  const medium = has(words, MEDIUM_VERBS);
+  const simple = has(words, SIMPLE_VERBS);
+  const scope = has(words, SCOPE);
+  const domains = has(words, DOMAINS);
+
+  if (complex.length) add(complex.length * 25, 'complex_verbs');
+  if (analysis.length) add(Math.min(analysis.length * 15, 20), 'analysis_verbs');
+  if (medium.length) add(medium.length * 12, 'medium_verbs');
+  if (simple.length) add(-Math.min(simple.length * 3, 10), 'simple_verbs');
+  if (scope.length) add(scope.length * 12, 'scope');
+  if (domains.length > 1) add(domains.length * 8, 'multi_domain');
+  else if (domains.length) add(5, 'domain');
+
+  // feature noun + an action verb => a real feature (pushes single-verb asks up a tier)
+  const nouns = has(words, COMPLEX_NOUNS);
+  if (nouns.length && (medium.length || complex.length)) add(nouns.length * 10, 'feature_nouns');
+  if (/\b(?:dark\s*mode|feature\s*flags?|real-?time|end-?to-?end|full-?stack)\b/.test(lower)) add(12, 'feature_pattern');
+  if (/\bintegrate\b.*\bwith\b/.test(lower)) add(15, 'integration');
+  if (/\b(?:improve|optimize)\s+(?:performance|speed|efficiency)\b/.test(lower)
+    && !/\b(?:this|the)\s+(?:function|method|query|loop)\b/.test(lower)) add(15, 'open_ended');
+
+  // structure / sequencing — multi-step asks are heavier
+  const seq = SEQUENCE.filter(m => lower.includes(m)).length;
+  if (seq) add(seq * 8, 'sequence');
+  const constraints = CONSTRAINTS.filter(m => lower.includes(m)).length;
+  if (constraints) add(constraints * 12, 'constraints');
+  const listItems = (text.match(/(?:^|\n)\s*(?:\d+[.)]|[-*])\s/g) || []).length;
+  if (listItems) add(listItems * 9, 'list');
+
+  // length: longer prompts trend more complex
+  if (wc > 40) add(15, 'long'); else if (wc > 20) add(10); else if (wc > 10) add(5);
+
+  // architectural / open-ended questions read simple lexically but imply design work
+  if (/\bbest\s+(?:way|approach|practice|architecture)\b|\barchitecture\s+for\b|\bhow (?:should|can|do) (?:we|i)\b.*\b(?:handle|design|implement|build)\b/.test(lower)) add(15, 'design_question');
+  if (/^(?:what is|where is|which|who|is there)\b/.test(lower)) add(-8, 'simple_question');
+
+  // a trivial edit (typo, comment, log line, version bump) stays simple even though its verb is
+  // "medium" weight — gated to trivial OBJECTS so real medium work isn't wrongly demoted.
+  const trivial = /\b(?:fix|add|remove|delete|rename|update|change)\b.*\b(?:typo|comment|console\.?log|variable|version|line|import)\b/.test(lower)
+    || /\bwrite\s+(?:a|the)\s+function\s+(?:that|to|which)\b/.test(lower);
+  if (trivial && !complex.length && !scope.length && wc <= 10) {
+    score = Math.min(score, SIMPLE_THRESHOLD);
+    signals.push('trivial_edit');
+  }
+
+  const level = score <= SIMPLE_THRESHOLD ? 'simple' : score <= MEDIUM_THRESHOLD ? 'medium' : 'complex';
+  return { level, score, needsPlanning: level !== 'simple', signals };
+}
+
+module.exports = { assessComplexity };

package/src/context-units.d.ts

@@ -34,6 +34,67 @@ export function fromUnits(units: Array<Record<string, any>>): Array<Record<strin
  * @returns {(msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>}
  */
 export function unitAssembler(assembleUnits: (units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)): (msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>;
+/**
+ * Wrap litectx's `trim(units, policy)` verb (R-C5) into the Loop's destructive `trim(msgs, ctx)` seam —
+ * the RT-2 harvest-before-evict interlock. Unlike {@link unitAssembler} (a non-destructive per-round VIEW),
+ * this is EVICTION: the Loop replaces its canonical transcript with the returned (smaller) msgs, so old
+ * turns are permanently dropped — which is only safe because every dropped turn is harvested FIRST.
+ *
+ * The returned function `(msgs, ctx) => keptMsgs`:
+ *   1. `toUnits(msgs)` → `trim(units, policy)` → `{ units (kept), dropped, harvest }`.
+ *   2. **Interlock — harvest BEFORE evict:** `await onHarvest({ key, content, unit })` for every harvest
+ *      unit. If `onHarvest` throws (e.g. a write-gate `deny` → HaltError, or a store fault), this throws
+ *      BEFORE returning the evicted view → the Loop fail-opens (no eviction that round) → nothing is lost;
+ *      the next round retries and the idempotent key upserts the already-persisted ones. You cannot drop
+ *      history you have not persisted.
+ *   3. `fromUnits(kept)` is the bounded transcript. Fail-OPEN: an unrecognised `trim` return shape → the
+ *      original msgs unchanged (no eviction). A throw propagates (HaltError → governance halt).
+ *
+ * `.flush(msgs, ctx)` — the F2 residual harvest: `trim` only hands back EVICTED turns, so the final
+ * keepLastN window is never harvested mid-run and a clean run would diverge from an end-of-task batch.
+ * Call `.flush` on completion to harvest the surviving non-pinned turns (no eviction); the idempotent key
+ * means it never duplicates what eviction already harvested. The Loop invokes it only on **clean
+ * completion** — on a halt (e.g. bareguard `maxTurns`), `stop()`, or error exit the survivors stay intact
+ * in `result.msgs` but are NOT auto-flushed (auto-flushing a content-halt could re-trigger the deny that
+ * caused it); harvest `result.msgs` yourself on those exits if you need the final window persisted.
+ *
+ * `onHarvest` is the consumer's harvest POLICY point (litectx CE-PRD §6/R-W*: bareagent owns the trigger
+ * + what's worth keeping, litectx owns the mechanism + worklist). It is REQUIRED — the adapter structurally
+ * enforces harvest-before-evict; pass `async () => {}` to opt INTO lossy bounding.
+ *
+ * @param {{ trim?: Function, onHarvest?: Function, policy?: any }} [opts]
+ *   `trim` — litectx's `(units, policy) => { units, harvest }` verb (REQUIRED). `onHarvest` —
+ *   `({ key, content, unit }) => void|Promise` (REQUIRED; the harvest policy point). `policy` — litectx
+ *   TrimPolicy: `{ keepLastN }` or `{ maxTokens }` (maxTokens wins). Both verbs are runtime-checked.
+ * @returns {((msgs: Array<Record<string, any>>, ctx?: any) => Promise<Array<Record<string, any>>>) & { flush: (msgs: Array<Record<string, any>>, ctx?: any) => Promise<void> }}
+ */
+export function unitTrimmer(opts?: {
+    trim?: Function;
+    onHarvest?: Function;
+    policy?: any;
+}): ((msgs: Array<Record<string, any>>, ctx?: any) => Promise<Array<Record<string, any>>>) & {
+    flush: (msgs: Array<Record<string, any>>, ctx?: any) => Promise<void>;
+};
+/**
+ * Stable harvest key for a unit — the dedup id for harvest-before-evict (RT-2). MUST come from a durable
+ * property of the TURN, never from `unit.id`: `toUnits` mints ids from a module counter, so the same turn
+ * is `u1` on one call and `u3` on the next (poc/rt2-trim-interlock.mjs F1) — keying on it double-writes.
+ * Derived here from the unit's verbatim `_msgs` backing: the joined `tool_call_id`s for a tool turn (stable
+ * by construction), else a hash of `[role, content]` for a plain turn. The consumer namespaces it (e.g.
+ * `${taskId}:${key}`) and feeds it to `remember(id, …)`, which upserts → a replayed hop overwrites instead
+ * of duplicating. NOT a content search (litectx FTS can't match ids; sealed meta is unsearchable) — a
+ * deterministic key passed to the keyed write. The consumer's `taskId` prefix is the isolation boundary;
+ * treat the returned key as opaque (don't re-parse it).
+ *
+ * Two collision hardenings (grounded in poc/rt2-audit-grounding.mjs): ids are `encodeURIComponent`-escaped
+ * before the `,` join, so `['a','b']` and `['a,b']` can no longer alias the same key; and the plain-turn
+ * hash is **two near-independent streams** (FNV-1a + DJB2) → ~64-bit, so a long-running agent's harvest
+ * can't silently overwrite a turn via a 32-bit birthday collision (a single 32-bit FNV exhausted in ~5e5
+ * distinct turns). Normal provider ids (`call_…`) round-trip unchanged through the escape.
+ * @param {Record<string, any>} unit - a unit from {@link toUnits} (its `_msgs` backing is read).
+ * @returns {string}
+ */
+export function harvestKey(unit: Record<string, any>): string;
 /** chars/4 token estimate over a list of messages (matches poc2 / the Loop's own heuristic). */
 export function approxTokens(msgs: any): number;
 /**

package/src/context-units.js

@@ -222,4 +222,104 @@ function unitAssembler(assembleUnits) {
   };
 }
 
-module.exports = { toUnits, fromUnits, unitAssembler, approxTokens, pairingSeatbelt };
+/**
+ * Stable harvest key for a unit — the dedup id for harvest-before-evict (RT-2). MUST come from a durable
+ * property of the TURN, never from `unit.id`: `toUnits` mints ids from a module counter, so the same turn
+ * is `u1` on one call and `u3` on the next (poc/rt2-trim-interlock.mjs F1) — keying on it double-writes.
+ * Derived here from the unit's verbatim `_msgs` backing: the joined `tool_call_id`s for a tool turn (stable
+ * by construction), else a hash of `[role, content]` for a plain turn. The consumer namespaces it (e.g.
+ * `${taskId}:${key}`) and feeds it to `remember(id, …)`, which upserts → a replayed hop overwrites instead
+ * of duplicating. NOT a content search (litectx FTS can't match ids; sealed meta is unsearchable) — a
+ * deterministic key passed to the keyed write. The consumer's `taskId` prefix is the isolation boundary;
+ * treat the returned key as opaque (don't re-parse it).
+ *
+ * Two collision hardenings (grounded in poc/rt2-audit-grounding.mjs): ids are `encodeURIComponent`-escaped
+ * before the `,` join, so `['a','b']` and `['a,b']` can no longer alias the same key; and the plain-turn
+ * hash is **two near-independent streams** (FNV-1a + DJB2) → ~64-bit, so a long-running agent's harvest
+ * can't silently overwrite a turn via a 32-bit birthday collision (a single 32-bit FNV exhausted in ~5e5
+ * distinct turns). Normal provider ids (`call_…`) round-trip unchanged through the escape.
+ * @param {Record<string, any>} unit - a unit from {@link toUnits} (its `_msgs` backing is read).
+ * @returns {string}
+ */
+function harvestKey(unit) {
+  const back = (unit && unit._msgs) || [];
+  /** @type {string[]} */
+  const calls = [];
+  for (const m of back) {
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls)) for (const tc of m.tool_calls) if (tc && tc.id) calls.push(tc.id);
+  }
+  // escape so a literal ',' inside an id can't alias across call shapes ([{id:'a,b'}] vs [{id:'a'},{id:'b'}]).
+  if (calls.length) return `tc:${calls.map((id) => encodeURIComponent(id)).join(',')}`;
+  // plain turn (no tool_calls): two near-independent rolling hashes over role+content (FNV-1a + DJB2),
+  // concatenated to ~64 bits → collision-resistant at agent scale. Stable across toUnits calls.
+  let h1 = 0x811c9dc5; // FNV-1a offset basis
+  let h2 = 5381;       // DJB2 seed
+  const s = JSON.stringify(back.map((m) => [m.role, m.content]));
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    h1 ^= c; h1 = Math.imul(h1, 0x01000193);
+    h2 = (Math.imul(h2, 33) + c) | 0;
+  }
+  return `h:${(h1 >>> 0).toString(36)}${(h2 >>> 0).toString(36)}`;
+}
+
+/**
+ * Wrap litectx's `trim(units, policy)` verb (R-C5) into the Loop's destructive `trim(msgs, ctx)` seam —
+ * the RT-2 harvest-before-evict interlock. Unlike {@link unitAssembler} (a non-destructive per-round VIEW),
+ * this is EVICTION: the Loop replaces its canonical transcript with the returned (smaller) msgs, so old
+ * turns are permanently dropped — which is only safe because every dropped turn is harvested FIRST.
+ *
+ * The returned function `(msgs, ctx) => keptMsgs`:
+ *   1. `toUnits(msgs)` → `trim(units, policy)` → `{ units (kept), dropped, harvest }`.
+ *   2. **Interlock — harvest BEFORE evict:** `await onHarvest({ key, content, unit })` for every harvest
+ *      unit. If `onHarvest` throws (e.g. a write-gate `deny` → HaltError, or a store fault), this throws
+ *      BEFORE returning the evicted view → the Loop fail-opens (no eviction that round) → nothing is lost;
+ *      the next round retries and the idempotent key upserts the already-persisted ones. You cannot drop
+ *      history you have not persisted.
+ *   3. `fromUnits(kept)` is the bounded transcript. Fail-OPEN: an unrecognised `trim` return shape → the
+ *      original msgs unchanged (no eviction). A throw propagates (HaltError → governance halt).
+ *
+ * `.flush(msgs, ctx)` — the F2 residual harvest: `trim` only hands back EVICTED turns, so the final
+ * keepLastN window is never harvested mid-run and a clean run would diverge from an end-of-task batch.
+ * Call `.flush` on completion to harvest the surviving non-pinned turns (no eviction); the idempotent key
+ * means it never duplicates what eviction already harvested. The Loop invokes it only on **clean
+ * completion** — on a halt (e.g. bareguard `maxTurns`), `stop()`, or error exit the survivors stay intact
+ * in `result.msgs` but are NOT auto-flushed (auto-flushing a content-halt could re-trigger the deny that
+ * caused it); harvest `result.msgs` yourself on those exits if you need the final window persisted.
+ *
+ * `onHarvest` is the consumer's harvest POLICY point (litectx CE-PRD §6/R-W*: bareagent owns the trigger
+ * + what's worth keeping, litectx owns the mechanism + worklist). It is REQUIRED — the adapter structurally
+ * enforces harvest-before-evict; pass `async () => {}` to opt INTO lossy bounding.
+ *
+ * @param {{ trim?: Function, onHarvest?: Function, policy?: any }} [opts]
+ *   `trim` — litectx's `(units, policy) => { units, harvest }` verb (REQUIRED). `onHarvest` —
+ *   `({ key, content, unit }) => void|Promise` (REQUIRED; the harvest policy point). `policy` — litectx
+ *   TrimPolicy: `{ keepLastN }` or `{ maxTokens }` (maxTokens wins). Both verbs are runtime-checked.
+ * @returns {((msgs: Array<Record<string, any>>, ctx?: any) => Promise<Array<Record<string, any>>>) & { flush: (msgs: Array<Record<string, any>>, ctx?: any) => Promise<void> }}
+ */
+function unitTrimmer(opts) {
+  const { trim, onHarvest, policy = {} } = opts || {};
+  if (typeof trim !== 'function') throw new Error('[context-units] unitTrimmer({ trim }): trim must be litectx\'s (units, policy) => { units, harvest } verb');
+  if (typeof onHarvest !== 'function') throw new Error('[context-units] unitTrimmer({ onHarvest }): onHarvest is required (harvest-before-evict). Pass `async () => {}` to opt into lossy bounding.');
+
+  /** @type {any} */
+  const run = async (/** @type {Array<Record<string, any>>} */ msgs /*, ctx */) => {
+    const units = toUnits(msgs);
+    const r = await trim(units, policy);
+    const kept = r && Array.isArray(r.units) ? r.units : null;
+    if (!kept) return msgs; // fail-open: unrecognised return shape → no eviction
+    const harvest = r && Array.isArray(r.harvest) ? r.harvest : [];
+    for (const u of harvest) await onHarvest({ key: harvestKey(u), content: u.content, unit: u }); // BEFORE evict
+    return fromUnits(kept);
+  };
+
+  // F2 residual: harvest the surviving non-pinned turns (no eviction). pinned (system + first user) are
+  // reconstructable/anchor turns, never evicted by trim, so they're excluded here for symmetry.
+  run.flush = async (/** @type {Array<Record<string, any>>} */ msgs /*, ctx */) => {
+    for (const u of toUnits(msgs)) if (!u.pinned) await onHarvest({ key: harvestKey(u), content: u.content, unit: u });
+  };
+
+  return run;
+}
+
+module.exports = { toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey, approxTokens, pairingSeatbelt };

package/src/loop.d.ts

@@ -34,6 +34,16 @@ export type LoopOptions = {
      * summary tokens count against the budget.
      */
     assemble?: Function | undefined;
+    /**
+     * - async (msgs, ctx) => msgs. DESTRUCTIVE transcript-trim chokepoint (RT-2),
+     * the opposite of `assemble`: it BOUNDS the canonical transcript — the Loop replaces `msgs` with what
+     * this returns, evicting old turns AFTER they are harvested. Runs once per round before `assemble`.
+     * So eviction never drops un-persisted history, wire it via `unitTrimmer({ trim, onHarvest, policy })`
+     * (src/context-units.js), which performs the harvest-before-evict interlock over litectx's `trim` verb.
+     * An optional `.flush(msgs, ctx)` method is called on clean completion for the residual-window harvest.
+     * Fail-open (a trim fault degrades to no eviction that round); a thrown HaltError propagates.
+     */
+    trim?: Function | undefined;
     /**
      * - async (event) => void after each LLM call; forwards usage to
      * gate.record (via wireGate). `event.kind` discriminates the source: `'turn'` for a main-loop round,
@@ -69,6 +79,7 @@ export class Loop {
     store: import("../types").Store | null;
     policy: Function | null;
     assemble: Function | null;
+    trim: Function | null;
     onLlmResult: Function | null;
     onToolResult: Function | null;
     _stopped: boolean;

package/src/loop.js

@@ -37,6 +37,13 @@ const { ToolError, HaltError } = require('./errors');
  *   non-enumerable): assemble calls it to roll a summary window — bareagent makes the one model
  *   call, the consumer owns the trigger/N/splice. Its usage is forwarded to `onLlmResult` so the
  *   summary tokens count against the budget.
+ * @property {Function} [trim] - async (msgs, ctx) => msgs. DESTRUCTIVE transcript-trim chokepoint (RT-2),
+ *   the opposite of `assemble`: it BOUNDS the canonical transcript — the Loop replaces `msgs` with what
+ *   this returns, evicting old turns AFTER they are harvested. Runs once per round before `assemble`.
+ *   So eviction never drops un-persisted history, wire it via `unitTrimmer({ trim, onHarvest, policy })`
+ *   (src/context-units.js), which performs the harvest-before-evict interlock over litectx's `trim` verb.
+ *   An optional `.flush(msgs, ctx)` method is called on clean completion for the residual-window harvest.
+ *   Fail-open (a trim fault degrades to no eviction that round); a thrown HaltError propagates.
  * @property {Function} [onLlmResult] - async (event) => void after each LLM call; forwards usage to
  *   gate.record (via wireGate). `event.kind` discriminates the source: `'turn'` for a main-loop round,
  *   `'summarize'` for an out-of-band `ctx.summarize` call (R-C6). Both count against the budget.
@@ -181,6 +188,15 @@ class Loop {
       throw new Error('[Loop] options.assemble must be a function (msgs, info) => msgs');
     }
     this.assemble = options.assemble || null;
+    // RT-2: optional DESTRUCTIVE transcript-trim seam. Unlike `assemble` (a non-destructive view), `trim`
+    // bounds the canonical transcript — the Loop replaces `msgs` with what it returns, evicting old turns
+    // AFTER they've been harvested (the harvest-before-evict interlock lives in the trimmer; see
+    // src/context-units.js unitTrimmer). Opt-in: a Loop with no `trim` is unchanged. A `.flush` method on
+    // the function (if present) is called on clean completion for the F2 residual harvest.
+    if (options.trim != null && typeof options.trim !== 'function') {
+      throw new Error('[Loop] options.trim must be a function (msgs, ctx) => msgs (e.g. unitTrimmer({ trim, onHarvest, policy }))');
+    }
+    this.trim = options.trim || null;
     if (options.onLlmResult != null && typeof options.onLlmResult !== 'function') {
       throw new Error('[Loop] options.onLlmResult must be a function');
     }
@@ -351,6 +367,29 @@ class Loop {
     for (let round = 0; round < HARD_ROUND_LIMIT; round++) {
       if (this._stopped) break;
 
+      // RT-2: destructive transcript-trim chokepoint — bound the canonical transcript before assembling
+      // the window. Runs BEFORE assemble (trim shrinks canonical; assemble shapes the per-call view of
+      // what remains). The trimmer harvests every evicted turn BEFORE returning the smaller set, so this
+      // never drops un-persisted history. Mutate `msgs` IN PLACE (it's `const`, and result.msgs returns
+      // this same reference) → result.msgs becomes the bounded transcript; evicted turns live in the
+      // harvest store, restorable by id. Fail-OPEN: a trim fault degrades to no eviction this round (a
+      // context-bounding bug must not halt the agent); a HaltError (e.g. a write-gate deny during harvest)
+      // propagates as a clean governance exit — same contract as assemble/onLlmResult.
+      if (this.trim) {
+        try {
+          const before = msgs.length;
+          const kept = await this.trim(msgs, ctx);
+          if (Array.isArray(kept) && kept !== msgs) {
+            msgs.length = 0;
+            msgs.push(...kept);
+            if (msgs.length !== before) this._safeEmit({ type: 'loop:trim', data: { round, before, after: msgs.length } });
+          }
+        } catch (err) {
+          if (err instanceof HaltError) throw err;
+          this._reportError('trim', err, { round });
+        }
+      }
+
       // RT-1: context-assembly chokepoint. Let a caller (e.g. a context-engineering library) shape
       // the window sent to the provider this round. Returns a VIEW — the canonical `msgs` transcript
       // is never mutated, so result.msgs stays complete and correct. Fail-OPEN: an assembly error
@@ -412,6 +451,15 @@ class Loop {
         this._safeCall('onText', this.onText, result.text);
         this._safeEmit({ type: 'loop:done', data: { text: result.text, usage: lastUsage, cost: totalCost } });
         msgs.push({ role: 'assistant', content: result.text });
+        // RT-2 F2: residual harvest of the surviving window (incl. this final answer) on clean completion.
+        // `trim` only harvests EVICTED turns; without this, the never-evicted tail would diverge from an
+        // end-of-task batch. The trimmer's idempotent key means it never re-writes what eviction harvested.
+        // Fail-open / HaltError per the trim seam contract. No-op unless a `.flush`-capable trim is wired.
+        const flush = this.trim && /** @type {any} */ (this.trim).flush;
+        if (typeof flush === 'function') {
+          try { await flush(msgs, ctx); }
+          catch (err) { if (err instanceof HaltError) throw err; this._reportError('trim-flush', err, { round }); }
+        }
         return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, msgs };
       }
 

package/tools/spawn.d.ts

@@ -42,9 +42,16 @@ export type SpawnChildOptions = {
      */
     cliPath?: string | undefined;
     /**
-     * - Force-kill child after this many ms.
+     * - Force-kill child after this many ms (wall-clock hard ceiling).
      */
     timeoutMs?: number | undefined;
+    /**
+     * - Force-kill child after this many ms with NO output on either
+     * stdout or stderr (heartbeat/liveness watchdog). The clock arms at spawn and resets on every JSONL
+     * line, so a child doing real work is never killed, but one that hangs silently is. Opt-in
+     * (0/undefined disables); independent of `timeoutMs`, which remains the absolute ceiling.
+     */
+    idleTimeoutMs?: number | undefined;
     /**
      * - bareagent Stream — child:stderr events get re-emitted here.
      */
@@ -56,13 +63,16 @@ export type Stream = import("../src/stream").Stream;
  *
  * @param {object} [options]
  * @param {string} [options.cliPath] - Override the bareagent CLI path (default: ./bin/cli.js relative to this file).
- * @param {number} [options.timeoutMs] - Force-kill child after this many ms (default 10 min).
+ * @param {number} [options.timeoutMs] - Force-kill child after this many ms (default 10 min, wall-clock ceiling).
+ * @param {number} [options.idleTimeoutMs] - Force-kill child after this many ms of no stdout/stderr output
+ *   (heartbeat watchdog; default off). Resets on every line, so slow-but-working children survive.
  * @param {Stream} [options.stream] - bareagent Stream instance — child:stderr events get re-emitted here.
  * @returns {{tool: import('../types').ToolDef, spawnChild: typeof spawnChild}}
  */
 export function createSpawnTool(options?: {
     cliPath?: string | undefined;
     timeoutMs?: number | undefined;
+    idleTimeoutMs?: number | undefined;
     stream?: import("../src/stream").Stream | undefined;
 }): {
     tool: import("../types").ToolDef;
@@ -86,12 +96,16 @@ export function createSpawnTool(options?: {
  * @property {string} [config] - Path to a bareagent config JSON file.
  * @property {*} [input] - Optional JSON input passed to the child on stdin.
  * @property {string} [cliPath] - Override the bareagent CLI path.
- * @property {number} [timeoutMs] - Force-kill child after this many ms.
+ * @property {number} [timeoutMs] - Force-kill child after this many ms (wall-clock hard ceiling).
+ * @property {number} [idleTimeoutMs] - Force-kill child after this many ms with NO output on either
+ *   stdout or stderr (heartbeat/liveness watchdog). The clock arms at spawn and resets on every JSONL
+ *   line, so a child doing real work is never killed, but one that hangs silently is. Opt-in
+ *   (0/undefined disables); independent of `timeoutMs`, which remains the absolute ceiling.
  * @property {Stream} [stream] - bareagent Stream — child:stderr events get re-emitted here.
  *
  * @param {SpawnChildOptions} [opts]
  */
-export function spawnChild({ config, input, cliPath, timeoutMs, stream }?: SpawnChildOptions): {
+export function spawnChild({ config, input, cliPath, timeoutMs, idleTimeoutMs, stream }?: SpawnChildOptions): {
     wait: () => Promise<{
         text: any;
         usage: any;
@@ -100,6 +114,7 @@ export function spawnChild({ config, input, cliPath, timeoutMs, stream }?: Spawn
         events: ChildEvent[];
         exitCode: any;
         signal: any;
+        idleKilled: boolean;
     }>;
     onLine: (fn: (event: ChildEvent) => void) => () => void;
     kill: (sig?: NodeJS.Signals) => void;

package/tools/spawn.js

@@ -66,12 +66,16 @@ function resolveCliPath() {
  * @property {string} [config] - Path to a bareagent config JSON file.
  * @property {*} [input] - Optional JSON input passed to the child on stdin.
  * @property {string} [cliPath] - Override the bareagent CLI path.
- * @property {number} [timeoutMs] - Force-kill child after this many ms.
+ * @property {number} [timeoutMs] - Force-kill child after this many ms (wall-clock hard ceiling).
+ * @property {number} [idleTimeoutMs] - Force-kill child after this many ms with NO output on either
+ *   stdout or stderr (heartbeat/liveness watchdog). The clock arms at spawn and resets on every JSONL
+ *   line, so a child doing real work is never killed, but one that hangs silently is. Opt-in
+ *   (0/undefined disables); independent of `timeoutMs`, which remains the absolute ceiling.
  * @property {Stream} [stream] - bareagent Stream — child:stderr events get re-emitted here.
  *
  * @param {SpawnChildOptions} [opts]
  */
-function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
+function spawnChild({ config, input, cliPath, timeoutMs, idleTimeoutMs, stream } = {}) {
   if (typeof config !== 'string' || !config) {
     throw new Error('[spawn] requires { config: <path> }');
   }
@@ -104,10 +108,29 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
     if (i >= 0) lineSubscribers.splice(i, 1);
   }; };
 
+  // Idle watchdog: kill the child after `idleTimeoutMs` of silence on BOTH stdio streams.
+  // Distinct from `timeoutMs` (wall-clock ceiling): this catches a child that is alive but stuck
+  // producing nothing — the "no activity in stderr" hang — without punishing one doing slow work,
+  // since `armIdle()` resets on every line. Armed at spawn so a child that never emits is caught too.
+  let idleTimer = null;
+  let idleKilled = false;
+  const armIdle = () => {
+    if (!idleTimeoutMs || idleTimeoutMs <= 0) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      idleKilled = true;
+      try { child.kill('SIGTERM'); } catch { /* already dead */ }
+      setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* already dead */ } }, 5000).unref();
+    }, idleTimeoutMs);
+    idleTimer.unref();
+  };
+  armIdle();
+
   // stdout — JSONL events from the child loop
   const outRl = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
   outRl.on('line', (line) => {
     if (!line) return;
+    armIdle();
     let event;
     try { event = JSON.parse(line); }
     catch {
@@ -130,6 +153,7 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
   const errRl = readline.createInterface({ input: child.stderr, crlfDelay: Infinity });
   errRl.on('line', (line) => {
     if (!line) return;
+    armIdle();
     const event = { type: 'child:stderr', text: line, ts: new Date().toISOString() };
     events.push(event);
     if (stream) {
@@ -157,18 +181,20 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
   const exitPromise = new Promise((resolve) => {
     child.on('exit', async (code, signal) => {
       if (killTimer) clearTimeout(killTimer);
+      if (idleTimer) clearTimeout(idleTimer);
       // Drain stdio readlines before resolving — last line may still be in buffer.
       await Promise.all([outClosePromise, errClosePromise]);
-      resolve({ code, signal });
+      resolve({ code, signal, idleKilled });
     });
     child.on('error', (err) => {
       if (killTimer) clearTimeout(killTimer);
+      if (idleTimer) clearTimeout(idleTimer);
       resolve({ code: null, signal: null, spawnError: err });
     });
   });
 
   async function wait() {
-    const { code, signal, spawnError } = await exitPromise;
+    const { code, signal, spawnError, idleKilled: idle } = await exitPromise;
     if (spawnError) {
       return {
         text: '',
@@ -178,6 +204,7 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
         events,
         exitCode: null,
         signal: null,
+        idleKilled: false,
       };
     }
     // Pluck the final loop:done event — that's the canonical child result.
@@ -194,18 +221,21 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
         events,
         exitCode: code,
         signal,
+        idleKilled: !!idle,
       };
     }
     // No loop:done — child exited abnormally or never reached the LLM.
     const errEvent = events.find(e => e.type === 'loop:error' || e.type === 'error');
+    const idleNote = idle ? `[spawn] child killed after idle timeout (no output; signal=${signal})` : null;
     return {
       text: '',
       usage: { inputTokens: 0, outputTokens: 0 },
       cost: 0,
-      error: errEvent?.data?.error || `[spawn] child exited (code=${code}, signal=${signal}) without loop:done`,
+      error: idleNote || errEvent?.data?.error || `[spawn] child exited (code=${code}, signal=${signal}) without loop:done`,
       events,
       exitCode: code,
       signal,
+      idleKilled: !!idle,
     };
   }
 
@@ -222,7 +252,9 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
  *
  * @param {object} [options]
  * @param {string} [options.cliPath] - Override the bareagent CLI path (default: ./bin/cli.js relative to this file).
- * @param {number} [options.timeoutMs] - Force-kill child after this many ms (default 10 min).
+ * @param {number} [options.timeoutMs] - Force-kill child after this many ms (default 10 min, wall-clock ceiling).
+ * @param {number} [options.idleTimeoutMs] - Force-kill child after this many ms of no stdout/stderr output
+ *   (heartbeat watchdog; default off). Resets on every line, so slow-but-working children survive.
  * @param {Stream} [options.stream] - bareagent Stream instance — child:stderr events get re-emitted here.
  * @returns {{tool: import('../types').ToolDef, spawnChild: typeof spawnChild}}
  */
@@ -250,6 +282,7 @@ function createSpawnTool(options = {}) {
         input,
         cliPath: options.cliPath,
         timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        idleTimeoutMs: options.idleTimeoutMs,
         stream: options.stream,
       });
       return await handle.wait();