@ipv9/tokentracker-cli 0.39.0

package/src/lib/passive-mode.js

@@ -0,0 +1,185 @@
+/**
+ * Passive-mode detection.
+ *
+ * Token Tracker normally collects token usage by installing SessionEnd hooks
+ * into supported CLIs (Claude Code, Codex CLI, Gemini CLI, …). The hook
+ * fires `notify.cjs` after each turn → sync runs immediately → data is
+ * fresh within seconds.
+ *
+ * On environments where hook installation fails — WSL with read-only mount,
+ * UNC paths on Windows, locked `settings.json`, sandboxed processes —
+ * SessionEnd hooks never fire, but the underlying CLIs *still* write
+ * session logs (`~/.claude/projects/`, `~/.gemini/sessions/`, etc.). Our
+ * parsers can read those logs directly without the hook; the only loss is
+ * "data is fresh within seconds" → it's now "data is fresh after the next
+ * scheduled `tracker sync`".
+ *
+ * This module surfaces that fact: for each hook-driven provider, decide
+ * whether the local install is in **passive mode** (no hook + log dir
+ * present). `tracker status` reports it, and the dashboard can show a
+ * single banner asking the user whether to acknowledge & continue in
+ * passive mode or attempt re-install (`tracker init`).
+ *
+ * Detection is purely best-effort — we never *fail* sync because hooks are
+ * missing; we just label the source so users / AI agents know latency is
+ * minutes, not seconds.
+ */
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+/**
+ * @typedef {Object} PassiveProvider
+ * @property {string} name              - canonical provider name
+ * @property {boolean} hook_expected    - whether this provider supports hooks
+ * @property {boolean} hook_installed   - true when the hook is set
+ * @property {boolean} logs_present     - true when the provider's log dir
+ *                                        exists and contains at least one
+ *                                        session file we can parse
+ * @property {boolean} passive          - true iff hook_expected &&
+ *                                        !hook_installed && logs_present
+ * @property {string|null} hook_failure_reason - if hook_expected and not
+ *                                        installed, why we think it failed
+ *                                        (e.g. "settings.json not writable",
+ *                                        "config dir not found")
+ */
+
+function dirHasFile(dir, predicate) {
+  if (!dir || !fs.existsSync(dir)) return false;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_e) {
+    return false;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    // Let the predicate accept either a file OR a directory name (so
+    // "sessions" or "tmp" as a bare subdirectory still counts).
+    if (!predicate || predicate(full, entry.name, entry.isDirectory())) return true;
+    if (entry.isDirectory()) {
+      // Shallow recurse — at most 1 level (covers projects/<name>/*.jsonl)
+      if (dirHasFile(full, predicate)) return true;
+    }
+  }
+  return false;
+}
+
+function classifyWritableFailure(filePath) {
+  if (!filePath) return "no path";
+  try {
+    fs.accessSync(filePath, fs.constants.W_OK);
+    return "writable (hook may have been removed externally)";
+  } catch (e) {
+    if (e && e.code === "ENOENT") return "settings file missing";
+    if (e && e.code === "EACCES") return "permission denied";
+    if (e && e.code === "EROFS") return "read-only filesystem";
+    return e?.code || "unknown";
+  }
+}
+
+/**
+ * Detect passive mode for each hook-driven provider.
+ *
+ * @param {Object} opts
+ * @param {string} opts.home  - user home directory
+ * @param {Object} opts.hookStatus - per-provider hook-installed booleans
+ *   (already collected by status.js); shape: { claude, gemini, codex,
+ *   every_code, opencode, openclaw, codebuddy, grok }
+ * @returns {PassiveProvider[]}
+ */
+function detectPassiveProviders({ home, hookStatus }) {
+  const out = [];
+
+  // Claude Code — logs at ~/.claude/projects/<name>/*.jsonl
+  out.push(buildEntry({
+    name: "claude",
+    hookExpected: true,
+    hookInstalled: Boolean(hookStatus?.claude),
+    logsDir: path.join(home, ".claude", "projects"),
+    logsPredicate: (full) => full.endsWith(".jsonl"),
+    settingsPath: path.join(home, ".claude", "settings.json"),
+  }));
+
+  // Gemini CLI — logs at ~/.gemini/tmp/<session-id>/logs.json
+  // (path varies by version; presence of ~/.gemini/sessions or
+  // ~/.gemini/tmp is enough to call it "active")
+  out.push(buildEntry({
+    name: "gemini",
+    hookExpected: true,
+    hookInstalled: Boolean(hookStatus?.gemini),
+    logsDir: path.join(home, ".gemini"),
+    logsPredicate: (_full, name, isDir) =>
+      (isDir && (name === "tmp" || name === "sessions")) || name === "logs.json",
+    settingsPath: path.join(home, ".gemini", "settings.json"),
+  }));
+
+  // Codex CLI — logs at ~/.codex/sessions/
+  // Match either a "sessions" subdir (even if empty — the CLI created it)
+  // or any *.jsonl session file.
+  out.push(buildEntry({
+    name: "codex",
+    hookExpected: true,
+    hookInstalled: Boolean(hookStatus?.codex_notify ?? hookStatus?.codex),
+    logsDir: path.join(home, ".codex"),
+    logsPredicate: (_full, name, isDir) =>
+      (isDir && name === "sessions") || (!isDir && name.endsWith(".jsonl")),
+    settingsPath: path.join(home, ".codex", "config.toml"),
+  }));
+
+  // Every Code — same shape as Codex, different home
+  out.push(buildEntry({
+    name: "every_code",
+    hookExpected: true,
+    hookInstalled: Boolean(hookStatus?.every_code_notify ?? hookStatus?.every_code),
+    logsDir: path.join(home, ".code"),
+    logsPredicate: (_full, name, isDir) =>
+      (isDir && name === "sessions") || (!isDir && name.endsWith(".jsonl")),
+    settingsPath: path.join(home, ".code", "config.toml"),
+  }));
+
+  // CodeBuddy — Claude-fork; hook in ~/.codebuddy/settings.json
+  out.push(buildEntry({
+    name: "codebuddy",
+    hookExpected: true,
+    hookInstalled: Boolean(hookStatus?.codebuddy),
+    logsDir: path.join(home, ".codebuddy"),
+    logsPredicate: (_full, name) => name === "projects" || name.endsWith(".jsonl"),
+    settingsPath: path.join(home, ".codebuddy", "settings.json"),
+  }));
+
+  return out;
+}
+
+function buildEntry({ name, hookExpected, hookInstalled, logsDir, logsPredicate, settingsPath }) {
+  const logsPresent = dirHasFile(logsDir, logsPredicate);
+  const passive = hookExpected && !hookInstalled && logsPresent;
+  let reason = null;
+  if (hookExpected && !hookInstalled) {
+    reason = classifyWritableFailure(settingsPath);
+  }
+  return {
+    name,
+    hook_expected: hookExpected,
+    hook_installed: hookInstalled,
+    logs_present: logsPresent,
+    passive,
+    hook_failure_reason: reason,
+  };
+}
+
+/**
+ * Convenience boolean: is at least one provider in passive mode?
+ */
+function isPassiveModeActive(providers) {
+  return providers.some((p) => p.passive);
+}
+
+module.exports = {
+  detectPassiveProviders,
+  isPassiveModeActive,
+  // Exposed for unit testing
+  dirHasFile,
+  classifyWritableFailure,
+};

