burner-cc 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+<img src="assets/logo-mark.png" alt="Burner" width="90" />
+
+# burner
+
+Itemized dollar-and-token cost receipts for Claude Code sessions.
+
+## Usage
+
+```
+node bin/burner-cc.js                 # latest session -> opens a receipt
+node bin/burner-cc.js <session-id>    # specific session (accepts a prefix)
+node bin/burner-cc.js --all           # every session found, sliding through one receipt each
+node bin/burner-cc.js list            # quick terminal table, no browser
+node bin/burner-cc.js --json          # machine-readable, no browser
+```
+
+Once published: `npx burner-cc`, `npx burner-cc --all`, etc.
+
+## How it works
+
+- **Discovery** (`src/discover.js`) walks `~/.claude/projects/**/*.jsonl`, matching each top-level session transcript with any `subagents/agent-*.jsonl` files spawned inside it (those are billed separately by the API and get folded into the parent session's receipt).
+- **Parsing** (`src/parse.js`) reads each assistant turn's `usage` block (input/output/cache-write/cache-read tokens) straight from the transcript.
+- **Pricing** (`src/pricing.js`) is fetched automatically — no file to hand-edit. It pulls Anthropic's per-model rates from [LiteLLM's community-maintained pricing JSON](https://github.com/BerriAI/litellm) (sourced from `platform.claude.com/docs/.../pricing`), caches it locally for 6 hours, and falls back to a stale cache or a small bundled snapshot (`src/pricing-fallback.json`) if offline.
+- **Receipt** (`src/build-receipt.js`) groups tokens by model and computes cost per token-type line.
+- **Rendering** (`src/render.js` + `web/`) injects the receipt JSON into `web/receipt.html` and opens it in the default browser. Theme buttons (paper / thermal / matrix / dark) switch CSS variables client-side.
+
+
+
+## What this is not
+
+Not official billing. Composition breakdown by *source* (system prompt vs. skills vs. MCP tool schemas) isn't available from local transcripts alone — that needs request interception, which this tool doesn't do. The receipt instead itemizes by token *type*: fresh input, cache write, cache read, output.

package/bin/burner-cc.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "burner-cc",
+  "version": "0.1.0",
+  "description": "Itemized dollar-and-token cost receipts for Claude Code sessions.",
+  "type": "module",
+  "bin": {
+    "burner-cc": "bin/burner-cc.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "web"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude",
+    "anthropic",
+    "cost",
+    "tokens",
+    "cli",
+    "usage",
+    "billing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shoryasethia/burner.git"
+  },
+  "homepage": "https://github.com/shoryasethia/burner#readme",
+  "bugs": {
+    "url": "https://github.com/shoryasethia/burner/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Shorya"
+}

package/src/billing-mode.js

@@ -0,0 +1,22 @@
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// Claude Code can run on pay-per-token API billing, or on a flat-fee
+// Pro/Max/Team/Enterprise subscription where tokens don't map to dollars
+// the way this tool assumes. There's no reliable local signal for *which*
+// subscription tier someone's on, but ~/.claude/config.json having a
+// primaryApiKey is a reasonable signal that this account bills per token.
+// We only check whether the field exists — its value is never read into
+// anything we log, render, or persist.
+export function detectBillingMode() {
+  const configPath = path.join(os.homedir(), '.claude', 'config.json');
+  if (!existsSync(configPath)) return 'unknown';
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    const hasApiKey = typeof config.primaryApiKey === 'string' && config.primaryApiKey.length > 0;
+    return hasApiKey ? 'api-key' : 'subscription-likely';
+  } catch {
+    return 'unknown';
+  }
+}

package/src/build-receipt.js

