@ai-dossier/core 1.4.1 → 1.5.0

package/README.md

@@ -105,6 +105,9 @@ import {
   verifyWithEd25519,
   verifyWithKms,
   loadTrustedKeys,
+  findTrustedIdentifier,
+  normalizePublicKey,
+  isSupportedPublicKey,
 } from '@ai-dossier/core';
 ```
 
@@ -119,7 +122,7 @@ console.log(result.valid); // true | false
 
 #### `verifyWithEd25519(content: string, signature: string, publicKey: string): VerifyResult`
 
-Verify an Ed25519 signature directly.
+Verify an Ed25519 signature directly. `publicKey` may be SPKI PEM, raw 32-byte base64, or base64 SPKI DER.
 
 #### `verifyWithKms(content: string, signature: string, keyId: string, region?: string): Promise<VerifyResult>`
 
@@ -127,7 +130,17 @@ Verify an ECDSA-SHA-256 signature using AWS KMS.
 
 #### `loadTrustedKeys(filePath?: string): Map<string, string>`
 
-Load trusted public keys from a file (default: `~/.dossier/trusted-keys.txt`). Returns a map of public key to key ID.
+Load trusted public keys from a file (default: `~/.dossier/trusted-keys.txt`), format `<public-key> <identifier>` one per line. Returns a map of public key to identifier, indexed under both the written and the normalized form. Unreadable lines are reported to stderr, not dropped silently.
+
+#### `findTrustedIdentifier(trustedKeys, signature): string | undefined`
+
+Resolve the identifier a signature is trusted under. Use this rather than probing the map by hand — it consults `key_id` only when there is no `public_key`, which is what stops a dossier from claiming a trusted signer's identity while verifying under a different key.
+
+#### `normalizePublicKey(key) / isSupportedPublicKey(key)`
+
+Reduce an Ed25519 key to its canonical raw 32-byte base64 form, and test whether a key is one this project can verify against. Validate with `isSupportedPublicKey` before *storing* a key: `normalizePublicKey` deliberately passes uninterpretable input through.
+
+See [core API reference](../../docs/reference/core-api.md#key-format-and-trust-file-helpers) for the full trust-file helper set.
 
 ### Linting
 
@@ -192,6 +205,38 @@ const verifier = registry.get('ed25519');
 const result = await verifier.verify(content, signature);
 ```
 
+### Agent Usage & Run Log
+
+Shared with `packages/sched` so both the `ai-dossier run` headless path and the
+scheduler's detached dispatch path agree on which block of an agent's result is the
+source of record.
+
+```typescript
+import {
+  parseAgentUsage,      // claude: one --output-format json object, OR a stream-json event stream
+  parseOpenCodeUsage,   // opencode: a `run --format json` JSONL event stream
+  usageParserFor,       // pick the parser from the spawned binary's basename
+  runsLogPath,          // ~/.dossier/runs.jsonl
+  SCHED_DISPATCH_EVENT, // the sched dispatch-log preamble `type`, skipped by both parsers
+  type AgentRunUsage,
+  type RunLogEntry,
+} from '@ai-dossier/core';
+
+const usage = parseAgentUsage(stdout);
+// → { model, input_tokens, output_tokens, cache_creation_tokens,
+//     cache_read_tokens, total_cost_usd, result_text } — every field null
+//     when the agent did not report it; values are never fabricated.
+```
+
+`parseAgentUsage` treats the agent's per-model **`modelUsage` map as the source of
+record** whenever it carries at least one object-shaped entry, summed across models. The
+top-level `usage` block is used only when `modelUsage` has no such entry — the two are
+never blended field-by-field, because they have been observed to disagree enough to
+fabricate a ~43% "saving" when mixed (ai-dossier#524). Cost is read from `costUSD` (the
+key claude writes), falling back to the top-level total when `modelUsage` reports no cost
+at all. For a `stream-json` log the final `type:"result"` event wins; with no such event
+(an agent killed mid-run) per-turn `assistant` usage is summed instead.
+
 ## Types
 
 All TypeScript types are exported from the package root:

