@diogonzafe/tokenwatch 0.2.0 → 0.4.0

package/dist/index.js

@@ -25,8 +25,45 @@ function lookupInMap(model, map) {
   }
   return void 0;
 }
-function calculateCost(inputTokens, outputTokens, price) {
-  return inputTokens / 1e6 * price.input + outputTokens / 1e6 * price.output;
+function calculateCost(inputTokens, outputTokens, price, cachedTokens = 0, cacheCreationTokens = 0) {
+  const regularInputCost = inputTokens / 1e6 * price.input;
+  const cachedReadCost = cachedTokens / 1e6 * (price.cachedInput ?? price.input);
+  const cacheCreationCost = cacheCreationTokens / 1e6 * (price.cacheCreationInput ?? price.input * 1.25);
+  const outputCost = outputTokens / 1e6 * price.output;
+  return regularInputCost + cachedReadCost + cacheCreationCost + outputCost;
+}
+
+// src/core/suggestions.ts
+var PROVIDER_PREFIXES = ["gpt-", "claude-", "gemini-", "deepseek-"];
+function getProviderPrefix(model) {
+  return PROVIDER_PREFIXES.find((p) => model.startsWith(p));
+}
+function maybeSuggestCheaperModel(model, costUSD, inputTokens, outputTokens, layers) {
+  if (costUSD <= 0) return;
+  const prefix = getProviderPrefix(model);
+  if (!prefix) return;
+  const mergedMap = {
+    ...layers.bundledPrices,
+    ...layers.remotePrices ?? {},
+    ...layers.customPrices ?? {}
+  };
+  let cheapestModel;
+  let cheapestCost = Infinity;
+  for (const key of Object.keys(mergedMap)) {
+    if (key === model || !key.startsWith(prefix)) continue;
+    const price = mergedMap[key];
+    if (!price) continue;
+    const candidateCost = calculateCost(inputTokens, outputTokens, price);
+    if (candidateCost < cheapestCost) {
+      cheapestCost = candidateCost;
+      cheapestModel = key;
+    }
+  }
+  if (cheapestModel === void 0 || cheapestCost >= costUSD * 0.5) return;
+  const savingsPct = Math.round((1 - cheapestCost / costUSD) * 100);
+  console.log(
+    `[tokenwatch] Suggestion: ${cheapestModel} could handle this for ~$${cheapestCost.toFixed(4)} (${savingsPct}% cheaper than ${model})`
+  );
 }
 
 // src/core/storage.ts
@@ -74,29 +111,51 @@ var SqliteStorage = class {
   migrate() {
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS usage (
-        id            INTEGER PRIMARY KEY AUTOINCREMENT,
-        model         TEXT    NOT NULL,
-        input_tokens  INTEGER NOT NULL,
-        output_tokens INTEGER NOT NULL,
-        cost_usd      REAL    NOT NULL,
-        session_id    TEXT,
-        user_id       TEXT,
-        timestamp     TEXT    NOT NULL
+        id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+        model                 TEXT    NOT NULL,
+        input_tokens          INTEGER NOT NULL,
+        output_tokens         INTEGER NOT NULL,
+        reasoning_tokens      INTEGER NOT NULL DEFAULT 0,
+        cached_tokens         INTEGER NOT NULL DEFAULT 0,
+        cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+        cost_usd              REAL    NOT NULL,
+        session_id            TEXT,
+        user_id               TEXT,
+        feature               TEXT,
+        timestamp             TEXT    NOT NULL
       )
     `);
+    const cols = this.db.prepare(`PRAGMA table_info(usage)`).all().map((c) => c.name);
+    if (!cols.includes("reasoning_tokens")) {
+      this.db.exec(`ALTER TABLE usage ADD COLUMN reasoning_tokens INTEGER NOT NULL DEFAULT 0`);
+    }
+    if (!cols.includes("feature")) {
+      this.db.exec(`ALTER TABLE usage ADD COLUMN feature TEXT`);
+    }
+    if (!cols.includes("cached_tokens")) {
+      this.db.exec(`ALTER TABLE usage ADD COLUMN cached_tokens INTEGER NOT NULL DEFAULT 0`);
+    }
+    if (!cols.includes("cache_creation_tokens")) {
+      this.db.exec(`ALTER TABLE usage ADD COLUMN cache_creation_tokens INTEGER NOT NULL DEFAULT 0`);
+    }
   }
   record(entry) {
     this.db.prepare(
       `INSERT INTO usage
-         (model, input_tokens, output_tokens, cost_usd, session_id, user_id, timestamp)
-         VALUES (?, ?, ?, ?, ?, ?, ?)`
+         (model, input_tokens, output_tokens, reasoning_tokens, cached_tokens, cache_creation_tokens,
+          cost_usd, session_id, user_id, feature, timestamp)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
     ).run(
       entry.model,
       entry.inputTokens,
       entry.outputTokens,
+      entry.reasoningTokens ?? 0,
+      entry.cachedTokens ?? 0,
+      entry.cacheCreationTokens ?? 0,
       entry.costUSD,
       entry.sessionId ?? null,
       entry.userId ?? null,
+      entry.feature ?? null,
       entry.timestamp
     );
   }
@@ -106,9 +165,13 @@ var SqliteStorage = class {
       model: r.model,
       inputTokens: r.input_tokens,
       outputTokens: r.output_tokens,
+      ...r.reasoning_tokens > 0 && { reasoningTokens: r.reasoning_tokens },
+      ...r.cached_tokens > 0 && { cachedTokens: r.cached_tokens },
+      ...r.cache_creation_tokens > 0 && { cacheCreationTokens: r.cache_creation_tokens },
       costUSD: r.cost_usd,
       ...r.session_id != null && { sessionId: r.session_id },
       ...r.user_id != null && { userId: r.user_id },
+      ...r.feature != null && { feature: r.feature },
       timestamp: r.timestamp
     }));
   }
@@ -140,7 +203,7 @@ async function fetchRemotePrices(url = REMOTE_URL) {
     const data = await res.json();
     if (!data?.models) return null;
     await persistCache(data);
-    return data.models;
+    return { models: data.models, updated_at: data.updated_at ?? "" };
   } catch {
     return null;
   }
@@ -152,7 +215,8 @@ async function loadCachedPrices() {
     const data = JSON.parse(raw);
     const age = Date.now() - (data._cachedAt ?? 0);
     if (age > CACHE_TTL_MS) return null;
-    return data.models ?? null;
+    if (!data.models) return null;
+    return { models: data.models, updated_at: data.updated_at ?? "" };
   } catch {
     return null;
   }
@@ -173,87 +237,110 @@ async function getRemotePrices() {
 
 // prices.json
 var prices_default = {
-  updated_at: "2026-04-21",
+  updated_at: "2026-04-22",
   source: "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
   models: {
     "gpt-4o": {
       input: 2.5,
       output: 10,
+      cachedInput: 1.25,
       maxInputTokens: 128e3
     },
     "gpt-4o-mini": {
       input: 0.15,
       output: 0.6,
+      cachedInput: 0.075,
       maxInputTokens: 128e3
     },
     "gpt-5": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 272e3
     },
     "gpt-5-mini": {
       input: 0.25,
       output: 2,
+      cachedInput: 0.025,
       maxInputTokens: 272e3
     },
     "gpt-5-nano": {
       input: 0.05,
       output: 0.4,
+      cachedInput: 5e-3,
       maxInputTokens: 272e3
     },
     "claude-opus-4-6": {
       input: 5,
       output: 25,
+      cachedInput: 0.5,
+      cacheCreationInput: 6.25,
       maxInputTokens: 1e6
     },
     "claude-sonnet-4-6": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 1e6
     },
     "claude-haiku-4-5": {
       input: 1,
       output: 5,
+      cachedInput: 0.1,
+      cacheCreationInput: 1.25,
       maxInputTokens: 2e5
     },
     "gemini-2.5-pro": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 1048576
     },
     "gemini-2.5-flash": {
       input: 0.3,
       output: 2.5,
+      cachedInput: 0.03,
       maxInputTokens: 1048576
     },
     "deepseek-chat": {
       input: 0.28,
       output: 0.42,
+      cachedInput: 0.028,
       maxInputTokens: 131072
     },
     "deepseek-reasoner": {
       input: 0.28,
       output: 0.42,
+      cachedInput: 0.028,
       maxInputTokens: 131072
     },
     "claude-opus-4-5": {
       input: 5,
       output: 25,
+      cachedInput: 0.5,
+      cacheCreationInput: 6.25,
       maxInputTokens: 2e5
     },
     "claude-opus-4-7": {
       input: 5,
       output: 25,
+      cachedInput: 0.5,
+      cacheCreationInput: 6.25,
       maxInputTokens: 1e6
     },
     "claude-opus-4-1": {
       input: 15,
       output: 75,
+      cachedInput: 1.5,
+      cacheCreationInput: 18.75,
       maxInputTokens: 2e5
     },
     "claude-sonnet-4-5": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 2e5
     },
     "gpt-oss-120b": {
@@ -344,36 +431,43 @@ var prices_default = {
     "gpt-4.1": {
       input: 2,
       output: 8,
+      cachedInput: 0.5,
       maxInputTokens: 1047576
     },
     "gpt-4.1-2025-04-14": {
       input: 2,
       output: 8,
+      cachedInput: 0.5,
       maxInputTokens: 1047576
     },
     "gpt-4.1-mini": {
       input: 0.4,
       output: 1.6,
+      cachedInput: 0.1,
       maxInputTokens: 1047576
     },
     "gpt-4.1-mini-2025-04-14": {
       input: 0.4,
       output: 1.6,
+      cachedInput: 0.1,
       maxInputTokens: 1047576
     },
     "gpt-4.1-nano": {
       input: 0.1,
       output: 0.4,
+      cachedInput: 0.025,
       maxInputTokens: 1047576
     },
     "gpt-4.1-nano-2025-04-14": {
       input: 0.1,
       output: 0.4,
+      cachedInput: 0.025,
       maxInputTokens: 1047576
     },
     "gpt-4.5-preview": {
       input: 75,
       output: 150,
+      cachedInput: 37.5,
       maxInputTokens: 128e3
     },
     "gpt-4o-2024-05-13": {
@@ -384,11 +478,13 @@ var prices_default = {
     "gpt-4o-2024-08-06": {
       input: 2.5,
       output: 10,
+      cachedInput: 1.25,
       maxInputTokens: 128e3
     },
     "gpt-4o-2024-11-20": {
       input: 2.5,
       output: 10,
+      cachedInput: 1.25,
       maxInputTokens: 128e3
     },
     "gpt-audio-2025-08-28": {
@@ -414,6 +510,7 @@ var prices_default = {
     "gpt-4o-mini-2024-07-18": {
       input: 0.15,
       output: 0.6,
+      cachedInput: 0.075,
       maxInputTokens: 128e3
     },
     "gpt-4o-mini-audio-preview-2024-12-17": {
@@ -424,21 +521,25 @@ var prices_default = {
     "gpt-4o-mini-realtime-preview-2024-12-17": {
       input: 0.6,
       output: 2.4,
+      cachedInput: 0.3,
       maxInputTokens: 128e3
     },
     "gpt-realtime-2025-08-28": {
       input: 4,
       output: 16,
+      cachedInput: 0.4,
       maxInputTokens: 32e3
     },
     "gpt-realtime-1.5-2026-02-23": {
       input: 4,
       output: 16,
+      cachedInput: 4,
       maxInputTokens: 32e3
     },
     "gpt-realtime-mini-2025-10-06": {
       input: 0.6,
       output: 2.4,
+      cachedInput: 0.06,
       maxInputTokens: 128e3
     },
     "gpt-4o-mini-transcribe": {
@@ -449,11 +550,13 @@ var prices_default = {
     "gpt-4o-realtime-preview-2024-10-01": {
       input: 5,
       output: 20,
+      cachedInput: 2.5,
       maxInputTokens: 128e3
     },
     "gpt-4o-realtime-preview-2024-12-17": {
       input: 5,
       output: 20,
+      cachedInput: 2.5,
       maxInputTokens: 128e3
     },
     "gpt-4o-transcribe": {
@@ -469,51 +572,61 @@ var prices_default = {
     "gpt-5.1-2025-11-13": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 272e3
     },
     "gpt-5.1-chat-2025-11-13": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 128e3
     },
     "gpt-5.1-codex-2025-11-13": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 272e3
     },
     "gpt-5.1-codex-mini-2025-11-13": {
       input: 0.25,
       output: 2,
+      cachedInput: 0.025,
       maxInputTokens: 272e3
     },
     "gpt-5-2025-08-07": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 272e3
     },
     "gpt-5-chat": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 128e3
     },
     "gpt-5-chat-latest": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 128e3
     },
     "gpt-5-codex": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 272e3
     },
     "gpt-5-mini-2025-08-07": {
       input: 0.25,
       output: 2,
+      cachedInput: 0.025,
       maxInputTokens: 272e3
     },
     "gpt-5-nano-2025-08-07": {
       input: 0.05,
       output: 0.4,
+      cachedInput: 5e-3,
       maxInputTokens: 272e3
     },
     "gpt-5-pro": {
@@ -524,61 +637,73 @@ var prices_default = {
     "gpt-5.1": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 272e3
     },
     "gpt-5.1-chat": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 128e3
     },
     "gpt-5.1-codex": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 272e3
     },
     "gpt-5.1-codex-max": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 272e3
     },
     "gpt-5.1-codex-mini": {
       input: 0.25,
       output: 2,
+      cachedInput: 0.025,
       maxInputTokens: 272e3
     },
     "gpt-5.2": {
       input: 1.75,
       output: 14,
+      cachedInput: 0.175,
       maxInputTokens: 272e3
     },
     "gpt-5.2-2025-12-11": {
       input: 1.75,
       output: 14,
+      cachedInput: 0.175,
       maxInputTokens: 272e3
     },
     "gpt-5.2-chat": {
       input: 1.75,
       output: 14,
+      cachedInput: 0.175,
       maxInputTokens: 128e3
     },
     "gpt-5.2-chat-2025-12-11": {
       input: 1.75,
       output: 14,
+      cachedInput: 0.175,
       maxInputTokens: 128e3
     },
     "gpt-5.2-codex": {
       input: 1.75,
       output: 14,
+      cachedInput: 0.175,
       maxInputTokens: 272e3
     },
     "gpt-5.3-chat": {
       input: 1.75,
       output: 14,
+      cachedInput: 0.175,
       maxInputTokens: 128e3
     },
     "gpt-5.3-codex": {
       input: 1.75,
       output: 14,
+      cachedInput: 0.175,
       maxInputTokens: 272e3
     },
     "gpt-5.2-pro": {
@@ -594,71 +719,85 @@ var prices_default = {
     "gpt-5.4": {
       input: 2.5,
       output: 15,
+      cachedInput: 0.25,
       maxInputTokens: 105e4
     },
     "gpt-5.4-2026-03-05": {
       input: 2.5,
       output: 15,
+      cachedInput: 0.25,
       maxInputTokens: 105e4
     },
     "gpt-5.4-pro": {
       input: 30,
       output: 180,
+      cachedInput: 3,
       maxInputTokens: 105e4
     },
     "gpt-5.4-pro-2026-03-05": {
       input: 30,
       output: 180,
+      cachedInput: 3,
       maxInputTokens: 105e4
     },
     "gpt-5.4-mini": {
       input: 0.75,
       output: 4.5,
+      cachedInput: 0.075,
       maxInputTokens: 272e3
     },
     "gpt-5.4-nano": {
       input: 0.2,
       output: 1.25,
+      cachedInput: 0.02,
       maxInputTokens: 272e3
     },
     "o1-2024-12-17": {
       input: 15,
       output: 60,
+      cachedInput: 7.5,
       maxInputTokens: 2e5
     },
     "o1-mini": {
       input: 1.21,
       output: 4.84,
+      cachedInput: 0.605,
       maxInputTokens: 128e3
     },
     "o1-mini-2024-09-12": {
       input: 1.1,
       output: 4.4,
+      cachedInput: 0.55,
       maxInputTokens: 128e3
     },
     "o1-preview": {
       input: 15,
       output: 60,
+      cachedInput: 7.5,
       maxInputTokens: 128e3
     },
     "o1-preview-2024-09-12": {
       input: 15,
       output: 60,
+      cachedInput: 7.5,
       maxInputTokens: 128e3
     },
     "o3-2025-04-16": {
       input: 2,
       output: 8,
+      cachedInput: 0.5,
       maxInputTokens: 2e5
     },
     "o3-mini": {
       input: 1.1,
       output: 4.4,
+      cachedInput: 0.55,
       maxInputTokens: 2e5
     },
     "o3-mini-2025-01-31": {
       input: 1.1,
       output: 4.4,
+      cachedInput: 0.55,
       maxInputTokens: 2e5
     },
     "o3-pro": {
@@ -674,11 +813,13 @@ var prices_default = {
     "o4-mini": {
       input: 1.1,
       output: 4.4,
+      cachedInput: 0.275,
       maxInputTokens: 2e5
     },
     "o4-mini-2025-04-16": {
       input: 1.1,
       output: 4.4,
+      cachedInput: 0.275,
       maxInputTokens: 2e5
     },
     "deepseek-v3.2": {
@@ -699,6 +840,7 @@ var prices_default = {
     "deepseek-v3": {
       input: 0.27,
       output: 1.1,
+      cachedInput: 0.07,
       maxInputTokens: 65536
     },
     "deepseek-v3-0324": {
@@ -714,76 +856,105 @@ var prices_default = {
     "claude-haiku-4-5-20251001": {
       input: 1,
       output: 5,
+      cachedInput: 0.1,
+      cacheCreationInput: 1.25,
       maxInputTokens: 2e5
     },
     "claude-3-7-sonnet-20250219": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 2e5
     },
     "claude-3-haiku-20240307": {
       input: 0.25,
       output: 1.25,
+      cachedInput: 0.03,
+      cacheCreationInput: 0.3,
       maxInputTokens: 2e5
     },
     "claude-3-opus-20240229": {
       input: 15,
       output: 75,
+      cachedInput: 1.5,
+      cacheCreationInput: 18.75,
       maxInputTokens: 2e5
     },
     "claude-4-opus-20250514": {
       input: 15,
       output: 75,
+      cachedInput: 1.5,
+      cacheCreationInput: 18.75,
       maxInputTokens: 2e5
     },
     "claude-4-sonnet-20250514": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 1e6
     },
     "claude-sonnet-4-5-20250929": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 2e5
     },
     "claude-sonnet-4-5-20250929-v1:0": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 2e5
     },
     "claude-opus-4-1-20250805": {
       input: 15,
       output: 75,
+      cachedInput: 1.5,
+      cacheCreationInput: 18.75,
       maxInputTokens: 2e5
     },
     "claude-opus-4-20250514": {
       input: 15,
       output: 75,
+      cachedInput: 1.5,
+      cacheCreationInput: 18.75,
       maxInputTokens: 2e5
     },
     "claude-opus-4-5-20251101": {
       input: 5,
       output: 25,
+      cachedInput: 0.5,
+      cacheCreationInput: 6.25,
       maxInputTokens: 2e5
     },
     "claude-opus-4-6-20260205": {
       input: 5,
       output: 25,
+      cachedInput: 0.5,
+      cacheCreationInput: 6.25,
       maxInputTokens: 1e6
     },
     "claude-opus-4-7-20260416": {
       input: 5,
       output: 25,
+      cachedInput: 0.5,
+      cacheCreationInput: 6.25,
       maxInputTokens: 1e6
     },
     "claude-sonnet-4-20250514": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 1e6
     },
     "codex-mini-latest": {
       input: 1.5,
       output: 6,
+      cachedInput: 0.375,
       maxInputTokens: 2e5
     },
     "deepseek-ai/deepseek-r1": {
@@ -833,6 +1004,7 @@ var prices_default = {
     "deepseek-ai/deepseek-v3.1-terminus": {
       input: 0.27,
       output: 1,
+      cachedInput: 0.216,
       maxInputTokens: 163840
     },
     "deepseek-coder": {
@@ -843,26 +1015,31 @@ var prices_default = {
     "gemini-2.0-flash": {
       input: 0.1,
       output: 0.4,
+      cachedInput: 0.025,
       maxInputTokens: 1048576
     },
     "gemini-2.0-flash-001": {
       input: 0.1,
       output: 0.4,
+      cachedInput: 0.025,
       maxInputTokens: 1048576
     },
     "gemini-2.0-flash-lite": {
       input: 0.075,
       output: 0.3,
+      cachedInput: 0.01875,
       maxInputTokens: 1048576
     },
     "gemini-2.0-flash-lite-001": {
       input: 0.075,
       output: 0.3,
+      cachedInput: 0.01875,
       maxInputTokens: 1048576
     },
     "gemini-2.5-flash-image": {
       input: 0.3,
       output: 2.5,
+      cachedInput: 0.03,
       maxInputTokens: 32768
     },
     "gemini-3-pro-image-preview": {
@@ -878,51 +1055,61 @@ var prices_default = {
     "gemini-3.1-flash-lite-preview": {
       input: 0.25,
       output: 1.5,
+      cachedInput: 0.025,
       maxInputTokens: 1048576
     },
     "gemini-2.5-flash-lite": {
       input: 0.1,
       output: 0.4,
+      cachedInput: 0.01,
       maxInputTokens: 1048576
     },
     "gemini-2.5-flash-lite-preview-09-2025": {
       input: 0.1,
       output: 0.4,
+      cachedInput: 0.01,
       maxInputTokens: 1048576
     },
     "gemini-2.5-flash-preview-09-2025": {
       input: 0.3,
       output: 2.5,
+      cachedInput: 0.075,
       maxInputTokens: 1048576
     },
     "gemini-live-2.5-flash-preview-native-audio-09-2025": {
       input: 0.3,
       output: 2,
+      cachedInput: 0.075,
       maxInputTokens: 1048576
     },
     "gemini-2.5-flash-lite-preview-06-17": {
       input: 0.1,
       output: 0.4,
+      cachedInput: 0.025,
       maxInputTokens: 1048576
     },
     "gemini-3-pro-preview": {
       input: 2,
       output: 12,
+      cachedInput: 0.2,
       maxInputTokens: 1048576
     },
     "gemini-3.1-pro-preview": {
       input: 2,
       output: 12,
+      cachedInput: 0.2,
       maxInputTokens: 1048576
     },
     "gemini-3.1-pro-preview-customtools": {
       input: 2,
       output: 12,
+      cachedInput: 0.2,
       maxInputTokens: 1048576
     },
     "gemini-3-flash-preview": {
       input: 0.5,
       output: 3,
+      cachedInput: 0.05,
       maxInputTokens: 1048576
     },
     "gemini-robotics-er-1.5-preview": {
@@ -938,11 +1125,13 @@ var prices_default = {
     "gemini-flash-latest": {
       input: 0.3,
       output: 2.5,
+      cachedInput: 0.03,
       maxInputTokens: 1048576
     },
     "gemini-flash-lite-latest": {
       input: 0.1,
       output: 0.4,
+      cachedInput: 0.01,
       maxInputTokens: 1048576
     },
     "gemini-gemma-2-27b-it": {
@@ -1018,39 +1207,47 @@ var prices_default = {
     "gpt-4o-mini-realtime-preview": {
       input: 0.6,
       output: 2.4,
+      cachedInput: 0.3,
       maxInputTokens: 128e3
     },
     "gpt-4o-realtime-preview": {
       input: 5,
       output: 20,
+      cachedInput: 2.5,
       maxInputTokens: 128e3
     },
     "gpt-4o-realtime-preview-2025-06-03": {
       input: 5,
       output: 20,
+      cachedInput: 2.5,
       maxInputTokens: 128e3
     },
     "gpt-image-1.5": {
       input: 5,
-      output: 10
+      output: 10,
+      cachedInput: 1.25
     },
     "gpt-image-1.5-2025-12-16": {
       input: 5,
-      output: 10
+      output: 10,
+      cachedInput: 1.25
     },
     "gpt-5.1-chat-latest": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 128e3
     },
     "gpt-5.2-chat-latest": {
       input: 1.75,
       output: 14,
+      cachedInput: 0.175,
       maxInputTokens: 128e3
     },
     "gpt-5.3-chat-latest": {
       input: 1.75,
       output: 14,
+      cachedInput: 0.175,
       maxInputTokens: 128e3
     },
     "gpt-5-pro-2025-10-06": {
@@ -1061,11 +1258,13 @@ var prices_default = {
     "gpt-realtime": {
       input: 4,
       output: 16,
+      cachedInput: 0.4,
       maxInputTokens: 32e3
     },
     "gpt-realtime-1.5": {
       input: 4,
       output: 16,
+      cachedInput: 0.4,
       maxInputTokens: 32e3
     },
     "gpt-realtime-mini": {
@@ -1112,6 +1311,7 @@ var prices_default = {
     o1: {
       input: 15,
       output: 60,
+      cachedInput: 7.5,
       maxInputTokens: 2e5
     },
     "o1-pro": {
@@ -1127,6 +1327,7 @@ var prices_default = {
     o3: {
       input: 2,
       output: 8,
+      cachedInput: 0.5,
       maxInputTokens: 2e5
     },
     "gpt-oss-20b": {
@@ -1151,6 +1352,8 @@ var prices_default = {
     "claude-haiku-4-5@20251001": {
       input: 1,
       output: 5,
+      cachedInput: 0.1,
+      cacheCreationInput: 1.25,
       maxInputTokens: 2e5
     },
     "claude-3-5-sonnet": {
@@ -1166,6 +1369,8 @@ var prices_default = {
     "claude-3-7-sonnet@20250219": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 2e5
     },
     "claude-3-haiku": {
@@ -1201,46 +1406,64 @@ var prices_default = {
     "claude-opus-4": {
       input: 15,
       output: 75,
+      cachedInput: 1.5,
+      cacheCreationInput: 18.75,
       maxInputTokens: 2e5
     },
     "claude-opus-4-1@20250805": {
       input: 15,
       output: 75,
+      cachedInput: 1.5,
+      cacheCreationInput: 18.75,
       maxInputTokens: 2e5
     },
     "claude-opus-4-5@20251101": {
       input: 5,
       output: 25,
+      cachedInput: 0.5,
+      cacheCreationInput: 6.25,
       maxInputTokens: 2e5
     },
     "claude-opus-4-6@default": {
       input: 5,
       output: 25,
+      cachedInput: 0.5,
+      cacheCreationInput: 6.25,
       maxInputTokens: 1e6
     },
     "claude-opus-4-7@default": {
       input: 5,
       output: 25,
+      cachedInput: 0.5,
+      cacheCreationInput: 6.25,
       maxInputTokens: 1e6
     },
     "claude-sonnet-4-5@20250929": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 2e5
     },
     "claude-opus-4@20250514": {
       input: 15,
       output: 75,
+      cachedInput: 1.5,
+      cacheCreationInput: 18.75,
       maxInputTokens: 2e5
     },
     "claude-sonnet-4": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 1e6
     },
     "claude-sonnet-4@20250514": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 1e6
     },
     "deepseek-ai/deepseek-v3.1-maas": {
@@ -1290,6 +1513,7 @@ var prices_default = {
     "gpt-realtime-mini-2025-12-15": {
       input: 0.6,
       output: 2.4,
+      cachedInput: 0.06,
       maxInputTokens: 128e3
     },
     "gemini-2.5-flash-native-audio-latest": {
@@ -1315,16 +1539,20 @@ var prices_default = {
     "gemini-pro-latest": {
       input: 1.25,
       output: 10,
+      cachedInput: 0.125,
       maxInputTokens: 1048576
     },
     "gemini-exp-1206": {
       input: 0.3,
       output: 2.5,
+      cachedInput: 0.03,
       maxInputTokens: 1048576
     },
     "claude-sonnet-4-6@default": {
       input: 3,
       output: 15,
+      cachedInput: 0.3,
+      cacheCreationInput: 3.75,
       maxInputTokens: 1e6
     }
   }
@@ -1332,11 +1560,19 @@ var prices_default = {
 
 // src/core/tracker.ts
 var bundledPrices = prices_default.models;
+var bundledUpdatedAt = prices_default.updated_at ?? "";
 var ModelPriceSchema = z.object({
   input: z.number().nonnegative(),
   output: z.number().nonnegative(),
+  cachedInput: z.number().nonnegative().optional(),
+  cacheCreationInput: z.number().nonnegative().optional(),
   maxInputTokens: z.number().positive().optional()
 });
+var BudgetConfigSchema = z.object({
+  threshold: z.number().positive(),
+  webhookUrl: z.string().url(),
+  mode: z.enum(["once", "always"]).optional().default("once")
+});
 var TrackerConfigSchema = z.object({
   storage: z.union([z.enum(["memory", "sqlite"]), z.custom((v) => {
     return v !== null && typeof v === "object" && typeof v.record === "function" && typeof v.getAll === "function" && typeof v.clearAll === "function" && typeof v.clearSession === "function";
@@ -1344,7 +1580,13 @@ var TrackerConfigSchema = z.object({
   alertThreshold: z.number().positive().optional(),
   webhookUrl: z.string().url().optional(),
   syncPrices: z.boolean().optional().default(true),
-  customPrices: z.record(z.string(), ModelPriceSchema).optional()
+  customPrices: z.record(z.string(), ModelPriceSchema).optional(),
+  warnIfStaleAfterHours: z.number().nonnegative().optional().default(72),
+  budgets: z.object({
+    perUser: BudgetConfigSchema.optional(),
+    perSession: BudgetConfigSchema.optional()
+  }).optional(),
+  suggestions: z.boolean().optional().default(false)
 });
 function createTracker(config = {}) {
   const parsed = TrackerConfigSchema.safeParse(config);
@@ -1358,19 +1600,45 @@ ${issues}`);
     alertThreshold,
     webhookUrl,
     syncPrices,
-    customPrices
+    customPrices,
+    warnIfStaleAfterHours,
+    budgets,
+    suggestions
   } = parsed.data;
   const storage = typeof storageOption === "object" ? storageOption : createStorage(storageOption);
   let remotePrices;
+  let pricesUpdatedAt = bundledUpdatedAt;
   if (syncPrices) {
     getRemotePrices().then((result) => {
-      if (result) remotePrices = result;
+      if (result) {
+        remotePrices = result.models;
+        pricesUpdatedAt = result.updated_at;
+      }
     }).catch(() => {
     });
   }
+  let stalenessChecked = false;
+  function maybeWarnStaleness() {
+    if (stalenessChecked || !warnIfStaleAfterHours) return;
+    stalenessChecked = true;
+    if (!pricesUpdatedAt) return;
+    try {
+      const updatedMs = new Date(pricesUpdatedAt).getTime();
+      const ageHours = (Date.now() - updatedMs) / (1e3 * 60 * 60);
+      if (ageHours > warnIfStaleAfterHours) {
+        console.warn(
+          `[tokenwatch] Price data is ${Math.round(ageHours)}h old (updated_at: ${pricesUpdatedAt}). Run "tokenwatch sync" to refresh, or set warnIfStaleAfterHours: 0 to suppress.`
+        );
+      }
+    } catch {
+    }
+  }
   let alertFired = false;
+  const firedUserAlerts = /* @__PURE__ */ new Set();
+  const firedSessionAlerts = /* @__PURE__ */ new Set();
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
   function resolveModelPrice(model) {
+    maybeWarnStaleness();
     return resolvePrice(model, {
       bundledPrices,
       ...customPrices !== void 0 && { customPrices },
@@ -1381,8 +1649,10 @@ ${issues}`);
     const price = resolveModelPrice(entry.model);
     const costUSD = calculateCost(
       entry.inputTokens,
-      entry.outputTokens + (entry.reasoningTokens ?? 0),
-      price
+      entry.outputTokens,
+      price,
+      entry.cachedTokens,
+      entry.cacheCreationTokens
     );
     const full = {
       ...entry,
@@ -1390,32 +1660,81 @@ ${issues}`);
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     };
     storage.record(full);
-    maybeFireAlert();
+    maybeFireAlerts(full);
+    if (suggestions) {
+      maybeSuggestCheaperModel(entry.model, costUSD, entry.inputTokens, entry.outputTokens, {
+        bundledPrices,
+        ...customPrices !== void 0 && { customPrices },
+        ...remotePrices !== void 0 && { remotePrices }
+      });
+    }
   }
-  function maybeFireAlert() {
-    if (!alertThreshold || !webhookUrl || alertFired) return;
-    alertFired = true;
-    Promise.resolve(storage.getAll()).then((entries) => {
-      const total = computeTotal(entries);
-      if (total < alertThreshold) {
-        alertFired = false;
-        return;
-      }
-      const payload = {
-        text: `[tokenwatch] Alert: total cost reached $${total.toFixed(4)} USD (threshold: $${alertThreshold})`
-      };
-      fetch(webhookUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(payload)
+  function maybeFireAlerts(entry) {
+    if (alertThreshold && webhookUrl && !alertFired) {
+      alertFired = true;
+      Promise.resolve(storage.getAll()).then((entries) => {
+        const total = computeTotal(entries);
+        if (total < alertThreshold) {
+          alertFired = false;
+          return;
+        }
+        fireWebhook(webhookUrl, {
+          text: `[tokenwatch] Alert: total cost reached $${total.toFixed(4)} USD (threshold: $${alertThreshold})`
+        });
       }).catch(() => {
+        alertFired = false;
       });
+    }
+    if (budgets?.perUser && entry.userId) {
+      const cfg = budgets.perUser;
+      const uid = entry.userId;
+      if (cfg.mode === "always" || !firedUserAlerts.has(uid)) {
+        if (cfg.mode !== "always") firedUserAlerts.add(uid);
+        Promise.resolve(storage.getAll()).then((entries) => {
+          const userCost = entries.filter((e) => e.userId === uid).reduce((s, e) => s + e.costUSD, 0);
+          if (userCost >= cfg.threshold) {
+            fireWebhook(cfg.webhookUrl, {
+              text: `[tokenwatch] Budget alert: user "${uid}" reached $${userCost.toFixed(4)} USD (threshold: $${cfg.threshold})`
+            });
+          } else {
+            if (cfg.mode !== "always") firedUserAlerts.delete(uid);
+          }
+        }).catch(() => {
+          if (cfg.mode !== "always") firedUserAlerts.delete(uid);
+        });
+      }
+    }
+    if (budgets?.perSession && entry.sessionId) {
+      const cfg = budgets.perSession;
+      const sid = entry.sessionId;
+      if (cfg.mode === "always" || !firedSessionAlerts.has(sid)) {
+        if (cfg.mode !== "always") firedSessionAlerts.add(sid);
+        Promise.resolve(storage.getAll()).then((entries) => {
+          const sessionCost = entries.filter((e) => e.sessionId === sid).reduce((s, e) => s + e.costUSD, 0);
+          if (sessionCost >= cfg.threshold) {
+            fireWebhook(cfg.webhookUrl, {
+              text: `[tokenwatch] Budget alert: session "${sid}" reached $${sessionCost.toFixed(4)} USD (threshold: $${cfg.threshold})`
+            });
+          } else {
+            if (cfg.mode !== "always") firedSessionAlerts.delete(sid);
+          }
+        }).catch(() => {
+          if (cfg.mode !== "always") firedSessionAlerts.delete(sid);
+        });
+      }
+    }
+  }
+  function fireWebhook(url, payload) {
+    fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
     }).catch(() => {
-      alertFired = false;
     });
   }
-  async function getReport() {
-    const entries = await Promise.resolve(storage.getAll());
+  async function getReport(options) {
+    const allEntries = await Promise.resolve(storage.getAll());
+    const entries = filterEntries(allEntries, options);
     const byModel = {};
     const bySession = {};
     const byUser = {};
@@ -1423,18 +1742,24 @@ ${issues}`);
     let totalInput = 0;
     let totalOutput = 0;
     let totalCost = 0;
-    let lastTimestamp = startedAt;
+    let periodFrom = options ? entries[0]?.timestamp ?? startedAt : startedAt;
+    let lastTimestamp = periodFrom;
     for (const e of entries) {
-      totalInput += e.inputTokens;
+      totalInput += e.inputTokens + (e.cachedTokens ?? 0) + (e.cacheCreationTokens ?? 0);
       totalOutput += e.outputTokens;
       totalCost += e.costUSD;
       if (e.timestamp > lastTimestamp) lastTimestamp = e.timestamp;
-      const m = byModel[e.model] ??= { costUSD: 0, calls: 0, tokens: { input: 0, output: 0, reasoning: 0 } };
+      const m = byModel[e.model] ??= {
+        costUSD: 0,
+        calls: 0,
+        tokens: { input: 0, output: 0, reasoning: 0, cached: 0 }
+      };
       m.costUSD += e.costUSD;
       m.calls += 1;
-      m.tokens.input += e.inputTokens;
+      m.tokens.input += e.inputTokens + (e.cachedTokens ?? 0) + (e.cacheCreationTokens ?? 0);
       m.tokens.output += e.outputTokens;
       m.tokens.reasoning += e.reasoningTokens ?? 0;
+      m.tokens.cached += e.cachedTokens ?? 0;
       if (e.sessionId) {
         const s = bySession[e.sessionId] ??= { costUSD: 0, calls: 0 };
         s.costUSD += e.costUSD;
@@ -1451,6 +1776,9 @@ ${issues}`);
         f.calls += 1;
       }
     }
+    if (options && entries.length > 0) {
+      periodFrom = entries[0]?.timestamp ?? periodFrom;
+    }
     return {
       totalCostUSD: totalCost,
       totalTokens: { input: totalInput, output: totalOutput },
@@ -1458,22 +1786,66 @@ ${issues}`);
       bySession,
       byUser,
       byFeature,
-      period: { from: startedAt, to: lastTimestamp }
+      period: { from: periodFrom, to: lastTimestamp },
+      ...pricesUpdatedAt ? { pricesUpdatedAt } : {}
+    };
+  }
+  async function getCostForecast(options = {}) {
+    const windowHours = options.windowHours ?? 24;
+    const allEntries = await Promise.resolve(storage.getAll());
+    const now = Date.now();
+    const windowStart = now - windowHours * 60 * 60 * 1e3;
+    const windowEntries = allEntries.filter(
+      (e) => new Date(e.timestamp).getTime() >= windowStart
+    );
+    if (windowEntries.length < 2) {
+      return {
+        burnRatePerHour: 0,
+        projectedDailyCostUSD: 0,
+        projectedMonthlyCostUSD: 0,
+        basedOnHours: 0,
+        basedOnPeriod: null
+      };
+    }
+    const first = windowEntries[0]?.timestamp ?? "";
+    const last = windowEntries[windowEntries.length - 1]?.timestamp ?? "";
+    const actualMs = new Date(last).getTime() - new Date(first).getTime();
+    const actualHours = actualMs / (1e3 * 60 * 60);
+    if (actualHours < 1e-3) {
+      return {
+        burnRatePerHour: 0,
+        projectedDailyCostUSD: 0,
+        projectedMonthlyCostUSD: 0,
+        basedOnHours: 0,
+        basedOnPeriod: { from: first, to: last }
+      };
+    }
+    const totalCost = windowEntries.reduce((s, e) => s + e.costUSD, 0);
+    const burnRatePerHour = totalCost / actualHours;
+    return {
+      burnRatePerHour,
+      projectedDailyCostUSD: burnRatePerHour * 24,
+      projectedMonthlyCostUSD: burnRatePerHour * 24 * 30,
+      basedOnHours: Math.round(actualHours * 100) / 100,
+      basedOnPeriod: { from: first, to: last }
     };
   }
   async function reset() {
     await Promise.resolve(storage.clearAll());
     alertFired = false;
+    firedUserAlerts.clear();
+    firedSessionAlerts.clear();
   }
   async function resetSession(sessionId) {
     await Promise.resolve(storage.clearSession(sessionId));
+    firedSessionAlerts.delete(sessionId);
   }
   async function exportJSON() {
     return JSON.stringify(await getReport(), null, 2);
   }
   async function exportCSV() {
     const entries = await Promise.resolve(storage.getAll());
-    const header = "timestamp,model,inputTokens,outputTokens,reasoningTokens,costUSD,sessionId,userId,feature";
+    const header = "timestamp,model,inputTokens,outputTokens,reasoningTokens,cachedTokens,cacheCreationTokens,costUSD,sessionId,userId,feature";
     const rows = entries.map(
       (e) => [
         csvEscape(e.timestamp),
@@ -1481,6 +1853,8 @@ ${issues}`);
         e.inputTokens,
         e.outputTokens,
         e.reasoningTokens ?? 0,
+        e.cachedTokens ?? 0,
+        e.cacheCreationTokens ?? 0,
         e.costUSD.toFixed(8),
         csvEscape(e.sessionId ?? ""),
         csvEscape(e.userId ?? ""),
@@ -1496,11 +1870,47 @@ ${issues}`);
       ...remotePrices !== void 0 && { remotePrices }
     }) ?? null;
   }
-  return { track, getReport, reset, resetSession, exportJSON, exportCSV, getModelInfo };
+  return {
+    track,
+    getReport,
+    getCostForecast,
+    reset,
+    resetSession,
+    exportJSON,
+    exportCSV,
+    getModelInfo
+  };
 }
 function computeTotal(entries) {
   return entries.reduce((sum, e) => sum + e.costUSD, 0);
 }
+function parseLastMs(last) {
+  const match = /^(\d+(?:\.\d+)?)(h|d)$/.exec(last.trim());
+  if (!match) throw new Error(`[tokenwatch] Invalid "last" value: "${last}". Use e.g. "24h", "7d".`);
+  const value = parseFloat(match[1] ?? "0");
+  const unit = match[2] ?? "h";
+  return unit === "h" ? value * 60 * 60 * 1e3 : value * 24 * 60 * 60 * 1e3;
+}
+function filterEntries(entries, options) {
+  if (!options) return entries;
+  let sinceMs;
+  let untilMs;
+  if (options.last) {
+    sinceMs = Date.now() - parseLastMs(options.last);
+  } else if (options.since) {
+    sinceMs = new Date(options.since).getTime();
+  }
+  if (options.until) {
+    untilMs = new Date(options.until).getTime();
+  }
+  if (sinceMs === void 0 && untilMs === void 0) return entries;
+  return entries.filter((e) => {
+    const ts = new Date(e.timestamp).getTime();
+    if (sinceMs !== void 0 && ts < sinceMs) return false;
+    if (untilMs !== void 0 && ts > untilMs) return false;
+    return true;
+  });
+}
 function csvEscape(value) {
   if (value.includes(",") || value.includes('"') || value.includes("\n")) {
     return `"${value.replace(/"/g, '""')}"`;
