bare-agent 0.25.0 → 0.26.2

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.25.0 | Node.js >= 18 | zero required deps (`bareguard ^0.9.0` optional peer for governance) | Apache 2.0
+> v0.26.2 | 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)
 
@@ -59,6 +59,7 @@ Eight entry points:
 | Catch typed errors programmatically | ProviderError, ToolError, TimeoutError, CircuitOpenError |
 | 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' }) |
 | 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`) |
@@ -739,9 +740,11 @@ new Ollama({ model: 'llama3.2', url: 'http://localhost:11434' })
 // CLIPipe — pipe prompts to any CLI tool via stdin/stdout
 new CLIPipe({ command: 'claude', args: ['--print'], systemPromptFlag: '--system-prompt', timeout: 30000 })
 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' })
 ```
 
-All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model? }`. The optional `model` (v0.16.1+) is the id the response was produced by — Loop prefers it over `provider.model` for cost accounting. CLIPipe always returns `toolCalls: []` and zero usage (CLI tools don't report tokens), and omits `model`.
+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.25.0",
+  "version": "0.26.2",
   "files": [
     "index.js",
     "index.d.ts",
@@ -80,7 +80,7 @@
     "cron-parser": "^4.9.0"
   },
   "peerDependencies": {
-    "bareguard": "^0.9.0",
+    "bareguard": ">=0.9.0 <0.13.0",
     "better-sqlite3": ">=9.0.0"
   },
   "peerDependenciesMeta": {
@@ -101,7 +101,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
-    "bareguard": "^0.9.0",
+    "bareguard": ">=0.9.0 <0.13.0",
     "litectx": "^0.26.0",
     "typescript": "^5.7.0"
   }

package/src/bareguard-adapter.d.ts

@@ -27,9 +27,9 @@ export type GateDecision = {
      */
     rule?: string | undefined;
     /**
-     * - Human-readable reason.
+     * - Human-readable reason (bareguard's Decision emits null when absent).
      */
-    reason?: string | undefined;
+    reason?: string | null | undefined;
     /**
      * - Arbitrary structured context.
      */

package/src/bareguard-adapter.js

@@ -21,7 +21,7 @@ const { HaltError } = require('./errors');
  * @property {string} [outcome] - 'allow' when permitted.
  * @property {string} [severity] - 'halt' for halt-severity denials.
  * @property {string} [rule] - The matched rule name.
- * @property {string} [reason] - Human-readable reason.
+ * @property {string | null} [reason] - Human-readable reason (bareguard's Decision emits null when absent).
  * @property {Record<string, any>} [context] - Arbitrary structured context.
  */
 

package/src/loop.js

@@ -153,6 +153,23 @@ function estimateCost(model, usage) {
   return Number.isFinite(cost) ? cost : null;
 }
 
+/**
+ * Resolve the priced USD for a round. A provider MAY report its own authoritative `costUsd` on the
+ * GenerateResult (e.g. CLIPipeProvider `parse:'claude-json'` surfacing the claude CLI's own
+ * `total_cost_usd` — a real price with NO local rate table). When present as a FINITE number it wins
+ * over the rate-table estimate — including `0`, a valid priced value (a subscription/marginal-$0 run),
+ * which stays 'priced', never demoted to the null/unpriced sentinel. A non-finite provider cost
+ * (±Inf/NaN) is NOT a price → fall through to estimateCost (same couldn't-price guard as above).
+ * @param {any} result - the GenerateResult from provider.generate()
+ * @param {string|null} model
+ * @param {Usage|null} usage
+ * @returns {number|null}
+ */
+function resolveRoundCost(result, model, usage) {
+  if (result && Number.isFinite(result.costUsd)) return result.costUsd;
+  return estimateCost(model, usage);
+}
+
 // R-C6: default instruction for the provider-bound `ctx.summarize` lent to the assemble seam.
 const DEFAULT_SUMMARY_INSTRUCTION =
   'You are a precise conversation summarizer. Produce a concise, factual summary of the following ' +
@@ -472,7 +489,7 @@ class Loop {
         const result = await loop.provider.generate(prompt, [], { temperature: 0, ...genOpts });
         const usage = (result && result.usage) || null;
         const model = (result && result.model) || loop.provider.model || null;
-        const cost = estimateCost(model, usage);
+        const cost = resolveRoundCost(result, model, usage);
         if (cost !== null) { totalCost += cost; pricedAny = true; }
         addUsage(usage); // summarize tokens are real spend → count them in the cumulative meter
         metrics.context.summaries++; // §3.6 CE-activity rollup
@@ -616,7 +633,7 @@ class Loop {
       // Prefer the model the response reports (robust when provider.model is absent or varies per
       // response — e.g. FallbackProvider, or a CircuitBreaker-wrapped provider that drops .model).
       const model = result.model || this.provider.model || null;
-      const roundCost = estimateCost(model, lastUsage);
+      const roundCost = resolveRoundCost(result, model, lastUsage);
       if (roundCost !== null) totalCost += roundCost;
 
       // Meter this round: count the turn, accumulate the four token tiers, and classify pricing —

package/src/provider-clipipe.d.ts

@@ -30,6 +30,10 @@ export type CLIPipeOptions = {
      * - Called with each stdout chunk as it streams.
      */
     onChunk?: ((chunk: string) => void) | undefined;
+    /**
+     * - Opt-in structured-output parser for stdout. Default (unset) returns stdout verbatim as `text` with zero usage (no behavior change). `'claude-json'` is a shipped preset for `claude -p --output-format json`: it maps the CLI's result envelope onto `GenerateResult` (text←`result`, usage←`usage.*`, model←first `modelUsage` key, costUsd←`total_cost_usd`) and throws `ProviderError` on malformed JSON or an error envelope (`is_error`/non-success subtype). A function is the CLI-agnostic escape hatch: it receives trimmed stdout and returns a partial `GenerateResult` (merged over defaults); throw to signal a parse failure.
+     */
+    parse?: "claude-json" | ((stdout: string) => Partial<GenerateResult>) | undefined;
 };
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -43,6 +47,7 @@ export type CLIPipeOptions = {
  * @property {number} [timeout=30000] - Timeout in milliseconds.
  * @property {string} [systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
  * @property {(chunk: string) => void} [onChunk] - Called with each stdout chunk as it streams.
+ * @property {'claude-json'|((stdout: string) => Partial<GenerateResult>)} [parse] - Opt-in structured-output parser for stdout. Default (unset) returns stdout verbatim as `text` with zero usage (no behavior change). `'claude-json'` is a shipped preset for `claude -p --output-format json`: it maps the CLI's result envelope onto `GenerateResult` (text←`result`, usage←`usage.*`, model←first `modelUsage` key, costUsd←`total_cost_usd`) and throws `ProviderError` on malformed JSON or an error envelope (`is_error`/non-success subtype). A function is the CLI-agnostic escape hatch: it receives trimmed stdout and returns a partial `GenerateResult` (merged over defaults); throw to signal a parse failure.
  */
 export class CLIPipeProvider {
     /**
@@ -58,6 +63,7 @@ export class CLIPipeProvider {
     timeout: number;
     systemPromptFlag: string | null;
     onChunk: ((chunk: string) => void) | null;
+    parse: "claude-json" | ((stdout: string) => Partial<GenerateResult>) | null;
     /**
      * Generate a response by piping messages to the CLI command.
      * @param {Message[]} messages - Conversation messages in OpenAI format.
@@ -70,6 +76,15 @@ export class CLIPipeProvider {
      * @throws {Error} `[CLIPipeProvider] process produced no output` — when stdout is empty.
      */
     generate(messages: Message[], tools?: ToolDef[], options?: Record<string, any>): Promise<GenerateResult>;
+    /**
+     * Map the `claude -p --output-format json` result envelope onto a normalized GenerateResult.
+     * The caller explicitly opted into structured output, so a malformed or error envelope is a LOUD
+     * ProviderError — never a silent fall-back to raw text.
+     * @param {string} stdout - Trimmed stdout from the CLI.
+     * @returns {GenerateResult}
+     * @throws {ProviderError} On non-JSON stdout, or an error envelope (`is_error` / non-success subtype).
+     */
+    _parseClaudeJson(stdout: string): GenerateResult;
     /**
      * Convert OpenAI-format messages to a plain text prompt.
      * @param {Message[]} messages

package/src/provider-clipipe.js

@@ -16,6 +16,7 @@ const { ProviderError } = require('./errors');
  * @property {number} [timeout=30000] - Timeout in milliseconds.
  * @property {string} [systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
  * @property {(chunk: string) => void} [onChunk] - Called with each stdout chunk as it streams.
+ * @property {'claude-json'|((stdout: string) => Partial<GenerateResult>)} [parse] - Opt-in structured-output parser for stdout. Default (unset) returns stdout verbatim as `text` with zero usage (no behavior change). `'claude-json'` is a shipped preset for `claude -p --output-format json`: it maps the CLI's result envelope onto `GenerateResult` (text←`result`, usage←`usage.*`, model←first `modelUsage` key, costUsd←`total_cost_usd`) and throws `ProviderError` on malformed JSON or an error envelope (`is_error`/non-success subtype). A function is the CLI-agnostic escape hatch: it receives trimmed stdout and returns a partial `GenerateResult` (merged over defaults); throw to signal a parse failure.
  */
 
 class CLIPipeProvider {
@@ -33,6 +34,10 @@ class CLIPipeProvider {
     this.timeout = options.timeout ?? 30000;
     this.systemPromptFlag = options.systemPromptFlag || null;
     this.onChunk = options.onChunk || null;
+    if (options.parse != null && options.parse !== 'claude-json' && typeof options.parse !== 'function') {
+      throw new Error("[CLIPipeProvider] options.parse must be 'claude-json' or a function");
+    }
+    this.parse = options.parse || null;
   }
 
   /**
@@ -61,14 +66,77 @@ class CLIPipeProvider {
     }
 
     const prompt = this._formatPrompt(promptMessages);
-    const text = await this._spawn(prompt, extraArgs);
+    const stdout = await this._spawn(prompt, extraArgs);
+
+    if (this.parse === 'claude-json') return this._parseClaudeJson(stdout);
+    if (typeof this.parse === 'function') {
+      const partial = this.parse(stdout) || {};
+      return {
+        text: '',
+        toolCalls: [],
+        ...partial,
+        usage: { inputTokens: 0, outputTokens: 0, ...(partial.usage || {}) },
+      };
+    }
     return {
-      text,
+      text: stdout,
       toolCalls: [],
       usage: { inputTokens: 0, outputTokens: 0 },
     };
   }
 
+  /**
+   * Map the `claude -p --output-format json` result envelope onto a normalized GenerateResult.
+   * The caller explicitly opted into structured output, so a malformed or error envelope is a LOUD
+   * ProviderError — never a silent fall-back to raw text.
+   * @param {string} stdout - Trimmed stdout from the CLI.
+   * @returns {GenerateResult}
+   * @throws {ProviderError} On non-JSON stdout, or an error envelope (`is_error` / non-success subtype).
+   */
+  _parseClaudeJson(stdout) {
+    let obj;
+    try {
+      obj = JSON.parse(stdout);
+    } catch (_) {
+      const preview = stdout.length > 200 ? `${stdout.slice(0, 200)}…` : stdout;
+      throw new ProviderError(`[CLIPipeProvider] parse:'claude-json' expected JSON on stdout, got: ${preview}`, /** @type {any} */ ({ status: 0 }));
+    }
+    if (!obj || typeof obj !== 'object') {
+      throw new ProviderError(`[CLIPipeProvider] parse:'claude-json' expected a JSON object, got ${obj === null ? 'null' : typeof obj}`, /** @type {any} */ ({ status: 0 }));
+    }
+    if (obj.is_error === true || obj.subtype !== 'success') {
+      const detail = typeof obj.result === 'string' ? obj.result : JSON.stringify(obj.result ?? null);
+      throw new ProviderError(`[CLIPipeProvider] claude CLI reported failure (subtype='${obj.subtype}'): ${detail}`, /** @type {any} */ ({ status: 0 }));
+    }
+
+    const u = (obj.usage && typeof obj.usage === 'object') ? obj.usage : {};
+    /** @type {import('../types').Usage} */
+    const usage = {
+      inputTokens: Number(u.input_tokens) || 0,
+      outputTokens: Number(u.output_tokens) || 0,
+    };
+    // Absent cache tiers mean the model didn't cache — omit rather than emit a synthetic 0 (per Usage docs).
+    if (Number.isFinite(u.cache_read_input_tokens)) usage.cacheReadTokens = u.cache_read_input_tokens;
+    if (Number.isFinite(u.cache_creation_input_tokens)) usage.cacheCreationTokens = u.cache_creation_input_tokens;
+
+    // `modelUsage` is an object keyed by model id (e.g. {"claude-opus-4-8[1m]": {...}}) — take the first key.
+    const model = (obj.modelUsage && typeof obj.modelUsage === 'object')
+      ? (Object.keys(obj.modelUsage)[0] ?? null)
+      : null;
+
+    /** @type {GenerateResult} */
+    const result = {
+      text: typeof obj.result === 'string' ? obj.result : '',
+      toolCalls: [],
+      usage,
+      model,
+    };
+    // The CLI's own price is authoritative (subscription runs report an equivalent cost even at $0
+    // marginal) — feeds bareguard's USD axis with no local rate table. Only a finite number counts.
+    if (Number.isFinite(obj.total_cost_usd)) result.costUsd = obj.total_cost_usd;
+    return result;
+  }
+
   /**
    * Convert OpenAI-format messages to a plain text prompt.
    * @param {Message[]} messages
@@ -97,39 +165,65 @@ class CLIPipeProvider {
 
       let stdout = '';
       let stderr = '';
-      let killed = false;
 
-      child.stdout.on('data', d => { stdout += d; this.onChunk?.(d.toString()); });
-      child.stderr.on('data', d => { stderr += d; });
-
-      child.on('error', err => {
-        reject(new ProviderError(`[CLIPipeProvider] failed to spawn "${this.command}": ${err.message}`, /** @type {any} */ ({ status: 0 })));
-      });
-
-      child.on('close', code => {
-        if (killed) return; // timeout already rejected
+      // Settle exactly once, no matter which combination of events fires. 'close' can be
+      // withheld indefinitely when the CLI spawns a grandchild that inherits its stdio pipes
+      // (the child exits, but the pipes stay open) — observed live as a generate() promise
+      // that never settled. Every path below funnels through settle().
+      let settled = false;
+      /** @type {NodeJS.Timeout[]} */
+      const timers = [];
+      const later = (fn, ms) => { timers.push(setTimeout(fn, ms)); };
+      const settle = (/** @type {Error|null} */ err, text = '') => {
+        if (settled) return;
+        settled = true;
+        for (const t of timers) clearTimeout(t);
+        if (err) reject(err); else resolve(text);
+      };
+
+      const finish = (/** @type {number|null} */ code) => {
         if (code !== 0) {
-          return reject(new ProviderError(`[CLIPipeProvider] process exited with code ${code}: ${stderr.trim()}`, /** @type {any} */ ({ status: code })));
+          // The claude CLI reports errors on STDOUT (a JSON envelope) with stderr often
+          // empty — fall back to a stdout tail so the operator never sees a blank reason.
+          const detail = stderr.trim() || (stdout.trim() ? `(stderr empty) stdout: ${stdout.trim().slice(-400)}` : '');
+          return settle(new ProviderError(`[CLIPipeProvider] process exited with code ${code}: ${detail}`, /** @type {any} */ ({ status: code })));
         }
         const text = stdout.trim();
         if (!text) {
-          return reject(new ProviderError('[CLIPipeProvider] process produced no output', /** @type {any} */ ({ status: 0 })));
+          return settle(new ProviderError('[CLIPipeProvider] process produced no output', /** @type {any} */ ({ status: 0 })));
+        }
+        settle(null, text);
+      };
+
+      child.stdout.on('data', d => {
+        stdout += d;
+        try {
+          this.onChunk?.(d.toString());
+        } catch (err) {
+          // an observer callback must fail the call loudly, never crash the host process
+          settle(new ProviderError(`[CLIPipeProvider] onChunk callback threw: ${/** @type {Error} */ (err).message}`, /** @type {any} */ ({ status: 0 })));
         }
-        resolve(text);
       });
+      child.stderr.on('data', d => { stderr += d; });
 
-      // Timeout handling
-      const timer = setTimeout(() => {
-        killed = true;
+      child.on('error', err => {
+        settle(new ProviderError(`[CLIPipeProvider] failed to spawn "${this.command}": ${err.message}`, /** @type {any} */ ({ status: 0 })));
+      });
+
+      // Primary completion path: all stdio drained.
+      child.on('close', code => finish(code));
+
+      // Fallback: the process exited but 'close' is being held open by inherited pipes.
+      // Give real drainage a short grace, then finish with what has arrived — a bounded
+      // wait, never a hang.
+      child.on('exit', code => later(() => finish(code), 2000));
+
+      later(() => {
         child.kill('SIGTERM');
-        setTimeout(() => {
-          try { child.kill('SIGKILL'); } catch (_) {}
-        }, 1000);
-        reject(new ProviderError(`[CLIPipeProvider] timed out after ${this.timeout}ms`, /** @type {any} */ ({ status: 0 })));
+        setTimeout(() => { try { child.kill('SIGKILL'); } catch (_) {} }, 1000).unref?.();
+        settle(new ProviderError(`[CLIPipeProvider] timed out after ${this.timeout}ms`, /** @type {any} */ ({ status: 0 })));
       }, this.timeout);
 
-      child.on('close', () => clearTimeout(timer));
-
       // Write prompt to stdin — catch errors silently (process may exit early)
       child.stdin.on('error', () => {});
       child.stdin.end(prompt);

package/types/index.d.ts

@@ -86,6 +86,14 @@ export interface GenerateResult {
    * temperature, not the one requested — callers reporting an effective temperature must honor this.
    */
   temperatureDropped?: boolean;
+  /**
+   * Authoritative per-call cost in USD, reported by the provider itself — e.g. CLIPipeProvider
+   * `parse:'claude-json'` surfacing the claude CLI's own `total_cost_usd`, a real price with no local
+   * rate table. When a FINITE number the Loop prefers it over `estimateCost` and treats the round as
+   * priced (feeding bareguard's USD budget axis). `0` is a valid priced value (a subscription/marginal-$0
+   * run) — distinct from omitted/null, which means "couldn't price" and falls back to the rate table.
+   */
+  costUsd?: number;
 }
 
 /** A conversation message in OpenAI chat format. */