feat(clipipe): structured-output parsing + provider costUsd (A1) — v0.26.0 (#11)

* feat(clipipe): opt-in structured-output parsing + Loop honors provider costUsd (A1)

CLIPipeProvider gains an opt-in `parse` option ('claude-json' preset or a
(stdout)=>Partial<GenerateResult> fn) that maps structured CLI output onto the
normalized GenerateResult/Usage shape; default (unset) stays raw-text/zero-usage
(byte-identical). GenerateResult gains optional `costUsd`, and the Loop prefers a
finite result.costUsd over estimateCost at both cost sites (resolveRoundCost) so
a CLI's own price feeds bareguard's USD axis without a local rate table. A
provider-supplied 0 is a valid priced value, distinct from null/unpriced.

Requested by adaptlearn (F2/A1).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016jdj7UfmMkPsvqqDN7ChhK

* release: v0.26.0 — CLIPipe structured output + provider costUsd (A1)

Version bump (package.json, package-lock ×2, context.md header), CHANGELOG cut
[Unreleased] -> [0.26.0], and bareagent.context.md provider-section update
(corrects the now-false 'CLIPipe always returns zero usage' claim + adds the
parse:'claude-json' surface and costUsd field).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016jdj7UfmMkPsvqqDN7ChhK

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: hamr0

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to bare-agent are documented here. Format: [Keep a Changelog
 
 ## [Unreleased]
 
+## [0.26.0] — 2026-07-08
+
+### Added
+
+- **`CLIPipeProvider` opt-in structured-output parsing — surfaces real usage + cost (adaptlearn F2/A1).** `generate()` returned stdout verbatim as `text` and hard-coded `usage: { inputTokens: 0, outputTokens: 0 }`, so a bareguard `Gate` with a token or USD cap saw **zero usage** from CLI-piped runs — the budget axis was blind (and, under an active USD cap, fails closed on unpriced cost). But `claude -p --output-format json` emits a single JSON envelope carrying everything a provider result needs. New opt-in `new CLIPipeProvider({ parse })`: `'claude-json'` is a shipped preset that `JSON.parse`s stdout and maps the envelope onto the normalized `GenerateResult`/`Usage` shape — `text ← result` (the assistant text, not the raw JSON), `usage.inputTokens ← usage.input_tokens`, `outputTokens ← usage.output_tokens`, `cacheReadTokens`/`cacheCreationTokens ← usage.cache_{read,creation}_input_tokens` (absent ⇒ omitted, per the `Usage` contract — never a synthetic 0), `model ← ` the first `modelUsage` key, and `costUsd ← total_cost_usd`. Malformed JSON, a non-object envelope, `is_error: true`, or a non-`success` subtype throw a **loud `ProviderError`** — never a silent fall-back to raw text (the caller explicitly asked for structured output). A `parse: (stdout) => Partial<GenerateResult>` **function** is the CLI-agnostic escape hatch (merged over defaults); `'claude-json'` is a preset over it. To make the CLI's own price actually enforce a budget **without a local rate table**, `GenerateResult` gains an optional `costUsd?: number` and the **Loop now prefers a finite `result.costUsd` over `estimateCost`** (both the main and summarize cost paths) and forwards it to `onLlmResult` as `pricing: 'priced'` — a provider-supplied `0` is a valid priced value (a subscription/marginal-$0 run), distinct from omitted/null which still falls back to the rate table. Out of scope for A1 (unchanged): tool calls (`toolCalls` stays `[]`), streaming, and any claude-specific default args. **POC-first** — the real `claude -p "say OK" --output-format json` envelope was captured live (2026-07-08) before building, and the shipped provider was driven end-to-end against the real CLI (`text:"OK"`, `inputTokens` > 0, authoritative `costUsd` surfaced). Default (no `parse`) is **byte-identical to before** (raw stdout as text, zero usage — a regression guard test asserts a raw JSON envelope stays unparsed). `src/provider-clipipe.js`, `src/loop.js`, `types/index.d.ts`, `test/provider-clipipe.test.js` (+11), `test/loop.test.js` (+3, provider-cost preference incl. the `0`-is-priced and non-finite-falls-back cases).
+
 ## [0.25.0] — 2026-07-03
 
 ### Added

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.0 | Node.js >= 18 | zero required deps (`bareguard ^0.9.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-lock.json

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

package.json

@@ -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 —

src/loop.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

src/provider-clipipe.js

@@ -1076,3 +1076,49 @@ describe('Loop — BA-11 deny-spin guard', () => {
     for (const id of toolCallIds) assert.ok(toolResultIds.has(id), `tool_call ${id} has a paired result`);
   });
 });
+
+describe('A1 — provider-supplied costUsd (CLI authoritative price)', () => {
+  it('prefers result.costUsd over estimateCost and forwards it as priced', async () => {
+    const events = [];
+    // No model → estimateCost would return null (unpriced). The provider's own costUsd must win.
+    const provider = {
+      model: null,
+      async generate() {
+        return { text: 'done', toolCalls: [], usage: { inputTokens: 100, outputTokens: 5 }, costUsd: 0.0495 };
+      },
+    };
+    const loop = new Loop({ provider, onLlmResult: (e) => { events.push(e); } });
+    const result = await loop.run([{ role: 'user', content: 'hi' }]);
+    assert.equal(result.cost, 0.0495, 'authoritative CLI cost accumulates into totalCost');
+    assert.equal(result.metrics.costUsd, 0.0495);
+    assert.equal(result.metrics.unpricedRounds, 0, 'a provider-priced round is NOT unpriced');
+    assert.equal(events.length, 1);
+    assert.equal(events[0].costUsd, 0.0495);
+    assert.equal(events[0].pricing, 'priced');
+  });
+
+  it('treats a provider costUsd of 0 as priced (not the null/unpriced sentinel)', async () => {
+    const provider = {
+      model: null,
+      async generate() {
+        return { text: 'ok', toolCalls: [], usage: { inputTokens: 1, outputTokens: 1 }, costUsd: 0 };
+      },
+    };
+    const result = await new Loop({ provider }).run([{ role: 'user', content: 'hi' }]);
+    assert.equal(result.metrics.costUsd, 0, 'a real $0 round is priced 0, never null');
+    assert.equal(result.metrics.unpricedRounds, 0);
+  });
+
+  it('falls back to estimateCost when costUsd is absent or non-finite', async () => {
+    // Non-finite provider cost is NOT a price → estimateCost path → null (no model) → unpriced.
+    const provider = {
+      model: null,
+      async generate() {
+        return { text: 'ok', toolCalls: [], usage: { inputTokens: 1, outputTokens: 1 }, costUsd: NaN };
+      },
+    };
+    const result = await new Loop({ provider }).run([{ role: 'user', content: 'hi' }]);
+    assert.equal(result.metrics.costUsd, null, 'NaN cost falls through, not treated as priced');
+    assert.equal(result.metrics.unpricedRounds, 1);
+  });
+});