@ycstudios/token-tab 0.1.0

package/src/core.mjs

@@ -0,0 +1,278 @@
+// Token Tab — pure parsing core.
+//
+// No I/O, no dependencies. Takes already-parsed JSONL objects and returns an
+// aggregate. Keeping this pure is what lets golden-fixture tests pin every edge
+// case (see the test plan) without touching the filesystem or a sandbox.
+//
+// It never touches `message.content` — only the metadata fields needed to count
+// tokens. That is the whole trust story: we read the numbers, never your text.
+
+/** Sum of all four token classes — matches ccusage's default total. cache_read
+ * usually dominates, so leaving it out would diverge wildly. */
+export function usageSum(u) {
+  if (!u) return 0;
+  return (
+    (u.input_tokens || 0) +
+    (u.cache_creation_input_tokens || 0) +
+    (u.cache_read_input_tokens || 0) +
+    (u.output_tokens || 0)
+  );
+}
+
+export function usageByClass(u) {
+  return {
+    input: u?.input_tokens || 0,
+    cacheCreate: u?.cache_creation_input_tokens || 0,
+    cacheRead: u?.cache_read_input_tokens || 0,
+    output: u?.output_tokens || 0,
+  };
+}
+
+/** Strip the `[1m]` 1M-context suffix; report whether it was present (it's a
+ * distinct price tier for the dollars layer later). */
+export function normalizeModel(model) {
+  if (typeof model !== "string") return { base: "<unknown>", oneM: false };
+  const oneM = model.endsWith("[1m]");
+  return { base: oneM ? model.slice(0, -4) : model, oneM };
+}
+
+/** Route a model id to a billing surface.
+ *  bedrock:      us.anthropic.* / anthropic.*:0
+ *  subscription: claude-* and bare names (sonnet/opus/haiku)
+ *  untracked:    <synthetic> and anything unrecognized (still counted for tokens) */
+export function classifySurface(model) {
+  const { base } = normalizeModel(model);
+  if (!base || base === "<synthetic>" || base === "<unknown>") return "untracked";
+  // Bedrock ids carry an optional region prefix (us./eu./apac./us-gov.) before
+  // `anthropic.`; strip it so every region routes to bedrock — matching the
+  // region set canonicalModelId strips in pricing.mjs (kept in lockstep).
+  const deregioned = base.replace(/^(us|eu|apac|us-gov)\./, "");
+  if (deregioned.startsWith("anthropic.")) return "bedrock";
+  if (base.startsWith("claude-") || /^(sonnet|opus|haiku)$/i.test(base)) return "subscription";
+  return "untracked";
+}
+
+const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
+
+function localDayKey(d) {
+  // YYYY-MM-DD in LOCAL time (logs are UTC; "today" must mean the user's day).
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+function startOfLocalWeek(now, weekStartsOn /* 0=Sun,1=Mon */) {
+  const d = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const diff = (d.getDay() - weekStartsOn + 7) % 7;
+  d.setDate(d.getDate() - diff);
+  return d;
+}
+
+
+/**
+ * Aggregate a stream of assistant usage records.
+ *
+ * @param {Iterable<{messageId?:string,requestId?:string,model:string,usage:object,timestamp:string,isSidechain?:boolean}>} records
+ * @param {{now?:Date, weekStartsOn?:number, cost?:(usage:object,model:string)=>{usd:number,priced:boolean}}} opts
+ *   opts.cost (optional): a pure pricing function (see src/pricing.mjs). When supplied,
+ *   the result carries a `cost` block (dollars per window + per model). Omit it and the
+ *   output is byte-for-byte unchanged — the dollars layer never alters the token numbers.
+ * @returns aggregate snapshot (plain value object — no content, no PII)
+ */
+export function aggregate(records, opts = {}) {
+  const now = opts.now ? new Date(opts.now) : new Date();
+  const weekStartsOn = opts.weekStartsOn ?? 1; // Monday
+  const costFn = typeof opts.cost === "function" ? opts.cost : null;
+  const todayKey = localDayKey(now);
+  const weekStart = startOfLocalWeek(now, weekStartsOn).getTime();
+  const rollingCutoff = now.getTime() - FIVE_HOURS_MS;
+
+  // Pass 1 — dedup with KEEP-LAST resolution.
+  // Key = `${messageId}:${requestId}` when BOTH exist; otherwise a unique key (so a
+  // line missing an id is always counted, never collapsed).
+  // Streaming emits several usage lines per message sharing one key; input/cache
+  // are constant across them but `output_tokens` GROWS, so the FINAL line is
+  // authoritative. Keeping last (verified against ccusage: output reconciles only
+  // with last-write-wins) — collisions with differing totals are still reported.
+  const kept = new Map(); // key -> record (last seen)
+  let uniqueCounter = 0;
+  let duplicatesDropped = 0;
+  let collisionsDifferingTotals = 0;
+  let approximate = false;
+
+  for (const r of records) {
+    const hasIds = !!(r.messageId && r.requestId);
+    const key = hasIds ? `${r.messageId}:${r.requestId}` : `__nokey__${uniqueCounter++}`;
+    if (!hasIds) approximate = true;
+    if (kept.has(key)) {
+      duplicatesDropped++;
+      if (usageSum(kept.get(key).usage) !== usageSum(r.usage)) collisionsDifferingTotals++;
+    }
+    kept.set(key, r); // last-write-wins (records arrive in deterministic file-mtime+line order)
+  }
+
+  // Pass 2 — aggregate the deduped records.
+  const byClass = { input: 0, cacheCreate: 0, cacheRead: 0, output: 0 };
+  const bySurface = {}; // surface -> tokens
+  const byModel = {}; // base model -> tokens
+  let total = 0;
+  let today = 0;
+  let thisWeek = 0;
+  let rolling5h = 0;
+  let counted = 0;
+  let untrackedTokens = 0;
+  let untrackedRequests = 0;
+  // Dollars (only when a pricing fn is injected). Mirrors the token windows so the
+  // estimate can be shown per today/week/5h. "unpriced" = a model with no rate in the
+  // table: its tokens still count everywhere else, just not toward dollars.
+  let costTotal = 0;
+  let costToday = 0;
+  let costWeek = 0;
+  let costRolling = 0;
+  const costByModel = {};
+  let unpricedTokens = 0;
+  let unpricedRequests = 0;
+  const unpricedModels = new Set();
+  const stamps = []; // {t, sum} for the window pass (past-dated only)
+
+  for (const r of kept.values()) {
+    const sum = usageSum(r.usage);
+    counted++;
+    total += sum;
+    const c = usageByClass(r.usage);
+    byClass.input += c.input;
+    byClass.cacheCreate += c.cacheCreate;
+    byClass.cacheRead += c.cacheRead;
+    byClass.output += c.output;
+
+    const surface = classifySurface(r.model);
+    bySurface[surface] = (bySurface[surface] || 0) + sum;
+    const { base } = normalizeModel(r.model);
+    byModel[base] = (byModel[base] || 0) + sum;
+    if (surface === "untracked") {
+      untrackedTokens += sum;
+      untrackedRequests++;
+    }
+
+    let usd = 0;
+    let priced = false;
+    if (costFn) {
+      const c2 = costFn(r.usage, r.model);
+      usd = c2.usd || 0;
+      priced = !!c2.priced;
+      if (priced) {
+        costTotal += usd;
+        costByModel[base] = (costByModel[base] || 0) + usd;
+      } else {
+        unpricedTokens += sum;
+        unpricedRequests++;
+        unpricedModels.add(base);
+      }
+    }
+
+    const ts = new Date(r.timestamp);
+    if (!isNaN(ts)) {
+      // Upper-bound every window at `now` so a future-dated line (clock skew)
+      // can't inflate today/week/5h. Total still includes it — it's real spend,
+      // just mis-stamped. Makes rolling5h the documented half-open (now-5h, now].
+      const tms = ts.getTime();
+      if (tms <= now.getTime()) {
+        if (localDayKey(ts) === todayKey) today += sum;
+        if (tms >= weekStart) thisWeek += sum;
+        if (tms > rollingCutoff) rolling5h += sum;
+        if (priced) {
+          if (localDayKey(ts) === todayKey) costToday += usd;
+          if (tms >= weekStart) costWeek += usd;
+          if (tms > rollingCutoff) costRolling += usd;
+        }
+        stamps.push({ t: tms, sum });
+      }
+    }
+  }
+
+  // Pass 3 — current usage window (Anthropic-style fixed 5h reset blocks).
+  // A block starts at the EXACT first message (verified: Claude anchors the window to
+  // your first message, not the top of the hour) and lasts blockHours; a gap >
+  // blockHours, or crossing the block end, starts a new block. The reset time is exact.
+  // The % needs the plan cap, which Anthropic does not publish — so pct is only given
+  // when opts.cap is supplied. calibratedCap (busiest completed block) is exposed as
+  // info but is NOT used as a denominator: you've usually never maxed a window, so it
+  // would over-report how close you are. Set the cap from Claude's /usage to get a %.
+  const blockMs = (opts.blockHours ?? 5) * 60 * 60 * 1000;
+  stamps.sort((a, b) => a.t - b.t);
+  const blocks = [];
+  for (const s of stamps) {
+    const last = blocks[blocks.length - 1];
+    if (last && s.t - last.lastT <= blockMs && s.t < last.start + blockMs) {
+      last.tokens += s.sum;
+      last.lastT = s.t;
+    } else {
+      blocks.push({ start: s.t, lastT: s.t, tokens: s.sum });
+    }
+  }
+  const nowMs = now.getTime();
+  const lastBlock = blocks[blocks.length - 1] || null;
+  const windowActive = !!(lastBlock && nowMs >= lastBlock.start && nowMs < lastBlock.start + blockMs);
+  const completed = windowActive ? blocks.slice(0, -1) : blocks;
+  const calibratedCap = completed.reduce((m, b) => Math.max(m, b.tokens), 0);
+  const cap = opts.cap != null && opts.cap > 0 ? opts.cap : 0;
+  const windowTokens = windowActive ? lastBlock.tokens : 0;
+  const resetAt = windowActive ? lastBlock.start + blockMs : null;
+  const windowStats = {
+    active: windowActive,
+    tokens: windowTokens,
+    resetAt, // ms epoch, or null when no active block
+    msToReset: resetAt != null ? resetAt - nowMs : null,
+    cap, // 0 when no configured cap
+    calibratedCap, // busiest completed block — informational only
+    capSource: cap > 0 ? "config" : "none",
+    pct: cap > 0 ? Math.round((windowTokens / cap) * 100) : null,
+  };
+
+  return {
+    total,
+    byClass,
+    bySurface,
+    byModel,
+    today,
+    thisWeek,
+    rolling5h,
+    window: windowStats,
+    dedup: { counted, duplicatesDropped, collisionsDifferingTotals },
+    approximate,
+    untracked: { tokens: untrackedTokens, requests: untrackedRequests },
+    // Present only when opts.cost was supplied. Dollars are an estimate; `unpriced`
+    // records the tokens we counted but had no rate for (honest gap, never guessed).
+    cost: costFn
+      ? {
+          total: costTotal,
+          today: costToday,
+          thisWeek: costWeek,
+          rolling5h: costRolling,
+          byModel: costByModel,
+          unpriced: {
+            tokens: unpricedTokens,
+            requests: unpricedRequests,
+            models: [...unpricedModels].sort(),
+          },
+        }
+      : undefined,
+  };
+}
+
+/** Extract the fields we care about from a raw JSONL object. Returns null for
+ * any line that is not an assistant turn carrying usage. Never reads content. */
+export function recordFromLine(obj) {
+  if (!obj || obj.type !== "assistant") return null;
+  const usage = obj.message?.usage;
+  if (!usage) return null;
+  return {
+    messageId: obj.message?.id,
+    requestId: obj.requestId,
+    model: obj.message?.model ?? "<unknown>",
+    usage,
+    timestamp: obj.timestamp,
+    isSidechain: !!obj.isSidechain, // counted, NOT filtered — sidechains are real spend
+  };
+}

package/src/live-parse.mjs

@@ -0,0 +1,74 @@
+// Token Tab — pure parser for the opt-in live usage window.
+//
+// PURE: no I/O, no subprocess, no network. Takes the raw stdout of
+// `claude -p "/usage" --output-format json` and returns the server-side
+// session/weekly percentages, or null on anything unexpected (fail closed).
+//
+// This file deliberately lives in src/ (the audited core); the live adapter that
+// produces its input lives under adapters/ (outside src/). Keeping the audited
+// core free of subprocess and network calls is the whole point — the audit greps
+// over src/ must keep printing nothing, so this file avoids those tokens even in
+// comments (it uses String.match, not the dotted variant the audit looks for).
+//
+// Robustness notes (each pins a real failure mode, see test/live-parse.test.mjs):
+//  - The percentage is matched INDEPENDENTLY of the "· resets …" tail, so a
+//    future separator/encoding change (the `·` is U+00B7) costs only the reset
+//    text, never the number the feature exists to show.
+//  - We split on "\n" and match per line; a single anchored regex against the
+//    whole multi-line `result` would never match.
+//  - The whole body is guarded so parseUsageOutput(null) returns null, never
+//    throws (JSON.parse("null") yields null without throwing).
+
+const PCT_RE = /^Current (session|week \(([^)]+)\)):\s*(\d+)%\s*used\b(.*)$/;
+const RESET_RE = /resets\s+(.+?)\s*$/;
+
+/**
+ * @param {string} stdout raw JSON string from `claude -p "/usage" --output-format json`
+ * @returns {null | {source:string, sessionPct?:number, sessionResetText?:string,
+ *   weeklyPct?:number, weeklyResetText?:string, weeklyByModel:Object}}
+ */
+export function parseUsageOutput(stdout) {
+  let obj;
+  try {
+    obj = JSON.parse(stdout);
+  } catch {
+    return null; // non-JSON stdout (e.g. "command not found")
+  }
+  // JSON.parse("null") returns null WITHOUT throwing — guard before any access.
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) return null;
+  if (obj.is_error === true || typeof obj.result !== "string") return null;
+
+  let sessionPct, sessionResetText, weeklyPct, weeklyResetText;
+  const weeklyByModel = {};
+  let found = false;
+
+  for (const raw of obj.result.split("\n")) {
+    const line = raw.replace(/\r$/, ""); // tolerate CRLF
+    const m = line.match(PCT_RE);
+    if (!m) continue;
+    const kind = m[1]; // "session" | "week (...)"
+    const inner = m[2]; // undefined | "all models" | "Sonnet only"
+    const pct = Number(m[3]);
+    const rm = (m[4] || "").match(RESET_RE); // tail parsed independently of the separator
+    const resetText = rm ? rm[1] : undefined; // undefined on idle / drift
+
+    if (kind === "session") {
+      sessionPct = pct;
+      sessionResetText = resetText;
+      found = true;
+    } else {
+      const label = inner.trim().toLowerCase();
+      if (label === "all models") {
+        weeklyPct = pct;
+        weeklyResetText = resetText;
+        found = true;
+      } else {
+        weeklyByModel[label.replace(/\s+only$/, "")] = pct; // "Sonnet only" -> "sonnet"
+        found = true;
+      }
+    }
+  }
+
+  if (!found) return null; // no "Current …% used" line anywhere
+  return { source: "claude /usage", sessionPct, sessionResetText, weeklyPct, weeklyResetText, weeklyByModel };
+}