@@ -0,0 +1,133 @@
+import { parseTranscript, timeRange, mergeActivity } from './parse.js';
+import { lookupPricing, costFor, loadPricingTable } from './pricing.js';
+
+function summarizeTurns(turns, table) {
+  // Group by the *priced* model identity (post lookup), not the raw string,
+  // so aliases like "sonnet" fold into the concrete model they resolved to.
+  const byModel = new Map();
+
+  for (const t of turns) {
+    const priced = lookupPricing(t.model, table);
+    const key = priced.displayName;
+    if (!byModel.has(key)) {
+      byModel.set(key, {
+        displayName: priced.displayName,
+        fidelity: priced.fidelity,
+        rates: priced.rates,
+        tokens: { input: 0, output: 0, cacheWrite5m: 0, cacheWrite1h: 0, cacheRead: 0 },
+        turnCount: 0,
+      });
+    }
+    const bucket = byModel.get(key);
+    bucket.turnCount += 1;
+    bucket.tokens.input += t.input;
+    bucket.tokens.output += t.output;
+    bucket.tokens.cacheWrite5m += t.cacheWrite5m;
+    bucket.tokens.cacheWrite1h += t.cacheWrite1h;
+    bucket.tokens.cacheRead += t.cacheRead;
+  }
+
+  const models = [];
+  for (const bucket of byModel.values()) {
+    const cost = costFor(bucket.tokens, bucket.rates);
+    models.push({
+      displayName: bucket.displayName,
+      fidelity: bucket.fidelity,
+      turnCount: bucket.turnCount,
+      tokens: bucket.tokens,
+      cost, // null if unpriced
+    });
+  }
+  return models;
+}
+
+function sumCost(models) {
+  return models.reduce((acc, m) => {
+    if (!m.cost) return acc;
+    acc.input += m.cost.input;
+    acc.output += m.cost.output;
+    acc.cacheWrite += m.cost.cacheWrite;
+    acc.cacheRead += m.cost.cacheRead;
+    acc.total += m.cost.total;
+    return acc;
+  }, { input: 0, output: 0, cacheWrite: 0, cacheRead: 0, total: 0 });
+}
+
+function sumTokens(models) {
+  return models.reduce((acc, m) => {
+    acc.input += m.tokens.input;
+    acc.output += m.tokens.output;
+    acc.cacheWrite5m += m.tokens.cacheWrite5m;
+    acc.cacheWrite1h += m.tokens.cacheWrite1h;
+    acc.cacheRead += m.tokens.cacheRead;
+    return acc;
+  }, { input: 0, output: 0, cacheWrite5m: 0, cacheWrite1h: 0, cacheRead: 0 });
+}
+
+// Groups subagent runs by their agentType (from the sidecar .meta.json),
+// each with its own real, measured cost — instead of lumping every
+// subagent run into one "SUBAGENTS" blob.
+function summarizeSubagentsByType(subagentFiles, table) {
+  const byType = new Map();
+
+  for (const { file, meta } of subagentFiles) {
+    const type = meta?.agentType ?? 'unknown';
+    const { turns } = parseTranscript(file);
+    if (!byType.has(type)) byType.set(type, { agentType: type, runCount: 0, turns: [] });
+    const bucket = byType.get(type);
+    bucket.runCount += 1;
+    bucket.turns.push(...turns);
+  }
+
+  return [...byType.values()].map((bucket) => ({
+    agentType: bucket.agentType,
+    runCount: bucket.runCount,
+    models: summarizeTurns(bucket.turns, table),
+  }));
+}
+
+// Builds one receipt object for a discovered session (main transcript +
+// any subagent transcripts spawned within it). `table` is the pricing
+// table already resolved once via loadPricingTable() by the caller.
+export function buildReceipt(session, table) {
+  const { turns: mainTurns, activity: mainActivity } = parseTranscript(session.mainFile);
+  const subagentParsed = session.subagentFiles.map(({ file }) => parseTranscript(file));
+  const subagentTurns = subagentParsed.flatMap((p) => p.turns);
+
+  const mainModels = summarizeTurns(mainTurns, table);
+  const subagentGroups = summarizeSubagentsByType(session.subagentFiles, table);
+  const allSubagentModels = subagentGroups.flatMap((g) => g.models);
+
+  const activity = mergeActivity([mainActivity, ...subagentParsed.map((p) => p.activity)]);
+
+  const { startedAt, endedAt } = timeRange([...mainTurns, ...subagentTurns]);
+  const hasUnpriced = [...mainModels, ...allSubagentModels].some((m) => !m.cost);
+
+  const totals = {
+    tokens: sumTokens([...mainModels, ...allSubagentModels]),
+    cost: sumCost([...mainModels, ...allSubagentModels]),
+  };
+
+  return {
+    sessionId: session.sessionId,
+    title: session.title,
+    project: session.project,
+    startedAt,
+    endedAt,
+    turnCount: mainTurns.length,
+    subagentCount: session.subagentFiles.length,
+    models: mainModels,
+    subagentGroups,
+    activity,
+    totals,
+    hasUnpriced,
+    pricingSource: table.source,
+  };
+}
+
+export async function buildAllReceipts(sessions) {
+  const table = await loadPricingTable();
+  return sessions.map((s) => buildReceipt(s, table));
+}
+
+export { loadPricingTable };

