llm-cost-attribution 0.1.0

package/src/pricing.mjs

@@ -0,0 +1,157 @@
+/**
+ * Per-model rate lookup + cost calculation.
+ *
+ * Costs are USD computed from list API rates. They are a *counterfactual*
+ * for users on flat-rate subscription plans (Claude Max, Codex Pro): the
+ * dollar number is what the same token volume would have cost on
+ * pay-as-you-go API, not the marginal cost of running it on a subscription.
+ */
+import { PRICING_TABLE, STALE_AFTER_DAYS } from './pricing-rates.mjs';
+
+const RATES_BY_NAME = buildRatesMap(PRICING_TABLE);
+
+function buildRatesMap(entries) {
+  const map = new Map();
+  for (const entry of entries) map.set(entry.model, entry);
+  return map;
+}
+
+/**
+ * Canonical name lookup. Strips Anthropic's `-YYYYMMDD` date suffix and
+ * `-latest`, and rewrites hyphenated decimals back to dotted form (the
+ * Claude transcript emits `claude-sonnet-4-6` for the model the rate
+ * table calls `claude-sonnet-4.6`).
+ */
+export function normalizeModelName(model) {
+  if (typeof model !== 'string') return '';
+  let s = model.replace(/-\d{8}$/, '').replace(/-latest$/, '');
+  s = s.replace(/(\d)-(\d)/g, '$1.$2');
+  return s;
+}
+
+/**
+ * Look up rates for a model name. Returns `null` if not in the table.
+ */
+export function ratesForModel(model) {
+  if (typeof model !== 'string' || model === '') return null;
+  return RATES_BY_NAME.get(model) ?? RATES_BY_NAME.get(normalizeModelName(model)) ?? null;
+}
+
+/**
+ * Compute API-equivalent cost from a TokenBuckets-shaped object.
+ *
+ * Returns:
+ *   {
+ *     model,
+ *     rates,                  the PricingEntry used
+ *     buckets: [              one entry per non-zero bucket, in display order
+ *       { label, tokens, ratePerMillion, costUsd, note? },
+ *       ...
+ *     ],
+ *     totalUsd,               sum of buckets[i].costUsd
+ *   }
+ *
+ * Returns `null` if no rates known for the model. Buckets with zero
+ * tokens are omitted. Buckets whose provider doesn't price them
+ * separately (e.g. Anthropic cache writes for an OpenAI model) are
+ * folded into `inputUncached` so the grand total still matches.
+ *
+ * @param {string} model
+ * @param {object} buckets   TokenBuckets shape (inputUncached, inputCached,
+ *                           cacheCreate5m, cacheCreate1h, outputVisible,
+ *                           outputReasoning).
+ */
+export function calculateCost(model, buckets) {
+  const rates = ratesForModel(model);
+  if (rates === null) return null;
+
+  const rows = [];
+
+  // Input — uncached. Cache writes that the provider doesn't price
+  // separately get rolled into here too.
+  let inputUncached = numOrZero(buckets.inputUncached);
+  if (rates.cacheWrite5mPerMillionUsd === null) {
+    inputUncached += numOrZero(buckets.cacheCreate5m);
+  }
+  if (rates.cacheWrite1hPerMillionUsd === null) {
+    inputUncached += numOrZero(buckets.cacheCreate1h);
+  }
+  pushIfNonZero(rows, 'input uncached', inputUncached, rates.inputPerMillionUsd);
+
+  // Input — cache read.
+  if (rates.cachedInputPerMillionUsd !== null) {
+    pushIfNonZero(rows, 'cache read', numOrZero(buckets.inputCached), rates.cachedInputPerMillionUsd);
+  } else {
+    // Provider doesn't price cache reads separately — treat them as uncached
+    // input. Add to the input-uncached row we already emitted (if any) or
+    // create one. Simpler: just emit a separate row at the input rate.
+    pushIfNonZero(rows, 'cache read', numOrZero(buckets.inputCached), rates.inputPerMillionUsd);
+  }
+
+  // Cache writes — only when the provider prices them separately.
+  if (rates.cacheWrite5mPerMillionUsd !== null) {
+    pushIfNonZero(rows, 'cache write 5m', numOrZero(buckets.cacheCreate5m), rates.cacheWrite5mPerMillionUsd);
+  }
+  if (rates.cacheWrite1hPerMillionUsd !== null) {
+    pushIfNonZero(rows, 'cache write 1h', numOrZero(buckets.cacheCreate1h), rates.cacheWrite1hPerMillionUsd);
+  }
+
+  // Output — visible and reasoning are billed at the same rate; show them
+  // as separate rows so the science-fair viewer sees the split.
+  pushIfNonZero(rows, 'output (visible)', numOrZero(buckets.outputVisible), rates.outputPerMillionUsd);
+  pushIfNonZero(rows, 'output (reasoning)', numOrZero(buckets.outputReasoning), rates.outputPerMillionUsd);
+
+  const totalUsd = rows.reduce((s, r) => s + r.costUsd, 0);
+
+  return { model, rates, buckets: rows, totalUsd };
+}
+
+function pushIfNonZero(rows, label, tokens, ratePerMillion) {
+  if (tokens === 0) return;
+  rows.push({
+    label,
+    tokens,
+    ratePerMillion,
+    costUsd: (tokens * ratePerMillion) / 1_000_000,
+  });
+}
+
+function numOrZero(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+/**
+ * Days since the pricing table was last verified against the provider's
+ * pricing page. Used by the CLI to warn that rates may be stale.
+ */
+export function daysSincePricingVerified(asOf = new Date()) {
+  let oldest = null;
+  for (const entry of PRICING_TABLE) {
+    const verified = new Date(entry.verifiedOn).getTime();
+    if (!Number.isFinite(verified)) continue;
+    if (oldest === null || verified < oldest) oldest = verified;
+  }
+  if (oldest === null) return Infinity;
+  return Math.floor((asOf.getTime() - oldest) / (1000 * 60 * 60 * 24));
+}
+
+export function isPricingStale(asOf = new Date()) {
+  return daysSincePricingVerified(asOf) > STALE_AFTER_DAYS;
+}
+
+/**
+ * Plan-type-aware hypothetical note for the printer.
+ */
+export function hypotheticalNoteFor(provider, planType) {
+  if (provider === 'codex' && typeof planType === 'string' && planType !== '') {
+    return `hypothetical — your Codex ${capitalize(planType)} plan covers this`;
+  }
+  if (provider === 'claude') {
+    return 'hypothetical — Anthropic API rate, your Max plan billing may differ';
+  }
+  return 'hypothetical — API list rate, your plan billing may differ';
+}
+
+function capitalize(s) {
+  return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1);
+}

