@vimoxshah/tokenflow 1.1.0

package/src/core/model-map.js

@@ -0,0 +1,157 @@
+/**
+ * Provider + model-family classification.
+ *
+ * Rules are DATA, not code paths: the list below is the built-in ruleset and
+ * a user's `~/.tokenflow/config.yaml` can prepend their own rules
+ * (`modelMappings:`) without touching the dashboard. A model that matches
+ * nothing becomes provider `unknown` with its raw string preserved — it is
+ * never bucketed into a plausible-looking vendor.
+ */
+
+/** @typedef {{match: string, provider: string, label: string, family?: string, familyFrom?: string[]}} ModelRule */
+
+/** @type {ModelRule[]} */
+export const BUILTIN_MODEL_RULES = [
+  {
+    match: '(^|/)claude|^anthropic\\.|claude-instant',
+    provider: 'anthropic',
+    label: 'Anthropic',
+    familyFrom: ['opus', 'sonnet', 'haiku'],
+  },
+  {
+    match: '(^|/)(gpt|chatgpt|o[1345](-|$)|codex|text-davinci|davinci)',
+    provider: 'openai',
+    label: 'OpenAI',
+  },
+  { match: 'deepseek', provider: 'deepseek', label: 'DeepSeek' },
+  { match: '(^|/)(glm|charglm|cogview)|z-?ai', provider: 'zai', label: 'Z.ai / GLM' },
+  { match: '(^|/)(gemini|gemma|palm|bison)', provider: 'google', label: 'Google' },
+  { match: '(^|/)(qwen|qwq)', provider: 'alibaba', label: 'Alibaba / Qwen' },
+  { match: 'kimi|moonshot', provider: 'moonshot', label: 'Moonshot / Kimi' },
+  { match: '(^|/)grok', provider: 'xai', label: 'xAI / Grok' },
+  { match: '(^|/)(llama|codellama)', provider: 'meta', label: 'Meta / Llama' },
+  { match: '(^|/)(mistral|mixtral|codestral|magistral)', provider: 'mistral', label: 'Mistral' },
+  { match: '(^|/)(command-?r?|cohere)', provider: 'cohere', label: 'Cohere' },
+  { match: '(^|/)(nova)|^amazon\\.', provider: 'amazon', label: 'Amazon / Nova' },
+  { match: '(^|/)(phi-|orca)', provider: 'microsoft', label: 'Microsoft' },
+  { match: '(^|/)composer-', provider: 'cursor', label: 'Cursor' },
+  // Gateways publish free/preview models under their own namespace; the slug
+  // prefix is the publisher's own attribution, same evidence as any vendor
+  // prefix above.
+  { match: '(^|/)minimax|(^|/)abab', provider: 'minimax', label: 'MiniMax' },
+  { match: 'upstage|(^|/)solar', provider: 'upstage', label: 'Upstage' },
+  { match: 'tencent|hunyuan|(^|/)hy\\d', provider: 'tencent', label: 'Tencent / Hunyuan' },
+  { match: '^nvidia|(^|/)nemotron', provider: 'nvidia', label: 'NVIDIA' },
+  { match: 'xiaomi|(^|/)(mi-?)?mimo', provider: 'xiaomi', label: 'Xiaomi / MiMo' },
+  // OpenRouter's own house/stealth series ("openrouter/owl-alpha"). This must
+  // stay AFTER the vendor rules: "openrouter/deepseek/v3" is DeepSeek, and
+  // only slugs no vendor rule can identify fall back to the namespace owner.
+  { match: '(^|/)openrouter/', provider: 'openrouter', label: 'OpenRouter' },
+  // OpenCode's own gateway catalog (served through the opencode adapter):
+  // the "x" preview family and the muse-spark community series. These slugs
+  // are published by OpenCode itself, so attribution follows the publisher.
+  { match: '(^|/)x-preview(-|$)', provider: 'opencode', label: 'OpenCode' },
+  { match: '(^|/)muse-spark', provider: 'opencode', label: 'OpenCode' },
+  // Hermes-routed stealth/preview models ("stealth/<name>"): these arrive via
+  // the Nous/openrouter gateways and carry no vendor slug of their own, but
+  // "unknown" hides real usage from the provider breakdown. Attribute to the
+  // nous gateway family so the UI shows where the traffic actually ran.
+  { match: '(^|/)stealth/', provider: 'nous', label: 'Nous (stealth)' },
+  // Billing-layer fallbacks from adapters: "@<gateway>" means the model slug
+  // was never recorded but the billing layer knows who served the call.
+  { match: '^@nous$', provider: 'nous', label: 'Nous' },
+  { match: '^@openrouter$', provider: 'openrouter', label: 'OpenRouter' },
+  // OpenRouter free-tier catalogues expose additional house/stealth slugs
+  // ("stepfun/step-*:free" and friends) that no vendor rule catches; route
+  // them to the namespace owner instead of "unknown".
+  { match: '(^|/)stepfun/', provider: 'stepfun', label: 'StepFun' },
+];
+
+const compiled = new WeakMap();
+
+function compile(rules) {
+  let c = compiled.get(rules);
+  if (!c) {
+    c = rules.map((r) => ({ ...r, re: new RegExp(r.match, 'i') }));
+    compiled.set(rules, c);
+  }
+  return c;
+}
+
+/**
+ * @param {string|null} raw model string as reported by the source
+ * @param {{rules?: ModelRule[], providerHint?: string|null}} [opt]
+ *   providerHint is used ONLY when the model string matches nothing — a hint
+ *   never overrides evidence from the model name itself.
+ * @returns {{provider:string, provider_label:string, model:string, model_family:string}}
+ */
+export function classifyModel(raw, opt = {}) {
+  const rules = compile(opt.rules ?? BUILTIN_MODEL_RULES);
+  const model = raw && String(raw).trim() ? String(raw).trim() : 'unknown';
+  if (model === 'unknown') {
+    return {
+      provider: opt.providerHint || 'unknown',
+      provider_label: opt.providerHint ? titleize(opt.providerHint) : 'Unknown',
+      model,
+      model_family: 'Unknown',
+    };
+  }
+
+  for (const r of rules) {
+    if (!r.re.test(model)) continue;
+    return {
+      provider: r.provider,
+      provider_label: r.label,
+      model,
+      model_family: r.family ?? familyOf(model, r),
+    };
+  }
+  return {
+    provider: opt.providerHint || 'unknown',
+    provider_label: opt.providerHint ? titleize(opt.providerHint) : 'Unknown',
+    model,
+    model_family: opt.providerHint ? `${titleize(opt.providerHint)} (unmapped)` : 'Unmapped',
+  };
+}
+
+/**
+ * Family label: the human-meaningful tier, with build dates and vendor
+ * prefixes stripped, so `claude-opus-4-5-20260101` and `claude-opus-5` land in
+ * comparable buckets without us pretending to know a version taxonomy.
+ */
+function familyOf(model, rule) {
+  const m = model.toLowerCase();
+  if (rule.familyFrom) {
+    for (const tier of rule.familyFrom) {
+      if (m.includes(tier)) {
+        const ver = m.match(new RegExp(`${tier}[-_]?(\\d+(?:[.-]\\d+)?)`)) || m.match(new RegExp(`(\\d+(?:[.-]\\d+)?)[-_]?${tier}`));
+        const v = ver ? ' ' + ver[1].replace('-', '.') : '';
+        return titleize(rule.provider === 'anthropic' ? 'Claude ' + tier : tier) + v;
+      }
+    }
+  }
+  // Strip a vendor prefix ("openrouter/x/y" -> "y"), then a trailing date stamp.
+  let base = m.split('/').pop();
+  base = base.replace(/[-_](\d{8}|\d{4}-\d{2}-\d{2}|latest|preview|exp)$/g, '');
+  // Collapse a trailing variant suffix (gpt-5.6-sol -> gpt-5.6) but keep it as
+  // a distinct family when it is the only distinguishing token.
+  const generation = base.match(/^([a-z]+[-_]?\d+(?:\.\d+)?)/);
+  if (generation) {
+    const suffix = base.slice(generation[1].length).replace(/^[-_]/, '');
+    const g = titleize(generation[1]);
+    return suffix ? `${g} (${suffix})` : g;
+  }
+  return titleize(base);
+}
+
+function titleize(s) {
+  return String(s)
+    .replace(/[-_]/g, ' ')
+    .replace(/\b([a-z])/g, (m) => m.toUpperCase())
+    .replace(/\bGpt\b/g, 'GPT')
+    .replace(/\bGlm\b/g, 'GLM')
+    .replace(/\bAi\b/g, 'AI')
+    .trim();
+}
+
+export { titleize };