package/src/cli.js

@@ -0,0 +1,81 @@
+import { discoverSessions, findSession, latestSession } from './discover.js';
+import { buildReceipt, loadPricingTable } from './build-receipt.js';
+import { renderReceipts, openInBrowser } from './render.js';
+import { detectBillingMode } from './billing-mode.js';
+
+function fmtUsd(n) {
+  return '$' + n.toFixed(3);
+}
+
+function printList(sessions, table) {
+  console.log('SESSION   TITLE                 PROJECT                     DATE          MODELS   COST');
+  for (const s of sessions) {
+    const r = buildReceipt(s, table);
+    const date = r.startedAt ? new Date(r.startedAt).toISOString().slice(0, 10) : 'unknown';
+    const models = r.models.map((m) => m.displayName.replace(/\s*\(.*\)/, '')).join(', ') || 'none';
+    const title = (s.title ?? '').slice(0, 20);
+    console.log(
+      `${s.sessionId.slice(0, 8)}  ${title.padEnd(20)}  ${s.project.slice(0, 25).padEnd(25)}  ${date.padEnd(12)}  ${models.padEnd(8)}  ${fmtUsd(r.totals.cost.total)}`
+    );
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const asJson = args.includes('--json');
+  const filtered = args.filter((a) => a !== '--json');
+
+  if (filtered[0] === 'list') {
+    const sessions = discoverSessions();
+    if (!sessions.length) {
+      console.log('No Claude Code sessions found under ~/.claude/projects.');
+      return;
+    }
+    const table = await loadPricingTable();
+    if (asJson) {
+      const billingMode = detectBillingMode();
+      console.log(JSON.stringify(sessions.map((s) => ({ ...buildReceipt(s, table), billingMode })), null, 2));
+    } else {
+      printList(sessions, table);
+    }
+    return;
+  }
+
+  let sessions;
+  if (filtered.includes('--all')) {
+    sessions = discoverSessions();
+  } else if (filtered[0]) {
+    const found = findSession(filtered[0]);
+    if (!found) {
+      console.error(`No session found matching "${filtered[0]}". Try "burner-cc list".`);
+      process.exitCode = 1;
+      return;
+    }
+    sessions = [found];
+  } else {
+    const latest = latestSession();
+    if (!latest) {
+      console.log('No Claude Code sessions found under ~/.claude/projects.');
+      return;
+    }
+    sessions = [latest];
+  }
+
+  const table = await loadPricingTable();
+  const billingMode = detectBillingMode();
+  const receipts = sessions.map((s) => ({ ...buildReceipt(s, table), billingMode }));
+
+  if (asJson) {
+    console.log(JSON.stringify(receipts, null, 2));
+    return;
+  }
+
+  const outFile = renderReceipts(receipts);
+  console.log(`Receipt written to ${outFile}`);
+  openInBrowser(outFile);
+}
+
+main().catch((err) => {
+  console.error('burner-cc failed:', err.message);
+  process.exitCode = 1;
+});

package/src/discover.js

@@ -0,0 +1,125 @@
+import { readdirSync, statSync, readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+function claudeProjectsRoot() {
+  return path.join(os.homedir(), '.claude', 'projects');
+}
+
+function walk(dir, out = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full, out);
+    } else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// Each "agent-<hash>.jsonl" subagent transcript has a sibling
+// "agent-<hash>.meta.json" naming its agent type and task description —
+// that's what lets a receipt break subagent cost down by type instead of
+// lumping every subagent run together.
+function readSubagentMeta(subagentFile) {
+  const metaPath = subagentFile.replace(/\.jsonl$/, '.meta.json');
+  if (!existsSync(metaPath)) return null;
+  try {
+    return JSON.parse(readFileSync(metaPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+// A session's human-readable name isn't the UUID filename — Claude Code
+// logs it as a "custom-title" event when the user runs /rename, falling
+// back to the auto-generated "slug" (e.g. "wise-bubbling-wadler") that's
+// stamped on every line. Either one should be usable to find a session.
+function readSessionTitle(mainFile) {
+  let text;
+  try {
+    text = readFileSync(mainFile, 'utf-8');
+  } catch {
+    return null;
+  }
+  let title = null;
+  let slug = null;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    if (!slug) {
+      const slugMatch = line.match(/"slug":"([^"]*)"/);
+      if (slugMatch) slug = slugMatch[1];
+    }
+    if (line.includes('"type":"custom-title"')) {
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed.customTitle) title = parsed.customTitle;
+      } catch {
+        // ignore malformed line
+      }
+    }
+  }
+  return title || slug || null;
+}
+
+// A session is identified by its top-level "<sessionId>.jsonl" file. Any
+// "<sessionId>/subagents/agent-*.jsonl" files sit alongside it and are
+// billed separately by the API, so their cost is real but attributed back
+// to the parent session rather than shown as their own session.
+export function discoverSessions() {
+  const root = claudeProjectsRoot();
+  const files = walk(root);
+
+  const sessions = new Map();
+
+  for (const file of files) {
+    const rel = path.relative(root, file);
+    const parts = rel.split(path.sep);
+    const project = parts[0];
+    const isSubagent = parts.includes('subagents');
+    const sessionId = isSubagent ? parts[1] : path.basename(file, '.jsonl');
+
+    if (!sessions.has(sessionId)) {
+      sessions.set(sessionId, { sessionId, project, mainFile: null, subagentFiles: [] });
+    }
+    const entry = sessions.get(sessionId);
+    if (isSubagent) {
+      entry.subagentFiles.push({ file, meta: readSubagentMeta(file) });
+    } else {
+      entry.mainFile = file;
+    }
+  }
+
+  // Drop entries that only have subagent files but never got a parent
+  // transcript picked up (shouldn't normally happen, but be defensive).
+  const result = [...sessions.values()].filter((s) => s.mainFile);
+
+  for (const s of result) {
+    s.mtime = statSync(s.mainFile).mtimeMs;
+    s.title = readSessionTitle(s.mainFile);
+  }
+
+  result.sort((a, b) => b.mtime - a.mtime);
+  return result;
+}
+
+export function findSession(idOrPrefix) {
+  const all = discoverSessions();
+  const needle = idOrPrefix.toLowerCase();
+  return (
+    all.find((s) => s.sessionId === idOrPrefix) ||
+    all.find((s) => s.title?.toLowerCase() === needle) ||
+    all.find((s) => s.sessionId.startsWith(idOrPrefix))
+  );
+}
+
+export function latestSession() {
+  return discoverSessions()[0] ?? null;
+}

package/src/parse.js

@@ -0,0 +1,80 @@
+import { readFileSync } from 'node:fs';
+
+// Reads one transcript file and returns a flat list of billed turns:
+// { model, timestamp, input, output, cacheWrite5m, cacheWrite1h, cacheRead }
+// plus a tool-activity tally: { mcp: {server: count}, skills: {name: count}, web: {WebFetch/WebSearch: count} }
+export function parseTranscript(file) {
+  let text;
+  try {
+    text = readFileSync(file, 'utf-8');
+  } catch {
+    return { turns: [], activity: { mcp: {}, skills: {}, web: {} } };
+  }
+
+  const turns = [];
+  const mcp = {};
+  const skills = {};
+  const web = {};
+
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const msg = entry.message;
+    if (!msg || msg.type !== 'message' || msg.role !== 'assistant') continue;
+
+    // Tool-call activity: tallied regardless of whether this line also
+    // carries usage, since a message can contain tool_use blocks either way.
+    if (Array.isArray(msg.content)) {
+      for (const block of msg.content) {
+        if (block.type !== 'tool_use') continue;
+        if (block.name === 'Skill' && block.input?.skill) {
+          skills[block.input.skill] = (skills[block.input.skill] ?? 0) + 1;
+        } else if (block.name.startsWith('mcp__')) {
+          const server = block.name.split('__')[1] ?? 'unknown';
+          mcp[server] = (mcp[server] ?? 0) + 1;
+        } else if (block.name === 'WebFetch' || block.name === 'WebSearch') {
+          web[block.name] = (web[block.name] ?? 0) + 1;
+        }
+      }
+    }
+
+    if (!msg.usage) continue;
+    if (msg.model === '<synthetic>') continue; // internal zero-usage marker, not a billed turn
+
+    const u = msg.usage;
+    const isAllZero = !u.input_tokens && !u.output_tokens && !u.cache_creation_input_tokens && !u.cache_read_input_tokens;
+    if (isAllZero) continue;
+    const cacheCreation = u.cache_creation ?? {};
+    turns.push({
+      model: msg.model ?? 'unknown',
+      timestamp: entry.timestamp ?? null,
+      input: u.input_tokens ?? 0,
+      output: u.output_tokens ?? 0,
+      cacheWrite5m: cacheCreation.ephemeral_5m_input_tokens ?? u.cache_creation_input_tokens ?? 0,
+      cacheWrite1h: cacheCreation.ephemeral_1h_input_tokens ?? 0,
+      cacheRead: u.cache_read_input_tokens ?? 0,
+    });
+  }
+  return { turns, activity: { mcp, skills, web } };
+}
+
+export function timeRange(turns) {
+  const stamps = turns.map((t) => t.timestamp).filter(Boolean).sort();
+  return { startedAt: stamps[0] ?? null, endedAt: stamps[stamps.length - 1] ?? null };
+}
+
+export function mergeActivity(activities) {
+  const merged = { mcp: {}, skills: {}, web: {} };
+  for (const a of activities) {
+    for (const [k, v] of Object.entries(a.mcp)) merged.mcp[k] = (merged.mcp[k] ?? 0) + v;
+    for (const [k, v] of Object.entries(a.skills)) merged.skills[k] = (merged.skills[k] ?? 0) + v;
+    for (const [k, v] of Object.entries(a.web)) merged.web[k] = (merged.web[k] ?? 0) + v;
+  }
+  return merged;
+}