package/src/quota.mjs

@@ -0,0 +1,57 @@
+/**
+ * Spec §5.2.3 quota helpers.
+ *
+ * A `quota` object on a usage record is a point-in-time sample of the
+ * provider's rate-limit state at the END of the turn. The spec shape:
+ *
+ *   {
+ *     "planType": "pro",
+ *     "windows": [
+ *       { "label": "primary",   "windowMinutes": 300,   "usedPercent": 64.0, "resetsAt": 1779863673 },
+ *       { "label": "secondary", "windowMinutes": 10080, "usedPercent": 57.0, "resetsAt": 1780187884 }
+ *     ]
+ *   }
+ *
+ * Reserved labels are `primary` (short window, e.g. 5h for Codex Pro) and
+ * `secondary` (long window, e.g. 7d for Codex Pro). Implementations MAY add
+ * additional labels; readers MUST treat unknown labels as opaque.
+ *
+ * `QuotaSample` (the in-memory shape used inside this package) is the same
+ * structure plus a `provider` tag and a `timestamp`:
+ *
+ *   {
+ *     "provider": "codex",
+ *     "timestamp": "2026-05-18T21:50:34Z",
+ *     "planType": "pro",
+ *     "windows": [...same as above...]
+ *   }
+ */
+
+/**
+ * Strip the in-memory `QuotaSample` wrapping down to the spec's bare
+ * `quota` object shape. Returns `null` if the sample has no windows.
+ */
+export function quotaSampleToSpecObject(sample) {
+  if (!sample || !Array.isArray(sample.windows) || sample.windows.length === 0) return null;
+  return {
+    planType: sample.planType ?? '',
+    windows: sample.windows.map((w) => {
+      const out = {
+        label: w.label,
+        windowMinutes: w.windowMinutes,
+        usedPercent: w.usedPercent,
+      };
+      if (typeof w.resetsAt === 'number') out.resetsAt = w.resetsAt;
+      return out;
+    }),
+  };
+}
+
+/**
+ * Find the window with the given label inside a QuotaSample. Returns
+ * `undefined` if absent.
+ */
+export function findWindow(sample, label) {
+  if (!sample || !Array.isArray(sample.windows)) return undefined;
+  return sample.windows.find((w) => w.label === label);
+}

