bare-agent 0.38.1 → 0.40.0

package/README.md

@@ -135,7 +135,7 @@ console.log(result.count, result.matchedIds);   // a code-derived count + the id
 
 **Deps:** none required — the core imports nothing. Optional peers: `bareguard ^0.9.0` (governance), `better-sqlite3` (SQLite store); optional: `cron-parser`, `barebrowse`, `baremobile`, `wearehere`.
 
-This table is the map, not the manual — per-component wiring and API detail live in the [Integration Guide](bareagent.context.md) and [Usage Guide](docs/02-features/usage-guide.md).
+This table is the map, not the manual — per-component wiring and API detail live in the [Integration Guide](bareagent.context.md) and [Usage Guide](docs/archive/usage-guide.md).
 
 ---
 
@@ -281,7 +281,7 @@ All wrappers support optional event streaming for intermediate results. See [`co
 
 Aurora replaced ~400 lines of hand-rolled orchestration with ~60 lines of bare-agent wiring — zero workarounds, zero framework plumbing, 100% domain logic.
 
-For wiring recipes and API details, see the **[Integration Guide](bareagent.context.md)** (LLM-optimized). For the full human guide — usage patterns, composition examples, and what bare-agent deliberately doesn't build in (with recipes to do it yourself), see the **[Usage Guide](docs/02-features/usage-guide.md)**. For error reference, see **[Error Guide](docs/02-features/errors.md)**. For release history, see **[CHANGELOG](CHANGELOG.md)**.
+For wiring recipes and API details, see the **[Integration Guide](bareagent.context.md)** (LLM-optimized). For the full human guide — usage patterns, composition examples, and what bare-agent deliberately doesn't build in (with recipes to do it yourself), see the **[Usage Guide](docs/archive/usage-guide.md)**. For error reference, see **[Error Guide](docs/product/errors.md)**. For release history, see **[CHANGELOG](CHANGELOG.md)**.
 
 ## The bare ecosystem
 

package/bareagent.context.md

@@ -1,9 +1,9 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.38.1 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.14.0` optional peer for governance) | Apache 2.0
+> v0.40.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.14.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)
+> Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/archive/usage-guide.md)
 
 ## What this is
 
@@ -891,7 +891,7 @@ All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model?, cos
 
 **Plaintext-key warning (Unreleased):** the OpenAI provider's `baseUrl` accepts `http://` (for local/OpenAI-compatible endpoints), but a `Bearer` key sent over plaintext http to a **non-loopback** host is exposed on the wire. The provider now warns once when that happens. Loopback hosts (`localhost`/`127.0.0.0/8`/`::1` — local proxies, Ollama-style endpoints) stay silent, since that's the legitimate keyless-local case. The header is **not** stripped (some local proxies want a key), so use `https` for any remote endpoint, or drop `apiKey` when the local endpoint needs none.
 
-**Cost estimation:** Loop automatically estimates USD cost per run based on model and token usage. The `cost` field appears in every `loop.run()` result and in `loop:done` stream events. **Pricing honesty (BA-21, v0.37.0):** a token-bearing round is ALWAYS priced (guesstimate-and-run — a null/unknown model no longer forces `unpriced`); rates resolve as caller-supplied `new Loop({ rates: { in, out } })` (authoritative) → a recognized Claude tier from the model id (`haiku`/`sonnet`) → the **Sonnet-tier** ceiling default ($0.003/$0.015 per 1K, no per-model table). Every metering payload carries a `rateSource: 'provider' | 'caller' | 'tier' | 'default' | null` field so a consumer can tell an authoritative price from a guess — and (BA-21 follow-up, v0.38.0) a recognized-tier guess (`'tier'`) from a blind ceiling fallback (`'default'`); a round priced off either guesstimate emits ONE loud `console.warn` per Loop instance naming the actual source (silenced by passing `rates`). To set your own rates, construct `new Loop({ rates })` — there is no longer a `COST_PER_1K` table to edit. The model is resolved as `result.model || provider.model` (v0.16.1+) — providers now echo the model in their `generate()` result, so cost accounting holds even when `provider.model` is absent or varies per response, e.g. behind `FallbackProvider` or `CircuitBreaker.wrapProvider` (the wrapper also preserves `model`/`name` passthrough props). Wire `onLlmResult` (via `wireGate`) and a `budget.maxCostUsd` cap then halts on token-heavy workloads too.
+**Cost estimation:** Loop automatically estimates USD cost per run based on model and token usage. The `cost` field appears in every `loop.run()` result and in `loop:done` stream events. **Pricing honesty (BA-21, v0.37.0):** a token-bearing round is ALWAYS priced (guesstimate-and-run — a null/unknown model no longer forces `unpriced`); rates resolve as caller-supplied `new Loop({ rates: { in, out } })` (authoritative) → a recognized Claude tier from the model id (`haiku`/`sonnet`) → the **Sonnet-tier** ceiling default ($0.003/$0.015 per 1K, no per-model table). Every metering payload carries a `rateSource: 'provider' | 'caller' | 'tier' | 'default' | null` field so a consumer can tell an authoritative price from a guess — and (BA-21 follow-up, v0.38.0) a recognized-tier guess (`'tier'`) from a blind ceiling fallback (`'default'`); a round priced off either guesstimate emits ONE loud `console.warn` per Loop instance naming the actual source (silenced by passing `rates`). To set your own rates, construct `new Loop({ rates })` — there is no longer a `COST_PER_1K` table to edit. The model is resolved as `result.model || provider.model` (v0.16.1+) — providers now echo the model in their `generate()` result, so cost accounting holds even when `provider.model` is absent or varies per response, e.g. behind `FallbackProvider` or `CircuitBreaker.wrapProvider` (the wrapper also preserves `model`/`name` passthrough props). Wire `onLlmResult` (via `wireGate`) and a `budget.maxCostUsd` cap then halts on token-heavy workloads too. **Usage-null boundary (BA-24, v0.39.0):** `GenerateResult.usage` is `Usage | null` — every provider (incl. native CLIPipe session-close) now surfaces `usage: null` when the raw API response carried NO usage block, instead of manufacturing an all-zeros object. A manufactured zero object used to sail past `resolveRoundCost`'s honest-null guard and get priced as a confident $0 (`rateSource:'tier'`/`'default'`) — an unpriceable round now stays unpriced. A *present* block with an explicit `0` field (e.g. a cache-only round) is unaffected and still prices normally.
 
 ## Store options
 
