token-trace-manager 0.7.0

package/lib/adapters.mjs

@@ -0,0 +1,428 @@
+// Extração de token usage por protocolo, para respostas streaming (SSE) e JSON.
+// Normalização entre protocolos:
+//   inputTokens        = tokens de entrada NÃO cacheados
+//   cacheReadTokens    = tokens de entrada lidos do cache
+//   cacheCreateTokens  = tokens de escrita de cache (só Anthropic cobra separado)
+//   outputTokens       = total de saída FATURÁVEL (inclui reasoning/thinking)
+//   reasoningTokens    = subconjunto informativo de outputTokens
+// Além do usage, os extratores acumulam o TEXTO visível da resposta (campo
+// text, limitado) para o payload de inspeção — ver storePayloads no daemon.
+
+export class SseParser {
+  constructor(onEvent) {
+    this.onEvent = onEvent
+    this.buf = ''
+  }
+
+  feed(chunk) {
+    this.buf += chunk
+    let idx
+    // Eventos SSE são separados por linha em branco (\n\n ou \r\n\r\n)
+    while ((idx = this.buf.search(/\r?\n\r?\n/)) !== -1) {
+      const rawEvent = this.buf.slice(0, idx)
+      this.buf = this.buf.slice(idx).replace(/^\r?\n\r?\n/, '')
+      this.parseEvent(rawEvent)
+    }
+  }
+
+  parseEvent(raw) {
+    let event = null
+    const dataLines = []
+    for (const line of raw.split(/\r?\n/)) {
+      if (line.startsWith('event:')) event = line.slice(6).trim()
+      else if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart())
+    }
+    if (!dataLines.length) return
+    const data = dataLines.join('\n')
+    if (data === '[DONE]') return
+    let json
+    try {
+      json = JSON.parse(data)
+    } catch {
+      return
+    }
+    this.onEvent(event, json)
+  }
+}
+
+const MAX_TEXT_CAPTURE = 200_000 // chars — o suficiente pra inspecionar
+
+function appendText(u, piece) {
+  if (typeof piece !== 'string' || !piece) return
+  if (u.text.length >= MAX_TEXT_CAPTURE) return
+  u.text += piece.slice(0, MAX_TEXT_CAPTURE - u.text.length)
+}
+
+function zeroUsage() {
+  return {
+    model: null,
+    providerId: null, // id da resposta no provedor (msg_.../chatcmpl-.../resp_...) — elo de auditoria
+    text: '', // texto visível da resposta (para o payload de inspeção)
+    inputTokens: 0,
+    cacheCreateTokens: 0,
+    cacheCreate1hTokens: 0, // subconjunto de cacheCreate com TTL 1h (Anthropic cobra 2x, não 1.25x)
+    cacheReadTokens: 0,
+    outputTokens: 0,
+    reasoningTokens: 0,
+    sawUsage: false,
+    // Quais campos de usage o upstream EFETIVAMENTE reportou (ex:
+    // ['input_tokens','output_tokens'] num compat que não emite cache).
+    // Torna subcontagem visível — ausência não é confundida com 0 real.
+    usageFields: [],
+    // true quando houve um objeto usage que NÃO bateu com nenhum campo
+    // reconhecido do dialeto (ex: shape Cohere num target openai). O daemon
+    // grava um evento flagged (tokens 0, usage_unknown=1) em vez de um
+    // fantasma "completo" de 0 — fica visível que a contagem falhou.
+    usageUnknown: false,
+  }
+}
+
+function markField(u, name) {
+  if (!u.usageFields.includes(name)) u.usageFields.push(name)
+}
+
+// ---------------------------------------------------------------------------
+// Anthropic Messages API (/v1/messages)
+// Não-stream: body.usage {input_tokens, cache_creation_input_tokens,
+//   cache_read_input_tokens, output_tokens}; input_tokens JÁ exclui cache.
+// Stream: message_start carrega message.model + usage inicial;
+//   message_delta carrega usage.output_tokens cumulativo (o último vale).
+// ---------------------------------------------------------------------------
+class AnthropicExtractor {
+  constructor() {
+    this.u = zeroUsage()
+  }
+
+  onSse(event, json) {
+    const type = json.type || event
+    if (type === 'message_start' && json.message) {
+      const usage = json.message.usage || {}
+      this.u.model = json.message.model ?? this.u.model
+      this.u.providerId = json.message.id ?? this.u.providerId
+      const has = []
+      if (typeof usage.input_tokens === 'number') has.push('input_tokens')
+      if (typeof usage.cache_creation_input_tokens === 'number') has.push('cache_creation_input_tokens')
+      if (typeof usage.cache_read_input_tokens === 'number') has.push('cache_read_input_tokens')
+      if (typeof usage.output_tokens === 'number') has.push('output_tokens')
+      if (!has.length) {
+        this.u.usageUnknown = true
+        return
+      }
+      for (const f of has) markField(this.u, f)
+      this.u.inputTokens = usage.input_tokens || 0
+      this.u.cacheCreateTokens = usage.cache_creation_input_tokens || 0
+      this.u.cacheCreate1hTokens = usage.cache_creation?.ephemeral_1h_input_tokens || 0
+      if (typeof usage.cache_creation?.ephemeral_1h_input_tokens === 'number') markField(this.u, 'cache_creation_1h')
+      this.u.cacheReadTokens = usage.cache_read_input_tokens || 0
+      this.u.outputTokens = usage.output_tokens || 0
+      this.u.sawUsage = true
+    } else if (type === 'content_block_delta' && json.delta?.type === 'text_delta') {
+      appendText(this.u, json.delta.text)
+    } else if (type === 'message_delta' && json.usage) {
+      const has = []
+      if (typeof json.usage.output_tokens === 'number') has.push('output_tokens')
+      if (typeof json.usage.input_tokens === 'number') has.push('input_tokens')
+      if (!has.length) return
+      for (const f of has) markField(this.u, f)
+      if (typeof json.usage.output_tokens === 'number') this.u.outputTokens = json.usage.output_tokens
+      if (typeof json.usage.input_tokens === 'number') this.u.inputTokens = json.usage.input_tokens
+      this.u.sawUsage = true
+    }
+  }
+
+  onJsonBody(body) {
+    const usage = body.usage || {}
+    this.u.model = body.model ?? this.u.model
+    this.u.providerId = body.id ?? this.u.providerId
+    for (const block of body.content ?? []) {
+      if (block?.type === 'text') appendText(this.u, block.text)
+    }
+    if (!('usage' in body)) return
+    const has = []
+    if (typeof usage.input_tokens === 'number') has.push('input_tokens')
+    if (typeof usage.cache_creation_input_tokens === 'number') has.push('cache_creation_input_tokens')
+    if (typeof usage.cache_read_input_tokens === 'number') has.push('cache_read_input_tokens')
+    if (typeof usage.output_tokens === 'number') has.push('output_tokens')
+    if (!has.length) {
+      this.u.usageUnknown = true
+      return
+    }
+    for (const f of has) markField(this.u, f)
+    this.u.inputTokens = usage.input_tokens || 0
+    this.u.cacheCreateTokens = usage.cache_creation_input_tokens || 0
+    this.u.cacheCreate1hTokens = usage.cache_creation?.ephemeral_1h_input_tokens || 0
+    if (typeof usage.cache_creation?.ephemeral_1h_input_tokens === 'number') markField(this.u, 'cache_creation_1h')
+    this.u.cacheReadTokens = usage.cache_read_input_tokens || 0
+    this.u.outputTokens = usage.output_tokens || 0
+    this.u.sawUsage = true
+  }
+
+  result() {
+    return this.u
+  }
+}
+
+// ---------------------------------------------------------------------------
+// OpenAI Chat Completions (/v1/chat/completions) e compatíveis (OpenRouter etc)
+// prompt_tokens INCLUI os cacheados → input = prompt - cached.
+// completion_tokens INCLUI reasoning → output = completion, reasoning = subset.
+// Stream: usage vem num chunk final (choices vazio), só com
+//   stream_options.include_usage — o proxy pode injetar isso na request.
+// ---------------------------------------------------------------------------
+class OpenAiChatExtractor {
+  constructor() {
+    this.u = zeroUsage()
+  }
+
+  applyUsage(usage, model, id) {
+    if (model) this.u.model = model
+    if (id) this.u.providerId = id
+    if (!usage) return
+    const has = []
+    if (typeof usage.prompt_tokens === 'number') has.push('prompt_tokens')
+    if (typeof usage.completion_tokens === 'number') has.push('completion_tokens')
+    if (usage.prompt_tokens_details?.cached_tokens != null) has.push('cached_tokens')
+    if (usage.completion_tokens_details?.reasoning_tokens != null) has.push('reasoning_tokens')
+    if (!has.length) {
+      // usage existente mas shape não-OpenAI (ex: Cohere) — não fabrica 0
+      this.u.usageUnknown = true
+      return
+    }
+    for (const f of has) markField(this.u, f)
+    const cached = usage.prompt_tokens_details?.cached_tokens || 0
+    this.u.inputTokens = Math.max(0, (usage.prompt_tokens || 0) - cached)
+    this.u.cacheReadTokens = cached
+    this.u.outputTokens = usage.completion_tokens || 0
+    this.u.reasoningTokens = usage.completion_tokens_details?.reasoning_tokens || 0
+    this.u.sawUsage = true
+  }
+
+  onSse(_event, json) {
+    if (json.model && !this.u.model) this.u.model = json.model
+    if (json.id && !this.u.providerId) this.u.providerId = json.id
+    for (const ch of json.choices ?? []) appendText(this.u, ch?.delta?.content)
+    if (json.usage) this.applyUsage(json.usage, json.model, json.id)
+  }
+
+  onJsonBody(body) {
+    for (const ch of body.choices ?? []) appendText(this.u, ch?.message?.content)
+    this.applyUsage(body.usage, body.model, body.id)
+  }
+
+  result() {
+    return this.u
+  }
+}
+
+// ---------------------------------------------------------------------------
+// OpenAI Responses API (/v1/responses) — protocolo do Codex CLI.
+// Stream: evento response.completed → response.usage
+//   {input_tokens, input_tokens_details.cached_tokens,
+//    output_tokens, output_tokens_details.reasoning_tokens}.
+// input_tokens INCLUI cache; output_tokens INCLUI reasoning.
+// ---------------------------------------------------------------------------
+class OpenAiResponsesExtractor {
+  constructor() {
+    this.u = zeroUsage()
+  }
+
+  applyResponse(response) {
+    if (!response) return
+    if (response.model) this.u.model = response.model
+    if (response.id) this.u.providerId = response.id
+    const usage = response.usage
+    if (!usage) return
+    const has = []
+    if (typeof usage.input_tokens === 'number') has.push('input_tokens')
+    if (typeof usage.output_tokens === 'number') has.push('output_tokens')
+    if (usage.input_tokens_details?.cached_tokens != null) has.push('cached_tokens')
+    if (usage.output_tokens_details?.reasoning_tokens != null) has.push('reasoning_tokens')
+    if (!has.length) {
+      this.u.usageUnknown = true
+      return
+    }
+    for (const f of has) markField(this.u, f)
+    const cached = usage.input_tokens_details?.cached_tokens || 0
+    this.u.inputTokens = Math.max(0, (usage.input_tokens || 0) - cached)
+    this.u.cacheReadTokens = cached
+    this.u.outputTokens = usage.output_tokens || 0
+    this.u.reasoningTokens = usage.output_tokens_details?.reasoning_tokens || 0
+    this.u.sawUsage = true
+  }
+
+  collectOutputText(response) {
+    if (this.u.text) return // já veio via deltas
+    for (const item of response?.output ?? []) {
+      for (const c of item?.content ?? []) {
+        if (c?.type === 'output_text') appendText(this.u, c.text)
+      }
+    }
+  }
+
+  onSse(event, json) {
+    const type = json.type || event
+    if (type === 'response.output_text.delta') {
+      appendText(this.u, json.delta)
+    } else if (type === 'response.completed' || type === 'response.incomplete' || type === 'response.failed') {
+      this.applyResponse(json.response)
+      this.collectOutputText(json.response)
+    } else if (json.response?.model && !this.u.model) {
+      this.u.model = json.response.model
+    }
+  }
+
+  onJsonBody(body) {
+    const response = body.object === 'response' ? body : body.response ?? body
+    this.applyResponse(response)
+    this.collectOutputText(response)
+  }
+
+  result() {
+    return this.u
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Gemini generateContent / streamGenerateContent
+// usageMetadata {promptTokenCount, candidatesTokenCount,
+//   cachedContentTokenCount, thoughtsTokenCount}.
+// promptTokenCount INCLUI cache → input = prompt - cached.
+// candidatesTokenCount EXCLUI thoughts → output faturável = candidates + thoughts.
+// Model vem da URL (/v1beta/models/{model}:...) e/ou modelVersion no body.
+// ---------------------------------------------------------------------------
+class GeminiExtractor {
+  constructor(urlPath) {
+    this.u = zeroUsage()
+    const m = /\/models\/([^:/]+):/.exec(urlPath || '')
+    if (m) this.u.model = m[1]
+    this.modelFromUrl = Boolean(m)
+  }
+
+  applyUsage(json) {
+    // O body não ecoa o model pedido; modelVersion é a versão resolvida
+    // (pode ter sufixo que não bate com a tabela de preços) — a URL vence.
+    if (json.modelVersion && !this.modelFromUrl) this.u.model = json.modelVersion
+    if (json.responseId) this.u.providerId = json.responseId
+    for (const cand of json.candidates ?? []) {
+      for (const part of cand?.content?.parts ?? []) appendText(this.u, part?.text)
+    }
+    const usage = json.usageMetadata
+    if (!usage) return
+    const has = []
+    if (typeof usage.promptTokenCount === 'number') has.push('promptTokenCount')
+    if (typeof usage.candidatesTokenCount === 'number') has.push('candidatesTokenCount')
+    if (usage.cachedContentTokenCount != null) has.push('cachedContentTokenCount')
+    if (usage.thoughtsTokenCount != null) has.push('thoughtsTokenCount')
+    if (!has.length) {
+      this.u.usageUnknown = true
+      return
+    }
+    for (const f of has) markField(this.u, f)
+    const cached = usage.cachedContentTokenCount || 0
+    const thoughts = usage.thoughtsTokenCount || 0
+    this.u.inputTokens = Math.max(0, (usage.promptTokenCount || 0) - cached)
+    this.u.cacheReadTokens = cached
+    this.u.outputTokens = (usage.candidatesTokenCount || 0) + thoughts
+    this.u.reasoningTokens = thoughts
+    this.u.sawUsage = true
+  }
+
+  onSse(_event, json) {
+    // usageMetadata é CUMULATIVO entre chunks; o último visto tem o valor
+    // final — sobrescrever a cada chunk (nunca somar).
+    this.applyUsage(json)
+  }
+
+  onJsonBody(body) {
+    // streamGenerateContent SEM ?alt=sse devolve um ARRAY JSON de chunks
+    if (Array.isArray(body)) {
+      for (const chunk of body) this.applyUsage(chunk)
+      return
+    }
+    this.applyUsage(body)
+  }
+
+  result() {
+    return this.u
+  }
+}
+
+// Protocolo de wire desconhecido: NÃO extrai nada. Evita o bug do "default
+// silencioso p/ OpenAiChatExtractor" que produzia 0 tokens sem erro visível
+// quando o usuário declarava um target custom com protocolo errado/typo.
+// Em runtime, readConfig já marca o target como _invalid e o proxyRequest
+// devolve 400 antes mesmo de chegar aqui; este extrator é a defesa em
+// profundidade caso algo escape.
+class NullExtractor {
+  constructor() {
+    this.u = zeroUsage()
+  }
+  onSse() {}
+  onJsonBody() {}
+  result() {
+    return this.u
+  }
+}
+
+export function createExtractor(protocol, { urlPath } = {}) {
+  switch (protocol) {
+    case 'anthropic':
+      return new AnthropicExtractor()
+    case 'openai': {
+      // /v1/responses e /v1/chat/completions compartilham o mesmo target
+      if (/\/responses(\?|$)/.test(urlPath || '')) return new OpenAiResponsesExtractor()
+      return new OpenAiChatExtractor()
+    }
+    case 'openai-responses':
+      return new OpenAiResponsesExtractor()
+    case 'gemini':
+      return new GeminiExtractor(urlPath)
+    default:
+      return new NullExtractor()
+  }
+}
+
+// Injeta stream_options.include_usage numa request de chat completions em
+// streaming que não pediu usage — sem isso o chunk final de usage não vem.
+//
+// IMPORTANTE: quando NÓS injetamos, o chunk terminal de usage (choices: []
+// + usage preenchido) precisa ser REMOVIDO da resposta repassada ao cliente
+// — wrappers comuns (LangChain, Haystack, mlflow...) quebram com choices[0]
+// num chunk que não pediram. O daemon usa isUsageOnlyChunk() para isso.
+export function maybeInjectIncludeUsage(protocol, urlPath, bodyBuffer) {
+  if (protocol !== 'openai' || !/\/chat\/completions(\?|$)/.test(urlPath || '')) return null
+  let body
+  try {
+    body = JSON.parse(bodyBuffer.toString('utf8'))
+  } catch {
+    return null
+  }
+  if (!body || body.stream !== true) return null
+  if (body.stream_options?.include_usage) return null
+  body.stream_options = { ...(body.stream_options || {}), include_usage: true }
+  return Buffer.from(JSON.stringify(body), 'utf8')
+}
+
+// Reconhece o chunk terminal exclusivo de usage do chat completions streaming
+// (o que include_usage acrescenta): choices vazio + usage preenchido.
+export function isUsageOnlyChunk(rawSseEvent) {
+  const dataLines = []
+  for (const line of rawSseEvent.split(/\r?\n/)) {
+    if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart())
+  }
+  if (!dataLines.length) return false
+  const data = dataLines.join('\n')
+  if (data === '[DONE]') return false
+  try {
+    const json = JSON.parse(data)
+    return (
+      json &&
+      json.object === 'chat.completion.chunk' &&
+      Array.isArray(json.choices) &&
+      json.choices.length === 0 &&
+      json.usage
+    )
+  } catch {
+    return false
+  }
+}

package/lib/audit.mjs

@@ -0,0 +1,238 @@
+// Auditoria agnóstica ao harness, em duas frentes:
+//
+// 1. MATEMÁTICA INTERNA (universal) — para cada evento, re-multiplica
+//    tokens × taxas gravadas no momento da chamada (coluna rates) e compara
+//    com cost_usd. Vale para QUALQUER TUI/provedor.
+//
+// 2. FONTES INDEPENDENTES (plugáveis) — cada harness que mantém a própria
+//    contabilidade local vira um adaptador de fonte. Estratégias de casamento:
+//      - por provider_id (id da resposta no provedor), quando a fonte o grava
+//        (Claude Code grava msg_... nos transcripts);
+//      - por impressão digital (tupla exata de tokens + mesma janela de tempo),
+//        quando a fonte não guarda o id (OpenCode).
+//    Novos harnesses = novo adaptador aqui; nada no resto do sistema muda.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import readline from 'node:readline'
+import { listUsageEvents } from './db.mjs'
+
+const FINGERPRINT_WINDOW_MS = 15 * 60 * 1000
+
+// ---------------------------------------------------------------------------
+// Fonte: Claude Code — transcripts JSONL com usage + message.id (provider_id)
+// ---------------------------------------------------------------------------
+function* walkJsonl(dir) {
+  let ents
+  try {
+    ents = fs.readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const e of ents) {
+    const p = path.join(dir, e.name)
+    if (e.isDirectory()) yield* walkJsonl(p)
+    else if (e.isFile() && e.name.endsWith('.jsonl')) yield p
+  }
+}
+
+async function indexClaudeCode({ sinceIso, rootDir }) {
+  const root = rootDir || path.join(os.homedir(), '.claude', 'projects')
+  const entries = []
+  for (const file of walkJsonl(root)) {
+    let stream
+    try {
+      stream = fs.createReadStream(file, { encoding: 'utf8' })
+    } catch {
+      continue
+    }
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity })
+    const byId = new Map()
+    for await (const line of rl) {
+      if (!line || !line.includes('"usage"')) continue
+      let e
+      try {
+        e = JSON.parse(line)
+      } catch {
+        continue
+      }
+      if (e.type !== 'assistant') continue
+      const msg = e.message || {}
+      const u = msg.usage
+      if (!u || !msg.id || msg.model === '<synthetic>') continue
+      if (sinceIso && e.timestamp && e.timestamp < sinceIso) continue
+      const prev = byId.get(msg.id)
+      if (prev && (prev.output_tokens || 0) >= (u.output_tokens || 0)) continue
+      byId.set(msg.id, {
+        providerId: msg.id,
+        model: msg.model,
+        ts: e.timestamp,
+        input_tokens: u.input_tokens || 0,
+        cache_create_tokens: u.cache_creation_input_tokens || 0,
+        cache_read_tokens: u.cache_read_input_tokens || 0,
+        output_tokens: u.output_tokens || 0,
+      })
+    }
+    entries.push(...byId.values())
+  }
+  return entries
+}
+
+// ---------------------------------------------------------------------------
+// Fonte: OpenCode — opencode.db (SQLite), message.data JSON com tokens
+// (sem provider_id -> casa por impressão digital)
+// ---------------------------------------------------------------------------
+async function indexOpenCode({ sinceIso, rootDir }) {
+  const dbPath = rootDir
+    ? path.join(rootDir, 'opencode.db')
+    : path.join(os.homedir(), '.local', 'share', 'opencode', 'opencode.db')
+  if (!fs.existsSync(dbPath)) return null // fonte indisponível nesta máquina
+  let db
+  try {
+    const { DatabaseSync } = await import('node:sqlite')
+    db = new DatabaseSync(dbPath, { readOnly: true })
+  } catch {
+    return null
+  }
+  const sinceMs = sinceIso ? Date.parse(sinceIso) : 0
+  const entries = []
+  try {
+    const rows = db
+      .prepare(
+        `SELECT data, time_created FROM message
+         WHERE data LIKE '%"role":"assistant"%' AND data LIKE '%"tokens"%' AND time_created >= ?`,
+      )
+      .all(sinceMs)
+    for (const row of rows) {
+      let d
+      try {
+        d = JSON.parse(row.data)
+      } catch {
+        continue
+      }
+      const t = d.tokens
+      if (!t || d.role !== 'assistant') continue
+      entries.push({
+        providerId: null,
+        model: d.modelID ?? null,
+        ts: new Date(d.time?.completed ?? d.time?.created ?? row.time_created).toISOString(),
+        input_tokens: t.input || 0,
+        cache_create_tokens: t.cache?.write || 0,
+        cache_read_tokens: t.cache?.read || 0,
+        output_tokens: t.output || 0,
+      })
+    }
+  } finally {
+    db.close()
+  }
+  return entries
+}
+
+export const AUDIT_SOURCES = [
+  { key: 'claude-code', title: 'Claude Code (transcripts ~/.claude/projects)', index: indexClaudeCode, match: 'provider_id' },
+  { key: 'opencode', title: 'OpenCode (opencode.db local)', index: indexOpenCode, match: 'fingerprint' },
+]
+
+const TOKEN_FIELDS = ['input_tokens', 'cache_create_tokens', 'cache_read_tokens', 'output_tokens']
+
+// Casamento 1:1 — uma entrada da fonte cobre no máximo UM evento do proxy
+// (consumida ao casar), senão um registro poderia "validar" dois eventos.
+function takeFingerprintMatch(ev, pool) {
+  const evMs = Date.parse(ev.ts)
+  const idx = pool.findIndex(
+    t =>
+      Math.abs(Date.parse(t.ts) - evMs) <= FINGERPRINT_WINDOW_MS &&
+      TOKEN_FIELDS.every(f => (ev[f] || 0) === (t[f] || 0)),
+  )
+  if (idx === -1) return undefined
+  return pool.splice(idx, 1)[0]
+}
+
+function recomputeFromRates(ev, rates) {
+  const create1h = Math.min(ev.cache_create_1h_tokens || 0, ev.cache_create_tokens || 0)
+  const create5m = (ev.cache_create_tokens || 0) - create1h
+  return (
+    ((ev.input_tokens || 0) / 1e6) * rates.input +
+    ((ev.cache_read_tokens || 0) / 1e6) * rates.cacheRead +
+    (create5m / 1e6) * rates.cacheWrite5m +
+    (create1h / 1e6) * (rates.cacheWrite1h ?? rates.cacheWrite5m) +
+    ((ev.output_tokens || 0) / 1e6) * rates.output
+  )
+}
+
+export async function runAudit({ sinceIso, sourceRoots = {} } = {}) {
+  const events = await listUsageEvents({ since: sinceIso })
+
+  // Frente 1: matemática interna (todo evento, qualquer harness)
+  const math = { checked: 0, ok: 0, drift: [], noRates: 0 }
+  for (const ev of events) {
+    if (!ev.rates) {
+      math.noRates++
+      continue
+    }
+    let rates
+    try {
+      rates = JSON.parse(ev.rates)
+    } catch {
+      math.noRates++
+      continue
+    }
+    math.checked++
+    const expected = recomputeFromRates(ev, rates)
+    if (Math.abs(expected - (ev.cost_usd ?? 0)) < 1e-9) math.ok++
+    else math.drift.push({ id: ev.id, ts: ev.ts, label: ev.label, stored: ev.cost_usd, recomputed: expected })
+  }
+
+  // Frente 2: cada fonte independente disponível tenta casar cada evento
+  const unmatched = new Map(events.map(ev => [ev.id, ev]))
+  const sources = []
+  for (const src of AUDIT_SOURCES) {
+    const entries = await src.index({ sinceIso, rootDir: sourceRoots[src.key] })
+    if (entries === null) {
+      sources.push({ key: src.key, title: src.title, available: false })
+      continue
+    }
+    const byProviderId = new Map(entries.filter(t => t.providerId).map(t => [t.providerId, t]))
+    const pool = [...entries]
+    const report = { key: src.key, title: src.title, available: true, strategy: src.match, matched: 0, identical: 0, mismatches: [] }
+
+    for (const ev of [...unmatched.values()]) {
+      let t
+      if (src.match === 'provider_id') {
+        t = ev.provider_id ? byProviderId.get(ev.provider_id) : undefined
+        if (t) byProviderId.delete(ev.provider_id) // 1:1 — consumida ao casar
+      } else {
+        t = takeFingerprintMatch(ev, pool)
+      }
+      if (!t) continue
+      unmatched.delete(ev.id)
+      report.matched++
+      const diffs = TOKEN_FIELDS.filter(f => (ev[f] || 0) !== (t[f] || 0))
+      if (!diffs.length) report.identical++
+      else {
+        report.mismatches.push({
+          event_id: ev.id,
+          provider_id: ev.provider_id,
+          label: ev.label,
+          fields: Object.fromEntries(diffs.map(f => [f, { proxy: ev[f] || 0, fonte: t[f] || 0 }])),
+        })
+      }
+    }
+    sources.push(report)
+  }
+
+  return {
+    since: sinceIso ?? 'tudo',
+    eventCount: events.length,
+    math,
+    sources,
+    uncovered: [...unmatched.values()].map(ev => ({
+      id: ev.id,
+      ts: ev.ts,
+      label: ev.label,
+      client: ev.client,
+      target: ev.target,
+    })),
+  }
+}