package/src/transcript-to-usage.mjs

@@ -0,0 +1,120 @@
+/**
+ * Convert ParsedSession objects (from src/transcripts/*.mjs) into spec-
+ * compliant usage.jsonl records.
+ *
+ * Emits every REQUIRED field in spec §5.1 plus the OPTIONAL provider-
+ * specific fields the transcript surface gives us:
+ *   §5.2.1 input-token breakdown (uncached / cached / cache-write tiers)
+ *   §5.2.2 output-token breakdown (visible / reasoning)
+ *   §5.2.3 quota object (built from Codex rate_limits samples, when present)
+ *   workspacePath
+ *
+ * Spec-optional fields the CLI transcript doesn't carry (`estimate`,
+ * `pullRequest`, `effort`, `exitReason`, ...) are left out.
+ *
+ * `botRole` is hardcoded to `developer` per spec §5.1: "Implementations
+ * that do not distinguish a reviewer role MUST emit `developer`."
+ */
+import { quotaSampleToSpecObject } from './quota.mjs';
+import { SCHEMA_VERSION } from './usage-jsonl.mjs';
+
+export { quotaSampleToSpecObject } from './quota.mjs';
+
+/**
+ * @param {import('./types').ParsedSession} session
+ * @param {string} issueIdentifier
+ * @param {object} [opts]
+ * @param {string} [opts.recordedAt]  Override the recordedAt timestamp (default: now).
+ */
+export function sessionToUsageRecords(session, issueIdentifier, opts = {}) {
+  const recordedAt = opts.recordedAt ?? new Date().toISOString();
+  const out = [];
+
+  // Sort turns by index so the per-record `turn` ordinal is monotonic.
+  const turns = [...session.turns].sort((a, b) => a.turnIdx - b.turnIdx);
+
+  for (let i = 0; i < turns.length; i++) {
+    const turn = turns[i];
+    const next = turns[i + 1];
+
+    // The CLI transcript only records ONE timestamp per turn. We use it as
+    // both startedAt and as the endedAt of the previous turn. For the LAST
+    // turn we have no successor, so endedAt == startedAt.
+    const startedAt = turn.timestamp || recordedAt;
+    const endedAt = next?.timestamp ?? startedAt;
+
+    // Spec totals: claude sums every input bucket + visible output; codex
+    // sums uncached + cached + visible + reasoning output. Both end up as
+    // (inputTokens + outputTokens) per spec §5.3.
+    const inputTokens = turn.tokens.inputUncached + turn.tokens.inputCached +
+                        turn.tokens.cacheCreate5m + turn.tokens.cacheCreate1h;
+    const outputTokens = turn.tokens.outputVisible + turn.tokens.outputReasoning;
+    const totalTokens = inputTokens + outputTokens;
+
+    const record = {
+      schemaVersion: SCHEMA_VERSION,
+      recordedAt,
+      runID: session.sessionId,
+      turn: i + 1, // spec §5.1: 1-based, strictly increasing within runID
+      issueIdentifier,
+      provider: session.provider,
+      model: turn.model ?? '',
+      botRole: 'developer',
+      inputTokens,
+      outputTokens,
+      totalTokens,
+      usageSource: 'provider_reported',
+      startedAt,
+      endedAt,
+    };
+
+    // OPTIONAL §5.2 — populate when the transcript gives us the value.
+    if (session.cwd !== '') {
+      record.workspacePath = session.cwd;
+    }
+
+    // §5.2.1 input-token breakdown — both Claude and Codex report uncached + cached;
+    // Claude additionally reports cache-creation tokens split by ephemeral tier;
+    // Codex bundles writes into the cached total.
+    record.inputUncachedTokens = turn.tokens.inputUncached;
+    record.inputCachedReadTokens = turn.tokens.inputCached;
+    if (session.provider === 'claude') {
+      const writeTotal = turn.tokens.cacheCreate5m + turn.tokens.cacheCreate1h;
+      if (writeTotal > 0) {
+        record.inputCacheWriteTokens = writeTotal;
+        if (turn.tokens.cacheCreate5m > 0) record.inputCacheWriteEphemeral5mTokens = turn.tokens.cacheCreate5m;
+        if (turn.tokens.cacheCreate1h > 0) record.inputCacheWriteEphemeral1hTokens = turn.tokens.cacheCreate1h;
+      }
+    }
+
+    // §5.2.2 output-token breakdown. Codex always reports
+    // reasoning_output_tokens (even when zero), so we emit it unconditionally
+    // for Codex — its presence is itself a provider signal.
+    record.outputVisibleTokens = turn.tokens.outputVisible;
+    if (session.provider === 'codex') {
+      record.outputReasoningTokens = turn.tokens.outputReasoning;
+    }
+
+    // §5.2.3 quota — Codex emits a rate_limits payload per token_count event.
+    // The per-turn `quota` is the point-in-time sample at the end of the turn;
+    // we use the last sample whose timestamp is ≤ this turn's endedAt.
+    const sample = lastQuotaSampleAtOrBefore(session.quotaSamples, endedAt);
+    if (sample !== null) {
+      const quota = quotaSampleToSpecObject(sample);
+      if (quota !== null) record.quota = quota;
+    }
+
+    out.push(record);
+  }
+
+  return out;
+}
+
+function lastQuotaSampleAtOrBefore(samples, ts) {
+  if (samples.length === 0) return null;
+  let best = null;
+  for (const s of samples) {
+    if (s.timestamp <= ts && (best === null || s.timestamp > best.timestamp)) best = s;
+  }
+  return best ?? samples[0];
+}