@@ -991,7 +991,7 @@ These are deliberately NOT in bare-agent. Don't look for them — build them fro
 | **Heartbeat (ambient awareness)** | "Check if anything needs attention" scope is your domain | Scheduler recurring job where the LLM triages: `scheduler.add({ type: 'recurring', schedule: '30m', action: 'Check if anything needs attention' })`. |
 | **Cron** | **This IS built in** | Scheduler supports cron expressions (requires `cron-parser` peer dep) and relative schedules (`5s`, `30m`, `2h`, `1d`) natively. |
 
-For full recipes with code examples, see `docs/02-features/usage-guide.md` § "Patterns, Not Features".
+For full recipes with code examples, see `docs/archive/usage-guide.md` § "Patterns, Not Features".
 
 ## Production usage
 
@@ -1010,7 +1010,7 @@ For full recipes with code examples, see `docs/02-features/usage-guide.md` § "P
 | Stream | — | — (deferred) |
 | CLIPipe | ✓ | — |
 
-Both projects kept their own memory/store implementations. Neither needed multi-agent routing. Full multis eval: `docs/03-logs/bareagent-eval-multis.md`.
+Both projects kept their own memory/store implementations. Neither needed multi-agent routing. Full multis eval: `docs/logs/bareagent-eval-multis.md`.
 
 ## Examples
 
