@goodandready/dsh-key-rotation 0.8.67 → 0.8.68

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.8.68 - 2026-10-19
+
+### Features
+- **24h Error Breakdown & Load Distribution Analytics (#505)**:
+  - Rolling 24-hour analytics engine (`lib/ops-analytics.js`): tracks sliding 24-hour request outcomes, key load distribution percentages, failovers, and cascade occurrences without memory leaks via bounded ring buffers.
+  - Multi-category failure classification: categorizes upstream errors into `429 Rate Limit`, `5xx Server`, `Timeout`, `Quota`, `Auth`, and `Other`.
+  - Health Index indicator: calculates the percentage of requests served clean on first attempt without failovers or retries (`cleanRequests / totalRequests * 100%`).
+  - Cooldown recovery telemetry: computes the average recovery time (`avgCooldownRecoveryMs`) from recent failure and recovery events.
+  - Settings Card UI: renders interactive Health Index badges (`🛡️ Health Index: 98% (clean)`), 24h error breakdown pills (`429: 2`, `5xx: 1`, `Timeout: 0`), cascade counters (`🔀 Cascades: X`), and average recovery time pills.
+- **Prompt Cache Savings Dashboard & Calculator (#497)**:
+  - Multi-provider prompt cache parser (`lib/prompt-cache.js`): extracts prefix cache hit and miss tokens across streaming and non-streaming responses from DeepSeek (`prompt_cache_hit_tokens`), Anthropic (`cache_read_input_tokens`), and OpenAI (`prompt_tokens_details.cached_tokens`).
+  - Financial savings engine: computes real-time USD cost savings based on provider-specific token discount tariffs (~90% discount on cache hits).
+  - Multi-window rolling aggregation: aggregates cached tokens, total input tokens, hit ratio (%), and dollar savings across 24h (`d1`), 7d (`d7`), and 30d (`d30`) sliding windows, plus per-model and per-key breakdowns.
+  - Settings Card Widget: compact «⚡ Prompt Cache Savings» card displaying 24h, 7d, and 30d cache hit tokens, effective cache hit ratio (%), and cumulative dollar savings.
+  - Telemetry & reporting: exposes prompt cache summaries and 24h analytics in `/dsh-key-rotation/status` and `/dsh-key-rotation/usage`.
+
 ## 0.8.67 - 2026-10-19
 
 ### Features

package/lib/client.js

@@ -283,6 +283,15 @@ window.__ModuleLoader__.load({
       passphrasePlaceholder: 'Enter master passphrase for encryption/decryption',
       jsonConfigPlaceholder: 'Paste JSON configuration here or choose a file...',
       previewSummary: 'Diff: {created} new providers, {updated} updated providers, {keys} keys ({added} new).',
+      promptCacheTitle: 'Prompt Cache Savings',
+      promptCacheDesc: 'Tokens served from prefix cache across sessions and estimated cost savings.',
+      promptCacheHitRatio: 'Hit Ratio',
+      promptCacheSaved: 'saved',
+      analytics24hTitle: '24h Pool Health & Load Balance',
+      healthIndex: 'Health Index',
+      cleanRequests: 'clean',
+      errorBreakdown: '24h Errors',
+      avgRecovery: 'Avg Recovery',
     };
 
     const zh = {
@@ -516,6 +525,15 @@ window.__ModuleLoader__.load({
       passphrasePlaceholder: '输入用于加密/解密的主密码',
       jsonConfigPlaceholder: '在此粘贴 JSON 配置或选择文件...',
       previewSummary: '差异: 新增 {created} 个提供商, 更新 {updated} 个提供商, 包含 {keys} 个密钥 (新增 {added} 个)。',
+      promptCacheTitle: 'Prompt 缓存节省',
+      promptCacheDesc: '会话间前缀缓存命中 Token 及预估节省成本。',
+      promptCacheHitRatio: '缓存命中率',
+      promptCacheSaved: '已节省',
+      analytics24hTitle: '24小时池健康度与负载分布',
+      healthIndex: '健康指数',
+      cleanRequests: '无重试',
+      errorBreakdown: '24小时错误',
+      avgRecovery: '平均恢复',
     };
 
     // Codes worth switching on. Host list is DEFAULT_SWITCH_CODES; config may
@@ -2482,7 +2500,55 @@ window.__ModuleLoader__.load({
             total > 0 && keyUsages.length > 1 ? h('div', { style: { marginTop: '8px', display: 'flex', alignItems: 'center', gap: '8px' } },
               h('span', { style: { fontSize: '11px', color: 'var(--dsw-alias-label-secondary)' } }, '📈 ' + t('sparklineTraffic') + ':'),
               h(Sparkline, { points: keyUsages.map(x => x.usage), width: 140, height: 20 })
-            ) : null
+            ) : null,
+            (() => {
+              const an = ps && ps.analytics24h ? ps.analytics24h : null;
+              if (!an || an.totalRequests === 0) return null;
+              const hColor = an.healthIndexPct >= 80 ? 'var(--dsw-alias-state-success-primary)' : an.healthIndexPct >= 50 ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-error-primary)';
+              return h('div', { style: { marginTop: '8px', display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: '6px' } },
+                h('span', { className: 'krot-badge', style: { color: hColor, fontWeight: 700 } }, '🛡️ ' + t('healthIndex') + ': ' + an.healthIndexPct + '% (' + an.firstAttemptSuccesses + '/' + an.totalRequests + ' ' + t('cleanRequests') + ')'),
+                an.errorBreakdown.rateLimit > 0 ? h('span', { className: 'krot-badge krot-badge-warn' }, '429: ' + an.errorBreakdown.rateLimit) : null,
+                an.errorBreakdown.server > 0 ? h('span', { className: 'krot-badge krot-badge-warn' }, '5xx: ' + an.errorBreakdown.server) : null,
+                an.errorBreakdown.timeout > 0 ? h('span', { className: 'krot-badge krot-badge-warn' }, 'Timeout: ' + an.errorBreakdown.timeout) : null,
+                an.errorBreakdown.quota > 0 ? h('span', { className: 'krot-badge krot-badge-warn' }, 'Quota: ' + an.errorBreakdown.quota) : null,
+                an.cascades > 0 ? h('span', { className: 'krot-badge' }, '🔀 Cascades: ' + an.cascades) : null,
+                an.avgCooldownRecoveryMs > 0 ? h('span', { className: 'krot-badge' }, '⏱️ ' + t('avgRecovery') + ': ' + Math.round(an.avgCooldownRecoveryMs / 1000) + 's') : null
+              );
+            })()
+          );
+        })();
+
+        const promptCacheWidget = (() => {
+          const ps = status[entry.provider];
+          const pc = ps && ps.promptCache ? ps.promptCache : null;
+          if (!pc || (!pc.d30?.cachedTokens && !pc.allTime?.cachedTokens)) return null;
+          const d1 = pc.d1 || { cachedTokens: 0, savingsUsd: 0, hitRatioPct: 0 };
+          const d7 = pc.d7 || { cachedTokens: 0, savingsUsd: 0, hitRatioPct: 0 };
+          const d30 = pc.d30 || { cachedTokens: 0, savingsUsd: 0, hitRatioPct: 0 };
+          const savedStr = d30.savingsUsd > 0 ? '$' + d30.savingsUsd.toFixed(2) : '$0.00';
+          return h('div', {
+            className: 'krot-prompt-cache-card',
+            style: {
+              marginTop: '6px',
+              marginBottom: '6px',
+              padding: '8px 10px',
+              background: 'var(--dsw-alias-bg-layer-2)',
+              borderRadius: '6px',
+              border: '1px solid var(--dsw-alias-border-subtle)',
+              display: 'flex',
+              flexDirection: 'column',
+              gap: '4px'
+            }
+          },
+            h('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' } },
+              h('span', { style: { fontWeight: 600, fontSize: '12px' } }, '⚡ ' + t('promptCacheTitle')),
+              h('span', { className: 'krot-badge krot-badge-ok', style: { fontSize: '11px', fontWeight: 600 } }, savedStr + ' ' + t('promptCacheSaved'))
+            ),
+            h('div', { style: { display: 'flex', flexWrap: 'wrap', gap: '10px', fontSize: '11px', color: 'var(--dsw-alias-label-secondary)' } },
+              h('span', null, h('strong', { style: { color: 'var(--dsw-alias-label-primary)' } }, '24h: '), (d1.cachedTokens || 0).toLocaleString() + ' tok (' + d1.hitRatioPct + '%)'),
+              h('span', null, h('strong', { style: { color: 'var(--dsw-alias-label-primary)' } }, '7d: '), (d7.cachedTokens || 0).toLocaleString() + ' tok (' + d7.hitRatioPct + '%)'),
+              h('span', null, h('strong', { style: { color: 'var(--dsw-alias-label-primary)' } }, '30d: '), (d30.cachedTokens || 0).toLocaleString() + ' tok (' + d30.hitRatioPct + '%)')
+            )
           );
         })();
 