package/src/transcripts/claude.mjs

@@ -0,0 +1,99 @@
+/**
+ * Parse Claude Code session JSONL files.
+ *
+ * Claude stores each session as one or more JSONL files under
+ * `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`, plus nested
+ * subagent files under `~/.claude/projects/<encoded-cwd>/<sessionId>/subagents/*.jsonl`.
+ *
+ * Each assistant turn carries a `message.usage` object with provider-reported
+ * token counts. This is the same accounting Anthropic bills against.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { numericOrZero, pathExists, readJsonl } from '../util.mjs';
+
+export async function findClaudeProjectDirs(claudeRootDir, matchesIssue) {
+  if (!(await pathExists(claudeRootDir))) return [];
+  let entries;
+  try {
+    entries = await readdir(claudeRootDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (entry.isDirectory() && matchesIssue(entry.name)) {
+      out.push(join(claudeRootDir, entry.name));
+    }
+  }
+  return out;
+}
+
+export async function listJsonlsRecursively(dir) {
+  if (!(await pathExists(dir))) return [];
+  const out = [];
+  async function walk(d) {
+    let entries;
+    try {
+      entries = await readdir(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = join(d, e.name);
+      if (e.isDirectory()) await walk(full);
+      else if (e.isFile() && e.name.endsWith('.jsonl')) out.push(full);
+    }
+  }
+  await walk(dir);
+  return out;
+}
+
+export async function parseClaudeSession(file) {
+  let sessionId;
+  let cwd;
+  const turns = [];
+  let turnIdx = 0;
+
+  for await (const rec of readJsonl(file)) {
+    if (typeof rec.sessionId === 'string' && sessionId === undefined) sessionId = rec.sessionId;
+    if (typeof rec.cwd === 'string' && cwd === undefined) cwd = rec.cwd;
+
+    const msg = rec.message;
+    const usage = msg?.usage;
+    if (!usage) continue;
+    const cacheCreation = usage.cache_creation;
+    const serverToolUse = usage.server_tool_use;
+    const ts = typeof rec.timestamp === 'string' ? rec.timestamp : '';
+    const model = typeof msg.model === 'string' ? msg.model : undefined;
+    turns.push({
+      provider: 'claude',
+      sessionId: sessionId ?? '',
+      turnIdx,
+      timestamp: ts,
+      model,
+      cwd: cwd ?? '',
+      tokens: {
+        inputUncached: numericOrZero(usage.input_tokens),
+        inputCached: numericOrZero(usage.cache_read_input_tokens),
+        cacheCreate5m: numericOrZero(cacheCreation?.ephemeral_5m_input_tokens),
+        cacheCreate1h: numericOrZero(cacheCreation?.ephemeral_1h_input_tokens),
+        outputVisible: numericOrZero(usage.output_tokens),
+        outputReasoning: 0,
+      },
+      webSearchRequests: numericOrZero(serverToolUse?.web_search_requests),
+      webFetchRequests: numericOrZero(serverToolUse?.web_fetch_requests),
+    });
+    turnIdx += 1;
+  }
+
+  if (turns.length === 0 && sessionId === undefined) return null;
+  return {
+    provider: 'claude',
+    sessionId: sessionId ?? '',
+    cwd: cwd ?? '',
+    sourceFile: file,
+    turns,
+    quotaSamples: [],
+  };
+}

package/src/transcripts/codex.mjs

@@ -0,0 +1,145 @@
+/**
+ * Parse Codex CLI rollout JSONL files.
+ *
+ * Codex stores each session as a single JSONL under
+ * `~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl`. The first
+ * record is `session_meta` with `payload.cwd`; subsequent `event_msg` records
+ * of type `token_count` carry both:
+ *   - `payload.info.total_token_usage`  (cumulative across the session)
+ *   - `payload.rate_limits`             (per-window quota % at this moment)
+ *
+ * We delta the cumulative usage to produce per-turn token counts, and
+ * collect every rate-limits sample we see.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { numericOrZero, pathExists, readJsonl } from '../util.mjs';
+
+const ZERO_CUMULATIVE = { total: 0, input: 0, cached: 0, output: 0, reasoning: 0 };
+
+export async function listCodexRollouts(codexRootDir) {
+  if (!(await pathExists(codexRootDir))) return [];
+  const out = [];
+  async function walk(d) {
+    let entries;
+    try {
+      entries = await readdir(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = join(d, e.name);
+      if (e.isDirectory()) await walk(full);
+      else if (e.isFile() && e.name.endsWith('.jsonl')) out.push(full);
+    }
+  }
+  await walk(codexRootDir);
+  return out;
+}
+
+export async function parseCodexSession(file) {
+  let sessionId;
+  let cwd;
+  let model;
+  let prev = ZERO_CUMULATIVE;
+  let turnIdx = 0;
+  const turns = [];
+  const quotaSamples = [];
+
+  for await (const rec of readJsonl(file)) {
+    const type = rec.type;
+    const payload = rec.payload;
+    const ts = typeof rec.timestamp === 'string' ? rec.timestamp : '';
+
+    if (type === 'session_meta' && payload !== undefined) {
+      if (typeof payload.id === 'string') sessionId = payload.id;
+      if (typeof payload.cwd === 'string') cwd = payload.cwd;
+      continue;
+    }
+    if (type === 'turn_context' && payload !== undefined && typeof payload.model === 'string') {
+      model = payload.model;
+      continue;
+    }
+    if (type !== 'event_msg' || payload === undefined || payload.type !== 'token_count') continue;
+
+    const totalUsage = payload.info?.total_token_usage;
+    if (totalUsage !== undefined) {
+      const current = {
+        total: numericOrZero(totalUsage.total_tokens),
+        input: numericOrZero(totalUsage.input_tokens),
+        cached: numericOrZero(totalUsage.cached_input_tokens),
+        output: numericOrZero(totalUsage.output_tokens),
+        reasoning: numericOrZero(totalUsage.reasoning_output_tokens),
+      };
+      const delta = {
+        total: current.total - prev.total,
+        input: current.input - prev.input,
+        cached: current.cached - prev.cached,
+        output: current.output - prev.output,
+        reasoning: current.reasoning - prev.reasoning,
+      };
+      const allNonNegative =
+        delta.input >= 0 && delta.cached >= 0 && delta.output >= 0 && delta.reasoning >= 0;
+      if (delta.total > 0 && allNonNegative) {
+        const inputUncached = Math.max(0, delta.input - delta.cached);
+        const outputVisible = Math.max(0, delta.output - delta.reasoning);
+        turns.push({
+          provider: 'codex',
+          sessionId: sessionId ?? '',
+          turnIdx,
+          timestamp: ts,
+          model,
+          cwd: cwd ?? '',
+          tokens: {
+            inputUncached,
+            inputCached: delta.cached,
+            cacheCreate5m: 0,
+            cacheCreate1h: 0,
+            outputVisible,
+            outputReasoning: delta.reasoning,
+          },
+          webSearchRequests: 0,
+          webFetchRequests: 0,
+        });
+        turnIdx += 1;
+        prev = current;
+      }
+    }
+
+    const rateLimits = payload.rate_limits;
+    if (rateLimits !== undefined && rateLimits !== null) {
+      // Build the spec §5.2.3 `quota` shape directly so the same structure
+      // round-trips through usage.jsonl without lossy reshaping.
+      const windows = [];
+      for (const [label, src] of [['primary', rateLimits.primary], ['secondary', rateLimits.secondary]]) {
+        if (!src) continue;
+        if (typeof src.window_minutes !== 'number' || src.window_minutes <= 0) continue;
+        const w = {
+          label,
+          windowMinutes: src.window_minutes,
+          usedPercent: numericOrZero(src.used_percent),
+        };
+        if (typeof src.resets_at === 'number') w.resetsAt = src.resets_at;
+        windows.push(w);
+      }
+      if (windows.length > 0) {
+        quotaSamples.push({
+          provider: 'codex',
+          timestamp: ts,
+          planType: typeof rateLimits.plan_type === 'string' ? rateLimits.plan_type : null,
+          windows,
+        });
+      }
+    }
+  }
+
+  if (turns.length === 0 && quotaSamples.length === 0 && sessionId === undefined) return null;
+  return {
+    provider: 'codex',
+    sessionId: sessionId ?? '',
+    cwd: cwd ?? '',
+    sourceFile: file,
+    turns,
+    quotaSamples,
+  };
+}

package/src/usage-aggregator.mjs

@@ -0,0 +1,114 @@
+/**
+ * Aggregate spec-compliant usage records into the same shape `rollupSessions`
+ * produces from raw transcripts. Keeps the CLI output identical regardless
+ * of which source the cost data came from.
+ *
+ * As of spec v1 with the §5.2.{1,2,3} additions, every signal the
+ * transcript carried is preserved on backfill:
+ *   - input/output token breakdowns
+ *   - Claude cache-tier split (ephemeral 5m vs 1h)
+ *   - Codex reasoning-vs-visible output split
+ *   - Codex per-window quota samples (`quota` object per record)
+ *
+ * When reading records produced by a writer that did NOT emit the OPTIONAL
+ * breakdown fields, this aggregator falls back to crediting the entire
+ * `inputTokens` to `inputUncached` and `outputTokens` to `outputVisible`.
+ * Grand totals are correct either way.
+ */
+import { emptyProviderTotals } from './aggregator.mjs';
+
+function numOr0(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+/**
+ * @param {string} issueIdentifier
+ * @param {Iterable<object>} records
+ */
+export function rollupUsageRecords(issueIdentifier, records) {
+  const providerTotals = {
+    claude: emptyProviderTotals(),
+    codex: emptyProviderTotals(),
+  };
+  const modelSets = { claude: new Set(), codex: new Set() };
+  const sessionsSeen = { claude: new Set(), codex: new Set() };
+
+  for (const rec of records) {
+    if (rec.issueIdentifier !== issueIdentifier) continue;
+    if (rec.provider !== 'claude' && rec.provider !== 'codex') continue;
+    if (rec.usageSource === 'unavailable') continue;
+
+    const totals = providerTotals[rec.provider];
+    totals.turnCount += 1;
+
+    // Prefer the §5.2.1 breakdown fields when present; fall back to the
+    // REQUIRED inputTokens total when not.
+    const hasInputBreakdown =
+      typeof rec.inputUncachedTokens === 'number' ||
+      typeof rec.inputCachedReadTokens === 'number' ||
+      typeof rec.inputCacheWriteTokens === 'number';
+    if (hasInputBreakdown) {
+      totals.tokens.inputUncached += numOr0(rec.inputUncachedTokens);
+      totals.tokens.inputCached += numOr0(rec.inputCachedReadTokens);
+      totals.tokens.cacheCreate5m += numOr0(rec.inputCacheWriteEphemeral5mTokens);
+      totals.tokens.cacheCreate1h += numOr0(rec.inputCacheWriteEphemeral1hTokens);
+      // If a writer emitted inputCacheWriteTokens but didn't split by tier
+      // (a non-Anthropic provider with a single cache tier, say), credit
+      // the unattributed write tokens to inputUncached so the grand total
+      // still matches.
+      const splitTotal = numOr0(rec.inputCacheWriteEphemeral5mTokens) + numOr0(rec.inputCacheWriteEphemeral1hTokens);
+      const writeTotal = numOr0(rec.inputCacheWriteTokens);
+      if (writeTotal > splitTotal) totals.tokens.inputUncached += (writeTotal - splitTotal);
+    } else {
+      totals.tokens.inputUncached += rec.inputTokens ?? 0;
+    }
+
+    // §5.2.2 output breakdown.
+    const hasOutputBreakdown =
+      typeof rec.outputVisibleTokens === 'number' || typeof rec.outputReasoningTokens === 'number';
+    if (hasOutputBreakdown) {
+      totals.tokens.outputVisible += numOr0(rec.outputVisibleTokens);
+      totals.tokens.outputReasoning += numOr0(rec.outputReasoningTokens);
+    } else {
+      totals.tokens.outputVisible += rec.outputTokens ?? 0;
+    }
+
+    // §5.2.3 quota — propagate the full per-turn sample if present.
+    if (rec.quota !== undefined && rec.quota !== null && typeof rec.quota === 'object' && Array.isArray(rec.quota.windows)) {
+      totals.quotaSamples.push({
+        provider: rec.provider,
+        timestamp: typeof rec.endedAt === 'string' ? rec.endedAt : '',
+        planType: typeof rec.quota.planType === 'string' ? rec.quota.planType : null,
+        windows: rec.quota.windows,
+      });
+    }
+
+    if (typeof rec.model === 'string' && rec.model !== '') modelSets[rec.provider].add(rec.model);
+    if (typeof rec.runID === 'string' && rec.runID !== '') sessionsSeen[rec.provider].add(rec.runID);
+    const startedAt = typeof rec.startedAt === 'string' ? rec.startedAt : null;
+    const endedAt = typeof rec.endedAt === 'string' ? rec.endedAt : null;
+    if (startedAt !== null && (totals.firstTimestamp === null || startedAt < totals.firstTimestamp)) {
+      totals.firstTimestamp = startedAt;
+    }
+    if (endedAt !== null && (totals.lastTimestamp === null || endedAt > totals.lastTimestamp)) {
+      totals.lastTimestamp = endedAt;
+    }
+  }
+
+  for (const provider of ['claude', 'codex']) {
+    const t = providerTotals[provider];
+    t.sessionCount = sessionsSeen[provider].size;
+    t.tokensGrandTotal =
+      t.tokens.inputUncached + t.tokens.inputCached + t.tokens.cacheCreate5m +
+      t.tokens.cacheCreate1h + t.tokens.outputVisible + t.tokens.outputReasoning;
+    t.models = [...modelSets[provider]].sort();
+  }
+
+  return {
+    issueIdentifier,
+    providerTotals,
+    combinedTokens: providerTotals.claude.tokensGrandTotal + providerTotals.codex.tokensGrandTotal,
+    combinedTurns: providerTotals.claude.turnCount + providerTotals.codex.turnCount,
+    combinedSessions: providerTotals.claude.sessionCount + providerTotals.codex.sessionCount,
+  };
+}