package/src/core/notify.js

@@ -0,0 +1,83 @@
+/**
+ * Best-effort OS notifications.
+ *
+ * TokenFlow's privacy model forbids network calls, so alerts surface through
+ * whatever the operating system already provides: osascript on macOS,
+ * notify-send on Linux, a toast via PowerShell on Windows 10/11. Everything
+ * here is fire-and-forget: a missing or failing notifier degrades to silence
+ * (the status file still records the alert), never to a crash or a hang.
+ */
+import { spawn } from 'node:child_process';
+
+/** Escape a string for an AppleScript double-quoted literal. */
+export function appleScriptEscape(s) {
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/** Escape for XML text nodes (PowerShell toast content travels as XML). */
+export function xmlEscape(s) {
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Show a notification. Resolves regardless of delivery outcome.
+ * @param {{title:string, body?:string}} p
+ */
+export function notify({ title, body = '' }) {
+  const t = String(title).slice(0, 120);
+  const b = String(body).slice(0, 240);
+  try {
+    switch (process.platform) {
+      case 'darwin': {
+        const script = `display notification "${appleScriptEscape(b)}" with title "${appleScriptEscape(t)}"`;
+        return spawnDetached('osascript', ['-e', script]);
+      }
+      case 'win32': {
+        // EncodedCommand sidesteps every quoting hazard between cmd, PowerShell
+        // and the XML payload. The well-known PowerShell AppId is what makes
+        // the toast appear on systems where "TokenFlow" itself has no identity.
+        const ps = `
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+$xml.GetElementsByTagName('text').Item(0).AppendChild($xml.CreateTextNode('${xmlEscape(t)}')) | Out-Null
+$xml.GetElementsByTagName('text').Item(1).AppendChild($xml.CreateTextNode('${xmlEscape(b)}')) | Out-Null
+$app = '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe'
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($app).Show([Windows.UI.Notifications.ToastNotification]::new($xml))
+`;
+        const encoded = Buffer.from(ps, 'utf16le').toString('base64');
+        return spawnDetached('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', encoded]);
+      }
+      default: {
+        // Linux and the BSDs: the freedesktop desktop-notification spec.
+        return spawnDetached('notify-send', ['-a', 'TokenFlow', t, b]);
+      }
+    }
+  } catch (err) {
+    // Notifications are strictly additive; a broken notifier must never take
+    // the watch daemon down. The transition is still recorded in status.json.
+    return Promise.resolve({ delivered: false, reason: err.message });
+  }
+}
+
+function spawnDetached(cmd, args) {
+  return new Promise((resolve) => {
+    try {
+      const child = spawn(cmd, args, {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      child.once('error', (err) => resolve({ delivered: false, reason: err.message }));
+      child.once('spawn', () => resolve({ delivered: true }));
+      child.unref();
+      // Belt and braces: a notifier that never emits either event must not
+      // hold the event loop open.
+      setTimeout(() => resolve({ delivered: false, reason: 'timeout' }), 3000).unref();
+    } catch (err) {
+      resolve({ delivered: false, reason: err.message });
+    }
+  });
+}

package/src/core/pricing.js

@@ -0,0 +1,288 @@
+/**
+ * Cost estimation.
+ *
+ * ## Hard rules
+ *
+ * 1. **Never invent a price.** A model with no entry and no user override
+ *    produces `estimated_cost: null` and is listed in the "pricing not
+ *    configured" report, ranked by token volume. A `$0` is only ever a real
+ *    measured zero.
+ * 2. **Every rate has a source.** Each entry names the `PRICING_SOURCES` key it
+ *    came from, so `tokenflow pricing --sources` can show where a number came
+ *    from and when it was fetched. Third-party sources are marked as such.
+ * 3. **Estimated is labelled estimated.** A cost that a source actually billed
+ *    (a gateway's own `cost_usd`) is `measured` and kept in its own column.
+ *
+ * ## Service tiers matter more than people expect
+ *
+ * OpenAI's Fast mode (renamed from "priority" on 2026-07-30) bills at **4x**
+ * the standard rate. Anthropic's Batch API bills at 0.5x. Both adapters record
+ * `metadata.service_tier`, so the estimate applies the right multiplier per
+ * request instead of quietly assuming everything was standard-rate.
+ *
+ * ## Known limitation: long-context tiers
+ *
+ * Several vendors charge a premium above a context threshold (Anthropic above
+ * 200K, OpenAI's "long context" rows). Applying that needs a per-request prompt
+ * size AND a per-model threshold and premium, which are not uniformly
+ * published. This table uses the short-context rate, so a long-context-heavy
+ * workload is UNDER-estimated. The UI says so rather than pretending
+ * otherwise.
+ *
+ * Rates are USD per 1,000,000 tokens.
+ */
+
+export const PRICING_TABLE_VERSION = '2026-08-20';
+
+/** Where each group of rates came from. Surfaced by `tokenflow pricing --sources`. */
+export const PRICING_SOURCES = {
+  anthropic: {
+    url: 'https://platform.claude.com/docs/en/about-claude/pricing',
+    fetched: '2026-08-20',
+    confidence: 'official',
+  },
+  openai: {
+    url: 'https://developers.openai.com/api/docs/pricing',
+    fetched: '2026-08-20',
+    confidence: 'official',
+  },
+  'openai-thirdparty': {
+    url: 'https://openrouter.ai/openai/gpt-5.5',
+    fetched: '2026-08-20',
+    confidence: 'third-party',
+    note: 'gpt-5.5 is no longer on OpenAI\'s own pricing page; this mirrors its baseline rate.',
+  },
+  deepseek: {
+    url: 'https://api-docs.deepseek.com/quick_start/pricing',
+    fetched: '2026-08-20',
+    confidence: 'official',
+    note: 'DeepSeek charges peak (01:00-04:00 and 06:00-10:00 UTC) at 2x off-peak. These are OFF-PEAK rates, so a peak-heavy workload is under-estimated.',
+  },
+  zai: {
+    url: 'https://docs.z.ai/guides/overview/pricing',
+    fetched: '2026-08-20',
+    confidence: 'official',
+  },
+  google: {
+    url: 'https://ai.google.dev/gemini-api/docs/pricing',
+    fetched: '2026-08-20',
+    confidence: 'official',
+    note: 'Flash/Pro rates vary above a 200K prompt; the short-context rate is used.',
+  },
+  legacy: {
+    url: 'https://platform.claude.com/docs/en/about-claude/pricing',
+    fetched: '2026-08-20',
+    confidence: 'official-historical',
+    note: 'Retired models, kept so historical records still cost out.',
+  },
+};
+
+/**
+ * Published list prices. First regex match wins, so specific patterns come
+ * before general ones.
+ *
+ * `cacheWrite` is the short-TTL (5-minute) write rate; `cacheRefresh` is the
+ * long-TTL (1-hour) rate applied to the `cache_refresh_tokens` subset.
+ *
+ * @type {{match:string,in:number,out:number,cacheRead?:number,cacheWrite?:number,cacheRefresh?:number,src:string}[]}
+ */
+export const BUILTIN_PRICES = [
+  // ---- Anthropic — platform.claude.com, fetched 2026-08-20 ----------------
+  { match: 'claude-(fable|mythos)-5', in: 10, out: 50, cacheRead: 1, cacheWrite: 12.5, cacheRefresh: 20, src: 'anthropic' },
+  { match: 'claude-opus-4-(1|0)|claude-4-1-opus|claude-4-opus', in: 15, out: 75, cacheRead: 1.5, cacheWrite: 18.75, cacheRefresh: 30, src: 'legacy' },
+  { match: 'claude-opus-(5|4-8|4-7|4-6|4-5)', in: 5, out: 25, cacheRead: 0.5, cacheWrite: 6.25, cacheRefresh: 10, src: 'anthropic' },
+  { match: 'claude-sonnet-5', in: 2, out: 10, cacheRead: 0.2, cacheWrite: 2.5, cacheRefresh: 4, src: 'anthropic' },
+  { match: 'claude-sonnet-4-(6|5)|claude-sonnet-4($|-2)', in: 3, out: 15, cacheRead: 0.3, cacheWrite: 3.75, cacheRefresh: 6, src: 'anthropic' },
+  { match: 'claude-haiku-4-5|claude-4-5-haiku', in: 1, out: 5, cacheRead: 0.1, cacheWrite: 1.25, cacheRefresh: 2, src: 'anthropic' },
+  { match: 'claude-(3-5-haiku|haiku-3-5)', in: 0.8, out: 4, cacheRead: 0.08, cacheWrite: 1, cacheRefresh: 1.6, src: 'legacy' },
+  // Older generations, so records predating the current line-up still cost out.
+  { match: 'claude-3-opus', in: 15, out: 75, cacheRead: 1.5, cacheWrite: 18.75, cacheRefresh: 30, src: 'legacy' },
+  { match: 'claude-3-haiku', in: 0.25, out: 1.25, cacheRead: 0.03, cacheWrite: 0.3, cacheRefresh: 0.5, src: 'legacy' },
+  { match: 'claude-3-(5|7)-sonnet', in: 3, out: 15, cacheRead: 0.3, cacheWrite: 3.75, cacheRefresh: 6, src: 'legacy' },
+
+  // ---- OpenAI — developers.openai.com, fetched 2026-08-20 -----------------
+  // Cache writes are not billed separately; cached input is the read rate.
+  { match: '^gpt-5\\.6-sol', in: 2.5, out: 15, cacheRead: 0.25, cacheWrite: 0, cacheRefresh: 0, src: 'openai' },
+  { match: '^gpt-5\\.6-terra', in: 1, out: 6, cacheRead: 0.1, cacheWrite: 0, cacheRefresh: 0, src: 'openai' },
+  { match: '^gpt-5\\.6-luna', in: 0.1, out: 0.6, cacheRead: 0.01, cacheWrite: 0, cacheRefresh: 0, src: 'openai' },
+  { match: '^gpt-5\\.3-codex|^gpt-5-codex', in: 1.75, out: 14, cacheRead: 0.175, cacheWrite: 0, cacheRefresh: 0, src: 'openai' },
+  { match: '^chat-latest', in: 5, out: 30, cacheRead: 0.5, cacheWrite: 0, cacheRefresh: 0, src: 'openai' },
+  { match: '^gpt-5\\.5', in: 5, out: 30, cacheRead: 0.5, cacheWrite: 0, cacheRefresh: 0, src: 'openai-thirdparty' },
+  // Older OpenAI generations.
+  { match: '^gpt-4o-mini', in: 0.15, out: 0.6, cacheRead: 0.075, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: '^gpt-4o', in: 2.5, out: 10, cacheRead: 1.25, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: '^gpt-4\\.1-nano', in: 0.1, out: 0.4, cacheRead: 0.025, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: '^gpt-4\\.1-mini', in: 0.4, out: 1.6, cacheRead: 0.1, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: '^gpt-4\\.1', in: 2, out: 8, cacheRead: 0.5, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: '^gpt-5-nano', in: 0.05, out: 0.4, cacheRead: 0.005, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: '^gpt-5-mini', in: 0.25, out: 2, cacheRead: 0.025, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: '^gpt-5($|[^.\\d])', in: 1.25, out: 10, cacheRead: 0.125, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: '^o4-mini', in: 1.1, out: 4.4, cacheRead: 0.275, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: '^o3-mini', in: 1.1, out: 4.4, cacheRead: 0.55, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: '^o3', in: 2, out: 8, cacheRead: 0.5, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+
+  // ---- DeepSeek — api-docs.deepseek.com, fetched 2026-08-20 (OFF-PEAK) ----
+  { match: 'deepseek-v4-flash', in: 0.22, out: 0.66, cacheRead: 0.007, cacheWrite: 0, cacheRefresh: 0, src: 'deepseek' },
+  { match: 'deepseek-v4-pro|deepseek-v4($|[^-])', in: 0.66, out: 1.98, cacheRead: 0.022, cacheWrite: 0, cacheRefresh: 0, src: 'deepseek' },
+  { match: 'deepseek-(chat|v3)', in: 0.27, out: 1.1, cacheRead: 0.07, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: 'deepseek-(reasoner|r1)', in: 0.55, out: 2.19, cacheRead: 0.14, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+
+  // ---- Z.ai / GLM — docs.z.ai, fetched 2026-08-20 -------------------------
+  { match: '^glm-5\\.(3|2|1)', in: 1.4, out: 4.4, cacheRead: 0.26, cacheWrite: 0, cacheRefresh: 0, src: 'zai' },
+  { match: '^glm-5-turbo', in: 1.2, out: 4, cacheRead: 0.24, cacheWrite: 0, cacheRefresh: 0, src: 'zai' },
+  { match: '^glm-5($|[^.\\d-])', in: 1, out: 3.2, cacheRead: 0.2, cacheWrite: 0, cacheRefresh: 0, src: 'zai' },
+  { match: '^glm-4\\.7-flashx', in: 0.07, out: 0.4, cacheRead: 0.01, cacheWrite: 0, cacheRefresh: 0, src: 'zai' },
+  { match: '^glm-4\\.(7|6|5)-flash', in: 0, out: 0, cacheRead: 0, cacheWrite: 0, cacheRefresh: 0, src: 'zai' },
+  { match: '^glm-4\\.5-airx', in: 1.1, out: 4.5, cacheRead: 0.22, cacheWrite: 0, cacheRefresh: 0, src: 'zai' },
+  { match: '^glm-4\\.5-air', in: 0.2, out: 1.1, cacheRead: 0.03, cacheWrite: 0, cacheRefresh: 0, src: 'zai' },
+  { match: '^glm-4\\.5-x', in: 2.2, out: 8.9, cacheRead: 0.45, cacheWrite: 0, cacheRefresh: 0, src: 'zai' },
+  { match: '^glm-4\\.(7|6|5)', in: 0.6, out: 2.2, cacheRead: 0.11, cacheWrite: 0, cacheRefresh: 0, src: 'zai' },
+
+  // ---- Google — ai.google.dev, fetched 2026-08-20 (short context) ---------
+  { match: 'gemini-3\\.(7|6)-flash', in: 0.75, out: 3.75, cacheRead: 0.075, cacheWrite: 0, cacheRefresh: 0, src: 'google' },
+  { match: 'gemini-3\\.5-flash-lite', in: 0.3, out: 2.5, cacheRead: 0.03, cacheWrite: 0, cacheRefresh: 0, src: 'google' },
+  { match: 'gemini-3\\.5-flash', in: 1.5, out: 9, cacheRead: 0.15, cacheWrite: 0, cacheRefresh: 0, src: 'google' },
+  { match: 'gemini-3\\.1-flash-lite', in: 0.25, out: 1.5, cacheRead: 0.025, cacheWrite: 0, cacheRefresh: 0, src: 'google' },
+  { match: 'gemini-2\\.5-pro', in: 1.25, out: 10, cacheRead: 0.125, cacheWrite: 0, cacheRefresh: 0, src: 'google' },
+  { match: 'gemini-2\\.5-flash-lite', in: 0.1, out: 0.4, cacheRead: 0.01, cacheWrite: 0, cacheRefresh: 0, src: 'google' },
+  { match: 'gemini-2\\.5-flash', in: 0.3, out: 2.5, cacheRead: 0.03, cacheWrite: 0, cacheRefresh: 0, src: 'google' },
+  { match: 'gemini-2\\.0-flash-lite', in: 0.075, out: 0.3, cacheRead: 0.01875, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: 'gemini-2\\.0-flash', in: 0.1, out: 0.4, cacheRead: 0.025, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: 'gemini-1\\.5-flash', in: 0.075, out: 0.3, cacheRead: 0.01875, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+  { match: 'gemini-1\\.5-pro', in: 1.25, out: 5, cacheRead: 0.3125, cacheWrite: 0, cacheRefresh: 0, src: 'legacy' },
+];
+
+/**
+ * Service-tier multipliers, applied to every rate for a request.
+ *
+ * OpenAI: Fast mode (renamed from "priority" on 2026-07-30) is 4x standard;
+ *         Batch and Flex are billed at standard rates.
+ * Anthropic: the Batch API is 0.5x.
+ *
+ * An unrecognised tier is treated as 1x — the standard rate — rather than
+ * guessed at.
+ */
+export const TIER_MULTIPLIERS = {
+  openai: { priority: 4, fast: 4, standard: 1, default: 1, auto: 1, batch: 1, flex: 1, scale: 1 },
+  anthropic: { batch: 0.5, standard: 1, default: 1, auto: 1, priority: 1 },
+  _default: { batch: 0.5, standard: 1, default: 1, auto: 1 },
+};
+
+/**
+ * @param {string|null} tier value of `metadata.service_tier`
+ * @param {string} provider
+ * @returns {{mult:number, known:boolean, tier:string|null}}
+ */
+export function tierMultiplier(tier, provider) {
+  if (!tier) return { mult: 1, known: false, tier: null };
+  const t = String(tier).toLowerCase();
+  const table = TIER_MULTIPLIERS[provider] || TIER_MULTIPLIERS._default;
+  if (Object.prototype.hasOwnProperty.call(table, t)) return { mult: table[t], known: true, tier: t };
+  return { mult: 1, known: false, tier: t };
+}
+
+/**
+ * Family fallback multipliers, used ONLY to derive a cache rate when an entry
+ * has an input/output price but no explicit cache rate. Never used to invent an
+ * input or output price. An absent multiplier is unknown, which is null.
+ */
+const CACHE_MULTIPLIERS = {
+  anthropic: { read: 0.1, write: 1.25, refresh: 2.0 },
+  openai: { read: 0.1, write: 0, refresh: 0 },
+  deepseek: { read: 0.26, write: 0, refresh: 0 },
+  google: { read: 0.25, write: 0, refresh: 0 },
+  zai: { read: 0.2, write: 0, refresh: 0 },
+  _default: { read: null, write: null, refresh: null },
+};
+
+function mult(v, base) {
+  if (v === null || v === undefined) return null;
+  return base * v;
+}
+
+export function buildPriceBook(userPricing = {}) {
+  const user = Object.entries(userPricing.models || {}).map(([match, v]) => ({
+    match: v.match || `^${escapeRe(match)}$`,
+    key: match,
+    in: num(v.in ?? v.input),
+    out: num(v.out ?? v.output),
+    cacheRead: num(v.cacheRead ?? v.cache_read),
+    cacheWrite: num(v.cacheWrite ?? v.cache_write),
+    cacheRefresh: num(v.cacheRefresh ?? v.cache_refresh),
+    src: 'user',
+    origin: 'user',
+  }));
+  const builtin = BUILTIN_PRICES.map((p) => ({ ...p, origin: 'builtin' }));
+  const all = [...user, ...builtin].map((p) => ({ ...p, re: new RegExp(p.match, 'i') }));
+  return {
+    version: PRICING_TABLE_VERSION,
+    sources: PRICING_SOURCES,
+    entries: all,
+    lookup(model, provider) {
+      if (!model) return null;
+      for (const e of all) {
+        if (!e.re.test(model)) continue;
+        if (e.in === null || e.out === null || e.in === undefined || e.out === undefined) continue;
+        const m = CACHE_MULTIPLIERS[provider] || CACHE_MULTIPLIERS._default;
+        return {
+          in: e.in,
+          out: e.out,
+          cacheRead: e.cacheRead ?? mult(m.read, e.in),
+          cacheWrite: e.cacheWrite ?? mult(m.write, e.in),
+          cacheRefresh: e.cacheRefresh ?? mult(m.refresh, e.in),
+          origin: e.origin,
+          src: e.src,
+          match: e.match,
+        };
+      }
+      return null;
+    },
+  };
+}
+
+/**
+ * @param {object} tok token fields
+ * @param {string} model
+ * @param {string} provider
+ * @param {ReturnType<typeof buildPriceBook>} book
+ * @param {{tier?:string|null}} [opt]
+ * @returns {{cost:number|null, basis:'estimated'|null, partial:boolean, tier:string|null, tierMult:number, src:string|null}}
+ */
+export function estimateCost(tok, model, provider, book, opt = {}) {
+  const p = book.lookup(model, provider);
+  if (!p) return { cost: null, basis: null, partial: false, tier: null, tierMult: 1, src: null };
+
+  const { mult: tm, tier } = tierMultiplier(opt.tier ?? null, provider);
+  let cost = 0;
+  let partial = false;
+  const add = (tokens, rate) => {
+    if (tokens === null || tokens === undefined) return;
+    if (rate === null || rate === undefined || !Number.isFinite(rate)) {
+      if (tokens > 0) partial = true;
+      return;
+    }
+    cost += (tokens / 1e6) * rate * tm;
+  };
+  add(tok.input_tokens, p.in);
+  add(tok.output_tokens, p.out);
+  add(tok.cache_read_tokens, p.cacheRead);
+  // Cache writes split into the long-TTL (refresh) subset and the rest, because
+  // the two are billed at different rates.
+  const refresh = tok.cache_refresh_tokens ?? null;
+  const write = tok.cache_write_tokens ?? null;
+  if (refresh !== null && write !== null && p.cacheRefresh !== null) {
+    add(Math.max(0, write - refresh), p.cacheWrite);
+    add(refresh, p.cacheRefresh);
+  } else {
+    add(write, p.cacheWrite);
+  }
+  if (!Number.isFinite(cost)) return { cost: null, basis: null, partial: true, tier, tierMult: tm, src: p.src };
+  return { cost, basis: 'estimated', partial, tier, tierMult: tm, src: p.src ?? null };
+}
+
+function num(v) {
+  return v === undefined || v === null || v === '' || Number.isNaN(Number(v)) ? null : Number(v);
+}
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/core/prompt-analytics.js

@@ -0,0 +1,127 @@
+/**
+ * Prompt-level analytics — strictly opt-in, privacy-preserving by design.
+ *
+ * DEFAULT STATE: OFF. No adapter captures prompts unless
+ *   promptAnalytics:
+ *     enabled: true
+ *     storeRaw: false          # raw content stays OFF unless separately opted in
+ * is present in config.yaml.
+ *
+ * What is captured when enabled (per request):
+ *   - sha256(prompt)[:16]  — a one-way hash; cannot be reversed to the prompt
+ *   - category             — heuristic keyword classifier (code-review,
+ *                            debug, test, docs, architecture, other)
+ *   - model, tokens, cost  — already collected by every adapter
+ *
+ * What is NEVER captured: raw prompt text (unless storeRaw: true), file
+ * contents, environment variables, credentials.
+ *
+ * Repeated-prompt detection falls out of the hash: identical normalized
+ * prompts share a hash across days/models.
+ */
+import crypto from 'node:crypto';
+
+export const CATEGORIES = [
+  ['code-review', /\b(review|pr|pull.request|diff|audit)\b/i],
+  ['debugging', /\b(debug|error|bug|fix|stack.?trace|exception|failing)\b/i],
+  ['testing', /\b(test|spec|coverage|jest|vitest|pytest)\b/i],
+  ['documentation', /\b(doc|readme|comment|javadoc|explain this code)/i],
+  ['architecture', /\b(architect|design|refactor|structure|pattern|migrate)\b/i],
+];
+/** Type note for tsc: entries are [label, RegExp]. */
+const CATEGORY_RULES = CATEGORIES;
+
+export function normalizePrompt(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+    .replace(/[^\w ]/g, '')
+    .trim()
+    .slice(0, 2000);
+}
+
+/** One-way hash. Short prefix only — collisions acceptable for analytics. */
+export function hashPrompt(text) {
+  return crypto.createHash('sha256').update(normalizePrompt(text)).digest('hex').slice(0, 16);
+}
+
+export function categorize(text) {
+  const n = normalizePrompt(text);
+  for (const [cat, re] of CATEGORY_RULES) if (re instanceof RegExp && re.test(n)) return cat;
+  return 'uncategorized';
+}
+
+/**
+ * The record adapters may emit when prompt analytics is enabled.
+ * Returns null fields when input has no prompt text (e.g. cache-only rows).
+ */
+/**
+ * @param {{promptText?: string, model?: string|null, tokens?: number|null, cost?: number|null, timestamp?: string|null}} args
+ */
+export function makePromptRecord({ promptText, model, tokens, cost, timestamp } = {}) {
+  if (!promptText) return null;
+  return {
+    promptHash: hashPrompt(promptText),
+    category: categorize(promptText),
+    model: model || null,
+    tokens: tokens ?? null,
+    estCostUsd: cost ?? null,
+    timestamp: timestamp || new Date().toISOString(),
+    // Raw text is captured ONLY when the user separately opts in.
+    ...(this?.storeRaw ? { raw: String(promptText).slice(0, 4000) } : {}),
+  };
+}
+
+/**
+ * Aggregate prompt records → the views the gauntlet asks for.
+ * @param {Array<{promptHash,category,model,tokens,estCostUsd}>} records
+ */
+export function aggregate(records) {
+  const byCat = new Map();
+  const byHash = new Map();
+  let totalTokens = 0;
+  let cacheCapable = 0;
+
+  for (const r of records) {
+    const c = byCat.get(r.category) || { requests: 0, tokens: 0, cost: 0 };
+    c.requests += 1;
+    c.tokens += r.tokens || 0;
+    c.cost += r.estCostUsd || 0;
+    byCat.set(r.category, c);
+
+    const h = byHash.get(r.promptHash) || { count: 0, categories: new Set(), models: new Set(), cost: 0 };
+    h.count += 1;
+    h.categories.add(r.category);
+    h.models.add(r.model);
+    h.cost += r.estCostUsd || 0;
+    byHash.set(r.promptHash, h);
+
+    totalTokens += r.tokens || 0;
+    cacheCapable += 1;
+  }
+
+  const categories = [...byCat.entries()]
+    .map(([category, v]) => ({
+      category,
+      requests: v.requests,
+      tokens: v.tokens,
+      estCostUsd: Math.round(v.cost * 100) / 100,
+      avgCostPerRequest: v.requests ? Math.round((v.cost / v.requests) * 10000) / 10000 : null,
+    }))
+    .sort((a, b) => b.estCostUsd - a.estCostUsd);
+
+  const repeats = [...byHash.entries()]
+    .filter(([, h]) => h.count > 1)
+    .map(([hash, h]) => ({ hash, count: h.count, models: [...h.models] }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 10);
+
+  return {
+    totalPrompts: records.length,
+    uniquePrompts: byHash.size,
+    repeatRatePct: records.length ? Math.round(((records.length - byHash.size) / records.length) * 1000) / 10 : 0,
+    avgTokensPerPrompt: records.length ? Math.round(totalTokens / records.length) : null,
+    categories,
+    repeats,
+  };
+}