package/src/lib/pricing/curated-overrides.json

@@ -0,0 +1,79 @@
+{
+  "_meta": {
+    "note": "Curated price overrides. Always wins over LiteLLM. Two reasons to live here: (1) self-defined alias names that LiteLLM will never carry (kiro-*, hy3-*, composer-*, kimi-for-coding, free-tier OpenRouter routes); (2) prices we want to pin even if LiteLLM has the model (e.g. cache_write fields LiteLLM often omits). Units: USD per million tokens. Edit this file to override pricing without redeploying.",
+    "units": "usd_per_million_tokens",
+    "deepseek_v4_pro_discount_expiry": "2026-05-31T15:59:00Z — DeepSeek v4-pro is currently at a 75% promotional discount. After expiry the prices revert to 4x: input $1.74/M, output $3.48/M, cache_read $0.0145/M, cache_write $1.74/M. Update this file before the cutover."
+  },
+  "exact": {
+    "claude-opus-4-8":  { "input": 5,    "output": 25,   "cache_read": 0.5,   "cache_write": 6.25, "note": "Opus 4.8 not yet in LiteLLM. Pin to the standard Opus tier (same as 4.6/4.7); remove once LiteLLM carries it." },
+    "kiro-agent":       { "input": 3,    "output": 15,   "cache_read": 0.3,   "cache_write": 3.75 },
+    "kiro-cli-agent":   { "input": 3,    "output": 15,   "cache_read": 0.3,   "cache_write": 3.75 },
+    "hy3-preview-agent":{ "input": 0,    "output": 0,    "cache_read": 0 },
+    "hy3-preview":      { "input": 0,    "output": 0,    "cache_read": 0 },
+    "composer-1":       { "input": 1.25, "output": 10,   "cache_read": 0.125 },
+    "composer-1.5":     { "input": 3.5,  "output": 17.5, "cache_read": 0.35 },
+    "composer-2":       { "input": 0.5,  "output": 2.5,  "cache_read": 0.2 },
+    "composer-2-fast":  { "input": 1.5,  "output": 7.5,  "cache_read": 0.15 },
+    "MiniMax-M2.7":     { "input": 0.3,  "output": 1.2,  "cache_read": 0.06,  "cache_write": 0.375 },
+    "MiniMax-M2.7-highspeed":{ "input": 0.6, "output": 2.4, "cache_read": 0.06, "cache_write": 0.375 },
+    "deepseek-v4-flash":{ "input": 0.14, "output": 0.28, "cache_read": 0.0028, "cache_write": 0.14 },
+    "deepseek-v4-pro":  { "input": 0.435,"output": 0.87, "cache_read": 0.003625, "cache_write": 0.435 },
+    "deepseek-chat":    { "input": 0.14, "output": 0.28, "cache_read": 0.0028, "cache_write": 0.14 },
+    "grok-build":       { "input": 1.25, "output": 2.50, "cache_read": 0.20, "note": "Grok Build TUI estimate. Local telemetry currently exposes totalTokens without a stable prompt/output/cache split, so TokenTracker estimates input/output split until Grok exposes per-call usage details." },
+    "grok-4-0709":      { "input": 3.00, "output": 15.00, "cache_read": 0.75 },
+    "grok-4":           { "input": 3.00, "output": 15.00, "cache_read": 0.75 },
+    "grok-4-latest":    { "input": 3.00, "output": 15.00, "cache_read": 0.75 },
+    "grok-4-fast":      { "input": 0.20, "output": 0.50, "cache_read": 0.05 },
+    "grok-4-fast-reasoning": { "input": 0.20, "output": 0.50, "cache_read": 0.05 },
+    "grok-4-fast-non-reasoning": { "input": 0.20, "output": 0.50, "cache_read": 0.05 },
+    "grok-4-1-fast-non-reasoning": { "input": 0.20, "output": 0.50, "cache_read": 0.05 },
+    "deepseek-reasoner":{ "input": 0.14, "output": 0.28, "cache_read": 0.0028, "cache_write": 0.14 },
+    "kimi-for-coding":  { "input": 0.6,  "output": 2,    "cache_read": 0.15 },
+    "kimi-k2.5":        { "input": 0.6,  "output": 2,    "cache_read": 0.15 },
+    "kimi-k2.5-free":   { "input": 0,    "output": 0,    "cache_read": 0 },
+    "kimi-k2.6":        { "input": 0.95, "output": 4,    "cache_read": 0.16 },
+    "glm-5.1":          { "input": 1.4,  "output": 4.4,  "cache_read": 0.26 },
+    "glm-5":            { "input": 1.0,  "output": 3.2,  "cache_read": 0.2 },
+    "glm-5-turbo":      { "input": 1.2,  "output": 4.0,  "cache_read": 0.24 },
+    "glm-4.7":          { "input": 0.6,  "output": 2.2,  "cache_read": 0.11 },
+    "glm-4.7-flashx":   { "input": 0.07, "output": 0.4,  "cache_read": 0.01 },
+    "glm-4.7-flash":    { "input": 0,    "output": 0,    "cache_read": 0 },
+    "glm-4.6":          { "input": 0.6,  "output": 2.2,  "cache_read": 0.11 },
+    "glm-4.5":          { "input": 0.6,  "output": 2.2,  "cache_read": 0.11 },
+    "glm-4.5-x":        { "input": 2.2,  "output": 8.9,  "cache_read": 0.45 },
+    "glm-4.5-air":      { "input": 0.2,  "output": 1.1,  "cache_read": 0.03 },
+    "glm-4.5-airx":     { "input": 1.1,  "output": 4.5,  "cache_read": 0.22 },
+    "glm-4.5-flash":    { "input": 0,    "output": 0,    "cache_read": 0 },
+    "glm-4.7-free":     { "input": 0,    "output": 0,    "cache_read": 0 },
+    "nemotron-3-super-free":{ "input": 0, "output": 0,   "cache_read": 0 },
+    "mimo-v2-pro-free": { "input": 0,    "output": 0,    "cache_read": 0 },
+    "minimax-m2.1-free":{ "input": 0,    "output": 0,    "cache_read": 0 },
+    "MiniMax-M2.1":     { "input": 0.5,  "output": 3,    "cache_read": 0.05 },
+    "antigravity-gpt-oss-120b": { "input": 2.5, "output": 10, "cache_read": 0, "note": "Antigravity bridge alias. Approximate with GPT-4o-class pricing until Google exposes route-specific billing metadata." }
+  },
+  "alias": {
+    "auto": "composer-1"
+  },
+  "fuzzy": [
+    { "match": "kiro",                   "ref": "kiro-cli-agent" },
+    { "match": "hy3",                    "ref": "hy3-preview-agent" },
+    { "match": "composer",               "ref": "composer-1" },
+    { "match": "minimax-m2.7-highspeed", "ref": "MiniMax-M2.7-highspeed" },
+    { "match": "minimax-m2.7",           "ref": "MiniMax-M2.7" },
+    { "match": "deepseek-v4-flash",      "ref": "deepseek-v4-flash" },
+    { "match": "deepseek-v4-pro",        "ref": "deepseek-v4-pro" },
+    { "match": "kimi",                   "ref": "kimi-k2.5" },
+    { "match": "glm-4.5-airx",           "ref": "glm-4.5-airx" },
+    { "match": "glm-4.5-air",            "ref": "glm-4.5-air" },
+    { "match": "glm-4.5-x",              "ref": "glm-4.5-x" },
+    { "match": "glm-4.5-flash",          "ref": "glm-4.5-flash" },
+    { "match": "glm-4.5",                "ref": "glm-4.5" },
+    { "match": "glm-4.7-flashx",         "ref": "glm-4.7-flashx" },
+    { "match": "glm-4.7-flash",          "ref": "glm-4.7-flash" },
+    { "match": "glm-4.7",                "ref": "glm-4.7" },
+    { "match": "glm-4.6",                "ref": "glm-4.6" },
+    { "match": "glm-5-turbo",            "ref": "glm-5-turbo" },
+    { "match": "glm-5.1",                "ref": "glm-5.1" },
+    { "match": "glm-5",                  "ref": "glm-5" }
+  ]
+}

