@goodandready/dsh-key-rotation 0.8.67 → 0.8.69

package/lib/pool-selection.js

@@ -0,0 +1,149 @@
+// lib/pool-selection.js — pool selection, sticky sessions, attempt sorting and budget metrics (#512).
+// Extracted from lib/pool.js to enforce < 600 line modularity standard.
+
+export const MAX_SESSION_STICKY_ENTRIES = 500;
+
+export function setSessionSticky(pool, sessionId, candidate) {
+  if (!sessionId || !candidate || !pool?.state) return;
+  if (!(pool.state.sessionSticky instanceof Map)) {
+    pool.state.sessionSticky = new Map();
+  }
+  if (pool.state.sessionSticky.has(sessionId)) {
+    pool.state.sessionSticky.delete(sessionId);
+  } else if (pool.state.sessionSticky.size >= MAX_SESSION_STICKY_ENTRIES) {
+    const oldest = pool.state.sessionSticky.keys().next().value;
+    if (oldest !== undefined) pool.state.sessionSticky.delete(oldest);
+  }
+  pool.state.sessionSticky.set(sessionId, candidate);
+}
+
+export function getSessionSticky(pool, sessionId) {
+  if (!sessionId || !pool?.state?.sessionSticky) return null;
+  return pool.state.sessionSticky.get(sessionId) ?? null;
+}
+
+export function clearSessionSticky(pool, sessionId) {
+  if (!sessionId || !pool?.state?.sessionSticky) return;
+  pool.state.sessionSticky.delete(sessionId);
+}
+
+/** Pick a key pool for a (provider, model) pair. */
+export function selectPool(modelPoolByProvider, providerToPool, provider, model) {
+  const byModel = modelPoolByProvider && modelPoolByProvider.get(provider);
+  const base = providerToPool && providerToPool.get(provider);
+  if (!byModel || !model) return base ?? null;
+  if (byModel.has(model)) return byModel.get(model);
+  let best = null;
+  for (const key of byModel.keys()) {
+    if (model.startsWith(key) && key.length > (best ? best.length : 0)) best = key;
+  }
+  return (best ? byModel.get(best) : base) ?? null;
+}
+
+/**
+ * Sort candidate refs according to pool routing strategy.
+ * Returns a new array; does not mutate input.
+ */
+export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
+  if (!Array.isArray(refs) || refs.length <= 1) return (refs ?? []).slice();
+  const list = refs.slice();
+  if (strategy === 'sticky') {
+    const last = deps.sessionSticky ||
+      (deps.sessionId && (deps.pool?.state?.sessionSticky?.get?.(deps.sessionId) || deps.sessionStickyMap?.get?.(deps.sessionId))) ||
+      deps.lastUsed ||
+      (deps.pool && deps.pool.state && deps.pool.state.lastUsed);
+    if (last && list.includes(last)) {
+      const idx = list.indexOf(last);
+      if (idx > 0) {
+        list.splice(idx, 1);
+        list.unshift(last);
+      }
+    }
+    return list;
+  }
+  if (strategy === 'tier-priority') {
+    const tiers = deps.tiers || (deps.pool && deps.pool.tiers) || {};
+    return list.sort((a, b) => {
+      const ta = (tiers[a] && Number(tiers[a]) >= 1) ? Number(tiers[a]) : 1;
+      const tb = (tiers[b] && Number(tiers[b]) >= 1) ? Number(tiers[b]) : 1;
+      return ta - tb;
+    });
+  }
+  if (strategy === 'least-loaded' && deps.concurrencyTracker && typeof deps.concurrencyTracker.getActive === 'function') {
+    const weights = deps.weights || (deps.pool && deps.pool.weightsMap) || {};
+    return list.sort((a, b) => {
+      const ca = deps.concurrencyTracker.getActive(a) ?? 0;
+      const cb = deps.concurrencyTracker.getActive(b) ?? 0;
+      const wa = (weights[a] && Number(weights[a]) > 0) ? Number(weights[a]) : 1;
+      const wb = (weights[b] && Number(weights[b]) > 0) ? Number(weights[b]) : 1;
+      const scoreA = ca / wa;
+      const scoreB = cb / wb;
+      if (scoreA !== scoreB) return scoreA - scoreB;
+      return ca - cb;
+    });
+  }
+  if (strategy === 'lowest-latency' && deps.latencyHistogram && typeof deps.latencyHistogram.snapshot === 'function') {
+    return list.sort((a, b) => {
+      const sa = deps.latencyHistogram.snapshot(a);
+      const sb = deps.latencyHistogram.snapshot(b);
+      const la = (sa && Number.isFinite(sa.p95)) ? sa.p95 : ((sa && Number.isFinite(sa.avg)) ? sa.avg : 500);
+      const lb = (sb && Number.isFinite(sb.p95)) ? sb.p95 : ((sb && Number.isFinite(sb.avg)) ? sb.avg : 500);
+      return la - lb;
+    });
+  }
+  return list;
+}
+
+/**
+ * Keys of pool whose expiresAt falls within the next warnDays.
+ * Returns [{ ref, expiresInDays, expiresAt }], soonest first.
+ */
+export function expiringSoon(pool, warnDays = 7, now = Date.now()) {
+  if (!pool || !pool.expiresAt) return [];
+  const DAY_MS = 86400000;
+  const horizon = now + Math.max(1, warnDays) * DAY_MS;
+  return Object.entries(pool.expiresAt)
+    .filter(([, at]) => at > now && at <= horizon)
+    .map(([ref, at]) => ({ ref, expiresAt: at, expiresInDays: Math.max(0, Math.floor((at - now) / DAY_MS)) }))
+    .sort((a, b) => a.expiresAt - b.expiresAt);
+}
+
+/** Dedupe: true when a day-level notification for key is due. */
+export function shouldNotifyDaily(lastNotified, key, now = Date.now()) {
+  const DAY_MS = 86400000;
+  if (!lastNotified.has(key)) {
+    lastNotified.set(key, now);
+    return true;
+  }
+  const last = lastNotified.get(key);
+  if (now - last < DAY_MS) return false;
+  lastNotified.set(key, now);
+  return true;
+}
+
+/** Total spend of a pool on ISO day day (defaults to today) across costDays Map<ref, Map<day, cost>>. */
+export function costForDay(costDays, day) {
+  const d = day ?? new Date().toISOString().slice(0, 10);
+  let total = 0;
+  for (const perRef of (costDays?.values() ?? [])) {
+    total += perRef.get(d) ?? 0;
+  }
+  return total;
+}
+
+/** Total spend over the last 7 ISO days ending today. */
+export function costForWeek(costDays, now = Date.now()) {
+  let total = 0;
+  for (let i = 0; i < 7; i++) {
+    const d = new Date(now - i * 86400000).toISOString().slice(0, 10);
+    total += costForDay(costDays, d);
+  }
+  return total;
+}
+
+/** Budget verdict for a pool: { spend, budget, ratio, warn, exceeded }. */
+export function budgetVerdict(spend, budget) {
+  if (!budget || budget <= 0) return { spend, budget: 0, ratio: 0, warn: false, exceeded: false };
+  const ratio = spend / budget;
+  return { spend, budget, ratio, warn: ratio >= 0.8, exceeded: ratio >= 1 };
+}