package/src/pricing-fallback.json

@@ -0,0 +1,9 @@
+{
+  "_comment": "Last-resort snapshot only, used when there's no network AND no prior cache at ~/.burner-cc-cache/litellm-pricing.json. Normal operation fetches live from LiteLLM's Anthropic-sourced pricing JSON — see src/pricing.js. Values below are USD per million tokens, captured 2026-09-27.",
+  "models": {
+    "claude-opus-5": { "displayName": "Claude Opus 5", "input": 5, "output": 25, "cacheWrite5m": 6.25, "cacheWrite1h": 10, "cacheRead": 0.5 },
+    "claude-sonnet-5": { "displayName": "Claude Sonnet 5", "input": 2, "output": 10, "cacheWrite5m": 2.5, "cacheWrite1h": 4, "cacheRead": 0.2 },
+    "claude-haiku-4-5": { "displayName": "Claude Haiku 4.5", "input": 1, "output": 5, "cacheWrite5m": 1.25, "cacheWrite1h": 2, "cacheRead": 0.1 },
+    "claude-fable-5": { "displayName": "Claude Fable 5", "input": 10, "output": 50, "cacheWrite5m": 12.5, "cacheWrite1h": 20, "cacheRead": 1 }
+  }
+}

package/src/pricing.js

@@ -0,0 +1,143 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import os from 'node:os';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const cacheDir = path.join(os.homedir(), '.burner-cc-cache');
+const cacheFile = path.join(cacheDir, 'litellm-pricing.json');
+const fallbackFile = path.join(__dirname, 'pricing-fallback.json');
+
+const SOURCE_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
+const TTL_MS = 6 * 60 * 60 * 1000; // 6h — pricing changes rarely, this just avoids hammering GitHub.
+
+// Anthropic bare-alias shorthands Claude Code sometimes writes instead of a
+// dated/versioned model id (e.g. subagent transcripts saying "sonnet").
+const ALIAS_FAMILIES = ['opus', 'sonnet', 'haiku', 'fable', 'mythos'];
+
+function toRates(entry, displayName) {
+  const mtok = 1_000_000;
+  return {
+    displayName,
+    input: entry.input_cost_per_token * mtok,
+    output: entry.output_cost_per_token * mtok,
+    cacheWrite5m: (entry.cache_creation_input_token_cost ?? 0) * mtok,
+    cacheWrite1h: (entry.cache_creation_input_token_cost_above_1hr ?? entry.cache_creation_input_token_cost ?? 0) * mtok,
+    cacheRead: (entry.cache_read_input_token_cost ?? 0) * mtok,
+  };
+}
+
+function buildTableFromLiteLLM(raw) {
+  const models = {};
+  for (const [key, entry] of Object.entries(raw)) {
+    if (entry.litellm_provider !== 'anthropic' || entry.mode !== 'chat') continue;
+    if (typeof entry.input_cost_per_token !== 'number' || typeof entry.output_cost_per_token !== 'number') continue;
+    models[key] = toRates(entry, prettyName(key));
+  }
+  return models;
+}
+
+function prettyName(modelId) {
+  const parts = modelId.split('-').filter((p) => p !== 'claude');
+  if (!parts.length) return modelId;
+  const family = parts[0][0].toUpperCase() + parts[0].slice(1);
+  const rest = parts.slice(1).join('.');
+  return rest ? `Claude ${family} ${rest}` : `Claude ${family}`;
+}
+
+async function fetchLiteLLMTable() {
+  const res = await fetch(SOURCE_URL, { signal: AbortSignal.timeout(8000) });
+  if (!res.ok) throw new Error(`pricing source returned ${res.status}`);
+  const raw = await res.json();
+  return buildTableFromLiteLLM(raw);
+}
+
+function readCache() {
+  if (!existsSync(cacheFile)) return null;
+  try {
+    return JSON.parse(readFileSync(cacheFile, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(models) {
+  mkdirSync(cacheDir, { recursive: true });
+  writeFileSync(cacheFile, JSON.stringify({ fetchedAt: Date.now(), models }, null, 2), 'utf-8');
+}
+
+function cacheIsFresh(cache) {
+  return cache && Date.now() - cache.fetchedAt < TTL_MS;
+}
+
+// Resolves the full pricing table once per CLI invocation: fresh cache wins,
+// otherwise re-fetch from LiteLLM's community-maintained (Anthropic-sourced)
+// pricing JSON, falling back to a stale cache or the bundled snapshot if
+// offline. This is the whole point: nobody has to hand-edit prices.
+export async function loadPricingTable() {
+  const cache = readCache();
+  if (cacheIsFresh(cache)) {
+    return { models: cache.models, source: 'cache', fetchedAt: cache.fetchedAt };
+  }
+
+  try {
+    const models = await fetchLiteLLMTable();
+    writeCache(models);
+    return { models, source: 'live', fetchedAt: Date.now() };
+  } catch (err) {
+    if (cache) {
+      return { models: cache.models, source: 'stale-cache', fetchedAt: cache.fetchedAt, error: err.message };
+    }
+    const fallback = JSON.parse(readFileSync(fallbackFile, 'utf-8'));
+    return { models: fallback.models, source: 'bundled-fallback', fetchedAt: null, error: err.message };
+  }
+}
+
+function resolveAlias(rawModel, models) {
+  const family = ALIAS_FAMILIES.find((f) => rawModel === f || rawModel.startsWith(f + '-'));
+  if (!family) return null;
+  // Pick the newest-looking concrete model in that family: prefer bare
+  // "claude-<family>-<N>" ids (no date suffix) and take the highest one.
+  const candidates = Object.keys(models).filter((k) => k.startsWith(`claude-${family}-`) && /^claude-[a-z]+-[\d.]+$/.test(k));
+  candidates.sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+  return candidates[0] ?? null;
+}
+
+export function lookupPricing(rawModel, table) {
+  if (!rawModel) return { fidelity: 'unknown', rates: null, displayName: 'unknown model' };
+  const models = table.models;
+
+  if (models[rawModel]) {
+    return { fidelity: 'measured', rates: models[rawModel], displayName: models[rawModel].displayName };
+  }
+
+  const aliasTarget = resolveAlias(rawModel, models);
+  if (aliasTarget) {
+    const rates = models[aliasTarget];
+    return { fidelity: 'approximate-alias', rates, displayName: `${rates.displayName} (via alias "${rawModel}")` };
+  }
+
+  // Longest-prefix match as a last resort (handles dated variants Claude
+  // Code might report that aren't in the pricing source verbatim).
+  const prefixMatch = Object.keys(models)
+    .filter((k) => rawModel.startsWith(k) || k.startsWith(rawModel))
+    .sort((a, b) => b.length - a.length)[0];
+  if (prefixMatch) {
+    const rates = models[prefixMatch];
+    return { fidelity: 'approximate-alias', rates, displayName: `${rates.displayName} (matched from "${rawModel}")` };
+  }
+
+  return { fidelity: 'unpriced', rates: null, displayName: rawModel };
+}
+
+export function costFor(usage, rates) {
+  if (!rates) return null;
+  const mtok = 1_000_000;
+  const cacheWrite5m = usage.cacheWrite5m ?? 0;
+  const cacheWrite1h = usage.cacheWrite1h ?? 0;
+  const input = (usage.input / mtok) * rates.input;
+  const output = (usage.output / mtok) * rates.output;
+  const cacheWrite = (cacheWrite5m / mtok) * rates.cacheWrite5m + (cacheWrite1h / mtok) * rates.cacheWrite1h;
+  const cacheRead = (usage.cacheRead / mtok) * rates.cacheRead;
+  return { input, output, cacheWrite, cacheRead, total: input + output + cacheWrite + cacheRead };
+}