@@ -1048,6 +1048,7 @@ Stale example removed in 0.10.4: `examples/mcp-bridge-gov.js` (used a hard-coded
 17. **Halt-path `msgs` is sealed (v0.10.3+)** — when Loop catches `HaltError` mid-round, every dangling assistant `tool_calls.id` from the halted round gets a synthetic `{ role:'tool', tool_call_id, content: '[halted:<rule>]' }` appended so the returned `result.msgs` is valid OpenAI shape. Safe to feed back into another provider call without protocol errors. The `[halted:<rule>]` tag is lowercase — distinct from the legacy `[HALT:]` deny strings (removed in 0.10.0, do not match on the old form).
 18. **`HaltError` with no `rule` resolves to `halt:unknown` (v0.10.3+)** — `new HaltError('msg')` without a `{ rule }` option still produces a stable `result.error = 'halt:unknown'` and `loop:done{halted:true, rule:'unknown'}`. Pre-0.10.3 produced the literal `'halt:null'` which broke string-matching consumers. The `_reportError('halt', ...)` extra carries the same `rule:'unknown'` token.
 19. **Pricing is a two-tier guesstimate, not a per-model table (BA-21, v0.37.0)** — a recognized Claude tier in the model id prices at `haiku` ($0.001/$0.005) or `sonnet` ($0.003/$0.015) per 1K; anything else (incl. a null/unknown model) falls through to the **Sonnet-tier ceiling default** ($0.003/$0.015) and still gets priced (`rateSource: 'default'`), never silently `unpriced`. Both guesstimate cases emit one `console.warn` per Loop instance. The `rateSource` on every metering payload distinguishes them: `'tier'` (a recognized haiku/sonnet match — a confident guess) vs `'default'` (the blind ceiling for an unrecognized/absent model), alongside `'provider'`/`'caller'` (authoritative) and `null` (unpriced). If you use a model whose real rates differ and care about `result.cost` accuracy or `budget.maxCostUsd` enforcement via `onLlmResult`, pass `new Loop({ rates: { in, out, cacheReadMult?, cacheWriteMult? } })` — that's authoritative (`rateSource: 'caller'`) and silences the warning. There is no `COST_PER_1K` table to edit.
+20. **A `GenerateResult` with `usage: null` means the provider reported no usage block at all — not a round that used zero tokens (BA-24, v0.39.0)** — every http/CLI provider used to coalesce an absent usage block into a truthy all-zeros `Usage` object (`field || 0` applied unconditionally), which `resolveRoundCost` then priced as a confident $0 instead of treating it as unpriceable. `GenerateResult.usage` is now typed `Usage | null`; `null` fires only when the raw API response carried no usage signal at all (checked field-by-field via `hasUsageSignal`, `src/provider-usage.js`), never on a present block whose fields are legitimately `0` (a cache-only round still prices normally). If your own code reads `result.usage.inputTokens` directly, guard for `null` first.
 
 ## Cross-language SDKs
 

package/examples/README.md

@@ -12,4 +12,4 @@ Runnable reference scripts for bare-agent. Each is self-contained — the top-of
 | [`replay-job.js`](replay-job.js) | Supervised replay POC: record a browser task once with the LLM driving, then replay against fresh snapshots with the LLM as locator-only. Falls back to full reasoning when the locator misses, and patches the trace. |
 | [`litectx-as-store.mjs`](litectx-as-store.mjs) | RT-3 Store mount: swap the zero-dep `JsonFileStore` for litectx's ranked, graph-aware recall in one line — the host code never changes. Runs the JsonFileStore half always; runs the litectx half if `litectx` is installed, else prints the one-line swap. |
 
-For wiring recipes and API details see the [Integration Guide](../bareagent.context.md); for usage patterns and design philosophy see the [Usage Guide](../docs/02-features/usage-guide.md).
+For wiring recipes and API details see the [Integration Guide](../bareagent.context.md); for usage patterns and design philosophy see the [Usage Guide](../docs/archive/usage-guide.md).

package/index.d.ts

@@ -1,3 +1,57 @@
+/**
+ * Re-export the shared cross-cutting type shapes so adopters can name them when
+ * annotating their own wiring (tools arrays, providers, ctx, metrics). Declared
+ * in `types/index.d.ts`; surfaced here on the root entry so `types` resolves them.
+ */
+export type ToolDef = import("./types").ToolDef;
+/**
+ * Re-export the shared cross-cutting type shapes so adopters can name them when
+ * annotating their own wiring (tools arrays, providers, ctx, metrics). Declared
+ * in `types/index.d.ts`; surfaced here on the root entry so `types` resolves them.
+ */
+export type ToolCall = import("./types").ToolCall;
+/**
+ * Re-export the shared cross-cutting type shapes so adopters can name them when
+ * annotating their own wiring (tools arrays, providers, ctx, metrics). Declared
+ * in `types/index.d.ts`; surfaced here on the root entry so `types` resolves them.
+ */
+export type Message = import("./types").Message;
+/**
+ * Re-export the shared cross-cutting type shapes so adopters can name them when
+ * annotating their own wiring (tools arrays, providers, ctx, metrics). Declared
+ * in `types/index.d.ts`; surfaced here on the root entry so `types` resolves them.
+ */
+export type Provider = import("./types").Provider;
+/**
+ * Re-export the shared cross-cutting type shapes so adopters can name them when
+ * annotating their own wiring (tools arrays, providers, ctx, metrics). Declared
+ * in `types/index.d.ts`; surfaced here on the root entry so `types` resolves them.
+ */
+export type GenerateResult = import("./types").GenerateResult;
+/**
+ * Re-export the shared cross-cutting type shapes so adopters can name them when
+ * annotating their own wiring (tools arrays, providers, ctx, metrics). Declared
+ * in `types/index.d.ts`; surfaced here on the root entry so `types` resolves them.
+ */
+export type Usage = import("./types").Usage;
+/**
+ * Re-export the shared cross-cutting type shapes so adopters can name them when
+ * annotating their own wiring (tools arrays, providers, ctx, metrics). Declared
+ * in `types/index.d.ts`; surfaced here on the root entry so `types` resolves them.
+ */
+export type RunMetrics = import("./types").RunMetrics;
+/**
+ * Re-export the shared cross-cutting type shapes so adopters can name them when
+ * annotating their own wiring (tools arrays, providers, ctx, metrics). Declared
+ * in `types/index.d.ts`; surfaced here on the root entry so `types` resolves them.
+ */
+export type Store = import("./types").Store;
+/**
+ * Re-export the shared cross-cutting type shapes so adopters can name them when
+ * annotating their own wiring (tools arrays, providers, ctx, metrics). Declared
+ * in `types/index.d.ts`; surfaced here on the root entry so `types` resolves them.
+ */
+export type Ctx = import("./types").Ctx;
 import { Loop } from "./src/loop";
 import { Planner } from "./src/planner";
 import { Evaluator } from "./src/evaluator";

package/index.js

@@ -1,5 +1,20 @@
 'use strict';
 
+/**
+ * Re-export the shared cross-cutting type shapes so adopters can name them when
+ * annotating their own wiring (tools arrays, providers, ctx, metrics). Declared
+ * in `types/index.d.ts`; surfaced here on the root entry so `types` resolves them.
+ * @typedef {import('./types').ToolDef} ToolDef
+ * @typedef {import('./types').ToolCall} ToolCall
+ * @typedef {import('./types').Message} Message
+ * @typedef {import('./types').Provider} Provider
+ * @typedef {import('./types').GenerateResult} GenerateResult
+ * @typedef {import('./types').Usage} Usage
+ * @typedef {import('./types').RunMetrics} RunMetrics
+ * @typedef {import('./types').Store} Store
+ * @typedef {import('./types').Ctx} Ctx
+ */
+
 const { Loop } = require('./src/loop');
 const { Planner } = require('./src/planner');
 const { Evaluator } = require('./src/evaluator');

package/package.json

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

package/src/provider-anthropic.js

@@ -6,6 +6,11 @@ const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
 const { resolveTimeoutMs, applyRequestBounds } = require('./provider-http');
+const { hasUsageSignal } = require('./provider-usage');
+
+// BA-24: the raw Anthropic usage field names. Presence of any (even value 0) means the API reported a
+// usage signal → build the object; absence of all means no signal → surface null (unpriceable).
+const ANTHROPIC_USAGE_KEYS = ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'];
 
 /** @param {string} hostname @returns {boolean} */
 function isLoopbackHost(hostname) {
@@ -191,12 +196,16 @@ class AnthropicProvider {
       }),
       // Anthropic's `input_tokens` is ALREADY the uncached remainder (cached tokens are reported
       // separately, not folded in — verified live), so no subtraction here, unlike OpenAI/Gemini.
-      usage: {
-        inputTokens: data.usage?.input_tokens || 0,
-        outputTokens: data.usage?.output_tokens || 0,
-        cacheReadTokens: data.usage?.cache_read_input_tokens || 0,
-        cacheCreationTokens: data.usage?.cache_creation_input_tokens || 0,
-      },
+      // BA-24: honest null when the API returned no usage block (or an empty one) — do NOT manufacture
+      // an all-zeros object, which launders an unpriceable round into a $0 PRICED one.
+      usage: hasUsageSignal(data.usage, ANTHROPIC_USAGE_KEYS)
+        ? {
+            inputTokens: data.usage.input_tokens || 0,
+            outputTokens: data.usage.output_tokens || 0,
+            cacheReadTokens: data.usage.cache_read_input_tokens || 0,
+            cacheCreationTokens: data.usage.cache_creation_input_tokens || 0,
+          }
+        : null,
       ...(temperatureDropped && { temperatureDropped: true }),
     };
   }

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