package/lib/pool.js

@@ -1,28 +1,15 @@
-export const MAX_SESSION_STICKY_ENTRIES = 500;
-
-export function setSessionSticky(pool, sessionId, candidate) {
-  if (!sessionId || !candidate || !pool?.state) return;
-  if (!(pool.state.sessionSticky instanceof Map)) {
-    pool.state.sessionSticky = new Map();
-  }
-  if (pool.state.sessionSticky.has(sessionId)) {
-    pool.state.sessionSticky.delete(sessionId);
-  } else if (pool.state.sessionSticky.size >= MAX_SESSION_STICKY_ENTRIES) {
-    const oldest = pool.state.sessionSticky.keys().next().value;
-    if (oldest !== undefined) pool.state.sessionSticky.delete(oldest);
-  }
-  pool.state.sessionSticky.set(sessionId, candidate);
-}
-
-export function getSessionSticky(pool, sessionId) {
-  if (!sessionId || !pool?.state?.sessionSticky) return null;
-  return pool.state.sessionSticky.get(sessionId) ?? null;
-}
-
-export function clearSessionSticky(pool, sessionId) {
-  if (!sessionId || !pool?.state?.sessionSticky) return;
-  pool.state.sessionSticky.delete(sessionId);
-}
+// lib/pool.js — pure pool arithmetic and selection logic for dsh-key-rotation.
+import {
+  MAX_SESSION_STICKY_ENTRIES, setSessionSticky, getSessionSticky, clearSessionSticky,
+  selectPool, sortAttemptList, expiringSoon, shouldNotifyDaily,
+  costForDay, costForWeek, budgetVerdict,
+} from './pool-selection.js';
+
+export {
+  MAX_SESSION_STICKY_ENTRIES, setSessionSticky, getSessionSticky, clearSessionSticky,
+  selectPool, sortAttemptList, expiringSoon, shouldNotifyDaily,
+  costForDay, costForWeek, budgetVerdict,
+};
 
 import { resetModelQuotaIfNeeded } from './model-quota.js';
 import { decryptSecret } from './crypto-storage.js';
