zevairouter 1.0.101 → 1.0.103

package/src/lib/alerter.js

@@ -0,0 +1,122 @@
+/**
+ * Webhook alerter — sends notifications to Discord / Telegram / generic webhook
+ * when something needs attention (provider down, quota exhausted, error spikes).
+ *
+ * Config (stored in settings):
+ *   alertWebhookUrl      — target URL (Discord webhook / generic HTTPS endpoint)
+ *   alertWebhookType     — "discord" | "telegram" | "generic"
+ *   alertTelegramChatId  — required when type=telegram (bot token goes in URL)
+ *   alertEnabled         — master switch
+ *   alertMinIntervalMs   — rate-limit identical alerts (default 5 min)
+ *
+ * Design: fire-and-forget. Alerting must NEVER block or fail a request.
+ */
+
+import { getSettings } from "./localDb.js";
+
+// Rate-limit identical alerts so a flapping provider doesn't spam the channel
+const lastSentByKey = new Map(); // key -> timestamp
+
+function shouldThrottle(key, minIntervalMs) {
+  const now = Date.now();
+  const last = lastSentByKey.get(key) || 0;
+  if (now - last < minIntervalMs) return true;
+  lastSentByKey.set(key, now);
+  return false;
+}
+
+function buildPayload(type, { title, message, severity = "warn", fields = [] }, config) {
+  if (type === "discord") {
+    const color = severity === "error" ? 0xef4444 : severity === "warn" ? 0xf59e0b : 0x3b82f6;
+    return {
+      embeds: [{
+        title,
+        description: message,
+        color,
+        fields: fields.map((f) => ({ name: f.name, value: String(f.value), inline: true })),
+        timestamp: new Date().toISOString(),
+        footer: { text: "ZevAI Router" },
+      }],
+    };
+  }
+  if (type === "telegram") {
+    // Telegram Bot API: URL contains bot token, chat_id goes in body
+    const icon = severity === "error" ? "🔴" : severity === "warn" ? "🟡" : "🔵";
+    const text = [`${icon} *${title}*`, message, ...fields.map((f) => `• ${f.name}: ${f.value}`)].join("\n");
+    return { chat_id: config.alertTelegramChatId, text, parse_mode: "Markdown" };
+  }
+  // generic — simple JSON POST
+  return { title, message, severity, fields, ts: new Date().toISOString(), source: "zevairouter" };
+}
+
+/**
+ * Send an alert. Never throws.
+ * @param {string} alertKey - Dedup key (e.g. "provider-down:anthropic")
+ * @param {object} opts - { title, message, severity, fields, force }
+ */
+export async function sendAlert(alertKey, opts) {
+  try {
+    const settings = await getSettings();
+    if (!settings.alertEnabled || !settings.alertWebhookUrl) return { sent: false, reason: "disabled" };
+
+    const type = settings.alertWebhookType || "generic";
+    const minInterval = Number(settings.alertMinIntervalMs) || 5 * 60 * 1000;
+    if (!opts.force && shouldThrottle(alertKey, minInterval)) {
+      return { sent: false, reason: "throttled" };
+    }
+
+    const payload = buildPayload(type, opts, settings);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 8000);
+    try {
+      const res = await fetch(settings.alertWebhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        console.warn(`[alert] webhook ${type} responded ${res.status}`);
+        return { sent: false, reason: `http-${res.status}` };
+      }
+      return { sent: true };
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (e) {
+    console.warn(`[alert] send failed: ${e.message}`);
+    return { sent: false, reason: e.message };
+  }
+}
+
+/** Convenience: provider is failing repeatedly */
+export function alertProviderDown(provider, detail) {
+  return sendAlert(`provider-down:${provider}`, {
+    title: `Provider down: ${provider}`,
+    message: detail || `${provider} is returning errors repeatedly.`,
+    severity: "error",
+    fields: [{ name: "provider", value: provider }],
+  });
+}
+
+/** Convenience: quota exhausted for an account */
+export function alertQuotaExhausted(provider, accountName) {
+  return sendAlert(`quota:${provider}:${accountName}`, {
+    title: `Quota exhausted: ${provider}`,
+    message: `Account "${accountName}" has exhausted its quota.`,
+    severity: "warn",
+    fields: [
+      { name: "provider", value: provider },
+      { name: "account", value: accountName },
+    ],
+  });
+}
+
+/** Convenience: error spike detected */
+export function alertErrorSpike(count, windowSec) {
+  return sendAlert(`error-spike`, {
+    title: `Error spike detected`,
+    message: `${count} failed requests in the last ${windowSec}s.`,
+    severity: "error",
+  });
+}

package/src/lib/db/index.js

@@ -42,6 +42,7 @@ export {
 // API keys
 export {
   getApiKeys, getApiKeyById, createApiKey, updateApiKey, deleteApiKey, validateApiKey,
+  checkApiKeyBudget,
 } from "./repos/apiKeysRepo.js";
 
 // Combos
@@ -71,6 +72,7 @@ export {
 export {
   statsEmitter, trackPendingRequest, getActiveRequests,
   saveRequestUsage, getUsageHistory, getUsageStats, getChartData,
+  getLatencyStats,
   appendRequestLog, getRecentLogs,
 } from "./repos/usageRepo.js";
 

package/src/lib/db/repos/apiKeysRepo.js

@@ -10,6 +10,8 @@ function rowToKey(row) {
     machineId: row.machineId,
     isActive: row.isActive === 1 || row.isActive === true,
     createdAt: row.createdAt,
+    budgetDaily: row.budgetDaily || 0,
+    budgetMonthly: row.budgetMonthly || 0,
   };
 }
 
@@ -53,8 +55,9 @@ export async function updateApiKey(id, data) {
     if (!row) return;
     const merged = { ...rowToKey(row), ...data };
     db.run(
-      `UPDATE apiKeys SET key = ?, name = ?, machineId = ?, isActive = ? WHERE id = ?`,
-      [merged.key, merged.name, merged.machineId, merged.isActive ? 1 : 0, id]
+      `UPDATE apiKeys SET key = ?, name = ?, machineId = ?, isActive = ?, budgetDaily = ?, budgetMonthly = ? WHERE id = ?`,
+      [merged.key, merged.name, merged.machineId, merged.isActive ? 1 : 0,
+       Number(merged.budgetDaily) || 0, Number(merged.budgetMonthly) || 0, id]
     );
     result = merged;
   });
@@ -73,3 +76,58 @@ export async function validateApiKey(key) {
   if (!row) return false;
   return row.isActive === 1 || row.isActive === true;
 }
+
+/**
+ * Check whether an API key has exceeded its configured budget.
+ * Spend is summed from usageHistory.cost (already computed per request).
+ *
+ * @param {string} key - The API key string
+ * @returns {Promise<{allowed: boolean, reason?: string, spentDaily?: number, spentMonthly?: number, budgetDaily?: number, budgetMonthly?: number}>}
+ */
+export async function checkApiKeyBudget(key) {
+  const db = await getAdapter();
+  const row = db.get(`SELECT budgetDaily, budgetMonthly FROM apiKeys WHERE key = ?`, [key]);
+  if (!row) return { allowed: true }; // unknown key → let validateApiKey handle it
+
+  const budgetDaily = row.budgetDaily || 0;
+  const budgetMonthly = row.budgetMonthly || 0;
+  if (budgetDaily <= 0 && budgetMonthly <= 0) {
+    return { allowed: true, budgetDaily, budgetMonthly };
+  }
+
+  let spentDaily = 0;
+  let spentMonthly = 0;
+  try {
+    if (budgetDaily > 0) {
+      const startOfDay = new Date();
+      startOfDay.setHours(0, 0, 0, 0);
+      const r = db.get(
+        `SELECT COALESCE(SUM(cost), 0) AS total FROM usageHistory WHERE apiKey = ? AND timestamp >= ?`,
+        [key, startOfDay.toISOString()]
+      );
+      spentDaily = r?.total || 0;
+    }
+    if (budgetMonthly > 0) {
+      const startOfMonth = new Date();
+      startOfMonth.setDate(1);
+      startOfMonth.setHours(0, 0, 0, 0);
+      const r = db.get(
+        `SELECT COALESCE(SUM(cost), 0) AS total FROM usageHistory WHERE apiKey = ? AND timestamp >= ?`,
+        [key, startOfMonth.toISOString()]
+      );
+      spentMonthly = r?.total || 0;
+    }
+  } catch (e) {
+    // On read failure, fail open (don't block legit traffic) but log
+    console.error("[apiKeysRepo] budget check failed:", e.message);
+    return { allowed: true };
+  }
+
+  if (budgetDaily > 0 && spentDaily >= budgetDaily) {
+    return { allowed: false, reason: `Daily budget exceeded ($${spentDaily.toFixed(4)} / $${budgetDaily})`, spentDaily, spentMonthly, budgetDaily, budgetMonthly };
+  }
+  if (budgetMonthly > 0 && spentMonthly >= budgetMonthly) {
+    return { allowed: false, reason: `Monthly budget exceeded ($${spentMonthly.toFixed(4)} / $${budgetMonthly})`, spentDaily, spentMonthly, budgetDaily, budgetMonthly };
+  }
+  return { allowed: true, spentDaily, spentMonthly, budgetDaily, budgetMonthly };
+}

package/src/lib/db/repos/usageRepo.js

@@ -33,23 +33,37 @@ function getLocalDateKey(timestamp) {
 }
 
 function addToCounter(target, key, values) {
-  if (!target[key]) target[key] = { requests: 0, promptTokens: 0, completionTokens: 0, cost: 0 };
+  if (!target[key]) target[key] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0 };
   target[key].requests += values.requests || 1;
   target[key].promptTokens += values.promptTokens || 0;
   target[key].completionTokens += values.completionTokens || 0;
+  target[key].cachedTokens = (target[key].cachedTokens || 0) + (values.cachedTokens || 0);
   target[key].cost += values.cost || 0;
   if (values.meta) Object.assign(target[key], values.meta);
 }
 