@@ -5,12 +5,10 @@ export type ParsedEnvelope = {
     toolName?: string | undefined;
     toolArguments?: Record<string, any> | undefined;
     answer?: string | undefined;
-    usage: import("../types").Usage;
+    usage: import("../types").Usage | null;
     model?: string | null | undefined;
     costUsd?: number | undefined;
 };
-/** @typedef {import('../types').Message} Message */
-/** @typedef {import('../types').ToolDef} ToolDef */
 /**
  * The JSON envelope the CLI is constrained to (claude `--json-schema`). `tool_call` carries the
  * name + args; `final_answer` carries prose. A closed `action` enum is the discriminator.
@@ -49,10 +47,10 @@ export function renderTranscript(messages: Message[]): string;
  * preset so the claude usage contract (token tiers, `modelUsage` first-key, `total_cost_usd`) lives
  * in exactly ONE place — a future CLI format change touches this function, not two copies.
  * @param {any} outer - the parsed outer CLI envelope (already validated non-null by the caller).
- * @returns {{usage: import('../types').Usage, model: string|null, costUsd?: number}}
+ * @returns {{usage: import('../types').Usage|null, model: string|null, costUsd?: number}}
  */
 export function mapClaudeMeta(outer: any): {
-    usage: import("../types").Usage;
+    usage: import("../types").Usage | null;
     model: string | null;
     costUsd?: number;
 };

package/src/provider-clipipe-tools.js

@@ -1,10 +1,14 @@
 'use strict';
 
 const { ProviderError } = require('./errors');
+const { hasUsageSignal } = require('./provider-usage');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
 
+// BA-24: raw claude-CLI envelope usage fields. Any present (even 0) ⇒ a usage signal; none ⇒ null.
+const CLAUDE_USAGE_KEYS = ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'];
+
 // CLIPipe tool-mode support (v0.32.0). A subscription CLI (`claude -p`, …) is a plain
 // TURN-provider: it takes text and returns text, with no native channel for a caller's tools. This
 // module adds Option C — SCHEMA-VALIDATED TOOL EMULATION: the caller's tools are described in the