@@ -1508,6 +1918,71 @@ function csvEscape(value) {
   return value;
 }
 
+// src/core/lazy-tracker.ts
+var CSV_HEADER = "timestamp,model,inputTokens,outputTokens,reasoningTokens,cachedTokens,cacheCreationTokens,costUSD,sessionId,userId,feature";
+function emptyReport() {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    totalCostUSD: 0,
+    totalTokens: { input: 0, output: 0 },
+    byModel: {},
+    bySession: {},
+    byUser: {},
+    byFeature: {},
+    period: { from: now, to: now }
+  };
+}
+function zeroForecast() {
+  return {
+    burnRatePerHour: 0,
+    projectedDailyCostUSD: 0,
+    projectedMonthlyCostUSD: 0,
+    basedOnHours: 0,
+    basedOnPeriod: null
+  };
+}
+function createLazyTracker() {
+  let delegate = null;
+  return {
+    init(config) {
+      if (delegate !== null) {
+        throw new Error(
+          "[tokenwatch] LazyTracker already initialized. init() may only be called once."
+        );
+      }
+      try {
+        delegate = createTracker(config ?? {});
+      } catch (err) {
+        throw err;
+      }
+    },
+    track(entry) {
+      delegate?.track(entry);
+    },
+    async getReport(options) {
+      return delegate?.getReport(options) ?? emptyReport();
+    },
+    async getCostForecast(options) {
+      return delegate?.getCostForecast(options) ?? zeroForecast();
+    },
+    async reset() {
+      await delegate?.reset();
+    },
+    async resetSession(sessionId) {
+      await delegate?.resetSession(sessionId);
+    },
+    async exportJSON() {
+      return delegate?.exportJSON() ?? "{}";
+    },
+    async exportCSV() {
+      return delegate?.exportCSV() ?? CSV_HEADER;
+    },
+    getModelInfo(model) {
+      return delegate?.getModelInfo(model) ?? null;
+    }
+  };
+}
+
 // src/providers/openai.ts
 function extractMeta(params) {
   const { __sessionId, __userId, __feature, ...cleaned } = params;
@@ -1519,19 +1994,24 @@ function extractMeta(params) {
   };
 }
 function extractUsage(usage) {
-  if (!usage) return { inputTokens: 0, outputTokens: 0, reasoningTokens: 0 };
+  if (!usage) return { inputTokens: 0, outputTokens: 0, reasoningTokens: 0, cachedTokens: 0 };
+  const totalInput = usage.prompt_tokens ?? usage.input_tokens ?? 0;
+  const cachedTokens = usage.prompt_tokens_details?.cached_tokens ?? 0;
   return {
-    inputTokens: usage.prompt_tokens ?? usage.input_tokens ?? 0,
+    // inputTokens = regular (non-cached) input; OpenAI prompt_tokens includes cached tokens
+    inputTokens: totalInput - cachedTokens,
     outputTokens: usage.completion_tokens ?? usage.output_tokens ?? 0,
-    reasoningTokens: usage.completion_tokens_details?.reasoning_tokens ?? 0
+    reasoningTokens: usage.completion_tokens_details?.reasoning_tokens ?? 0,
+    cachedTokens
   };
 }
