bare-agent 0.32.0 → 0.33.0

package/README.md

@@ -121,7 +121,7 @@ console.log(result.count, result.matchedIds);   // a code-derived count + the id
 
 **Govern — one gate over both axes.** `wireGate(gate)` routes every LLM + tool call through one bareguard policy + audit + budget. Denied tools never reach the model; halts (turn / budget / content caps) exit cleanly. A plain deny stays advisory (the model can pivot to an allowed tool), but the Loop short-circuits a *spin* — `maxConsecutiveDenials` consecutive denials of the same action (default 3) stop the run with `error:'denied:<tool>'` instead of burning the budget to the cap; under `recurse` that surfaces as `{ incomplete, blocker:'governance-deny' }`. The same bound covers a tool that keeps *failing*: `maxIdenticalToolErrors` (default 3) stops a model re-sending a byte-identical call that cannot succeed, with `error:'stuck:<tool>'`. `require('bare-agent/bareguard')`
 
-**Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Gemini (native), Ollama, CLIPipe, Fallback — or bring your own (one `generate` method). All return the same shape; swap freely. Usage including prompt-cache tiers is normalized, so `result.metrics` reports honest cumulative tokens + cost — and `null`, never a silent `0`, for a model it couldn't price. A model that rejects a non-default `temperature` (e.g. `claude-sonnet-5`, OpenAI o1/gpt-5-class return a `400`) is handled gracefully — the provider drops the param and retries once rather than failing the call, surfacing `temperatureDropped` so a caller can report the effective value. **CLIPipe can drive a full agentic Loop — tools and turns — over a CLI *subscription* instead of the metered API** (`CLIPipeProvider({ command:'claude', args:['-p','--model','sonnet'], toolProtocol:'claude' })`): schema-validated tool emulation with the Loop keeping governance, and a capable model enforced upfront (v0.32.0, sonnet-class+ for tools; Claude CLI for now).
+**Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Gemini (native), Ollama, CLIPipe, Fallback — or bring your own (one `generate` method). All return the same shape; swap freely. Usage including prompt-cache tiers is normalized, so `result.metrics` reports honest cumulative tokens + cost — and `null`, never a silent `0`, for a model it couldn't price. A model that rejects a non-default `temperature` (e.g. `claude-sonnet-5`, OpenAI o1/gpt-5-class return a `400`) is handled gracefully — the provider drops the param and retries once rather than failing the call, surfacing `temperatureDropped` so a caller can report the effective value. **CLIPipe can drive a full agentic Loop — tools and turns — over a CLI *subscription* instead of the metered API.** Two modes, chosen by cost: `toolProtocol:'claude-mcp'` (v0.33.0, NATIVE — the CLI runs its own session and calls your tools over an MCP bridge; the gate, spin guards, and turn bound ride the provider, and it caches session-side — ~$0.006/turn) is the default for the Claude CLI, while `toolProtocol:'claude'` (v0.32.0, schema-validated emulation with the Loop keeping the cycle) stays right for a CLI with no MCP channel. A capable model is enforced upfront (sonnet-class+ for tools; Claude CLI for now).
 
 **The run tells you the truth about what happened on the wire.** Every provider reports **why** generation ended (`stopReason`, normalized across all of them and surfaced on **every** `Loop.run()` return), so a round the API **cut off at the token cap** can no longer masquerade as a finished answer: it returns `error: 'truncated:max_tokens'` with the partial text preserved, instead of a silent `error: null` (BA-6). Its tool calls are **refused, never executed** — a *complete* tool call always arrives tagged `tool_use`, so one riding a truncated round was cut off mid-generation with arguments missing, which is exactly how a truncated `shell_write` can zero a file. The same honesty now covers **every** non-clean terminal signal (BA-13): a safety `refusal` returns `error: 'refusal'` and a blown context window returns `error: 'context_exceeded'` (both were previously laundered into an empty success), while a resumable `pause_turn` makes the loop resume rather than terminate. `error` is the sole success signal; a bound firing preserves the model's work rather than discarding it (BA-5).
 

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.32.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
+> v0.33.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -60,7 +60,8 @@ Eight entry points:
 | Cache identical planner calls | Planner({ cacheTTL: 60000 }) |
 | Stream CLIPipe output in real-time | CLIPipeProvider({ onChunk: fn }) |
 | Get real usage + cost from a CLI provider | CLIPipeProvider({ parse: 'claude-json' }) |