@@ -2646,6 +2712,7 @@ window.__ModuleLoader__.load({
           ),
           filterBar,
           loadChart,
+          promptCacheWidget,
           h('div', { className: 'krot-keys' }, keyRows),
           modelPools,
       h('div', { className: 'krot-foot' },

package/lib/ops-analytics.js

@@ -0,0 +1,162 @@
+// lib/ops-analytics.js — 24h error breakdown, load distribution, and health index analytics (#505).
+// Pure helpers with zero dependencies.
+
+const DAY_MS = 86400000;
+const MAX_RING_BUFFER = 200;
+
+/**
+ * Classifies an error code or message into canonical categories:
+ * 'rateLimit' | 'server' | 'timeout' | 'quota' | 'auth' | 'other'
+ */
+export function classifyErrorCategory(code, message = '') {
+  const c = String(code ?? '').toUpperCase();
+  const m = String(message ?? '').toLowerCase();
+
+  if (c === '429' || c.includes('RATE_LIMIT') || m.includes('rate limit') || m.includes('too many requests')) {
+    return 'rateLimit';
+  }
+  if (/^5\d\d$/.test(c) || c === 'SERVER' || c === 'BAD_GATEWAY' || c === 'SERVICE_UNAVAILABLE' || m.includes('internal server error')) {
+    return 'server';
+  }
+  if (c.includes('TIMEOUT') || c === 'ETIMEDOUT' || c === 'ESOCKETTIMEDOUT' || m.includes('timeout') || m.includes('timed out')) {
+    return 'timeout';
+  }
+  if (c === 'QUOTA' || c === '402' || c.includes('QUOTA') || m.includes('quota') || m.includes('credit') || m.includes('insufficient_quota')) {
+    return 'quota';
+  }
+  if (c === 'AUTH' || c === '401' || c === '403' || m.includes('unauthorized') || m.includes('invalid_api_key') || m.includes('forbidden')) {
+    return 'auth';
+  }
+  return 'other';
+}
+
+function initPoolAnalytics(pool) {
+  if (!pool.state.analytics24h) {
+    pool.state.analytics24h = {
+      requests: [], // Ring buffer of { at, ref, success, attempts, failovers, cascaded }
+      errorEvents: [], // Ring buffer of { at, category, code, ref }
+    };
+  }
+  return pool.state.analytics24h;
+}
+
+/**
+ * Records a failover error encountered during key rotation.
+ */
+export function recordFailureCategory(pool, code, message = '', ref = '', now = Date.now()) {
+  if (!pool?.state) return;
+  const a = initPoolAnalytics(pool);
+  const category = classifyErrorCategory(code, message);
+  a.errorEvents.push({
+    at: now,
+    category,
+    code: String(code ?? 'UNKNOWN'),
+    ref: ref || pool.state.lastUsed || '',
+  });
+  if (a.errorEvents.length > MAX_RING_BUFFER) {
+    a.errorEvents.shift();
+  }
+}
+
+/**
+ * Records a completed request outcome in the pool's 24h analytics buffer.
+ */
+export function recordRequestOutcome(pool, outcome, now = Date.now()) {
+  if (!pool?.state) return;
+  const a = initPoolAnalytics(pool);
+
+  const entry = {
+    at: now,
+    ref: outcome.ref || pool.state.lastUsed || '',
+    success: outcome.success !== false,
+    attempts: Number(outcome.attempts) || 1,
+    failovers: Number(outcome.failovers) || 0,
+    cascaded: Boolean(outcome.cascaded),
+  };
+
+  a.requests.push(entry);
+  if (a.requests.length > MAX_RING_BUFFER) {
+    a.requests.shift();
+  }
+}
+
+/**
+ * Computes 24h analytics snapshot for the pool.
+ */
+export function compute24hAnalytics(pool, now = Date.now()) {
+  const cutoff = now - DAY_MS;
+  const a = pool?.state?.analytics24h;
+  const requests = a?.requests?.filter(r => r.at >= cutoff) ?? [];
+  const errorEvents = a?.errorEvents?.filter(e => e.at >= cutoff) ?? [];
+
+  const totalRequests = requests.length;
+  let firstAttemptSuccesses = 0;
+  let cascades = 0;
+  const keyCounts = new Map();
+  const errors = {
+    rateLimit: 0,
+    server: 0,
+    timeout: 0,
+    quota: 0,
+    auth: 0,
+    other: 0,
+  };
+
+  for (const r of requests) {
+    if (r.ref) {
+      keyCounts.set(r.ref, (keyCounts.get(r.ref) ?? 0) + 1);
+    }
+    if (r.success && r.attempts <= 1 && r.failovers === 0) {
+      firstAttemptSuccesses++;
+    }
+    if (r.cascaded) {
+      cascades++;
+    }
+  }
+
+  for (const ev of errorEvents) {
+    if (ev.category && errors[ev.category] != null) {
+      errors[ev.category]++;
+    }
+  }
+
+  // Calculate load distribution across pool refs
+  const refs = pool?.refs ?? [...keyCounts.keys()];
+  const loadDistribution = refs.map(ref => {
+    const count = keyCounts.get(ref) ?? 0;
+    const pct = totalRequests > 0 ? Math.round((count / totalRequests) * 100) : 0;
+    return { ref, count, pct };
+  });
+
+  const totalErrors = Object.values(errors).reduce((sum, n) => sum + n, 0);
+
+  // Compute average cooldown recovery time from pool.state.events
+  let cooldownTotalMs = 0;
+  let cooldownCount = 0;
+  const events = pool?.state?.events ?? [];
+  for (const ev of events) {
+    if (ev.at >= cutoff && ev.type === 'fail' && Number.isFinite(ev.cooldownMs) && ev.cooldownMs > 0) {
+      cooldownTotalMs += ev.cooldownMs;
+      cooldownCount++;
+    }
+  }
+  const avgCooldownRecoveryMs = cooldownCount > 0 ? Math.round(cooldownTotalMs / cooldownCount) : 0;
+
+  // Health index: % of requests handled without retries or failover
+  const healthIndexPct = totalRequests > 0
+    ? Math.round((firstAttemptSuccesses / totalRequests) * 100)
+    : 100;
+
+  return {
+    totalRequests,
+    firstAttemptSuccesses,
+    healthIndexPct,
+    loadDistribution,
+    errorBreakdown: {
+      ...errors,
+      total: totalErrors,
+    },
+    cascades: Math.max(cascades, pool?.state?.cascadeCount ?? 0),
+    avgCooldownRecoveryMs,
+  };
+}

package/lib/ops-status.js

@@ -17,6 +17,8 @@ import {
 import { bucketInfo, tpmInfo } from './bucket.js';
 import { isBlockedUntilReset } from './quota-window.js';
 import { sanitizeSnapshot } from './sanitize-snapshot.js';
+import { compute24hAnalytics } from './ops-analytics.js';
+import { getPromptCacheSummary } from './prompt-cache.js';
 import {
   STATUS_PATH,
   HEALTH_PATH,
@@ -177,6 +179,8 @@ ctx.effect(() => ctx.webServer.register({
         routingStrategy: pool.routingStrategy ?? runtime.routingStrategy ?? 'round-robin',
         proactiveRateLimitGuard: pool.proactiveRateLimitGuard ?? runtime.proactiveRateLimitGuard ?? true,
         smoothedRequests: pool.state.smoothedRequests ?? 0,
+        promptCache: getPromptCacheSummary(pool, now),
+        analytics24h: compute24hAnalytics(pool, now),
       });
       } catch (e) {
         (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.(`[dsh-key-rotation] status: pool ${pool.base} failed: ${String(e?.message ?? e)} ${e?.stack ?? ''}`);

package/lib/ops-telemetry.js

@@ -21,6 +21,8 @@ import { simulateRouting } from './simulator.js';
 import { getSelectionTraces, clearSelectionTraces } from './selection-trace.js';
 import { findSecrets } from './keycheck.js';
 import { mutateSettings, sectionOps } from './settings-write.js';
+import { compute24hAnalytics } from './ops-analytics.js';
+import { getPromptCacheSummary } from './prompt-cache.js';
 
 /**
  * @param {object} ctx cordis context
@@ -68,7 +70,12 @@ ctx.effect(() => ctx.webServer.register({
       if (seen.has(pool.base)) continue;
       seen.add(pool.base);
       if (provider && pool.base !== provider && pool.provider !== provider) continue;
-      report.push({ provider: pool.base, rows: usageRows(pool, days, now) });
+      report.push({
+        provider: pool.base,
+        rows: usageRows(pool, days, now),
+        promptCache: getPromptCacheSummary(pool, now),
+        analytics24h: compute24hAnalytics(pool, now),
+      });
     }
     if (csv) {
       res.writeHead(200, { 'content-type': 'text/csv; charset=utf-8', 'content-disposition': 'attachment; filename="dsh-key-rotation-usage.csv"' });

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;
+}

package/lib/rotate.js

@@ -36,6 +36,8 @@ import {
 
 import { LOCAL_POOL_EXHAUSTED_CODE } from './resolver.js';
 import { extractProviderLimits } from './provider-limits-detector.js';
+import { recordPromptCache } from './prompt-cache.js';
+import { recordRequestOutcome, recordFailureCategory } from './ops-analytics.js';
 
 export const LOCAL_QUOTA_CODE = 'LOCAL_MODEL_QUOTA_EXHAUSTED';
 
@@ -479,6 +481,7 @@ export function createRotate(deps) {
                   const activeRef = reqStore.pickedRef ?? pool.state.lastUsed;
                   if (switchable) {
                     penalizeRef(activeRef, code ?? 'UNKNOWN', message, rawHdrs ?? failure?.headers ?? pool.state.detectedLimits?.get?.(activeRef));
+                    recordFailureCategory(pool, code ?? 'UNKNOWN', message, activeRef, now());
                     pool.state.switches = (pool.state.switches ?? 0) + 1;
                     pool.state.lastReason = String(code ?? 'UNKNOWN');
                     pool.state.lastSwitchAt = now();
@@ -537,6 +540,14 @@ export function createRotate(deps) {
                   if (activeRef) {
                     recordSuccess(pool, activeRef, now());
                     if (sessionId) setSessionSticky(pool, sessionId, activeRef);
+                    recordPromptCache(pool, activeRef, options.model, chunk?.usage ?? chunk?.metadata?.usage, Date.now());
+                    recordRequestOutcome(pool, {
+                      ref: activeRef,
+                      success: true,
+                      attempts: attempt + 1,
+                      failovers: attempt,
+                      cascaded: Boolean(options.__isCascade),
+                    }, Date.now());
                   }
                   if (activeRef) {
                     const usedTokens = extractUsageTokens(chunk?.usage ?? chunk?.metadata?.usage);
@@ -610,6 +621,7 @@ export function createRotate(deps) {
               const activeRef = _pickedRef ?? reqStore.pickedRef ?? pool.state.lastUsed;
               if (!yielded && isSwitchableError(e, effectiveSwitchCodes)) {
                 penalizeRef(activeRef, e?.code ?? 'TRANSPORT', String(e?.message ?? e), e?.headers ?? e?.response?.headers ?? pool.state.detectedLimits?.get?.(activeRef));
+                recordFailureCategory(pool, e?.code ?? 'TRANSPORT', String(e?.message ?? e), activeRef, now());
                 pool.state.switches = (pool.state.switches ?? 0) + 1;
                 pool.state.lastReason = String(e?.code ?? 'TRANSPORT');
                 pool.state.lastSwitchAt = now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.67",
+  "version": "0.8.68",
   "packageManager": "pnpm@10.33.2",
   "description": "Per-provider API key rotation for DeepSeek Harness: a key pool per provider, auto-created clone routes, and switching to the next key on quota/rate-limit errors. Includes a Settings section (Key Rotation) to edit the key pools, cooldown and switch codes.",
   "keywords": [