package/dist/agent-usage.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Parsers for headless-agent JSON result output — the token/cost/model data
+ * an `ai-dossier run` or `packages/sched` dispatch needs to record in
+ * `runs.jsonl` (#458, #524).
+ *
+ * Shared between `cli` (the `ai-dossier run` headless path) and `sched` (the
+ * scheduler's detached-agent dispatch path) so both consumers agree on which
+ * block of a claude/opencode result is the source of record — the divergence
+ * between them (one reading `usage`, the other `modelUsage`, and disagreeing
+ * enough to fabricate a ~43% "saving" when mixed, ai-dossier#524) is exactly
+ * the bug this module exists to close off. Lives in `core`, not `cli`,
+ * because `sched` cannot depend on `cli` (the dependency runs the other way:
+ * `cli` already depends on both `core` and `sched`).
+ */
+/**
+ * Usage data extracted from an agent CLI's JSON result output.
+ * Every field is null when the CLI did not report it — values are never
+ * fabricated or estimated.
+ */
+export interface AgentRunUsage {
+    /** Model id the agent reported; comma-joined when several models ran (token/cost fields are totals across all). */
+    model: string | null;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    /** Cache-creation (write) input tokens, summed across models when several ran. */
+    cache_creation_tokens: number | null;
+    /** Cache-read input tokens, summed across models when several ran. */
+    cache_read_tokens: number | null;
+    total_cost_usd: number | null;
+    /** The final result text (claude's `result` field), for re-emitting to stdout. */
+    result_text: string | null;
+}
+/**
+ * `type` of the preamble line `packages/sched` writes to a dispatch log at
+ * spawn time (ai-dossier#524). It exists so a log is never 0 bytes for a unit
+ * that ran; every parser here skips it rather than counting it as agent
+ * output. Shared from `core` so the writer (`sched`'s `createSpawnDeps`) and
+ * the readers (below) can never drift apart on the sentinel's spelling.
+ */
+export declare const SCHED_DISPATCH_EVENT = "sched-dispatch";
+/**
+ * Parse a claude headless result into usage data — both output formats.
+ *
+ * Accepts either shape, because the two consumers spawn claude differently:
+ *
+ * - **A single JSON object** (`--output-format json`, what `ai-dossier run`
+ *   uses): parsed whole.
+ * - **A JSONL event stream** (`--output-format stream-json`, what the
+ *   scheduler dispatches with since ai-dossier#524): the LAST `type:"result"`
+ *   event wins — a per-unit log is append-mode, so a prior dispatch's result
+ *   may precede this one in the same slice. With no `result` event at all (an
+ *   agent killed mid-run), per-turn `assistant` usage is summed instead, so an
+ *   interrupted dispatch still reports the tokens it really spent.
+ *
+ * Lines that do not parse as JSON objects are skipped rather than
+ * disqualifying the stream: the sched dispatch preamble
+ * ({@link SCHED_DISPATCH_EVENT}) sits at the head of every dispatch slice, and
+ * an agent killed mid-write leaves a truncated final line.
+ *
+ * Returns null when the output parses as neither shape (and for a stream
+ * holding no usage-bearing event). A result object that simply reported no
+ * usage yields an entry whose fields are all null, not `null` itself —
+ * "the agent reported nothing" and "there was no agent output" stay distinct.
+ */
+export declare function parseAgentUsage(stdout: string | null | undefined): AgentRunUsage | null;
+/**
+ * Parse an `opencode run --format json` result stream into usage data (#459).
+ *
+ * opencode emits one JSON event per line: the assistant's text arrives in
+ * `type:"text"` parts, and per-step token/cost totals in `type:"step_finish"`
+ * parts (a multi-step run emits several — tokens and cost are summed), with
+ * cache counts nested as `tokens.cache: { write, read }`. The model id is not
+ * present in the events, so `model` is null and callers fall back to the
+ * requested --model alias — that field, and only that field, is genuinely
+ * unavailable here rather than merely absent. Returns null when the output
+ * holds no opencode event at all; individual non-JSON lines (stderr warnings
+ * interleaved by the scheduler's merged stdout/stderr fd) are skipped, not
+ * treated as disqualifying.
+ *
+ * **Cross-agent caveat.** opencode reports `tokens.reasoning` SEPARATELY from
+ * `tokens.output` (a step's `total` is input + output + reasoning +
+ * cache.read), whereas claude folds thinking tokens into `output_tokens`.
+ * Reasoning is 45-75% of generated tokens in real logs, so an opencode
+ * `output_tokens` is NOT directly comparable to a claude one — do not put the
+ * two in the same column of a cost comparison without saying so. It is left
+ * out rather than summed in because this module never derives a value the
+ * agent did not report; capturing it needs a field of its own on
+ * {@link AgentRunUsage} and `RunLogEntry`, which is a schema change beyond
+ * ai-dossier#524's scope.
+ */
+export declare function parseOpenCodeUsage(stdout: string | null | undefined): AgentRunUsage | null;
+/**
+ * Pick the usage parser for a dispatched agent, keyed off the spawned
+ * binary's basename — `opencode` (any path) routes to
+ * {@link parseOpenCodeUsage}; everything else, including an
+ * operator-configured command this build doesn't specifically recognize,
+ * falls back to {@link parseAgentUsage} (the claude shape). A command this
+ * build doesn't recognize is not guessed at further than that fallback —
+ * its output either parses as a claude-shaped JSON result or the parser
+ * returns null, never a fabricated guess.
+ */
+export declare function usageParserFor(cmd0: string): (stdout: string | null | undefined) => AgentRunUsage | null;
+//# sourceMappingURL=agent-usage.d.ts.map

package/dist/agent-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-usage.d.ts","sourceRoot":"","sources":["../src/agent-usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,mHAAmH;IACnH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kFAAkF;IAClF,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kFAAkF;IAClF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAsFD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAoLrD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,IAAI,CA6BvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,IAAI,CA6F1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,GACX,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,aAAa,GAAG,IAAI,CAE7D"}

package/dist/agent-usage.js

@@ -0,0 +1,493 @@
+"use strict";
+/**
+ * Parsers for headless-agent JSON result output — the token/cost/model data
+ * an `ai-dossier run` or `packages/sched` dispatch needs to record in
+ * `runs.jsonl` (#458, #524).
+ *
+ * Shared between `cli` (the `ai-dossier run` headless path) and `sched` (the
+ * scheduler's detached-agent dispatch path) so both consumers agree on which
+ * block of a claude/opencode result is the source of record — the divergence
+ * between them (one reading `usage`, the other `modelUsage`, and disagreeing
+ * enough to fabricate a ~43% "saving" when mixed, ai-dossier#524) is exactly
+ * the bug this module exists to close off. Lives in `core`, not `cli`,
+ * because `sched` cannot depend on `cli` (the dependency runs the other way:
+ * `cli` already depends on both `core` and `sched`).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHED_DISPATCH_EVENT = void 0;
+exports.parseAgentUsage = parseAgentUsage;
+exports.parseOpenCodeUsage = parseOpenCodeUsage;
+exports.usageParserFor = usageParserFor;
+const path = __importStar(require("node:path"));
+/**
+ * Largest token count accepted from an agent (#524). Well above any real run
+ * (a 1M-token context ×1000 turns), and low enough that summing a cohort of
+ * them in `sched stats` cannot reach Infinity.
+ */
+const MAX_REPORTED_TOKENS = 1e15;
+/** Largest cost in USD accepted from an agent (#524) — no real dispatch approaches it. */
+const MAX_REPORTED_COST_USD = 1e6;
+/**
+ * Narrow untrusted agent output to a finite, non-negative number within a
+ * sane ceiling (#524). Used for token counts AND for costs — hence the
+ * explicit `max`, since the two have very different plausible ranges.
+ *
+ * The ceiling is not paranoia: `sched stats` sums these across a cohort, and
+ * a single `1e308` entry would carry the whole TOTAL row to Infinity, which
+ * the formatter renders as `-` — silently blanking every legitimate run
+ * alongside it. Out-of-range values are rejected (null = "not reported")
+ * rather than clamped, so a bogus number is never presented as a real one.
+ */
+function toBounded(value, max) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= max
+        ? value
+        : null;
+}
+/** Token-count flavour of {@link toBounded}. */
+function toCount(value) {
+    return toBounded(value, MAX_REPORTED_TOKENS);
+}
+/** Cost flavour of {@link toBounded} — a USD amount, not a count. */
+function toCost(value) {
+    return toBounded(value, MAX_REPORTED_COST_USD);
+}
+/** Longest `model` value written to `runs.jsonl` before truncation (#524). */
+const MAX_MODEL_LENGTH = 200;
+/**
+ * Most model names joined into one `model` value (#524). The map/stream those
+ * names come from is agent-controlled and unbounded, so the join is capped
+ * before {@link sanitizeModel} ever sees it — 16 distinct models in one run
+ * is already far beyond anything real.
+ */
+const MAX_MODELS_JOINED = 16;
+/** Join model names for the `model` field, bounded by {@link MAX_MODELS_JOINED}. */
+function joinModels(names) {
+    if (names.length === 0)
+        return null;
+    if (names.length === 1)
+        return names[0];
+    return names.slice(0, MAX_MODELS_JOINED).join(',');
+}
+/**
+ * `model` is copied verbatim from untrusted agent JSON into a `runs.jsonl`
+ * entry a later command (`ai-dossier history`, `sched stats`) may render.
+ * Strip control characters (the terminal-escape/log-injection risk) and cap
+ * the length, rather than trusting an agent-controlled string unbounded.
+ */
+function sanitizeModel(value) {
+    if (value === null)
+        return null;
+    let clean = '';
+    // Bound the WORK, not just the result: `value` is agent-controlled and can
+    // be arbitrarily long, so stop as soon as the cap is reached rather than
+    // materializing a sanitized copy of the whole string first.
+    for (const char of value) {
+        if (clean.length >= MAX_MODEL_LENGTH)
+            break;
+        const code = char.codePointAt(0) ?? 0;
+        // C0 (< 0x20), DEL (0x7f) and C1 (0x80-0x9f) alike: U+009B is the 8-bit
+        // CSI, which a terminal in a non-UTF-8 locale acts on exactly like ESC[.
+        if (code >= 0x20 && code !== 0x7f && !(code >= 0x80 && code <= 0x9f))
+            clean += char;
+    }
+    return clean;
+}
+/** Narrow an unknown value to a plain-object record; null for anything else. */
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * `type` of the preamble line `packages/sched` writes to a dispatch log at
+ * spawn time (ai-dossier#524). It exists so a log is never 0 bytes for a unit
+ * that ran; every parser here skips it rather than counting it as agent
+ * output. Shared from `core` so the writer (`sched`'s `createSpawnDeps`) and
+ * the readers (below) can never drift apart on the sentinel's spelling.
+ */
+exports.SCHED_DISPATCH_EVENT = 'sched-dispatch';
+/**
+ * Event `type`s that only ever appear INSIDE a stream, never as a whole
+ * `--output-format json` payload. A single such line must be parsed as a
+ * one-line stream, not mistaken for a result object (#524 review).
+ */
+const STREAM_EVENT_TYPES = new Set([
+    'assistant',
+    'user',
+    'system',
+    exports.SCHED_DISPATCH_EVENT,
+]);
+/** Parse one string as a JSON object; null for anything else (array, scalar, malformed). */
+function parseJsonObject(text) {
+    try {
+        return asRecord(JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract usage from a claude `result`-shaped object — the payload of
+ * `--output-format json`, and of the final `type:"result"` event of
+ * `--output-format stream-json`. Both carry the same fields.
+ *
+ * `modelUsage` (summed across every model entry) is the source of record for
+ * token counts and cost — it is the only block that reflects a multi-model
+ * run accurately. The top-level `usage` / `total_cost_usd` (older: `cost_usd`)
+ * fields are used ONLY when `modelUsage` has no object-shaped entry at all:
+ * they are never blended field-by-field with it, because the two blocks have been
+ * observed to disagree (ai-dossier#524) — picking one field from each would
+ * silently produce a number neither block actually reported.
+ */
+function extractResultUsage(parsed) {
+    const usage = asRecord(parsed.usage) ?? {};
+    const modelUsage = asRecord(parsed.modelUsage);
+    // Keep only object-shaped entries; a scalar entry is malformed, not a model.
+    const modelEntries = modelUsage
+        ? Object.entries(modelUsage).filter((entry) => !!asRecord(entry[1]))
+        : [];
+    const hasModelUsage = modelEntries.length > 0;
+    /** Sum one field across every model entry, trying each spelling in turn. */
+    const sumFromModelUsage = (keys, narrow = toCount) => {
+        let sum = 0;
+        let seen = false;
+        for (const [, entry] of modelEntries) {
+            let value = null;
+            for (const key of keys) {
+                value = narrow(entry[key]);
+                if (value !== null)
+                    break;
+            }
+            if (value !== null) {
+                sum += value;
+                seen = true;
+            }
+        }
+        return seen ? sum : null;
+    };
+    // modelUsage wins whenever it carries at least one object-shaped entry —
+    // even if that entry only answers some of the fields — so a run's numbers
+    // always come from a single, consistent block rather than a per-field blend
+    // with `usage`. (`modelUsage: {}`, or a map whose every entry is a scalar,
+    // is malformed rather than present: `usage` is used in that case.)
+    const input_tokens = hasModelUsage
+        ? sumFromModelUsage(['inputTokens', 'input_tokens'])
+        : toCount(usage.input_tokens);
+    const output_tokens = hasModelUsage
+        ? sumFromModelUsage(['outputTokens', 'output_tokens'])
+        : toCount(usage.output_tokens);
+    const cache_creation_tokens = hasModelUsage
+        ? sumFromModelUsage(['cacheCreationInputTokens', 'cache_creation_input_tokens'])
+        : toCount(usage.cache_creation_input_tokens);
+    const cache_read_tokens = hasModelUsage
+        ? sumFromModelUsage(['cacheReadInputTokens', 'cache_read_input_tokens'])
+        : toCount(usage.cache_read_input_tokens);
+    // `costUSD` FIRST: that is the key claude actually writes inside a
+    // `modelUsage` entry (verified against a live claude stats artifact, #524
+    // review). `totalCostUsd`/`total_cost_usd` are kept as tolerated spellings.
+    // When modelUsage reports no cost key at all, fall back to the top-level
+    // total rather than reporting null — the whole-run cost is not a per-field
+    // blend of two token blocks, it is the one number both shapes agree on, and
+    // dropping it silently regressed `ai-dossier run`'s existing cost recording.
+    const costFromModelUsage = hasModelUsage
+        ? sumFromModelUsage(['costUSD', 'totalCostUsd', 'total_cost_usd'], toCost)
+        : null;
+    const total_cost_usd = costFromModelUsage ?? toCost(parsed.total_cost_usd) ?? toCost(parsed.cost_usd);
+    const modelFromUsage = joinModels(modelEntries.map(([key]) => key));
+    const rawModel = typeof parsed.model === 'string' && parsed.model ? parsed.model : modelFromUsage;
+    const model = sanitizeModel(rawModel);
+    const result_text = typeof parsed.result === 'string' ? parsed.result : null;
+    return {
+        model,
+        input_tokens,
+        output_tokens,
+        cache_creation_tokens,
+        cache_read_tokens,
+        total_cost_usd,
+        result_text,
+    };
+}
+/**
+ * Sum per-turn usage from `type:"assistant"` stream events — the fallback for
+ * a run that produced NO final `result` event (ai-dossier#524).
+ *
+ * The scheduler kills an agent that is still alive when ground truth says its
+ * unit is already done (`reconcileRunning`'s external-advance branch), and a
+ * killed agent never emits its `result` event. Before stream-json that meant
+ * zero recoverable tokens for those dispatches — six of the eleven pilot units.
+ * Each `assistant` event carries the usage of the request that produced it, so
+ * summing them recovers what the run actually spent up to the kill.
+ *
+ * `total_cost_usd` stays null: per-turn events do not report cost, and this
+ * path must not fabricate one from token counts.
+ */
+function sumAssistantUsage(events) {
+    let input = 0;
+    let output = 0;
+    let cacheCreation = 0;
+    let cacheRead = 0;
+    let sawInput = false;
+    let sawOutput = false;
+    let sawCacheCreation = false;
+    let sawCacheRead = false;
+    const models = new Set();
+    for (const event of events) {
+        const message = asRecord(event.message);
+        if (!message)
+            continue;
+        if (typeof message.model === 'string' && message.model)
+            models.add(message.model);
+        const usage = asRecord(message.usage);
+        if (!usage)
+            continue;
+        const inputTokens = toCount(usage.input_tokens);
+        if (inputTokens !== null) {
+            input += inputTokens;
+            sawInput = true;
+        }
+        const outputTokens = toCount(usage.output_tokens);
+        if (outputTokens !== null) {
+            output += outputTokens;
+            sawOutput = true;
+        }
+        const cacheCreationTokens = toCount(usage.cache_creation_input_tokens);
+        if (cacheCreationTokens !== null) {
+            cacheCreation += cacheCreationTokens;
+            sawCacheCreation = true;
+        }
+        const cacheReadTokens = toCount(usage.cache_read_input_tokens);
+        if (cacheReadTokens !== null) {
+            cacheRead += cacheReadTokens;
+            sawCacheRead = true;
+        }
+    }
+    return {
+        model: sanitizeModel(joinModels([...models])),
+        input_tokens: sawInput ? input : null,
+        output_tokens: sawOutput ? output : null,
+        cache_creation_tokens: sawCacheCreation ? cacheCreation : null,
+        cache_read_tokens: sawCacheRead ? cacheRead : null,
+        total_cost_usd: null,
+        result_text: null,
+    };
+}
+/**
+ * Parse a claude headless result into usage data — both output formats.
+ *
+ * Accepts either shape, because the two consumers spawn claude differently:
+ *
+ * - **A single JSON object** (`--output-format json`, what `ai-dossier run`
+ *   uses): parsed whole.
+ * - **A JSONL event stream** (`--output-format stream-json`, what the
+ *   scheduler dispatches with since ai-dossier#524): the LAST `type:"result"`
+ *   event wins — a per-unit log is append-mode, so a prior dispatch's result
+ *   may precede this one in the same slice. With no `result` event at all (an
+ *   agent killed mid-run), per-turn `assistant` usage is summed instead, so an
+ *   interrupted dispatch still reports the tokens it really spent.
+ *
+ * Lines that do not parse as JSON objects are skipped rather than
+ * disqualifying the stream: the sched dispatch preamble
+ * ({@link SCHED_DISPATCH_EVENT}) sits at the head of every dispatch slice, and
+ * an agent killed mid-write leaves a truncated final line.
+ *
+ * Returns null when the output parses as neither shape (and for a stream
+ * holding no usage-bearing event). A result object that simply reported no
+ * usage yields an entry whose fields are all null, not `null` itself —
+ * "the agent reported nothing" and "there was no agent output" stay distinct.
+ */
+function parseAgentUsage(stdout) {
+    if (typeof stdout !== 'string' || stdout.trim() === '')
+        return null;
+    // `--output-format json`: the whole payload is one object. Checked first so
+    // a pretty-printed (multi-line) result is not mistaken for an event stream.
+    // Stream event types are excluded, or a stream that happens to hold exactly
+    // ONE line (an agent killed after a single turn, or whose preamble write
+    // failed) would take this path and report all-null instead of falling
+    // through to the per-turn sum below.
+    const single = parseJsonObject(stdout);
+    if (single && !STREAM_EVENT_TYPES.has(single.type))
+        return extractResultUsage(single);
+    let lastResult = null;
+    const assistants = [];
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const event = parseJsonObject(trimmed);
+        if (!event || event.type === exports.SCHED_DISPATCH_EVENT)
+            continue;
+        if (event.type === 'result')
+            lastResult = event;
+        else if (event.type === 'assistant')
+            assistants.push(event);
+    }
+    if (lastResult)
+        return extractResultUsage(lastResult);
+    if (assistants.length > 0)
+        return sumAssistantUsage(assistants);
+    return null;
+}
+/**
+ * Parse an `opencode run --format json` result stream into usage data (#459).
+ *
+ * opencode emits one JSON event per line: the assistant's text arrives in
+ * `type:"text"` parts, and per-step token/cost totals in `type:"step_finish"`
+ * parts (a multi-step run emits several — tokens and cost are summed), with
+ * cache counts nested as `tokens.cache: { write, read }`. The model id is not
+ * present in the events, so `model` is null and callers fall back to the
+ * requested --model alias — that field, and only that field, is genuinely
+ * unavailable here rather than merely absent. Returns null when the output
+ * holds no opencode event at all; individual non-JSON lines (stderr warnings
+ * interleaved by the scheduler's merged stdout/stderr fd) are skipped, not
+ * treated as disqualifying.
+ *
+ * **Cross-agent caveat.** opencode reports `tokens.reasoning` SEPARATELY from
+ * `tokens.output` (a step's `total` is input + output + reasoning +
+ * cache.read), whereas claude folds thinking tokens into `output_tokens`.
+ * Reasoning is 45-75% of generated tokens in real logs, so an opencode
+ * `output_tokens` is NOT directly comparable to a claude one — do not put the
+ * two in the same column of a cost comparison without saying so. It is left
+ * out rather than summed in because this module never derives a value the
+ * agent did not report; capturing it needs a field of its own on
+ * {@link AgentRunUsage} and `RunLogEntry`, which is a schema change beyond
+ * ai-dossier#524's scope.
+ */
+function parseOpenCodeUsage(stdout) {
+    if (typeof stdout !== 'string' || stdout.trim() === '')
+        return null;
+    let sawEvent = false;
+    const texts = [];
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheCreationTokens = 0;
+    let cacheReadTokens = 0;
+    let costUsd = 0;
+    let sawUsage = false;
+    let sawCacheCreation = false;
+    let sawCacheRead = false;
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const event = parseJsonObject(trimmed);
+        // Skip an unparseable line rather than discarding the whole stream
+        // (#524 review). `createSpawnDeps` merges stderr into the SAME fd as
+        // stdout, and opencode writes ANSI-coloured warnings there ("permission
+        // requested: ... auto-rejecting"), so ONE such line in a 1,600-line log
+        // used to null out the entire run — ~$28 and ~97M cache-read tokens
+        // across two real logs on a six-run cohort, recorded as indistinguishable
+        // nulls. Format-mismatch detection is preserved by `sawEvent` below: a
+        // stream with no valid opencode event at all still returns null.
+        if (!event)
+            continue;
+        // The sched dispatch preamble (#524) is written by the scheduler, not by
+        // opencode: skip it WITHOUT setting `sawEvent`, so a log holding only a
+        // preamble still reads as "the agent wrote nothing" (null) rather than an
+        // all-null usage object implying opencode reported no tokens.
+        if (event.type === exports.SCHED_DISPATCH_EVENT)
+            continue;
+        sawEvent = true;
+        const part = asRecord(event.part);
+        if (event.type === 'text' && part && typeof part.text === 'string') {
+            texts.push(part.text);
+        }
+        if (event.type === 'step_finish' && part) {
+            const tokens = asRecord(part.tokens);
+            if (tokens) {
+                const input = toCount(tokens.input);
+                if (input !== null) {
+                    inputTokens += input;
+                    sawUsage = true;
+                }
+                const output = toCount(tokens.output);
+                if (output !== null) {
+                    outputTokens += output;
+                    sawUsage = true;
+                }
+                // opencode nests cache counts one level down, as
+                // `tokens.cache: { write, read }` — verified against a real 310-event
+                // dispatch log (#524 review). They were previously hardcoded null on
+                // the mistaken belief opencode did not report them, silently dropping
+                // tens of millions of cache-read tokens per run.
+                const cache = asRecord(tokens.cache);
+                if (cache) {
+                    const write = toCount(cache.write);
+                    if (write !== null) {
+                        cacheCreationTokens += write;
+                        sawCacheCreation = true;
+                        sawUsage = true;
+                    }
+                    const read = toCount(cache.read);
+                    if (read !== null) {
+                        cacheReadTokens += read;
+                        sawCacheRead = true;
+                        sawUsage = true;
+                    }
+                }
+            }
+            const cost = toCost(part.cost);
+            if (cost !== null) {
+                costUsd += cost;
+                sawUsage = true;
+            }
+        }
+    }
+    if (!sawEvent)
+        return null;
+    return {
+        model: null,
+        input_tokens: sawUsage ? inputTokens : null,
+        output_tokens: sawUsage ? outputTokens : null,
+        cache_creation_tokens: sawCacheCreation ? cacheCreationTokens : null,
+        cache_read_tokens: sawCacheRead ? cacheReadTokens : null,
+        total_cost_usd: sawUsage ? costUsd : null,
+        result_text: texts.length > 0 ? texts.join('') : null,
+    };
+}
+/**
+ * Pick the usage parser for a dispatched agent, keyed off the spawned
+ * binary's basename — `opencode` (any path) routes to
+ * {@link parseOpenCodeUsage}; everything else, including an
+ * operator-configured command this build doesn't specifically recognize,
+ * falls back to {@link parseAgentUsage} (the claude shape). A command this
+ * build doesn't recognize is not guessed at further than that fallback —
+ * its output either parses as a claude-shaped JSON result or the parser
+ * returns null, never a fabricated guess.
+ */
+function usageParserFor(cmd0) {
+    return path.basename(cmd0) === 'opencode' ? parseOpenCodeUsage : parseAgentUsage;
+}
+//# sourceMappingURL=agent-usage.js.map