-function trackWithMeta(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature) {
+function trackWithMeta(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens = 0) {
   tracker.track({
     model,
     inputTokens,
-    outputTokens,
+    outputTokens: outputTokens + reasoningTokens,
     ...reasoningTokens > 0 && { reasoningTokens },
+    ...cachedTokens > 0 && { cachedTokens },
     ...sessionId !== void 0 && { sessionId },
     ...userId !== void 0 && { userId },
     ...feature !== void 0 && { feature }
@@ -1543,13 +2023,13 @@ async function* wrapStream(stream, model, sessionId, userId, feature, tracker) {
     lastChunk = chunk;
     yield chunk;
   }
-  const { inputTokens, outputTokens, reasoningTokens } = extractUsage(lastChunk?.usage);
+  const { inputTokens, outputTokens, reasoningTokens, cachedTokens } = extractUsage(lastChunk?.usage);
   if (!lastChunk?.usage) {
     console.warn(
       `[tokenwatch] No usage data in stream for model "${model}". Cost recorded as $0. Pass stream_options: { include_usage: true } to get accurate costs.`
     );
   }
-  trackWithMeta(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature);
+  trackWithMeta(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens);
 }
 function wrapOpenAI(client, tracker) {
   const proxiedCompletions = new Proxy(client.chat.completions, {
@@ -1571,7 +2051,7 @@ function wrapOpenAI(client, tracker) {
           );
         }
         const completion = result;
-        const { inputTokens, outputTokens, reasoningTokens } = extractUsage(completion.usage);
+        const { inputTokens, outputTokens, reasoningTokens, cachedTokens } = extractUsage(completion.usage);
         trackWithMeta(
           tracker,
           completion.model ?? model,
@@ -1580,7 +2060,8 @@ function wrapOpenAI(client, tracker) {
           reasoningTokens,
           sessionId,
           userId,
-          feature
+          feature,
+          cachedTokens
         );
         return result;
       };
@@ -1627,10 +2108,12 @@ function extractMeta2(params) {
   };
 }
 function extractUsage2(usage) {
-  if (!usage) return { inputTokens: 0, outputTokens: 0 };
+  if (!usage) return { inputTokens: 0, outputTokens: 0, cachedTokens: 0, cacheCreationTokens: 0 };
   return {
     inputTokens: usage.input_tokens ?? 0,
-    outputTokens: usage.output_tokens ?? 0
+    outputTokens: usage.output_tokens ?? 0,
+    cachedTokens: usage.cache_read_input_tokens ?? 0,
+    cacheCreationTokens: usage.cache_creation_input_tokens ?? 0
   };
 }
 function extractThinkingTokenApprox(content) {
@@ -1638,30 +2121,32 @@ function extractThinkingTokenApprox(content) {
   const chars = content.filter((b) => b.type === "thinking").reduce((sum, b) => sum + (b.thinking?.length ?? 0), 0);
   return chars > 0 ? Math.round(chars / 4) : 0;
 }
-function trackWithMeta2(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature) {
+function trackWithMeta2(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens = 0, cacheCreationTokens = 0) {
   tracker.track({
     model,
     inputTokens,
     outputTokens,
-    // For Anthropic, reasoningTokens is informational (thinking already in outputTokens).
-    // Pass 0 so tracker does not add it to cost (tracker only adds when > 0 AND separate).
-    // We store it as a field but the tracker cost formula adds reasoningTokens to outputTokens,
-    // so we must NOT pass it here to avoid double-counting.
+    ...reasoningTokens > 0 && { reasoningTokens },
+    ...cachedTokens > 0 && { cachedTokens },
+    ...cacheCreationTokens > 0 && { cacheCreationTokens },
     ...sessionId !== void 0 && { sessionId },
     ...userId !== void 0 && { userId },
-    ...feature !== void 0 && { feature },
-    ...reasoningTokens > 0 && { reasoningTokens }
+    ...feature !== void 0 && { feature }
   });
 }
 async function* wrapStream2(stream, model, sessionId, userId, feature, tracker) {
   let inputTokens = 0;
   let outputTokens = 0;
+  let cachedTokens = 0;
+  let cacheCreationTokens = 0;
   let currentBlockIsThinking = false;
   let thinkingCharCount = 0;
   for await (const event of stream) {
     yield event;
     if (event.type === "message_start" && event.message?.usage) {
       inputTokens = event.message.usage.input_tokens ?? 0;
+      cachedTokens = event.message.usage.cache_read_input_tokens ?? 0;
+      cacheCreationTokens = event.message.usage.cache_creation_input_tokens ?? 0;
     }
     if (event.type === "message_delta" && event.usage) {
       outputTokens = event.usage.output_tokens ?? 0;
@@ -1677,7 +2162,7 @@ async function* wrapStream2(stream, model, sessionId, userId, feature, tracker)
     }
   }
   const reasoningTokens = thinkingCharCount > 0 ? Math.round(thinkingCharCount / 4) : 0;
-  trackWithMeta2(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature);
+  trackWithMeta2(tracker, model, inputTokens, outputTokens, reasoningTokens, sessionId, userId, feature, cachedTokens, cacheCreationTokens);
 }
 function wrapAnthropic(client, tracker) {
   const proxiedMessages = new Proxy(client.messages, {
@@ -1699,7 +2184,7 @@ function wrapAnthropic(client, tracker) {
           );
         }
         const message = result;
-        const { inputTokens, outputTokens } = extractUsage2(message.usage);
+        const { inputTokens, outputTokens, cachedTokens, cacheCreationTokens } = extractUsage2(message.usage);
         const reasoningTokens = extractThinkingTokenApprox(message.content);
         trackWithMeta2(
           tracker,
@@ -1709,7 +2194,9 @@ function wrapAnthropic(client, tracker) {
           reasoningTokens,
           sessionId,
           userId,
-          feature
+          feature,
+          cachedTokens,
+          cacheCreationTokens
         );
         return result;
       };
@@ -1779,6 +2266,7 @@ function wrapGemini(client, tracker) {
   });
 }
 export {
+  createLazyTracker,
   createTracker,
   wrapAnthropic,
   wrapOpenAI as wrapDeepSeek,