voyage/lib/stats/token-usage.mjs

// lib/stats/token-usage.mjs
// SKAL-2 — pure token-usage parser + cache-aware cost derivation for Voyage
// observability. Captures MAIN-CONTEXT token/cost from the Claude Code
// transcript (transcript_path). Each assistant record carries message.usage
// with a per-REQUEST snapshot.
//
// Verified 2026-06-26 against a real local transcript (216 lines): 70
// assistant records collapse to 31 distinct requestIds — records duplicate
// per requestId (streamed snapshots), so we dedup by requestId keeping the
// LAST occurrence (GH #28197 streaming-placeholder mitigation), then sum
// across requests. The main transcript carried zero isSidechain:true records.
//
// v1 scope = MAIN-CONTEXT only. Sub-agent (swarm) turns live in separate
// agent-*.jsonl siblings and are a documented v2 follow-on — so the
// main-transcript sum UNDER-counts total Voyage cost. Every record is stamped
// scope:'main-context' so no reader mistakes cost_usd for the session total.
//
// All functions in this module are PURE (no I/O). The impure capture shell
// (captureTokenUsage) is added in Step 4.
//
// Zero npm dependencies. Node stdlib only.

// Per-Mtok USD prices, resolved 2026-06-26 via the claude-api skill reference:
// base input/output from the model table; cache rates from the prompt-caching
// doc multipliers (cache_read 0.1x, write_5m 1.25x, write_1h 2.0x of input).
export const PRICE_TABLE = Object.freeze({
  'claude-opus-4-8': Object.freeze({
    input: 5.0,
    output: 25.0,
    cache_read: 0.5,
    cache_write_5m: 6.25,
    cache_write_1h: 10.0,
  }),
});

// Date the PRICE_TABLE values were resolved/verified. Bump when prices change.
export const PRICE_TABLE_VERSION = '2026-06-26';

function num(v) {
  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
}

/**
 * Single pass over transcript JSONL text. Keeps only main-chain assistant
 * records (type==='assistant', isSidechain!==true), dedups by requestId
 * keeping the LAST occurrence (per-request usage snapshots duplicate across
 * streamed records), and sums the four usage token fields. Malformed lines
 * are skipped.
 *
 * @returns {{tokens_input:number, tokens_output:number,
 *            tokens_cache_creation:number, tokens_cache_read:number}}
 */
export function parseTranscriptUsage(text) {
  const lines = (text || '').split('\n');
  // requestId -> usage (last occurrence wins). Records without a requestId
  // get a unique sentinel key so each is still counted exactly once.
  const byRequest = new Map();
  let anon = 0;
  for (const line of lines) {
    const trimmed = line.trim();
    if (trimmed === '') continue;
    let obj;
    try { obj = JSON.parse(trimmed); }
    catch { continue; }
    if (!obj || obj.type !== 'assistant') continue;
    if (obj.isSidechain === true) continue;
    const usage = obj.message && obj.message.usage;
    if (!usage || typeof usage !== 'object') continue;
    const key = typeof obj.requestId === 'string' && obj.requestId
      ? obj.requestId
      : `__anon_${anon++}`;
    byRequest.set(key, usage); // last occurrence wins
  }
  const totals = {
    tokens_input: 0,
    tokens_output: 0,
    tokens_cache_creation: 0,
    tokens_cache_read: 0,
  };
  for (const usage of byRequest.values()) {
    totals.tokens_input += num(usage.input_tokens);
    totals.tokens_output += num(usage.output_tokens);
    totals.tokens_cache_creation += num(usage.cache_creation_input_tokens);
    totals.tokens_cache_read += num(usage.cache_read_input_tokens);
  }
  return totals;
}

/**
 * Cache-aware USD cost. Lumped cache_creation is priced at the 5m write rate
 * (Claude Code's default cache TTL; verified the dominant case on a real
 * transcript — the 1h split is a documented v2 refinement). When the model is
 * absent from the table we REFUSE to estimate: {cost_usd:null, is_estimate:true}.
 *
 * @returns {{cost_usd:number|null, is_estimate:boolean}}
 */
export function deriveCost(totals, model, priceTable = PRICE_TABLE) {
  const price = priceTable && priceTable[model];
  if (!price) return { cost_usd: null, is_estimate: true };
  const t = totals || {};
  const cost =
    (num(t.tokens_input) * price.input +
      num(t.tokens_output) * price.output +
      num(t.tokens_cache_creation) * price.cache_write_5m +
      num(t.tokens_cache_read) * price.cache_read) / 1_000_000;
  return { cost_usd: cost, is_estimate: false };
}

/**
 * Build the flat numeric record. Stamps scope:'main-context' and
 * price_table_version. session_id is written for upsert keying but MUST be
 * stripped at export (CWE-212, enforced by the field allowlist in Step 2).
 *
 * @param {{sessionId:string, model:string, totals:object,
 *          priceTable?:object, now:string}} args
 */
export function buildRecord({ sessionId, model, totals, priceTable = PRICE_TABLE, now }) {
  const t = totals || {};
  const { cost_usd, is_estimate } = deriveCost(t, model, priceTable);
  return {
    ts: now,
    session_id: sessionId,
    scope: 'main-context',
    model,
    tokens_input: num(t.tokens_input),
    tokens_output: num(t.tokens_output),
    tokens_cache_creation: num(t.tokens_cache_creation),
    tokens_cache_read: num(t.tokens_cache_read),
    cost_usd,
    is_estimate,
    price_table_version: PRICE_TABLE_VERSION,
  };
}

/**
 * Pure read-modify-write. Parses existing JSONL lines, REPLACES the line whose
 * session_id matches the record (dropping any further same-session dupes),
 * else APPENDS. Returns the new file text (one line per session, trailing
 * newline). One-line-per-session is what keeps cross-session sums from
 * double-counting (vs append-and-grow).
 */
export function upsertSessionRecord(existingText, record) {
  const lines = (existingText || '').split('\n');
  const out = [];
  let replaced = false;
  for (const line of lines) {
    const trimmed = line.trim();
    if (trimmed === '') continue;
    let obj;
    try { obj = JSON.parse(trimmed); }
    catch { out.push(trimmed); continue; } // preserve unparseable lines verbatim
    if (obj && obj.session_id === record.session_id) {
      if (!replaced) { out.push(JSON.stringify(record)); replaced = true; }
      // else: duplicate same-session line — drop it
    } else {
      out.push(trimmed);
    }
  }
  if (!replaced) out.push(JSON.stringify(record));
  return out.join('\n') + '\n';
}