@@ -124,23 +128,27 @@ function renderTranscript(messages) {
  * preset so the claude usage contract (token tiers, `modelUsage` first-key, `total_cost_usd`) lives
  * in exactly ONE place — a future CLI format change touches this function, not two copies.
  * @param {any} outer - the parsed outer CLI envelope (already validated non-null by the caller).
- * @returns {{usage: import('../types').Usage, model: string|null, costUsd?: number}}
+ * @returns {{usage: import('../types').Usage|null, model: string|null, costUsd?: number}}
  */
 function mapClaudeMeta(outer) {
-  const u = (outer.usage && typeof outer.usage === 'object') ? outer.usage : {};
-  /** @type {import('../types').Usage} */
-  const usage = {
-    inputTokens: Number(u.input_tokens) || 0,
-    outputTokens: Number(u.output_tokens) || 0,
-  };
+  // BA-24: an ABSENT/empty usage block ⇒ usage null (unpriceable), not a manufactured all-zeros object.
+  // The absent-block case is usually rescued by an authoritative `total_cost_usd` (a subscription run
+  // reports one even at $0 marginal → priced at source 'provider'); when the CLI omits BOTH, the round
+  // is honestly unpriced instead of a silent $0. Same principle line 136 already applies to the cache
+  // tiers, lifted one level up to the whole block. A present block with an explicit 0 field stays priced.
+  const raw = hasUsageSignal(outer.usage, CLAUDE_USAGE_KEYS) ? outer.usage : null;
+  /** @type {import('../types').Usage|null} */
+  const usage = raw
+    ? { inputTokens: Number(raw.input_tokens) || 0, outputTokens: Number(raw.output_tokens) || 0 }
+    : null;
   // 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;
+  if (usage && Number.isFinite(raw.cache_read_input_tokens)) usage.cacheReadTokens = raw.cache_read_input_tokens;
+  if (usage && Number.isFinite(raw.cache_creation_input_tokens)) usage.cacheCreationTokens = raw.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 = (outer.modelUsage && typeof outer.modelUsage === 'object')
     ? (Object.keys(outer.modelUsage)[0] ?? null)
     : null;
-  /** @type {{usage: import('../types').Usage, model: string|null, costUsd?: number}} */
+  /** @type {{usage: import('../types').Usage|null, model: string|null, costUsd?: number}} */
   const meta = { usage, model };
   // The CLI's own price is authoritative (a subscription run reports an equivalent cost even at $0
   // marginal) — feeds bareguard's USD axis with no local rate table. Only a finite number counts.
@@ -154,7 +162,7 @@ function mapClaudeMeta(outer) {
  * @property {string} [toolName]
  * @property {Record<string, any>} [toolArguments]
  * @property {string} [answer]
- * @property {import('../types').Usage} usage
+ * @property {import('../types').Usage|null} usage
  * @property {string|null} [model]
  * @property {number} [costUsd]
  */

package/src/provider-clipipe.d.ts

@@ -1,6 +1,7 @@
 export type Message = import("../types").Message;
 export type ToolDef = import("../types").ToolDef;
 export type GenerateResult = import("../types").GenerateResult;
+export type ParsedEnvelope = import("./provider-clipipe-tools.js").ParsedEnvelope;
 export type CLIPipeOptions = {
     /**
      * - CLI command to spawn (required).
@@ -142,11 +143,11 @@ export class CLIPipeProvider {
     toolProtocol: {
         name: string;
         turnArgs(systemPrompt: string): string[];
-        parseResult(stdout: string): ParsedEnvelope;
+        parseResult(stdout: string): import("./provider-clipipe-tools").ParsedEnvelope;
         probe: {
             system: string;
             user: string;
-            isCapable: (parsed: ParsedEnvelope) => boolean;
+            isCapable: (parsed: import("./provider-clipipe-tools").ParsedEnvelope) => boolean;
         };
     } | null;
     probeCapability: boolean;

package/src/provider-clipipe.js

@@ -8,6 +8,12 @@ const { createBridge, resolveSessionError, runSession } = require('./provider-cl
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
 /** @typedef {import('../types').GenerateResult} GenerateResult */
+// `toolProtocol`'s inferred type references ParsedEnvelope, which is declared in
+// provider-clipipe-tools.js. Without this alias the name is not in scope when tsc
+// emits this file's .d.ts, so the declaration shipped a bare `ParsedEnvelope` that
+// adopters could not resolve (TS2304) — invisible here because our own tsconfig
+// sets skipLibCheck.
+/** @typedef {import('./provider-clipipe-tools.js').ParsedEnvelope} ParsedEnvelope */
 
 /**
  * @typedef {object} CLIPipeOptions
@@ -217,13 +223,16 @@ class CLIPipeProvider {
         text: '',
         toolCalls: [],
         ...partial,
-        usage: { inputTokens: 0, outputTokens: 0, ...(partial.usage || {}) },
+        // BA-24: a parse fn that reports usage is trusted (missing tiers fill to 0); one that reports
+        // none surfaces null (unpriceable) rather than a manufactured all-zeros object.
+        usage: partial.usage ? { inputTokens: 0, outputTokens: 0, ...(/** @type {any} */ (partial.usage)) } : null,
       };
     }
+    // BA-24: raw text mode carries NO token data ever — honest null (unpriceable), not a synthetic $0.
     return {
       text: stdout,
       toolCalls: [],
-      usage: { inputTokens: 0, outputTokens: 0 },
+      usage: null,
     };
   }
 