+function extractCachedTokens(tokens) {
+  if (!tokens || typeof tokens !== "object") return 0;
+  // OpenAI-style: prompt_tokens_details.cached_tokens; Anthropic-style: cache_read_input_tokens
+  return (
+    tokens.cached_tokens
+    || tokens.prompt_tokens_details?.cached_tokens
+    || tokens.cache_read_input_tokens
+    || 0
+  );
+}
+
 function aggregateEntryToDay(day, entry) {
   const promptTokens = entry.tokens?.prompt_tokens || entry.tokens?.input_tokens || 0;
   const completionTokens = entry.tokens?.completion_tokens || entry.tokens?.output_tokens || 0;
+  const cachedTokens = extractCachedTokens(entry.tokens);
   const cost = entry.cost || 0;
-  const vals = { promptTokens, completionTokens, cost };
+  const vals = { promptTokens, completionTokens, cachedTokens, cost };
 
   day.requests = (day.requests || 0) + 1;
   day.promptTokens = (day.promptTokens || 0) + promptTokens;
   day.completionTokens = (day.completionTokens || 0) + completionTokens;
+  day.cachedTokens = (day.cachedTokens || 0) + cachedTokens;
   day.cost = (day.cost || 0) + cost;
 
   day.byProvider ||= {};
@@ -188,6 +202,10 @@ export function trackPendingRequest(model, provider, connectionId, started, erro
   if (!started && error && provider) {
     lastErrorProvider.provider = provider.toLowerCase();
     lastErrorProvider.ts = Date.now();
+    // Fire-and-forget alert (alerter respects alertEnabled setting + throttling)
+    import("../../alerter.js")
+      .then((m) => m.alertProviderDown(provider, `${provider} request failed`))
+      .catch(() => {});
   }
 
   const t = new Date().toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit", second: "2-digit" });
@@ -260,7 +278,11 @@ export async function saveRequestUsage(entry) {
           entry.timestamp, entry.provider || null, entry.model || null,
           entry.connectionId || null, entry.apiKey || null, entry.endpoint || null,
           promptTokens, completionTokens, entry.cost || 0, entry.status || "ok",
-          stringifyJson(tokens), stringifyJson({}),
+          stringifyJson(tokens), stringifyJson(
+            entry.latency && typeof entry.latency === "object"
+              ? { latency: { ttft: entry.latency.ttft || 0, total: entry.latency.total || 0 } }
+              : {}
+          ),
         ]
       );
 
@@ -366,7 +388,7 @@ export async function getUsageStats(period = "all") {
 
   const stats = {
     totalRequests: 0,
-    totalPromptTokens: 0, totalCompletionTokens: 0, totalCost: 0,
+    totalPromptTokens: 0, totalCompletionTokens: 0, totalCachedTokens: 0, totalCost: 0,
     byProvider: {}, byModel: {}, byAccount: {}, byApiKey: {}, byEndpoint: {},
     last10Minutes: [],
     pending: pendingRequests,
@@ -427,13 +449,15 @@ export async function getUsageStats(period = "all") {
       const day = parseJson(dr.data, {});
       stats.totalPromptTokens += day.promptTokens || 0;
       stats.totalCompletionTokens += day.completionTokens || 0;
+      stats.totalCachedTokens += day.cachedTokens || 0;
       stats.totalCost += day.cost || 0;
 
       for (const [prov, p] of Object.entries(day.byProvider || {})) {
-        if (!stats.byProvider[prov]) stats.byProvider[prov] = { requests: 0, promptTokens: 0, completionTokens: 0, cost: 0 };
+        if (!stats.byProvider[prov]) stats.byProvider[prov] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0 };
         stats.byProvider[prov].requests += p.requests || 0;
         stats.byProvider[prov].promptTokens += p.promptTokens || 0;
         stats.byProvider[prov].completionTokens += p.completionTokens || 0;
+        stats.byProvider[prov].cachedTokens = (stats.byProvider[prov].cachedTokens || 0) + (p.cachedTokens || 0);
         stats.byProvider[prov].cost += p.cost || 0;
       }
 
@@ -547,17 +571,20 @@ export async function getUsageStats(period = "all") {
       const tokens = parseJson(r.tokens, {}) || {};
       const promptTokens = tokens.prompt_tokens || 0;
       const completionTokens = tokens.completion_tokens || 0;
+      const cachedTokens = extractCachedTokens(tokens);
       const entryCost = r.cost || 0;
       const providerDisplayName = providerNodeNameMap[r.provider] || r.provider;
 
       stats.totalPromptTokens += promptTokens;
       stats.totalCompletionTokens += completionTokens;
+      stats.totalCachedTokens += cachedTokens;
       stats.totalCost += entryCost;
 
-      if (!stats.byProvider[r.provider]) stats.byProvider[r.provider] = { requests: 0, promptTokens: 0, completionTokens: 0, cost: 0 };
+      if (!stats.byProvider[r.provider]) stats.byProvider[r.provider] = { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cost: 0 };
       stats.byProvider[r.provider].requests++;
       stats.byProvider[r.provider].promptTokens += promptTokens;
       stats.byProvider[r.provider].completionTokens += completionTokens;
+      stats.byProvider[r.provider].cachedTokens = (stats.byProvider[r.provider].cachedTokens || 0) + cachedTokens;
       stats.byProvider[r.provider].cost += entryCost;
 
       const modelKey = r.provider ? `${r.model} (${r.provider})` : r.model;
@@ -696,6 +723,47 @@ function formatLogDate(date = new Date()) {
 }
 
 // No-op: request log is now derived from usageHistory table on read.
+/**
+ * Get average latency per (provider, connectionId) over a recent window.
+ * Used by lowest-latency combo strategy to prefer the fastest account,
+ * not just the next one in rotation.
+ *
+ * @param {number} windowMs - Look-back window (default 5 minutes)
+ * @param {number} minSamples - Minimum requests required for an account to be ranked
+ * @returns {Promise<Map<string, { avgMs: number, samples: number }>>} key = `${provider}|${connectionId}`
+ */
+export async function getLatencyStats(windowMs = 5 * 60 * 1000, minSamples = 2) {
+  const result = new Map();
+  try {
+    const db = await getAdapter();
+    const cutoff = new Date(Date.now() - windowMs).toISOString();
+    const rows = db.all(
+      `SELECT provider, connectionId, meta FROM usageHistory WHERE timestamp >= ? AND status = 'ok'`,
+      [cutoff]
+    );
+    const acc = new Map(); // key -> { total, count }
+    for (const r of rows) {
+      if (!r.provider || !r.connectionId) continue;
+      const meta = parseJson(r.meta, {});
+      const totalMs = meta?.latency?.total;
+      if (typeof totalMs !== "number" || totalMs <= 0) continue;
+      const key = `${r.provider}|${r.connectionId}`;
+      const cur = acc.get(key) || { total: 0, count: 0 };
+      cur.total += totalMs;
+      cur.count += 1;
+      acc.set(key, cur);
+    }
+    for (const [key, v] of acc.entries()) {
+      if (v.count >= minSamples) {
+        result.set(key, { avgMs: Math.round(v.total / v.count), samples: v.count });
+      }
+    }
+  } catch (e) {
+    console.error("[usageRepo] getLatencyStats failed:", e.message);
+  }
+  return result;
+}
+
 export async function appendRequestLog() {}
 
 export async function getRecentLogs(limit = 200) {

package/src/lib/db/schema.js

@@ -79,6 +79,9 @@ export const TABLES = {
       machineId: "TEXT",
       isActive: "INTEGER DEFAULT 1",
       createdAt: "TEXT NOT NULL",
+      // Per-key spending caps (USD). NULL/0 = unlimited.
+      budgetDaily: "REAL DEFAULT 0",
+      budgetMonthly: "REAL DEFAULT 0",
     },
     indexes: ["CREATE INDEX IF NOT EXISTS idx_ak_key ON apiKeys(key)"],
   },

package/src/lib/localDb.js

@@ -15,6 +15,7 @@ export {
   listContextFiles, getEnabledContextFiles, getContextFile,
   createContextFile, createContextFilesBulk, updateContextFile, deleteContextFile,
   getApiKeys, getApiKeyById, createApiKey, updateApiKey, deleteApiKey, validateApiKey,
+  checkApiKeyBudget,
   getCombos, getComboById, getComboByName,
   createCombo, updateCombo, deleteCombo,
   getModelAliases, setModelAlias, deleteModelAlias,

package/src/lib/responseCache.js

@@ -0,0 +1,159 @@
+/**
+ * Response cache for identical non-streaming chat completions.
+ *
+ * Goal: identical request → serve the previous response without hitting the
+ * provider at all. Saves cost AND latency. This is an exact-match cache
+ * (byte-identical request body), not semantic similarity — semantic caching
+ * needs embeddings infra which is out of scope for a self-hosted router.
+ *
+ * What's cached:
+ *   - Non-streaming (stream: false) successful (2xx) JSON responses
+ *   - Keyed by SHA-256 of (model + canonical request body)
+ *
+ * What's NEVER cached (correctness first):
+ *   - Streaming requests (stream: true) — SSE can't be replayed safely
+ *   - Requests with tools / tool_choice (tool results are time-sensitive)
+ *   - Responses with usage.estimated (we don't trust token counts)
+ *   - Anything with cache-control hints from client (x-zevai-no-cache header)
+ *
+ * Storage: in-memory LRU (configurable max entries + TTL). Restart clears it.
+ * Persistent cache is a future enhancement — in-memory covers the hot path
+ * (repeated identical prompts within a session) without DB bloat.
+ */
+
+import crypto from "crypto";
+
+const DEFAULT_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const DEFAULT_MAX_ENTRIES = 500;
+
+class ResponseCache {
+  constructor() {
+    this.store = new Map(); // key -> { body, status, headers, storedAt, hits }
+    this.maxEntries = DEFAULT_MAX_ENTRIES;
+    this.ttlMs = DEFAULT_TTL_MS;
+    this.stats = { hits: 0, misses: 0, stores: 0, evictions: 0 };
+  }
+
+  configure({ ttlMs, maxEntries } = {}) {
+    if (Number.isFinite(ttlMs) && ttlMs > 0) this.ttlMs = ttlMs;
+    if (Number.isFinite(maxEntries) && maxEntries > 0) this.maxEntries = maxEntries;
+  }
+
+  /**
+   * Build a deterministic cache key from the request.
+   * Canonicalizes JSON (sorted keys) so key order doesn't matter.
+   */
+  buildKey(body) {
+    try {
+      const canonical = JSON.stringify(sortKeysDeep(stripVolatile(body)));
+      return crypto.createHash("sha256").update(canonical).digest("hex");
+    } catch {
+      return null;
+    }
+  }
+
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      this.stats.misses++;
+      return null;
+    }
+    const age = Date.now() - entry.storedAt;
+    if (age > this.ttlMs) {
+      this.store.delete(key);
+      this.stats.misses++;
+      return null;
+    }
+    // Refresh recency (LRU touch)
+    this.store.delete(key);
+    this.store.set(key, entry);
+    entry.hits++;
+    this.stats.hits++;
+    return entry;
+  }
+
+  set(key, value) {
+    if (!key) return;
+    // LRU eviction: delete oldest when at capacity
+    if (this.store.size >= this.maxEntries) {
+      const oldestKey = this.store.keys().next().value;
+      if (oldestKey !== undefined) {
+        this.store.delete(oldestKey);
+        this.stats.evictions++;
+      }
+    }
+    this.store.set(key, { ...value, storedAt: Date.now(), hits: 0 });
+    this.stats.stores++;
+  }
+
+  getStats() {
+    return {
+      ...this.stats,
+      entries: this.store.size,
+      hitRate: this.stats.hits + this.stats.misses > 0
+        ? (this.stats.hits / (this.stats.hits + this.stats.misses)) : 0,
+    };
+  }
+
+  clear() {
+    this.store.clear();
+    this.stats = { hits: 0, misses: 0, stores: 0, evictions: 0 };
+  }
+}
+
+// Deep-sort object keys for canonical serialization
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value && typeof value === "object") {
+    return Object.keys(value).sort().reduce((acc, k) => {
+      acc[k] = sortKeysDeep(value[k]);
+      return acc;
+    }, {});
+  }
+  return value;
+}
+
+// Remove fields that legitimately differ between identical-intent requests
+// but shouldn't bust the cache.
+function stripVolatile(body) {
+  if (!body || typeof body !== "object") return body;
+  const { user, session_id, request_id, ...rest } = body;
+  return rest;
+}
+
+// Singleton
+export const responseCache = new ResponseCache();
+
+/**
+ * Decide whether a request is cacheable at all.
+ * @param {object} body - Parsed request body
+ * @param {object} [headers] - Request headers (Headers instance or plain obj)
+ * @returns {{cacheable: boolean, reason?: string}}
+ */
+export function isCacheableRequest(body, headers) {
+  if (!body || typeof body !== "object") return { cacheable: false, reason: "no-body" };
+  if (body.stream === true) return { cacheable: false, reason: "streaming" };
+  if (Array.isArray(body.tools) && body.tools.length > 0) return { cacheable: false, reason: "tools" };
+  if (body.tool_choice) return { cacheable: false, reason: "tool_choice" };
+
+  // Respect client opt-out header
+  const h = headers && typeof headers.get === "function"
+    ? headers.get("x-zevai-no-cache")
+    : headers?.["x-zevai-no-cache"];
+  if (h) return { cacheable: false, reason: "client-opt-out" };
+
+  return { cacheable: true };
+}
+
+/**
+ * Decide whether a response is safe to store.
+ */
+export function isCacheableResponse(responseBody, status) {
+  if (status !== 200) return false;
+  if (!responseBody || typeof responseBody !== "object") return false;
+  // Don't cache error payloads even at 200
+  if (responseBody.error) return false;
+  // Don't cache estimated usage (token counts unreliable)
+  if (responseBody.usage?.estimated) return false;
+  return true;
+}

package/src/shared/components/UsageStats.js

@@ -122,7 +122,7 @@ function groupDataByKey(data, keyField) {
     if (!groups[gk]) {
       groups[gk] = {
         groupKey: gk,
-        summary: { requests: 0, promptTokens: 0, completionTokens: 0, totalTokens: 0, cost: 0, inputCost: 0, outputCost: 0, lastUsed: null, pending: 0 },
+        summary: { requests: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, totalTokens: 0, cost: 0, inputCost: 0, outputCost: 0, lastUsed: null, pending: 0 },
         items: [],
       };
     }
@@ -130,6 +130,7 @@ function groupDataByKey(data, keyField) {
     s.requests += item.requests || 0;
     s.promptTokens += item.promptTokens || 0;
     s.completionTokens += item.completionTokens || 0;
+    s.cachedTokens += item.cachedTokens || 0;
     s.totalTokens += item.totalTokens || 0;
     s.cost += item.cost || 0;
     s.inputCost += item.inputCost || 0;

package/src/sse/handlers/chat.js

@@ -78,6 +78,16 @@ export async function handleChat(request, clientRawRequest = null) {
       log.warn("AUTH", "Invalid API key (requireApiKey=true)");
       return errorResponse(HTTP_STATUS.UNAUTHORIZED, "Invalid API key");
     }
+
+    // Per-key budget enforcement (only when a key is present & validated)
+    if (apiKey) {
+      const { checkApiKeyBudget } = await import("@/lib/db/index.js");
+      const budget = await checkApiKeyBudget(apiKey);
+      if (!budget.allowed) {
+        log.warn("BUDGET", `Blocked: ${budget.reason}`);
+        return errorResponse(HTTP_STATUS.PAYMENT_REQUIRED, budget.reason || "Budget exceeded");
+      }
+    }
   }
 
   if (!modelStr) {
@@ -85,6 +95,27 @@ export async function handleChat(request, clientRawRequest = null) {
     return errorResponse(HTTP_STATUS.BAD_REQUEST, "Missing model");
   }
 
+  // ── Response cache: serve identical non-streaming requests instantly ──
+  const { responseCache, isCacheableRequest } = await import("@/lib/responseCache.js");
+  const cacheCheck = settings.responseCacheEnabled !== false ? isCacheableRequest(body, request.headers) : { cacheable: false, reason: "disabled" };
+  let cacheKey = null;
+  if (cacheCheck.cacheable) {
+    cacheKey = responseCache.buildKey(body);
+    const cached = cacheKey ? responseCache.get(cacheKey) : null;
+    if (cached) {
+      log.info("CACHE", `HIT ${modelStr} | age=${Math.round((Date.now() - cached.storedAt) / 1000)}s | hits=${cached.hits}`);
+      return new Response(JSON.stringify(cached.body), {
+        status: cached.status,
+        headers: {
+          "Content-Type": "application/json",
+          "X-ZevAI-Cache": "HIT",
+          "X-ZevAI-Cache-Age": String(Math.round((Date.now() - cached.storedAt) / 1000)),
+        },
+      });
+    }
+    log.debug("CACHE", `MISS ${modelStr} (${cacheCheck.reason || "new"})`);
+  }
+
   // Bypass naming/warmup requests before combo rotation to avoid wasting rotation slots
   const userAgent = request?.headers?.get("user-agent") || "";
   const bypassResponse = handleBypassRequest(body, modelStr, userAgent, !!settings.ccFilterNaming);
@@ -100,7 +131,7 @@ export async function handleChat(request, clientRawRequest = null) {
     
     const comboStickyLimit = settings.comboStickyRoundRobinLimit;
     log.info("CHAT", `Combo "${modelStr}" with ${comboModels.length} models (strategy: ${comboStrategy}, sticky: ${comboStickyLimit})`);
-    return handleComboChat({
+    const comboResp = await handleComboChat({
       body,
       models: comboModels,
       handleSingleModel: (b, m) => handleSingleModelChat(b, m, clientRawRequest, request, apiKey),
@@ -109,10 +140,34 @@ export async function handleChat(request, clientRawRequest = null) {
       comboStrategy,
       comboStickyLimit
     });
+    return maybeCacheResponse(comboResp, cacheKey, modelStr);
   }
 
   // Single model request
-  return handleSingleModelChat(body, modelStr, clientRawRequest, request, apiKey);
+  const singleResp = await handleSingleModelChat(body, modelStr, clientRawRequest, request, apiKey);
+  return maybeCacheResponse(singleResp, cacheKey, modelStr);
+}
+
+/**
+ * Store a successful JSON response in the cache (if we have a key and the
+ * response is safe to cache). Returns a fresh Response (body was consumed).
+ */
+async function maybeCacheResponse(response, cacheKey, modelStr) {
+  if (!cacheKey || !response || !response.ok) return response;
+  const contentType = response.headers.get("content-type") || "";
+  if (!contentType.includes("application/json")) return response; // streaming / SSE
+  try {
+    const { responseCache, isCacheableResponse } = await import("@/lib/responseCache.js");
+    const bodyJson = await response.clone().json();
+    if (!isCacheableResponse(bodyJson, response.status)) return response;
+    responseCache.set(cacheKey, {
+      body: bodyJson,
+      status: response.status,
+      model: modelStr,
+    });
+    log.debug("CACHE", `STORE ${modelStr} (key ${cacheKey.slice(0, 8)}…)`);
+  } catch { /* cache failures are non-fatal */ }
+  return response;
 }
 
 /**