@@ -288,19 +275,6 @@ export function parseRetryAfter(value) {
 }
 
 /** Pick a key pool for a (provider, model) pair. */
-export function selectPool(modelPoolByProvider, providerToPool, provider, model) {
-  const byModel = modelPoolByProvider && modelPoolByProvider.get(provider);
-  const base = providerToPool && providerToPool.get(provider);
-  if (!byModel || !model) return base ?? null;
-  if (byModel.has(model)) return byModel.get(model);
-  let best = null;
-  for (const key of byModel.keys()) {
-    if (model.startsWith(key) && key.length > (best ? best.length : 0)) best = key;
-  }
-  return (best ? byModel.get(best) : base) ?? null;
-}
-
-/** Parse an expiry value (timestamp ms or ISO date string) to epoch ms. */
 export function parseExpiry(v) {
   if (typeof v === 'number' && v > 0) return v;
   if (typeof v === 'string' && v.length > 0) { const ts = Date.parse(v); return Number.isNaN(ts) ? undefined : ts; }
@@ -434,61 +408,6 @@ export function isRateLimited(rate, threshold = 0.1) {
  * - 'least-loaded': keys with lowest active concurrency count first
  * - 'lowest-latency': keys with lowest p95 (or avg) latency first; unsampled keys neutral
  */
-export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
-  if (!Array.isArray(refs) || refs.length <= 1) return (refs ?? []).slice();
-  const list = refs.slice();
-  if (strategy === 'sticky') {
-    const last = deps.sessionSticky ||
-      (deps.sessionId && (deps.pool?.state?.sessionSticky?.get?.(deps.sessionId) || deps.sessionStickyMap?.get?.(deps.sessionId))) ||
-      deps.lastUsed ||
-      (deps.pool && deps.pool.state && deps.pool.state.lastUsed);
-    if (last && list.includes(last)) {
-      const idx = list.indexOf(last);
-      if (idx > 0) {
-        list.splice(idx, 1);
-        list.unshift(last);
-      }
-    }
-    return list;
-  }
-  if (strategy === 'tier-priority') {
-    const tiers = deps.tiers || (deps.pool && deps.pool.tiers) || {};
-    return list.sort((a, b) => {
-      const ta = (tiers[a] && Number(tiers[a]) >= 1) ? Number(tiers[a]) : 1;
-      const tb = (tiers[b] && Number(tiers[b]) >= 1) ? Number(tiers[b]) : 1;
-      return ta - tb;
-    });
-  }
-  if (strategy === 'least-loaded' && deps.concurrencyTracker && typeof deps.concurrencyTracker.getActive === 'function') {
-    const weights = deps.weights || (deps.pool && deps.pool.weightsMap) || {};
-    return list.sort((a, b) => {
-      const ca = deps.concurrencyTracker.getActive(a) ?? 0;
-      const cb = deps.concurrencyTracker.getActive(b) ?? 0;
-      const wa = (weights[a] && Number(weights[a]) > 0) ? Number(weights[a]) : 1;
-      const wb = (weights[b] && Number(weights[b]) > 0) ? Number(weights[b]) : 1;
-      const scoreA = ca / wa;
-      const scoreB = cb / wb;
-      if (scoreA !== scoreB) return scoreA - scoreB;
-      return ca - cb;
-    });
-  }
-  if (strategy === 'lowest-latency' && deps.latencyHistogram && typeof deps.latencyHistogram.snapshot === 'function') {
-    return list.sort((a, b) => {
-      const sa = deps.latencyHistogram.snapshot(a);
-      const sb = deps.latencyHistogram.snapshot(b);
-      const la = (sa && Number.isFinite(sa.p95)) ? sa.p95 : ((sa && Number.isFinite(sa.avg)) ? sa.avg : 500);
-      const lb = (sb && Number.isFinite(sb.p95)) ? sb.p95 : ((sb && Number.isFinite(sb.avg)) ? sb.avg : 500);
-      return la - lb;
-    });
-  }
-  return list;
-}
-
-/**
- * Unified check whether an error or payload represents a switchable failure.
- * Prioritizes explicit HTTP status codes and gRPC codes before text matching.
- */
-/** Raw socket-level codes the taxonomy maps to TRANSPORT (see classifyFailure). */
 const SOCKET_TRANSPORT_CODES = new Set([
   'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE', 'EAI_AGAIN', 'ENOTFOUND',
   'ECONNABORTED', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET', 'UND_ERR_HEADERS_TIMEOUT',
@@ -565,58 +484,6 @@ export function formatExhaustionMessage(provider, pool, now = Date.now()) {
  * Keys of pool whose expiresAt falls within the next warnDays.
  * Returns [{ ref, expiresInDays, expiresAt }], soonest first.
  */
-export function expiringSoon(pool, warnDays = 7, now = Date.now()) {
-  if (!pool || !pool.expiresAt) return [];
-  const DAY_MS = 86400000;
-  const horizon = now + Math.max(1, warnDays) * DAY_MS;
-  return Object.entries(pool.expiresAt)
-    .filter(([, at]) => at > now && at <= horizon)
-    .map(([ref, at]) => ({ ref, expiresAt: at, expiresInDays: Math.max(0, Math.floor((at - now) / DAY_MS)) }))
-    .sort((a, b) => a.expiresAt - b.expiresAt);
-}
-
-/** Dedupe: true when a day-level notification for key is due. */
-export function shouldNotifyDaily(lastNotified, key, now = Date.now()) {
-  const DAY_MS = 86400000;
-  if (!lastNotified.has(key)) {
-    lastNotified.set(key, now);
-    return true;
-  }
-  const last = lastNotified.get(key);
-  if (now - last < DAY_MS) return false;
-  lastNotified.set(key, now);
-  return true;
-}
-
-/** Total spend of a pool on ISO day day (defaults to today) across costDays Map<ref, Map<day, cost>>. */
-export function costForDay(costDays, day) {
-  const d = day ?? new Date().toISOString().slice(0, 10);
-  let total = 0;
-  for (const perRef of (costDays?.values() ?? [])) {
-    total += perRef.get(d) ?? 0;
-  }
-  return total;
-}
-
-/** Total spend over the last 7 ISO days ending today. */
-export function costForWeek(costDays, now = Date.now()) {
-  let total = 0;
-  for (let i = 0; i < 7; i++) {
-    const d = new Date(now - i * 86400000).toISOString().slice(0, 10);
-    total += costForDay(costDays, d);
-  }
-  return total;
-}
-
-/** Budget verdict for a pool: { spend, budget, ratio, warn, exceeded }. */
-export function budgetVerdict(spend, budget) {
-  if (!budget || budget <= 0) return { spend, budget: 0, ratio: 0, warn: false, exceeded: false };
-  const ratio = spend / budget;
-  return { spend, budget, ratio, warn: ratio >= 0.8, exceeded: ratio >= 1 };
-}
-
-
-/** Safely reset a provider's circuit breaker to closed state. */
 export function resetCircuitForProvider(circuitBreaker, provider) {
   if (!circuitBreaker || !provider) return false;
   const ok = bestEffort('resetCircuitForProvider', () => {

package/lib/prompt-cache.js

@@ -0,0 +1,252 @@
+// lib/prompt-cache.js — prompt caching token tracking, economics calculator, and summary (#497).
+// Pure helpers with zero dependencies.
+
+const DAY_MS = 86400000;
+
+/**
+ * Extracts prompt cache token counters from streaming/non-streaming usage payloads.
+ * Supports DeepSeek, Anthropic, and OpenAI formats.
+ * @param {object} usage
+ * @returns {{ cachedTokens: number, uncachedTokens: number, totalInputTokens: number } | null}
+ */
+export function extractPromptCacheTokens(usage) {
+  if (!usage || typeof usage !== 'object') return null;
+
+  let cachedTokens = 0;
+  let uncachedTokens = 0;
+  let detected = false;
+
+  // 1. DeepSeek format: prompt_cache_hit_tokens, prompt_cache_miss_tokens
+  if (usage.prompt_cache_hit_tokens != null) {
+    cachedTokens = Math.max(0, Number(usage.prompt_cache_hit_tokens) || 0);
+    uncachedTokens = Math.max(0, Number(usage.prompt_cache_miss_tokens) || 0);
+    detected = true;
+  }
+
+  // 2. Anthropic format: cache_read_input_tokens, cache_creation_input_tokens
+  if (usage.cache_read_input_tokens != null) {
+    cachedTokens = Math.max(0, Number(usage.cache_read_input_tokens) || 0);
+    const creation = Math.max(0, Number(usage.cache_creation_input_tokens) || 0);
+    const rawInput = Math.max(0, Number(usage.input_tokens) || 0);
+    uncachedTokens = creation > 0 ? creation : Math.max(0, rawInput - cachedTokens);
+    detected = true;
+  }
+
+  // 3. OpenAI format: prompt_tokens_details.cached_tokens
+  if (usage.prompt_tokens_details?.cached_tokens != null) {
+    cachedTokens = Math.max(0, Number(usage.prompt_tokens_details.cached_tokens) || 0);
+    const totalP = Math.max(0, Number(usage.prompt_tokens) || 0);
+    uncachedTokens = Math.max(0, totalP - cachedTokens);
+    detected = true;
+  }
+
+  const explicitTotal = Number(usage.prompt_tokens ?? usage.input_tokens);
+  const totalInputTokens = Number.isFinite(explicitTotal) && explicitTotal > 0
+    ? Math.max(cachedTokens, explicitTotal)
+    : (cachedTokens + uncachedTokens);
+
+  if (!detected && cachedTokens === 0 && totalInputTokens === 0) {
+    return null;
+  }
+
+  return {
+    cachedTokens,
+    uncachedTokens,
+    totalInputTokens,
+  };
+}
+
+/**
+ * Calculates financial savings in USD based on cached token count and model rates.
+ * Standard input cost minus discounted cache read cost (typically 90% savings).
+ */
+export function calculateCacheSavings(provider = '', model = '', cachedTokens = 0) {
+  if (!Number.isFinite(cachedTokens) || cachedTokens <= 0) return 0;
+
+  const key = `${provider}/${model}`.toLowerCase();
+  let savingsPerToken = 0.0000009; // Default: $0.90 per 1M tokens saved (90% off $1.00/M)
+
+  if (key.includes('deepseek')) {
+    // DeepSeek: standard $0.14/M, cache hit $0.014/M -> saves $0.126/M ($0.000000126/token)
+    savingsPerToken = 0.000000126;
+  } else if (key.includes('claude') || key.includes('anthropic')) {
+    // Anthropic: Sonnet base $3.00/M, cache read $0.30/M -> saves $2.70/M ($0.0000027/token)
+    savingsPerToken = 0.0000027;
+  } else if (key.includes('gpt-4') || key.includes('openai')) {
+    // OpenAI: GPT-4o base $2.50/M, cache read $1.25/M -> saves $1.25/M ($0.00000125/token)
+    savingsPerToken = 0.00000125;
+  }
+
+  const saved = cachedTokens * savingsPerToken;
+  return Math.round(saved * 1000000) / 1000000;
+}
+
+function formatSavings(val) {
+  if (!Number.isFinite(val) || val <= 0) return 0;
+  return val < 0.01 ? Math.round(val * 10000) / 10000 : Math.round(val * 100) / 100;
+}
+
+/**
+ * Records prompt cache usage in pool state.
+ */
+export function recordPromptCache(pool, ref, model, usage, now = Date.now()) {
+  if (!pool?.state) return null;
+  const parsed = extractPromptCacheTokens(usage);
+  if (!parsed || (parsed.cachedTokens === 0 && parsed.totalInputTokens === 0)) return null;
+
+  const savings = calculateCacheSavings(pool.provider ?? pool.base, model, parsed.cachedTokens);
+
+  if (!pool.state.promptCache) {
+    pool.state.promptCache = {
+      cachedTokens: 0,
+      totalInputTokens: 0,
+      savingsUsd: 0,
+      days: new Map(),
+      byRef: new Map(),
+      byModel: new Map(),
+    };
+  }
+
+  const pc = pool.state.promptCache;
+  pc.cachedTokens += parsed.cachedTokens;
+  pc.totalInputTokens += parsed.totalInputTokens;
+  pc.savingsUsd = Math.round((pc.savingsUsd + savings) * 1000000) / 1000000;
+
+  const todayIso = new Date(now).toISOString().slice(0, 10);
+  const dayEntry = pc.days.get(todayIso) || { cachedTokens: 0, totalInputTokens: 0, savingsUsd: 0 };
+  dayEntry.cachedTokens += parsed.cachedTokens;
+  dayEntry.totalInputTokens += parsed.totalInputTokens;
+  dayEntry.savingsUsd = Math.round((dayEntry.savingsUsd + savings) * 1000000) / 1000000;
+  pc.days.set(todayIso, dayEntry);
+
+  if (ref) {
+    const refEntry = pc.byRef.get(ref) || { cachedTokens: 0, totalInputTokens: 0, savingsUsd: 0 };
+    refEntry.cachedTokens += parsed.cachedTokens;
+    refEntry.totalInputTokens += parsed.totalInputTokens;
+    refEntry.savingsUsd = Math.round((refEntry.savingsUsd + savings) * 1000000) / 1000000;
+    pc.byRef.set(ref, refEntry);
+  }
+
+  const mKey = model || 'default';
+  const mEntry = pc.byModel.get(mKey) || { cachedTokens: 0, totalInputTokens: 0, savingsUsd: 0 };
+  mEntry.cachedTokens += parsed.cachedTokens;
+  mEntry.totalInputTokens += parsed.totalInputTokens;
+  mEntry.savingsUsd = Math.round((mEntry.savingsUsd + savings) * 1000000) / 1000000;
+  pc.byModel.set(mKey, mEntry);
+
+  return parsed;
+}
+
+function sumWindow(daysMap, dayKeys) {
+  let cachedTokens = 0;
+  let totalInputTokens = 0;
+  let savingsUsd = 0;
+
+  for (const d of dayKeys) {
+    const entry = daysMap?.get(d);
+    if (entry) {
+      cachedTokens += entry.cachedTokens ?? 0;
+      totalInputTokens += entry.totalInputTokens ?? 0;
+      savingsUsd += entry.savingsUsd ?? 0;
+    }
+  }
+
+  const hitRatioPct = totalInputTokens > 0
+    ? Math.round((cachedTokens / totalInputTokens) * 1000) / 10
+    : 0;
+
+  return {
+    cachedTokens,
+    totalInputTokens,
+    hitRatioPct,
+    savingsUsd: formatSavings(savingsUsd),
+  };
+}
+
+/**
+ * Returns structured summary of prompt cache metrics for 24h, 7d, 30d, plus models and keys.
+ */
+export function getPromptCacheSummary(pool, now = Date.now()) {
+  const pc = pool?.state?.promptCache;
+  if (!pc) {
+    return {
+      allTime: { cachedTokens: 0, totalInputTokens: 0, hitRatioPct: 0, savingsUsd: 0 },
+      d1: { cachedTokens: 0, totalInputTokens: 0, hitRatioPct: 0, savingsUsd: 0 },
+      d7: { cachedTokens: 0, totalInputTokens: 0, hitRatioPct: 0, savingsUsd: 0 },
+      d30: { cachedTokens: 0, totalInputTokens: 0, hitRatioPct: 0, savingsUsd: 0 },
+      byModel: {},
+      byRef: {},
+    };
+  }
+
+  const makeDayKeys = (count) => {
+    const keys = [];
+    for (let i = 0; i < count; i++) {
+      keys.push(new Date(now - i * DAY_MS).toISOString().slice(0, 10));
+    }
+    return keys;
+  };
+
+  const d1 = sumWindow(pc.days, makeDayKeys(1));
+  const d7 = sumWindow(pc.days, makeDayKeys(7));
+  const d30 = sumWindow(pc.days, makeDayKeys(30));
+
+  const allHitRatio = pc.totalInputTokens > 0
+    ? Math.round((pc.cachedTokens / pc.totalInputTokens) * 1000) / 10
+    : 0;
+
+  const byModel = {};
+  if (pc.byModel) {
+    for (const [m, e] of pc.byModel.entries()) {
+      byModel[m] = {
+        cachedTokens: e.cachedTokens,
+        totalInputTokens: e.totalInputTokens,
+        hitRatioPct: e.totalInputTokens > 0 ? Math.round((e.cachedTokens / e.totalInputTokens) * 1000) / 10 : 0,
+        savingsUsd: formatSavings(e.savingsUsd),
+      };
+    }
+  }
+
+  const byRef = {};
+  if (pc.byRef) {
+    for (const [r, e] of pc.byRef.entries()) {
+      byRef[r] = {
+        cachedTokens: e.cachedTokens,
+        totalInputTokens: e.totalInputTokens,
+        hitRatioPct: e.totalInputTokens > 0 ? Math.round((e.cachedTokens / e.totalInputTokens) * 1000) / 10 : 0,
+        savingsUsd: formatSavings(e.savingsUsd),
+      };
+    }
+  }
+
+  return {
+    allTime: {
+      cachedTokens: pc.cachedTokens,
+      totalInputTokens: pc.totalInputTokens,
+      hitRatioPct: allHitRatio,
+      savingsUsd: formatSavings(pc.savingsUsd),
+    },
+    d1,
+    d7,
+    d30,
+    byModel,
+    byRef,
+  };
+}
+
+/**
+ * Compact prompt cache history older than maxDays (default 30).
+ */
+export function compactPromptCache(pool, maxDays = 30, now = Date.now()) {
+  const days = pool?.state?.promptCache?.days;
+  if (!days) return 0;
+  const cutoffIso = new Date(now - maxDays * DAY_MS).toISOString().slice(0, 10);
+  let purged = 0;
+  for (const d of [...days.keys()]) {
+    if (d < cutoffIso) {
+      days.delete(d);
+      purged++;
+    }
+  }
+  return purged;
+}