@@ -333,12 +342,22 @@ class CLIPipeProvider {
     // captures a turn the CLI billed but never emitted as an event (measured — a bounded session's
     // cut-off turn). Summing the per-turn records is the fallback for a session we killed before its
     // result event. Either way the arithmetic is per-TURN, never per block-event (BA-17).
-    const usage = (meta && r.final.usage) ? meta.usage : r.turns.reduce((/** @type {any} */ a, t) => ({
-      inputTokens: a.inputTokens + (t.inputTokens || 0),
-      outputTokens: a.outputTokens + (t.outputTokens || 0),
-      cacheReadTokens: a.cacheReadTokens + (t.cacheReadTokens || 0),
-      cacheCreationTokens: a.cacheCreationTokens + (t.cacheCreationTokens || 0),
-    }), { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 });
+    // BA-24: key on the NORMALIZED meta.usage (a signal-bearing block), not the raw r.final.usage — an
+    // absent/empty raw block now normalizes to null, so fall back to the per-turn sum rather than null.
+    // The per-turn sum is a real signal ONLY when turns actually streamed; a session that died before
+    // any turn (zero-turn native session, no final usage block) has NOTHING to sum, and reducing over
+    // an empty array would MANUFACTURE a truthy all-zeros object — the exact absence→$0-priced laundering
+    // BA-24 eliminates at every other site. So absence (no meta.usage AND no turns) surfaces null.
+    const usage = (meta && meta.usage)
+      ? meta.usage
+      : (r.turns.length > 0
+        ? r.turns.reduce((/** @type {any} */ a, t) => ({
+          inputTokens: a.inputTokens + (t.inputTokens || 0),
+          outputTokens: a.outputTokens + (t.outputTokens || 0),
+          cacheReadTokens: a.cacheReadTokens + (t.cacheReadTokens || 0),
+          cacheCreationTokens: a.cacheCreationTokens + (t.cacheCreationTokens || 0),
+        }), { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 })
+        : null);
 
     const { stopReason, error } = resolveSessionError({
       // A bridge/guard terminal is more specific than the turn backstop, so it wins the tag.
@@ -362,7 +381,9 @@ class CLIPipeProvider {
     // real but SHORT of the session total. Sending the difference makes a gate's token axis add up
     // to exactly what the CLI itself reports — where sending the total would double-count everything
     // already streamed, and sending zero would leave the axis quietly under-fed.
-    const residual = subtractUsage(usage, r.turns);
+    // BA-24: a null usage (zero-turn session, no reported block) has no residual to reconcile — pass
+    // the honest null through to the meter rather than dereferencing null in subtractUsage.
+    const residual = usage ? subtractUsage(usage, r.turns) : null;
     if (this.onTurn) {
       try {
         await this.onTurn({

package/src/provider-gemini.d.ts

@@ -72,9 +72,9 @@ export class GeminiProvider {
      * (total = prompt + candidates + thoughts — confirmed against live usageMetadata). Implicit caching
      * has no separate write tier → cacheCreationTokens 0.
      * @param {any} u - raw `data.usageMetadata`
-     * @returns {import('../types').Usage}
+     * @returns {import('../types').Usage|null}
      */
-    _normalizeUsage(u: any): import("../types").Usage;
+    _normalizeUsage(u: any): import("../types").Usage | null;
     /**
      * @param {string} path
      * @param {Record<string, any>} body

package/src/provider-gemini.js

@@ -6,6 +6,10 @@ const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
 const { resolveTimeoutMs, applyRequestBounds } = require('./provider-http');
+const { hasUsageSignal } = require('./provider-usage');
+
+// BA-24: raw Gemini usageMetadata fields. Any present (even 0) ⇒ a usage signal; none ⇒ null.
+const GEMINI_USAGE_KEYS = ['promptTokenCount', 'candidatesTokenCount', 'thoughtsTokenCount', 'cachedContentTokenCount'];
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -168,9 +172,12 @@ class GeminiProvider {
    * (total = prompt + candidates + thoughts — confirmed against live usageMetadata). Implicit caching
    * has no separate write tier → cacheCreationTokens 0.
    * @param {any} u - raw `data.usageMetadata`
-   * @returns {import('../types').Usage}
+   * @returns {import('../types').Usage|null}
    */
   _normalizeUsage(u) {
+    // BA-24: no usageMetadata (or an empty one) ⇒ null, not an all-zeros object (which would launder an
+    // unpriceable round into a $0 PRICED one). A present block with an explicit 0 field stays priced.
+    if (!hasUsageSignal(u, GEMINI_USAGE_KEYS)) return null;
     const cacheRead = u?.cachedContentTokenCount || 0;
     return {
       inputTokens: Math.max(0, (u?.promptTokenCount || 0) - cacheRead),

package/src/provider-ollama.js

@@ -5,6 +5,10 @@ const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
 const { resolveTimeoutMs, applyRequestBounds } = require('./provider-http');
+const { hasUsageSignal } = require('./provider-usage');
+
+// BA-24: raw Ollama usage fields. Any present (even 0) ⇒ a usage signal; none ⇒ null (unpriceable).
+const OLLAMA_USAGE_KEYS = ['prompt_eval_count', 'eval_count'];
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -101,10 +105,11 @@ class OllamaProvider {
       // Like Gemini, Ollama has NO tool_use done_reason — a complete tool call returns `stop` (measured).
       // `hasToolCalls` lets the normalizer say so, instead of reporting a tool round as a clean finish.
       stopReason: normalizeStopReason(data.done_reason, 'ollama', { hasToolCalls: toolCalls.length > 0 }),
-      usage: {
-        inputTokens: data.prompt_eval_count || 0,
-        outputTokens: data.eval_count || 0,
-      },
+      // BA-24: honest null when the response carried no token counts — do NOT manufacture an all-zeros
+      // object (which launders an unpriceable round into a $0 PRICED one).
+      usage: hasUsageSignal(data, OLLAMA_USAGE_KEYS)
+        ? { inputTokens: data.prompt_eval_count || 0, outputTokens: data.eval_count || 0 }
+        : null,
       ...(temperatureDropped && { temperatureDropped: true }),
     };
   }

package/src/provider-openai.d.ts

@@ -82,9 +82,9 @@ export class OpenAIProvider {
      * remainder (else the cached tokens are double-counted and priced at the full input rate, a ~2x
      * over-charge on a warm prompt). OpenAI has no separate cache-write tier → cacheCreationTokens 0.
      * @param {any} u - raw `data.usage`
-     * @returns {import('../types').Usage}
+     * @returns {import('../types').Usage|null}
      */
-    _normalizeUsage(u: any): import("../types").Usage;
+    _normalizeUsage(u: any): import("../types").Usage | null;
     /**
      * @param {string} path
      * @param {Record<string, any>} body

package/src/provider-openai.js

@@ -6,6 +6,10 @@ const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
 const { resolveTimeoutMs, applyRequestBounds } = require('./provider-http');
+const { hasUsageSignal } = require('./provider-usage');
+
+// BA-24: raw OpenAI usage fields. Any present (even 0) ⇒ a usage signal; none ⇒ null (unpriceable).
+const OPENAI_USAGE_KEYS = ['prompt_tokens', 'completion_tokens', 'prompt_tokens_details'];
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -126,9 +130,12 @@ class OpenAIProvider {
    * remainder (else the cached tokens are double-counted and priced at the full input rate, a ~2x
    * over-charge on a warm prompt). OpenAI has no separate cache-write tier → cacheCreationTokens 0.
    * @param {any} u - raw `data.usage`
-   * @returns {import('../types').Usage}
+   * @returns {import('../types').Usage|null}
    */
   _normalizeUsage(u) {
+    // BA-24: no usage block (or an empty one) ⇒ null, not an all-zeros object (which would launder an
+    // unpriceable round into a $0 PRICED one). A present block with an explicit 0 field stays priced.
+    if (!hasUsageSignal(u, OPENAI_USAGE_KEYS)) return null;
     const cacheRead = u?.prompt_tokens_details?.cached_tokens || 0;
     return {
       inputTokens: Math.max(0, (u?.prompt_tokens || 0) - cacheRead),

package/src/provider-usage.d.ts

@@ -0,0 +1,24 @@
+/**
+ * BA-24: the discriminator between an ABSENT usage block and a PRESENT one whose token fields are
+ * legitimately 0.
+ *
+ * A provider that returns no usage information (the API sent a 200 with no `usage` block, or an empty
+ * `{}`) must surface `usage: null` so the round reads as UNPRICEABLE — `resolveRoundCost`'s
+ * `if (!usage) return {cost:null, source:null}` branch (the honest-null contract) only fires on a
+ * falsy usage. Coalescing an absent block into an all-zeros object (`data.usage?.field || 0` built
+ * unconditionally) launders that unknown into a $0 PRICED round — worse, at the confident `'tier'`
+ * rate label, so a consumer filtering for `'default'` guesses never sees it. That laundering was the
+ * BA-23 fix relocated one layer up: loop.js stopped feeding stale usage to the resolver, but every
+ * http provider still MANUFACTURED a truthy zero object, so the null branch stayed unreachable on the
+ * paid path.
+ *
+ * Per-field `|| 0` stays correct (a real round can report an individual tier as 0); it is the coalescing
+ * of the WHOLE block's absence into a default object that is the bug. A present block with an explicit
+ * zero — e.g. a cache-only round: `input_tokens:0` + `cache_read_input_tokens>0` — carries a signal and
+ * stays priced, because that field is present (`!= null`), even at value 0.
+ *
+ * @param {any} block - raw provider usage object (`data.usage` / `usageMetadata` / the CLI envelope's `usage`)
+ * @param {string[]} keys - the recognized raw field names for this provider
+ * @returns {boolean} true iff `block` is an object carrying at least one recognized field as a non-null value
+ */
+export function hasUsageSignal(block: any, keys: string[]): boolean;

package/src/provider-usage.js

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * BA-24: the discriminator between an ABSENT usage block and a PRESENT one whose token fields are
+ * legitimately 0.
+ *
+ * A provider that returns no usage information (the API sent a 200 with no `usage` block, or an empty
+ * `{}`) must surface `usage: null` so the round reads as UNPRICEABLE — `resolveRoundCost`'s
+ * `if (!usage) return {cost:null, source:null}` branch (the honest-null contract) only fires on a
+ * falsy usage. Coalescing an absent block into an all-zeros object (`data.usage?.field || 0` built
+ * unconditionally) launders that unknown into a $0 PRICED round — worse, at the confident `'tier'`
+ * rate label, so a consumer filtering for `'default'` guesses never sees it. That laundering was the
+ * BA-23 fix relocated one layer up: loop.js stopped feeding stale usage to the resolver, but every
+ * http provider still MANUFACTURED a truthy zero object, so the null branch stayed unreachable on the
+ * paid path.
+ *
+ * Per-field `|| 0` stays correct (a real round can report an individual tier as 0); it is the coalescing
+ * of the WHOLE block's absence into a default object that is the bug. A present block with an explicit
+ * zero — e.g. a cache-only round: `input_tokens:0` + `cache_read_input_tokens>0` — carries a signal and
+ * stays priced, because that field is present (`!= null`), even at value 0.
+ *
+ * @param {any} block - raw provider usage object (`data.usage` / `usageMetadata` / the CLI envelope's `usage`)
+ * @param {string[]} keys - the recognized raw field names for this provider
+ * @returns {boolean} true iff `block` is an object carrying at least one recognized field as a non-null value
+ */
+function hasUsageSignal(block, keys) {
+  if (!block || typeof block !== 'object') return false;
+  for (const k of keys) {
+    if (block[k] != null) return true;
+  }
+  return false;
+}
+
+module.exports = { hasUsageSignal };

package/src/recurse-retrieval.d.ts

@@ -143,7 +143,7 @@ export function buildScanTool(corpus: Slice[] | (() => Promise<Slice[]>), opts:
 /**
  * Build a SCAN slice-source backed by a litectx-RESIDENT corpus (facts/episodes the agent already accrued) —
  * the §10-step-7 deferral un-blocked by litectx 0.26's `enumerate` verb (spec:
- * docs/01-product/prd.md). Returns the generic async slice-source recurse's scan reads: a
+ * docs/archive/prd.md). Returns the generic async slice-source recurse's scan reads: a
  * `() => Promise<Slice[]>` that pages through EVERY row of `kind` via `enumerate` (exhaustive — the rank-free
  * read `recall` structurally cannot do) and maps each to `{id: item.path, text: item.body}`. recurse stays
  * litectx-agnostic: it depends on this source SHAPE, never on litectx (same stance as `remember`'s Store

package/src/recurse-retrieval.js

@@ -16,7 +16,7 @@
 //
 // THE CORPUS FOR SCAN IS A GENERIC ARRAY SLICE-SOURCE (`opts.corpus`), NOT litectx: litectx has no exhaustive,
 // rank-free enumerate verb today (every read is FTS-gated). The "corpus that already LIVES in litectx" case
-// waits on the litectx `enumerate` verb (docs/01-product/prd.md) and drops in behind this
+// waits on the litectx `enumerate` verb (docs/archive/prd.md) and drops in behind this
 // same slice-source socket with ZERO recurse changes — the same backend-agnostic stance as `remember`'s Store
 // socket. Composes AROUND a Loop; NEVER imported by loop.js.
 
@@ -326,7 +326,7 @@ const ENUM_PAGE = 200;
 /**
  * Build a SCAN slice-source backed by a litectx-RESIDENT corpus (facts/episodes the agent already accrued) —
  * the §10-step-7 deferral un-blocked by litectx 0.26's `enumerate` verb (spec:
- * docs/01-product/prd.md). Returns the generic async slice-source recurse's scan reads: a
+ * docs/archive/prd.md). Returns the generic async slice-source recurse's scan reads: a
  * `() => Promise<Slice[]>` that pages through EVERY row of `kind` via `enumerate` (exhaustive — the rank-free
  * read `recall` structurally cannot do) and maps each to `{id: item.path, text: item.body}`. recurse stays
  * litectx-agnostic: it depends on this source SHAPE, never on litectx (same stance as `remember`'s Store

package/src/recurse.js

@@ -1037,7 +1037,7 @@ async function recurseRefineLeaf(task, ctx, opts, state) {
  * never folded into the count as a zero; a governance HaltError mid-scan → clean incomplete.
  *
  * The corpus is the generic array slice-source `opts.corpus`. Absent it, scan has nothing to read — litectx's
- * resident-corpus enumerate path is deferred (docs/01-product/prd.md) — so we return an
+ * resident-corpus enumerate path is deferred (docs/archive/prd.md) — so we return an
  * honest incomplete, never a fabricated zero.
  * @param {string} task
  * @param {RecurseCtx} ctx

package/types/index.d.ts

@@ -86,7 +86,9 @@ export interface ToolCall {
 export interface GenerateResult {
   text: string;
   toolCalls: ToolCall[];
-  usage: Usage;
+  /** Normalized token usage, or `null` when the provider reported NO usage block (BA-24) — an
+   *  unpriceable round, distinct from a present block whose fields are legitimately 0. */
+  usage: Usage | null;
   /** Model id the response was produced by; preferred over Provider.model for cost accounting. */
   model?: string | null;
   /**