-| Drive tools over a CLI subscription (no metered API) | CLIPipeProvider({ toolProtocol: 'claude' }) |
+| Drive tools over a CLI subscription — NATIVE, cheapest (no metered API) | CLIPipeProvider({ toolProtocol: 'claude-mcp', policy }) |
+| Drive tools over a CLI with no MCP support (emulation) | CLIPipeProvider({ toolProtocol: 'claude' }) |
 | Browse the web (inline snapshots) | createBrowsingTools + Loop |
 | Browse the web (token-efficient, disk-based) | `barebrowse` CLI session — snapshots to `.barebrowse/*.yml` |
 | Assess website privacy risk | createBrowsingTools + Loop (requires `npm install wearehere`) |
@@ -801,14 +802,27 @@ new CLIPipe({ command: 'claude', args: ['--print'], systemPromptFlag: '--system-
 new CLIPipe({ command: 'ollama', args: ['run', 'llama3.2'] })
 // CLIPipe structured output (v0.26.0+) — map a CLI's JSON envelope to real usage + cost
 new CLIPipe({ command: 'claude', args: ['-p', '--output-format', 'json'], parse: 'claude-json' })
-// CLIPipe TOOL MODE (v0.32.0+) — drive a Loop's tools over a CLI SUBSCRIPTION (no metered API).
-// toolProtocol enables schema-validated tool emulation; the Loop keeps governance/round-accounting.
-// Tools are auto-used when passed; a weak model (e.g. haiku) is rejected UPFRONT by a capability
-// probe (needs sonnet-class+ for tools; haiku is fine for plain text). setting-sources '' is applied
-// internally for an ~18x cost drop. Claude-only for now.
+// CLIPipe TOOL MODE — drive a Loop's tools over a CLI SUBSCRIPTION (no metered API). TWO modes:
+// 'claude-mcp' (BA-16, NATIVE — prefer on the claude CLI) vs 'claude' (v0.32.0, EMULATION). The
+// difference is COST, not capability. Emulation re-sends the whole transcript every round
+// ($0.25-0.55/round measured); native runs one CLI session that caches session-side (~$0.006/turn).
+// Native: caller tools ride an MCP bridge back to your in-process closures; the CLI owns the cycle.
+// Gate + BA-11/BA-12 guards + turn bound live on the PROVIDER (not the Loop) — see below.
+new CLIPipe({ command: 'claude', args: ['-p', '--model', 'sonnet'], toolProtocol: 'claude-mcp', policy, onTurn, maxTurns: 20 })
+// Emulation (v0.32.0) — still right for a CLI with NO MCP support. Weak models rejected upfront by a
+// capability probe (needs sonnet-class+; haiku fine for plain text). setting-sources '' cuts ~18x cost.
 new CLIPipe({ command: 'claude', args: ['-p', '--model', 'sonnet'], toolProtocol: 'claude' })
 ```
 
+**CLIPipe NATIVE tool mode (BA-16, `toolProtocol:'claude-mcp'`).** The claude CLI has a real tool channel; native mode uses it instead of emulating one. The CLI runs its OWN multi-turn session per `generate()` call and executes your `tools` natively over an MCP bridge that calls back into your in-process `execute` closures. Because the CLI owns the inner cycle, the Loop's per-round machinery cannot run — so the governance you'd wire on `Loop` moves to the **provider**, at the one seam every tool call crosses:
+- `policy` — the SAME `(tool, args, ctx) => true|string` chokepoint as `Loop({policy})`, so a wired `wireGate(gate).policy` writes **audit rows of identical shape, zero gate changes**. A deny is a tool result (advisory); the handler never runs. **Required here** — a `Loop({policy})` in native mode would be a fence that is silently not there, so the Loop throws.
+- `maxConsecutiveDenials` (3) / `maxIdenticalToolErrors` (3) — BA-11/BA-12 guards at the bridge, same narrowest triggers; end the session `denied:<tool>` / `stuck:<tool>`.
+- `maxTurns` — maps to the CLI's `--max-turns`; the bound stop is `error:'max_turns'`, never a silent success.
+- `onTurn` — streams each completed turn's usage (four cache tiers, `costUsd:null` — the CLI prices the session) as it arrives, then one closing `kind:'session'` event with the authoritative total. Shape mirrors `onLlmResult`, so `wireGate(gate).onLlmResult` drops in; when wired the Loop skips its own forward (billed once, never starved).
+- `sessionTimeout` (600s) / `bridgeTimeoutMs` (120s) — whole-session and per-handler ceilings.
+
+`GenerateResult.session` (`{turns, toolCalls, error, usageReported}`) carries what really happened; `metrics.sessionTurns` reports the real turn count so a 14-turn session never reads as one round. A terminal the CLI detects inside the session (bound, guard, or a **broken tool bridge** — a dead bridge still ends `subtype:'success'`, so it is caught parent-side by attempted-vs-served tool calls) surfaces as the run's `error`, never a laundered clean finish. `assemble`/`trim`/`cacheMessages` and a Loop-level `policy` all THROW at construction in native mode (no silently-dead knobs — the CLI owns the transcript). The bridge is a unix socket (0600 in a 0700 dir), never a listening port. Claude-only for now; the CLI-specific parts live in `src/provider-clipipe-mcp.js` + `src/mcp-bridge-stub.js` behind the same seam as emulation.
+
 All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model?, costUsd? }`. The optional `model` (v0.16.1+) is the id the response was produced by — Loop prefers it over `provider.model` for cost accounting. By default CLIPipe returns `toolCalls: []` and zero usage (CLI tools don't report tokens) and omits `model`. **Structured output (v0.26.0+):** set `parse: 'claude-json'` (a preset for `claude -p --output-format json`) — or a `(stdout) => Partial<GenerateResult>` function for any other CLI — and CLIPipe maps the CLI's JSON envelope onto real `usage`, `model`, and `costUsd`, throwing `ProviderError` on a malformed/error envelope (never a silent raw-text fall-back). `costUsd` (optional `GenerateResult` field) is an **authoritative** per-call price the provider reports itself; when finite the Loop prefers it over the internal rate-table `estimateCost`, so a CLI-piped run enforces a bareguard USD cap with no local pricing table (a `0` counts as priced, distinct from null/unpriced). `toolCalls` stays `[]` regardless (CLIPipe is tool-free).
 
 **Temperature graceful degradation (BA-10).** Newer models reject ANY non-default `temperature` with a `400` (`claude-sonnet-5`: `` `temperature` is deprecated for this model. ``; OpenAI o1/gpt-5-class: `Unsupported value: 'temperature' … Only the default (1) …`). All four providers detect that specific 400 (message names `temperature` as unsupported/deprecated AND a temperature was sent), **drop the param, warn once per instance, and retry once** — so a call that would otherwise throw succeeds at the model's default temperature. Keyed off the API error text, not a model list. A genuine out-of-range 400 is NOT degraded (it re-throws — dropping it would mask a caller bug). When a drop happens the result carries `temperatureDropped: true` (an optional `GenerateResult`/`Loop.run` field) so a caller can report the effective temperature — `recurse`'s `refineLeaf` uses it for an honest receipt. Dormant on models that accept temperature (byte-identical to before).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "files": [
     "index.js",
     "index.d.ts",

package/src/loop.js

@@ -277,6 +277,30 @@ class Loop {
       throw new Error('[Loop] options.trim must be a function (msgs, ctx) => msgs (e.g. unitTrimmer({ trim, onHarvest, policy }))');
     }
     this.trim = options.trim || null;
+    // BA-16: a CYCLE-OWNING provider (one that runs its own multi-turn session internally, e.g.
+    // CLIPipe native tool mode) has no per-round seam for the Loop to hand a transcript to — the
+    // transcript lives inside the provider's session. `assemble`/`trim` would therefore be accepted
+    // and then silently never called, which is precisely the "silently-dead knob" shape this repo
+    // keeps paying for. Fail at CONSTRUCTION instead: an unhonorable option is a configuration
+    // error, not a no-op.
+    if (this.provider && this.provider.ownsCycle && (this.assemble || this.trim)) {
+      const named = [this.assemble && 'assemble', this.trim && 'trim'].filter(Boolean).join(' and ');
+      throw new Error(
+        `[Loop] provider '${this.provider.name || 'unknown'}' owns its own turn cycle, so ${named} can never run `
+        + '(the provider owns the transcript, not the Loop). Remove the option, or use a provider whose cycle the Loop drives.',
+      );
+    }
+    // The same rule, applied to the option where being silently dead is WORST. With a cycle-owning
+    // provider no tool call ever reaches the Loop, so a `Loop({policy})` is a fence that is simply
+    // not there — the run looks governed and is not. Refuse it: the gate must be wired on the
+    // provider, where every tool call actually crosses.
+    if (this.provider && this.provider.ownsCycle && this.policy && !this.provider.policy) {
+      throw new Error(
+        `[Loop] provider '${this.provider.name || 'unknown'}' owns its own turn cycle, so Loop-level policy would `
+        + 'NEVER run — no tool call reaches the Loop. Wire the gate on the provider instead '
+        + '(e.g. new CLIPipeProvider({ toolProtocol: \'claude-mcp\', policy })).',
+      );
+    }
     if (options.onLlmResult != null && typeof options.onLlmResult !== 'function') {
       throw new Error('[Loop] options.onLlmResult must be a function');
     }
@@ -491,6 +515,12 @@ class Loop {
     const metrics = {
       turns: 0,
       toolCalls: 0,
+      // BA-16 — turns that happened INSIDE a cycle-owning provider's own session (CLIPipe native tool
+      // mode). Such a session is ONE Loop round no matter how many turns it really took, so `turns`
+      // alone would report a 14-turn session as 1 — a round count that reads far cheaper and far
+      // shorter than the run actually was. Reporting the real number keeps the meter honest; 0 for
+      // every provider whose cycle the Loop drives.
+      sessionTurns: 0,
       /** @type {Record<string, number>} */
       byTool: {},
       tokens: { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 },
@@ -525,6 +555,7 @@ class Loop {
     /** Snapshot the meter for a return — finalizes the run-scoped fields. @returns {RunMetrics} */
     const finalizeMetrics = () => ({
       turns: metrics.turns,
+      sessionTurns: metrics.sessionTurns,
       toolCalls: metrics.toolCalls,
       byTool: metrics.byTool,
       tokens: { ...metrics.tokens },
@@ -742,11 +773,22 @@ class Loop {
       metrics.turns++;
       addUsage(result.usage);
       if (roundCost === null) metrics.unpricedRounds++; else pricedAny = true;
+      // BA-16: a cycle-owning provider reports what really happened inside its session.
+      const session = (result.session && typeof result.session === 'object') ? result.session : null;
+      if (session) {
+        if (Number.isFinite(session.turns)) metrics.sessionTurns += session.turns;
+        if (Number.isFinite(session.toolCalls)) metrics.toolCalls += session.toolCalls;
+      }
 
       // BA1: forward LLM usage to gate.record (via wireGate) so budget.maxCostUsd
       // covers token-heavy / tool-light workloads. Callback errors route through
       // _reportError but never kill the loop — governance failure ≠ run failure.
-      if (this.onLlmResult) {
+      // BA-16: when a cycle-owning provider has ALREADY streamed this call's usage per internal turn
+      // (so a session that dies mid-run has surfaced every completed turn's spend rather than losing
+      // all of it), forwarding the summed total here too would bill the gate twice for one session.
+      // The provider only sets this when it genuinely reported; unwired, it stays false and the
+      // normal forward below runs — so the gate is never silently starved either.
+      if (this.onLlmResult && !(session && session.usageReported === true)) {
         try {
           await this.onLlmResult({
             model,
@@ -766,6 +808,20 @@ class Loop {
         }
       }
 
+      // BA-16: a cycle-owning provider detected a terminal INSIDE its own session — a turn bound, a
+      // guard streak, or a broken tool bridge. It is reported as the run's `error` (never merely
+      // surfaced) because every downstream consumer — `recurse`, the bareloop adopter — branches on
+      // `error` as the SOLE success signal. Surfacing alone would let a session in which no tool call
+      // ever succeeded propagate as converged. `lastText` (BA-5) preserves the partial work: a bound
+      // firing is normal termination for a bounded attempt, and that text is the only channel from
+      // attempt N to N+1.
+      if (session && typeof session.error === 'string' && session.error) {
+        sealDanglingToolCalls(msgs, `[halted:${session.error}]`);
+        this._reportError('session', new Error(`provider session terminated: ${session.error}`), { rule: session.error, sessionTurns: session.turns ?? null });
+        this._safeEmit({ type: 'loop:done', data: { text: lastText, rule: session.error, sessionTurns: session.turns ?? null, cost: totalCost } });
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: session.error, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+      }
+
       // BA-13: classify this round's terminal signal against the neutral stop-reason vocabulary. BA-6
       // short-circuited exactly one non-clean reason (max_tokens); this gate is the general form. It sits
       // AFTER metering (the tokens were really spent — the gate must see them) and BEFORE tool execution,

package/src/mcp-bridge-stub.d.ts

@@ -0,0 +1 @@
+export {};

package/src/mcp-bridge-stub.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * BA-16 — the MCP stdio server the CLI spawns in native tool mode (`toolProtocol:'claude-mcp'`).
+ *
+ * This file owns NO tool logic. bare-agent's tools are `execute` CLOSURES living in the caller's
+ * process, but `--mcp-config` can only point the CLI at a COMMAND — so the tool surface has to cross
+ * a process boundary that the closures cannot. This stub is the bridge for exactly that hop:
+ *
+ *   claude CLI  <--stdio JSON-RPC-->  THIS FILE  <--unix socket-->  parent (caller's closures)
+ *
+ * It is deliberately dumb. Everything that can decide anything — the manifest, the gate, the spin
+ * guards, redaction — lives parent-side, so the stub can never become a second place where policy
+ * is enforced (and never a second place where a secret can be logged: it writes no files at all).
+ *
+ * The one rule it does enforce is the BA-15 principle at the process boundary: EVERY failure of the
+ * hop is returned as a tool RESULT, never as a crash and never as a hang. A dead parent, a malformed
+ * frame and a slow handler all become `isError` results the model can read and react to — validated
+ * live before this shipped (probe 6: parent killed mid-call, session ended in 5.9s, no hang).
+ *
+ * Not a package export and never `require`d by the library — it is spawned as `node <this file>`.
+ */
+
+const { createInterface } = require('readline');
+const net = require('net');
+
+const SOCK = process.env.BAREAGENT_BRIDGE_SOCK;
+const CALL_TIMEOUT_MS = Number(process.env.BAREAGENT_BRIDGE_TIMEOUT_MS) || 120000;
+
+const send = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
+const errResult = (text) => ({ content: [{ type: 'text', text }], isError: true });
+
+/**
+ * One request/response over the unix socket.
+ *
+ * A FRESH connection per call is deliberate: a pooled socket opened while the parent was alive
+ * hides a parent that died later, turning "the bridge is gone" into a silent hang. Connecting per
+ * call makes a dead parent surface immediately, as an error result.
+ *
+ * @param {object} payload
+ * @returns {Promise<any>} always resolves — never rejects, so no failure can escape as a crash.
+ */
+function bridge(payload) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    if (!SOCK) return done({ error: 'bridge not configured' });
+
+    const sock = net.createConnection(SOCK);
+    let buf = '';
+
+    // A hung parent handler must not hang the CLI session. Bounded, always.
+    const timer = setTimeout(() => {
+      try { sock.destroy(); } catch (_) { /* already gone */ }
+      done({ error: `bridge timeout after ${CALL_TIMEOUT_MS}ms` });
+    }, CALL_TIMEOUT_MS);
+
+    const finish = (v) => {
+      clearTimeout(timer);
+      try { sock.end(); } catch (_) { /* already gone */ }
+      done(v);
+    };
+
+    sock.on('connect', () => sock.write(JSON.stringify(payload) + '\n'));
+    sock.on('data', (d) => {
+      buf += d;
+      const nl = buf.indexOf('\n');
+      if (nl === -1) return; // frame incomplete — wait for the rest
+      try { finish(JSON.parse(buf.slice(0, nl))); }
+      catch (err) { finish({ error: `bridge sent malformed JSON: ${/** @type {Error} */ (err).message}` }); }
+    });
+    sock.on('error', (err) => finish({ error: `bridge unreachable: ${/** @type {any} */ (err).code || /** @type {Error} */ (err).message}` }));
+    sock.on('close', () => finish({ error: 'bridge closed before responding' }));
+  });
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on('line', async (line) => {
+  if (!line.trim()) return;
+  let msg;
+  try { msg = JSON.parse(line); } catch (_) { return; } // not JSON — not ours to answer
+  const { id, method, params } = msg;
+
+  if (method === 'initialize') {
+    return send({ jsonrpc: '2.0', id, result: {
+      protocolVersion: (params && params.protocolVersion) || '2025-06-18',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'bareagent', version: '1' },
+    } });
+  }
+
+  if (method === 'tools/list') {
+    // The PARENT owns the manifest — a tool definition is never duplicated here.
+    const res = await bridge({ op: 'list' });
+    return send({ jsonrpc: '2.0', id, result: { tools: (res && res.tools) || [] } });
+  }
+
+  if (method === 'tools/call') {
+    const res = await bridge({ op: 'call', name: params && params.name, args: (params && params.arguments) || {} });
+    if (res && res.error) return send({ jsonrpc: '2.0', id, result: errResult(`TOOL BRIDGE ERROR: ${res.error}`) });
+    if (res && res.isError) return send({ jsonrpc: '2.0', id, result: errResult(String(res.text)) });
+    return send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: String((res && res.text) ?? '') }] } });
+  }
+
+  if (method === 'ping') return send({ jsonrpc: '2.0', id, result: {} });
+  if (id !== undefined) send({ jsonrpc: '2.0', id, error: { code: -32601, message: `method not found: ${method}` } });
+});

package/src/provider-clipipe-mcp.d.ts

@@ -0,0 +1,128 @@
+/** Path to the stdio stub the CLI spawns. Resolved once — it ships inside the package. */
+export const STUB_PATH: string;
+/** The MCP server name the CLI sees; tool names reach the model as `mcp__bareagent__<tool>`. */
+export const SERVER_NAME: "bareagent";
+/** Mirrors the Loop's own BA-11 / BA-12 defaults so native mode is not quietly laxer. */
+export const DEFAULT_MAX_CONSECUTIVE_DENIALS: 3;
+export const DEFAULT_MAX_IDENTICAL_TOOL_ERRORS: 3;
+/**
+ * Stable key for BA-12's identical-tool-error guard. NARROWEST trigger by design: only a
+ * BYTE-IDENTICAL repeat counts. Counting any consecutive failure was measured to punish the
+ * recovery it exists to protect (a model varying args while working through an ENOENT).
+ * @param {string} name
+ * @param {any} args
+ * @returns {string}
+ */
+export function toolErrorKey(name: string, args: any): string;
+/**
+ * Clamp a diagnostic built from a thrown value of unknown shape before it can ride into a
+ * `receipts`/audit string. A non-Error throw serialized wholesale has previously pushed a secret
+ * into a plaintext audit log (the F16/BA-1 capture class), and an append-only log that captures a
+ * key captures it forever. Conventional fields only, hard length cap, never the whole object.
+ * @param {any} err
+ * @returns {string}
+ */
+export function safeErrorText(err: any): string;
+/**
+ * The parent-side bridge: a unix-socket server backed by the caller's in-process tool closures,
+ * with the gate and both spin guards wired at the one seam that sees every call.
+ *
+ * Unix socket, not loopback TCP: a library must not open a listening network port as a side effect
+ * of running a tool loop. The socket lives in a 0700 directory and is itself chmod 0600.
+ *
+ * @param {object} opts
+ * @param {import('../types').ToolDef[]} opts.tools - the caller's tools (with live `execute` closures).
+ * @param {Function|null} [opts.policy] - the SAME contract as `Loop({policy})`: only `true` allows;
+ *   a string is the deny reason fed back verbatim.
+ * @param {any} [opts.ctx] - opaque governance ctx, forwarded to `policy` unchanged.
+ * @param {number} [opts.maxConsecutiveDenials]
+ * @param {number} [opts.maxIdenticalToolErrors]
+ * @returns {Promise<{sockPath: string, state: any, close: () => void}>}
+ */
+export function createBridge({ tools, policy, ctx, maxConsecutiveDenials, maxIdenticalToolErrors }: {
+    tools: import("../types").ToolDef[];
+    policy?: Function | null | undefined;
+    ctx?: any;
+    maxConsecutiveDenials?: number | undefined;
+    maxIdenticalToolErrors?: number | undefined;
+}): Promise<{
+    sockPath: string;
+    state: any;
+    close: () => void;
+}>;
+/**
+ * @param {string|null|undefined} subtype
+ * @returns {{stopReason: string|null, error: string|null}}
+ */
+export function classifySubtype(subtype: string | null | undefined): {
+    stopReason: string | null;
+    error: string | null;
+};
+/**
+ * Decide the session's terminal tag. Pure, so the precedence is testable without a live CLI.
+ *
+ * The ordering is the whole point:
+ *   1. `terminal`   — a guard tripped and WE killed the session; most specific, and it explains why
+ *                     the CLI's own subtype is missing or odd.
+ *   2. bridge broken — a tool call the CLI ATTEMPTED but the bridge never SERVED never reached the
+ *                     caller's closure. This must outrank a reported `success`, because a session
+ *                     whose tools were all broken still ends `subtype:'success'` — the model writes
+ *                     a tidy final answer explaining that its tools failed, and mapping that onto
+ *                     `error:null` reports a run in which nothing worked as converged.
+ *   3. `timedOut`   — we killed it on the wall clock.
+ *   4. the subtype  — what the CLI itself said.
+ *
+ * @param {{terminal: string|null, bridgeDown: boolean, attempted: number, served: number, timedOut: boolean, subtype: string|null|undefined}} facts
+ * @returns {{stopReason: string|null, error: string|null}}
+ */
+export function resolveSessionError(facts: {
+    terminal: string | null;
+    bridgeDown: boolean;
+    attempted: number;
+    served: number;
+    timedOut: boolean;
+    subtype: string | null | undefined;
+}): {
+    stopReason: string | null;
+    error: string | null;
+};
+/**
+ * Line-oriented processor for the CLI's `stream-json` stdout.
+ *
+ * FRAMING IS SYNCHRONOUS. The obvious shape — an `async` stdout handler that `await`s `onTurn`
+ * inside its parse loop — has a data-corruption bug: while the `await` is suspended, the next
+ * `'data'` event re-enters the handler and mutates the SHARED line buffer, so the suspended parse
+ * resumes against a buffer that moved under it (dropped/duplicated/mangled lines). It is invisible
+ * with a synchronous `onTurn` (the await resolves on the microtask queue before the next macrotask
+ * `'data'` event) and REACHABLE the moment `onTurn` does real async work — e.g. a wired gate's
+ * `gate.record`, which is exactly the intended consumer. So framing never awaits: it parses lines
+ * synchronously and pushes per-turn forwards onto a queue that a SERIAL async drainer empties in
+ * arrival order. Extracted from `runSession` so this can be unit-tested without spawning the CLI.
+ *
+ * @param {object} o
+ * @param {Function|null} o.onTurn
+ * @param {any} o.ctx
+ * @param {number} o.startedAt
+ * @param {(err: Error) => void} o.onHalt - called if a forwarded `onTurn` throws a HaltError.
+ */
+export function createSessionStream({ onTurn, ctx, startedAt, onHalt }: {
+    onTurn: Function | null;
+    ctx: any;
+    startedAt: number;
+    onHalt: (err: Error) => void;
+}): {
+    /** Feed a stdout chunk. Pure synchronous framing — never awaits. */
+    feed(chunk: Buffer | string): void;
+    /** Await every queued per-turn forward — call before resolving the session. */
+    flush(): Promise<void>;
+    readonly turns: import("../types").Usage[];
+    readonly attempted: number;
+    readonly final: any;
+};
+/**
+ * Run ONE native CLI session to completion, streaming per-turn usage as it arrives.
+ *
+ * @param {object} opts
+ * @returns {Promise<any>}
+ */
+export function runSession(opts: object): Promise<any>;