package/src/lib/pricing/index.js

@@ -0,0 +1,143 @@
+// Public pricing API. Replaces the hard-coded MODEL_PRICING table that used
+// to live in src/lib/local-api.js. Keeps the same synchronous shape so all
+// existing callers (computeRowCost, /functions/* handlers, tests) work
+// unchanged after `await ensurePricingLoaded()` is awaited once at startup.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const curatedOverrides = require("./curated-overrides.json");
+const {
+  lookupPricing,
+  buildLitellmPerMillionMap,
+} = require("./matcher");
+const { loadLitellmData } = require("./litellm-fetcher");
+
+const ZERO_PRICING = { input: 0, output: 0, cache_read: 0, cache_write: 0 };
+const SEED_SNAPSHOT_PATH = path.resolve(__dirname, "seed-snapshot.json");
+
+// Sync seed load. Done at require-time so callers that haven't awaited
+// ensurePricingLoaded() (e.g. tests, vite mock startup, edge functions) still
+// get LiteLLM-backed pricing instead of all-zero. ensurePricingLoaded() will
+// later upgrade this to fresh disk cache or upstream data.
+function loadSeedSync() {
+  try {
+    const raw = fs.readFileSync(SEED_SNAPSHOT_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    delete parsed._meta;
+    return parsed;
+  } catch (e) {
+    return {};
+  }
+}
+
+const seedRaw = loadSeedSync();
+
+const state = {
+  loaded: false,
+  loadingPromise: null,
+  litellmRawMap: seedRaw, // raw per-token; field shape from LiteLLM JSON
+  litellmPerMillionMap: buildLitellmPerMillionMap(seedRaw), // USD/MTok
+  source: Object.keys(seedRaw).length ? "seed-snapshot:sync" : null,
+  // negativeCache prevents re-walking the LiteLLM map for models we've already
+  // determined are unknown. Cleared on every reload.
+  negativeCache: new Set(),
+};
+
+function defaultCachePath() {
+  return path.join(os.homedir(), ".tokentracker", "cache", "pricing.json");
+}
+
+async function ensurePricingLoaded(opts = {}) {
+  if (state.loaded) return state;
+  if (state.loadingPromise) return state.loadingPromise;
+
+  state.loadingPromise = (async () => {
+    try {
+      const cachePath = opts.cachePath || defaultCachePath();
+      const { data, source } = await loadLitellmData({ ...opts, cachePath });
+      state.litellmRawMap = data || {};
+      state.litellmPerMillionMap = buildLitellmPerMillionMap(state.litellmRawMap);
+      state.source = source;
+      state.loaded = true;
+      state.negativeCache.clear();
+      return state;
+    } finally {
+      state.loadingPromise = null;
+    }
+  })();
+
+  return state.loadingPromise;
+}
+
+// For tests: drop loaded state so a fresh call can re-load. Seeds with the
+// bundled snapshot so getModelPricing() still works without ensurePricingLoaded.
+function resetPricingForTests() {
+  state.loaded = false;
+  state.loadingPromise = null;
+  state.litellmRawMap = seedRaw;
+  state.litellmPerMillionMap = buildLitellmPerMillionMap(seedRaw);
+  state.source = Object.keys(seedRaw).length ? "seed-snapshot:sync" : null;
+  state.negativeCache.clear();
+}
+
+function getModelPricing(model, opts = {}) {
+  if (!model) return ZERO_PRICING;
+  let lookupSource = null;
+  if (typeof opts === "string") {
+    lookupSource = opts.toLowerCase();
+  } else if (typeof opts.source === "string") {
+    lookupSource = opts.source.toLowerCase();
+  }
+  const cacheKey = lookupSource ? `${lookupSource}\0${model}` : model;
+  if (state.negativeCache.has(cacheKey)) return ZERO_PRICING;
+
+  const result = lookupPricing(model, {
+    curated: curatedOverrides,
+    litellm: state.litellmPerMillionMap,
+    source: lookupSource,
+  });
+  if (result.hit) return result.value;
+
+  state.negativeCache.add(cacheKey);
+  return ZERO_PRICING;
+}
+
+// Same formula and Codex/every-code reasoning-folding rule as the previous
+// computeRowCost in src/lib/local-api.js. Moved here so vite mock + local
+// server share one source of truth.
+function computeRowCost(row) {
+  const pricing = getModelPricing(row.model, { source: row.source });
+  const reasoningIncludedInOutput = row.source === "codex" || row.source === "every-code";
+  const reasoningCost = reasoningIncludedInOutput
+    ? 0
+    : (row.reasoning_output_tokens || 0) * (pricing.output || 0);
+  return (
+    ((row.input_tokens || 0) * (pricing.input || 0) +
+      (row.output_tokens || 0) * (pricing.output || 0) +
+      (row.cached_input_tokens || 0) * (pricing.cache_read || 0) +
+      (row.cache_creation_input_tokens || 0) * (pricing.cache_write || 0) +
+      reasoningCost) /
+    1_000_000
+  );
+}
+
+// Backwards-compatible MODEL_PRICING export. Test at
+// test/model-breakdown.test.js:236 reads `localApi.MODEL_PRICING["kiro-agent"]`
+// and expects { input, output, cache_read, cache_write } shape. We expose the
+// CURATED.exact map (which contains the kiro entries by design); LiteLLM
+// entries are NOT included here because they're keyed dynamically and the old
+// table was authoritative for what is now CURATED.
+const MODEL_PRICING = curatedOverrides.exact;
+
+module.exports = {
+  ensurePricingLoaded,
+  getModelPricing,
+  computeRowCost,
+  resetPricingForTests,
+  MODEL_PRICING,
+  ZERO_PRICING,
+  // Internal hooks for tests.
+  __getStateForTests: () => state,
+};

package/src/lib/pricing/litellm-fetcher.js

@@ -0,0 +1,172 @@
+// LiteLLM data loader: 24h disk cache + bundled seed snapshot fallback.
+// Fetches from upstream once when cache is missing or stale, then keeps a
+// per-process in-memory map. fetchModelPricing() is async; subsequent reads
+// (lookupPricing in matcher.js) operate on the in-memory map synchronously.
+
+const fs = require("node:fs");
+const fsp = require("node:fs/promises");
+const path = require("node:path");
+
+const LITELLM_PRICING_URL =
+  "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
+const SEED_SNAPSHOT_PATH = path.resolve(__dirname, "seed-snapshot.json");
+
+function readJsonSync(p) {
+  const raw = fs.readFileSync(p, "utf8");
+  return JSON.parse(raw);
+}
+
+async function readJsonAsync(p) {
+  const raw = await fsp.readFile(p, "utf8");
+  return JSON.parse(raw);
+}
+
+function isFresh(stat, ttlMs) {
+  if (!stat) return false;
+  return Date.now() - stat.mtimeMs < ttlMs;
+}
+
+async function statSafe(p) {
+  try {
+    return await fsp.stat(p);
+  } catch (e) {
+    if (e?.code === "ENOENT") return null;
+    throw e;
+  }
+}
+
+async function loadSeedSnapshot() {
+  // Sync read is fine — file is bundled and small (~250KB). Falling back to
+  // sync avoids a race with caller's synchronous lookup if seed must answer
+  // immediately.
+  try {
+    return readJsonSync(SEED_SNAPSHOT_PATH);
+  } catch (e) {
+    // Tolerate missing seed in dev environments where the build script
+    // hasn't run yet. Empty data = LiteLLM lookup miss = falls back to
+    // CURATED only.
+    return {};
+  }
+}
+
+async function fetchUpstream({ url = LITELLM_PRICING_URL, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS } = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal });
+    if (!res.ok) {
+      throw new Error(`LiteLLM fetch failed: HTTP ${res.status} ${res.statusText}`);
+    }
+    return await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function writeCache(cachePath, data) {
+  await fsp.mkdir(path.dirname(cachePath), { recursive: true });
+  // Persist only the slimmed shape (4 cost fields) to keep disk small and
+  // make the cache file easy to inspect/edit.
+  const slim = {};
+  let kept = 0;
+  for (const [name, entry] of Object.entries(data)) {
+    if (!entry || typeof entry !== "object" || name.startsWith("_")) continue;
+    const out = {};
+    let hasAny = false;
+    for (const f of [
+      "input_cost_per_token",
+      "output_cost_per_token",
+      "cache_read_input_token_cost",
+      "cache_creation_input_token_cost",
+    ]) {
+      const v = entry[f];
+      if (typeof v === "number" && Number.isFinite(v)) {
+        out[f] = v;
+        hasAny = true;
+      }
+    }
+    if (hasAny) {
+      slim[name] = out;
+      kept++;
+    }
+  }
+  const payload = {
+    _meta: {
+      source: LITELLM_PRICING_URL,
+      cached_at: new Date().toISOString(),
+      kept_models: kept,
+    },
+    ...slim,
+  };
+  await fsp.writeFile(cachePath, JSON.stringify(payload) + "\n");
+  return slim;
+}
+
+// Public: load LiteLLM data into memory. Resolution chain:
+//   1. disk cache (if mtime < ttl)
+//   2. fetch upstream + write disk cache
+//   3. stale disk cache (network failed)
+//   4. bundled seed snapshot (fresh install / offline)
+async function loadLitellmData({
+  cachePath,
+  ttlMs = DEFAULT_TTL_MS,
+  fetchTimeoutMs = DEFAULT_FETCH_TIMEOUT_MS,
+  fetchImpl = fetchUpstream,
+  url = LITELLM_PRICING_URL,
+  logger = null,
+} = {}) {
+  if (!cachePath) {
+    throw new Error("loadLitellmData: cachePath is required");
+  }
+  const log = (level, msg) => {
+    if (logger && typeof logger[level] === "function") logger[level](msg);
+  };
+
+  // 1. Fresh disk cache
+  const stat = await statSafe(cachePath);
+  if (isFresh(stat, ttlMs)) {
+    try {
+      const data = await readJsonAsync(cachePath);
+      delete data._meta;
+      return { data, source: "disk-cache" };
+    } catch (e) {
+      log("warn", `[pricing] disk cache unreadable: ${e?.message || e}`);
+    }
+  }
+
+  // 2. Fetch upstream
+  try {
+    const upstream = await fetchImpl({ url, timeoutMs: fetchTimeoutMs });
+    const slim = await writeCache(cachePath, upstream);
+    return { data: slim, source: "upstream" };
+  } catch (e) {
+    log("warn", `[pricing] upstream fetch failed: ${e?.message || e}`);
+  }
+
+  // 3. Stale disk cache (better than seed)
+  if (stat) {
+    try {
+      const data = await readJsonAsync(cachePath);
+      delete data._meta;
+      log("warn", "[pricing] using stale disk cache");
+      return { data, source: "stale-cache" };
+    } catch (e) {
+      log("warn", `[pricing] stale cache unreadable: ${e?.message || e}`);
+    }
+  }
+
+  // 4. Bundled seed snapshot
+  const seed = await loadSeedSnapshot();
+  delete seed._meta;
+  return { data: seed, source: "seed-snapshot" };
+}
+
+module.exports = {
+  LITELLM_PRICING_URL,
+  DEFAULT_TTL_MS,
+  loadLitellmData,
+  loadSeedSnapshot,
+  fetchUpstream,
+};