package/src/pricing.mjs

@@ -0,0 +1,104 @@
+// Token Tab — price table + cost math (pure, no I/O, no dependencies).
+//
+// Dollars are an ESTIMATE, not an invoice (this is a stated premise of the design:
+// "good enough to know your tab, not good enough for accounting"). It is a bundled
+// per-model rate table applied to the four token classes the logs already carry —
+// no network call, no key, nothing retrieved. Just arithmetic on numbers already on disk.
+//
+// Rates are USD per MILLION tokens, from Anthropic's public list pricing. Input and
+// output are listed per model; the two cache classes are derived from the input rate
+// using Anthropic's published multipliers:
+//   cache WRITE (cache_creation_input_tokens) = 1.25x input  — the 5-minute-TTL write
+//        rate. The logs don't record the TTL, so we assume 5m (what ccusage assumes too).
+//   cache READ  (cache_read_input_tokens)      = 0.10x input
+//
+// Unknown models are NEVER invented a price for. costOfUsage returns priced:false and
+// the caller still counts the tokens — "tracked tokens, untracked price." A guessed
+// dollar figure that disagrees with the real bill is worse than honestly saying "unknown."
+
+import { usageByClass, normalizeModel } from "./core.mjs";
+
+const CACHE_WRITE_MULT = 1.25; // 5-minute cache-write rate, relative to input
+const CACHE_READ_MULT = 0.1; // cache-read rate, relative to input
+
+// input / output USD per 1M tokens, from Anthropic's published list pricing. Covers every
+// model Anthropic still publishes a standard rate for — current models plus older ones that
+// remain billable (several only on Bedrock/Vertex now). Models with NO published rate
+// (e.g. Haiku 3) and synthetic ids fall through to unpriced on purpose — a guessed figure
+// is worse than an honest "no rate." The 1M-context tier ([1m] suffix) is standard-priced
+// on current models (no long-context premium), so it shares the base rate — normalizeModel
+// strips the suffix before lookup.
+const RATES = {
+  // Current models.
+  "claude-fable-5": { input: 10, output: 50 },
+  "claude-opus-4-8": { input: 5, output: 25 },
+  "claude-opus-4-7": { input: 5, output: 25 },
+  "claude-opus-4-6": { input: 5, output: 25 },
+  // Sonnet 5 list price. Anthropic is running a $2/$10 introductory rate through
+  // 2026-08-31, but the table isn't date-aware and documents itself as list pricing —
+  // the intro discount would silently go stale on 2026-09-01. (Same as Sonnet 4.6.)
+  "claude-sonnet-5": { input: 3, output: 15 },
+  "claude-sonnet-4-6": { input: 3, output: 15 },
+  "claude-haiku-4-5": { input: 1, output: 5 },
+  // Older, still-billable models. canonicalModelId reduces dated/Bedrock ids to these keys
+  // (e.g. claude-sonnet-4-20250514 and anthropic.claude-sonnet-4-...-v1:0 -> claude-sonnet-4).
+  "claude-opus-4-5": { input: 5, output: 25 },
+  "claude-opus-4-1": { input: 15, output: 75 },
+  "claude-opus-4": { input: 15, output: 75 },
+  "claude-sonnet-4-5": { input: 3, output: 15 },
+  "claude-sonnet-4": { input: 3, output: 15 },
+  "claude-3-5-haiku": { input: 0.8, output: 4 },
+};
+
+// Bare aliases Claude Code sometimes writes (e.g. "sonnet") resolve to the current
+// model in that family. This is the same family→latest mapping the official tooling uses.
+const ALIASES = {
+  opus: "claude-opus-4-8",
+  sonnet: "claude-sonnet-5",
+  haiku: "claude-haiku-4-5",
+};
+
+/** Reduce any model id to the rate-table key:
+ *  - strip the [1m] suffix (same surface, same price on current models)
+ *  - strip Bedrock region prefixes (us./eu./apac.) and the `anthropic.` vendor prefix
+ *  - strip the Bedrock `-vN:M` version suffix and a trailing `-YYYYMMDD` snapshot date
+ *  So `us.anthropic.claude-opus-4-8-20251101-v1:0` and `claude-opus-4-8[1m]` both → `claude-opus-4-8`.
+ *  Bedrock thus reuses the list-price table (region surcharges are not modeled — part of the stated tolerance). */
+export function canonicalModelId(model) {
+  let id = normalizeModel(model).base;
+  if (typeof id !== "string") return "";
+  id = id.toLowerCase();
+  id = id.replace(/^(us|eu|apac|us-gov)\./, ""); // Bedrock region prefix
+  id = id.replace(/^anthropic\./, ""); // Bedrock vendor prefix
+  id = id.replace(/-v\d+:\d+$/, ""); // Bedrock version suffix
+  id = id.replace(/-\d{8}$/, ""); // dated snapshot suffix (e.g. -20251001)
+  return id;
+}
+
+/** Per-class USD-per-million rates for a model, or null when it isn't in the table. */
+export function ratesFor(model) {
+  const id = canonicalModelId(model);
+  const base = RATES[id] || RATES[ALIASES[id]];
+  if (!base) return null;
+  return {
+    input: base.input,
+    cacheWrite: base.input * CACHE_WRITE_MULT,
+    cacheRead: base.input * CACHE_READ_MULT,
+    output: base.output,
+  };
+}
+
+/** Cost of one usage block under a model. Returns {usd, priced}: priced:false means
+ *  the model isn't in the table — usd is 0 and the caller should track tokens, not dollars. */
+export function costOfUsage(usage, model) {
+  const r = ratesFor(model);
+  if (!r) return { usd: 0, priced: false };
+  const c = usageByClass(usage);
+  const usd =
+    (c.input * r.input +
+      c.cacheCreate * r.cacheWrite +
+      c.cacheRead * r.cacheRead +
+      c.output * r.output) /
+    1e6;
+  return { usd, priced: true };
+}