@goodandready/dsh-key-rotation 0.7.27 → 0.7.28

package/README.md

@@ -39,6 +39,11 @@
   - **Interactive webhooks** (added in 0.7.27) — set `webhookActionToken` and exhaustion notifications gain action buttons on Telegram (`inline_keyboard`), Discord (buttons) and Slack (actions block): *Reset cooldown* and *Pause 1h* per pool. Buttons call back to `POST /dsh-key-rotation/webhook-action` with a bearer token; actions `reset-<provider>`, `pause-<provider>` (1 h), `disable-rotation`, `enable-rotation`.
   - **Token leak detector** (added in 0.7.27) — recognizes live key shapes (OpenAI `sk-`, Anthropic `sk-ant-`, Google `AIza…`, GitHub `ghp_…`, AWS `AKIA…`, Slack `xox…`, Telegram bot tokens, Stripe, PEM blocks). Saving the config section with a real key pasted into a wrong field is rejected (`400 secret-in-config`); the key-save response carries `looksLikeSecret`, and the card hints when the value does not look like an API key.
   - **Header status chip** (added in 0.7.27) — a small chip in the session header shows one dot for all pools (green = all keys healthy, amber = some cooling, red = a pool fully exhausted) plus a `healthy/total` counter; polls every 4 s.
+  - **Key expiry pre-warning** (added in 0.7.28) — `expiryWarnDays` (default 7): keys expiring within that horizon send one webhook notification per key per day and show a yellow *expires in Nd* badge in the card.
+  - **Provider cost budget** (added in 0.7.28) — per-provider `costBudgetDaily` / `costBudgetWeekly` (0 = off): a warn webhook fires from 80% spend, and with `pauseOnBudget: true` the whole pool is paused for 24 h at 100%. The card shows a live budget line with warn/red coloring.
+  - **Usage report + CSV export** (added in 0.7.28) — `GET /dsh-key-rotation/usage?days=N[&provider=…][&format=csv]` returns per-key requests/cost over the window; an *Export CSV* button in the card downloads the same data for one provider.
+  - **RPM capacity indicator** (added in 0.7.28) — `/status` carries `rpm: {used, remaining, resetMs}` per key; the card shows a ⏱ counter next to the active key.
+  - **Real key test probe** (added in 0.7.28) — the per-key *Test* button now sends `probe=models` through the existing `/test` route, so it validates the key against the live API (models list + latency), not just credential presence.
 
 ## Install
 
@@ -83,6 +88,9 @@ dsh-key-rotation:
 | `providers` | — | `[{ provider, keys: [envName, ...] }]`. `keys` are credential/env **names**, not the key values themselves. |
 | `rpmLimit` | `0` | Requests-per-minute cap **per key** (0 = off). A capped key is skipped pre-emptively until its 60 s window frees up. |
 | `webhookActionToken` | `''` | Bearer token for the interactive webhook callback route. When set, exhaustion webhooks carry action buttons; empty disables them. |
+| `expiryWarnDays` | `7` | Pre-warning horizon (days) for keys with `expiresAt`: webhook + card badge. |
+| `providers[].costBudgetDaily` / `.costBudgetWeekly` | `0` | Daily / weekly spend budget per provider (0 = off). Warn webhook from 80%. |
+| `providers[].pauseOnBudget` | `false` | Pause the whole pool for 24 h when a budget is exceeded. |
 | `providers[].tags` | `[]` | Free-form labels for a provider pool, surfaced in `GET /status`. |
 
 ### Interactive webhook actions (added in 0.7.27)
@@ -98,6 +106,15 @@ curl -X POST http://127.0.0.1:3080/dsh-key-rotation/webhook-action \
 
 Actions: `reset-<provider>` (clear cooldowns), `pause-<provider>` (pause the whole pool for 1 hour), `disable-rotation` / `enable-rotation` (global). Platform callback payloads (`callback_data`, Discord `custom_id`, Slack button `value`) are accepted too. Without the correct bearer token the route answers `401`; without a configured token — `503`.
 
+### Usage report (added in 0.7.28)
+
+```bash
+curl "http://127.0.0.1:3080/dsh-key-rotation/usage?days=7"           # JSON
+curl "http://127.0.0.1:3080/dsh-key-rotation/usage?format=csv&days=30&provider=my-provider" > usage.csv
+```
+
+Per-key rows: `requests`, `cost`, `active`, and per-day counts over the window (1–90 days, default 7).
+
 ### How keys are stored
 
 The plugin config only ever references keys by **name** (e.g. `MY_PROVIDER_API_KEY`). The values live in the dsh **Credentials** service or `$DSH_HOME/.credentials.yaml` — never in the plugin config.

package/lib/bucket.js

@@ -39,3 +39,14 @@ export function bucketSweep(windows, liveRefs) {
     if (!liveRefs.has(ref)) windows.delete(ref);
   }
 }
+
+/** #210: snapshot for /status - used/remaining/resetMs for one ref. */
+export function bucketInfo(windows, ref, limit, now = Date.now()) {
+  if (!limit || limit <= 0) return null;
+  const hits = (windows?.get(ref) ?? []).filter((t) => t > now - WINDOW_MS);
+  return {
+    used: hits.length,
+    remaining: Math.max(0, limit - hits.length),
+    resetMs: hits.length ? Math.max(0, hits[0] + WINDOW_MS - now) : 0,
+  };
+}

package/lib/client.js

@@ -64,6 +64,9 @@ window.__ModuleLoader__.load({
       keyFromEnv: 'from the environment, read-only here',
       keyWriteFailed: 'could not store the key: {msg}',
       notSecretShape: 'saved, but the value does not look like an API key - check for a typo',
+      rpmTitle: 'requests/min: {u} used, {r} remaining',
+      budgetLabel: 'budget:',
+      exportCsv: 'Export CSV',
       keyHint: 'The value is stored in DSH credentials and never sent back to the browser — only its last 5 characters are shown. Names are generated for you; hover a key to see the one it uses.',
       brokenKey: 'broken (3× AUTH)',
       keyExpired: 'expired',
@@ -121,6 +124,9 @@ window.__ModuleLoader__.load({
       keyFromEnv: 'задан в окружении, отсюда не меняется',
       keyWriteFailed: 'не удалось сохранить ключ: {msg}',
       notSecretShape: 'сохранено, но значение не похоже на API-ключ — проверьте опечатки',
+      rpmTitle: 'запросов/мин: {u} использовано, {r} осталось',
+      budgetLabel: 'бюджет:',
+      exportCsv: 'CSV',
       keyHint: 'Значение хранится в учётных данных DSH и обратно в браузер не отдаётся — показываются только последние 5 символов. Имена переменных создаются автоматически; наведите на ключ, чтобы увидеть используемое имя.',
       brokenKey: 'сломан (3× AUTH)',
       keyExpired: 'истёк',
@@ -294,7 +300,8 @@ window.__ModuleLoader__.load({
       }); };
       const doTest = (ref) => {
         setTesting(ref); setTestResult((m) => ({ ...m, [ref]: null }));
-        fetch('/dsh-key-rotation/test', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ref }) })
+        // #212: real API probe (models is free on most providers), not just presence
+        fetch('/dsh-key-rotation/test', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ref, probe: 'models' }) })
           .then((r) => r.json())
           .then((data) => setTestResult((m) => ({ ...m, [ref]: data })))
           .catch((e) => setTestResult((m) => ({ ...m, [ref]: { ok: false, message: String(e?.message ?? e) } })))
@@ -517,7 +524,8 @@ window.__ModuleLoader__.load({
         if (hit.expired) return { color: 'var(--dsw-alias-state-error-primary)', text: t('keyExpired') };
         if (hit.expiresAt && !hit.expired) {
           const days = Math.ceil((hit.expiresAt - Date.now()) / 86400000);
-          if (days <= 7) return { color: 'var(--dsw-alias-state-warning-primary)', text: t('keyExpiringSoon').replace('{n}', String(days)) };
+          const warnDays = Number(val?.expiryWarnDays) || 7; // #207: configurable horizon
+          if (days <= warnDays) return { color: 'var(--dsw-alias-state-warning-primary)', text: t('keyExpiringSoon').replace('{n}', String(days)) };
         }
         if (hit.broken) return { color: 'var(--dsw-alias-state-error-primary)', text: t('brokenKey') };
         if (!hit.present) return { color: 'var(--dsw-alias-state-error-primary)', text: t('keyMissing') };
@@ -593,12 +601,19 @@ window.__ModuleLoader__.load({
             }
           }
           if (info && info.lastUsedAt) meta.push(h('span', { key: 'lu', className: 'krot-tail', title: 'last used' }, formatAgo((k)=>t(k), info.lastUsedAt)));
+          // #210: RPM capacity indicator (only when rpmLimit is active)
+          if (info && info.rpm) meta.push(h('span', { key: 'rpm', className: 'krot-tail',
+            title: t('rpmTitle').replace('{u}', String(info.rpm.used)).replace('{r}', String(info.rpm.remaining)),
+            style: info.rpm.remaining === 0 ? { color: 'var(--dsw-alias-state-error-primary)', fontWeight: 700 } : undefined },
+            '⏱' + info.rpm.remaining));
           if (info && typeof info.cost === 'number' && info.cost > 0) meta.push(h('span', { key: 'c', className: 'krot-tail', title: 'cost' }, '$' + info.cost.toFixed(2)));
           const tr = testResult[key];
           if (tr) meta.push(h('span', { key: 'tr', className: 'krot-tail',
-            title: tr.message || (tr.ok ? t('testOk') : t('testFail')),
+            title: (tr.message || (tr.ok ? t('testOk') : t('testFail')))
+              + (tr.ok && tr.modelsCount ? ' · ' + tr.modelsCount + ' models' : '')
+              + (tr.ok && tr.latencyMs ? ' · ' + tr.latencyMs + 'ms' : ''),
             style: { color: tr.ok ? 'var(--dsw-alias-state-success-primary)' : 'var(--dsw-alias-state-error-primary)', fontWeight: 700 } },
-            tr.ok ? '✓' : '✕'));
+            tr.ok ? (tr.modelsCount ? tr.modelsCount + 'm' : '✓') : '✕'));
           meta.push(h('button', { key: 't', className: 'krot-btn', onClick: () => doTest(key), disabled: testing === key, title: t('testKey') }, testing === key ? '…' : t('testKey')));
           meta.push(h('span', { key: 'a', className: 'krot-acts' },
             btn('↑', () => moveKey(pIndex, kIndex, -1), { disabled: kIndex === 0, title: t('moveUp') }),
@@ -623,6 +638,28 @@ window.__ModuleLoader__.load({
         const exhaustionWarning = providerStatus && providerStatus.lastExhaustionAt && (Date.now() - providerStatus.lastExhaustionAt) < 3600000
           ? h('p', { className: 'krot-err' }, t('poolExhausted') + ' (' + formatAgo(t, providerStatus.lastExhaustionAt) + ')')
           : null;
+        // #208: budget line (warn color at >=80%, red at 100%)
+        const budgetLine = providerStatus && (providerStatus.budgetDaily > 0 || providerStatus.budgetWeekly > 0)
+          ? (() => {
+              const dayRatio = providerStatus.budgetDaily > 0 ? providerStatus.todayCost / providerStatus.budgetDaily : 0;
+              const weekRatio = providerStatus.budgetWeekly > 0 ? providerStatus.weeklyCost / providerStatus.budgetWeekly : 0;
+              const worst = Math.max(dayRatio, weekRatio);
+              const color = worst >= 1 ? 'var(--dsw-alias-state-error-primary)' : worst >= 0.8 ? 'var(--dsw-alias-state-warning-primary)' : 'var(--dsw-alias-label-tertiary)';
+              const parts = [];
+              if (providerStatus.budgetDaily > 0) parts.push('$' + (providerStatus.todayCost ?? 0).toFixed(2) + '/' + '$' + providerStatus.budgetDaily);
+              if (providerStatus.budgetWeekly > 0) parts.push('week $' + (providerStatus.weeklyCost ?? 0).toFixed(2) + '/' + '$' + providerStatus.budgetWeekly);
+              if (worst >= 1 && providerStatus.pauseOnBudget) parts.push('· paused');
+              return h('p', { className: 'krot-hint', style: { color } }, t('budgetLabel') + ' ' + parts.join(' · '));
+            })()
+          : null;
+        // #209: CSV export for this provider's usage (last 7 days)
+        const exportCsv = h('button', { className: 'krot-btn', title: t('exportCsv'),
+          onClick: () => {
+            const url = '/dsh-key-rotation/usage?format=csv&days=7&provider=' + encodeURIComponent(entry.provider);
+            const a = document.createElement('a');
+            a.href = url; a.download = 'usage-' + entry.provider + '.csv';
+            document.body.appendChild(a); a.click(); a.remove();
+          } }, t('exportCsv'));
 
         return h('div', { key: pIndex, className: 'krot-prov' },
           h('div', { className: 'krot-prov-head' },
@@ -660,11 +697,13 @@ window.__ModuleLoader__.load({
           h('div', { className: 'krot-foot' },
             btn(t('addKey'), () => addKey(pIndex), { title: t('addKeyTitle') }),
             switchesLine,
+            budgetLine,
             exhaustionWarning,
             (providerStatus && Array.isArray(providerStatus.events) && providerStatus.events.length > 0 ? h('div', { style: { display: 'flex', gap: '2px', alignItems: 'end', height: '24px', marginTop: '4px' } }, (() => { const now = Date.now(); const buckets = Array(24).fill(0); for (const ev of providerStatus.events) { const h = Math.floor((now - ev.at) / 3600000); if (h >= 0 && h < 24) buckets[23 - h]++; } const max = Math.max(1, ...buckets); return buckets.map((c, i) => h('div', { key: i, title: c + ' switches', style: { flex: 1, background: c ? 'var(--dsw-alias-state-warning-primary)' : 'var(--dsw-alias-border-l2)', height: (c / max * 24) + 'px', minHeight: '2px', borderRadius: '2px' } })); })()) : null),
             (providerStatus && Array.isArray(providerStatus.events) && providerStatus.events.length > 0 ? h('details', { style: { fontSize: '11px', marginTop: '6px' } }, h('summary', null, 'Recent failures ('+providerStatus.events.length+')'), h('ul', { style: { margin: '4px 0 0', paddingLeft: '16px' } }, providerStatus.events.slice().reverse().map((ev, i) => h('li', { key: i, style: ev.type === 'probe' ? { opacity: .5 } : null }, new Date(ev.at).toLocaleTimeString() + ' ' + (ev.type === 'probe' ? '[probe] ' : '') + ev.ref + ' ' + ev.reason + ' cd=' + ev.cooldownMs)) )) : null),
             btn(t('resetCooldown'), () => doReset(entry.provider), { disabled: !(providerStatus && providerStatus.switches > 0) || resetting === entry.provider, title: t('resetCooldown') }),
             btn(testAllProvider === entry.provider ? t('testing') : t('testAll'), () => doTestAll(entry.provider), { disabled: testAllProvider === entry.provider, title: t('testAll') }),
+            exportCsv,
           ),
         );
       });

package/lib/index.js

@@ -48,6 +48,7 @@ const KEY_PATH = '/dsh-key-rotation/key';
 const RESET_PATH = '/dsh-key-rotation/reset';
 const IMPORT_PATH = '/dsh-key-rotation/import';
 const HEALTH_PATH = '/dsh-key-rotation/health';
+const USAGE_PATH = '/dsh-key-rotation/usage';
 const TEST_PATH = '/dsh-key-rotation/test';
 const SANDBOX_CACHE_PATH = '/dsh-key-rotation/sandbox-cache';
 const AGENT_BUDGET_PATH = '/dsh-key-rotation/agent-budget';
@@ -69,7 +70,9 @@ import { RegionMap } from './region.js';
 import { IncidentReporter } from './incident.js';
 import { ShadowRouter } from './shadow.js';
 import { WebhookSender } from './webhook.js';
-import { bucketAllow, bucketRetryMs, bucketSweep } from './bucket.js';
+import { bucketAllow, bucketRetryMs, bucketSweep, bucketInfo } from './bucket.js';
+import { expiringSoon, shouldNotifyDaily, costForDay, budgetVerdict, costForWeek } from './maintenance.js';
+import { usageRows, usageCsv } from './usage-report.js';
 import { findSecrets, looksLikeApiSecret } from './keycheck.js';
 
 /** The llm-pi-ai namespace whose provider profiles map providers to pools. */
@@ -78,6 +81,10 @@ const PIAI_NS = 'llm-pi-ai';
 const MARKER = '__dshKeyRotation';
 /** #199: set true via webhook action; checked in the llm/stream interceptor. */
 let rotationDisabled = false;
+// #207/#208 dedupe maps: one notification per key/window per day.
+const expiryNotifiedAt = new Map();
+const budgetNotifiedAt = new Map();
+const DAY_MS = 86400000;
 const MAX_EVENTS = 50;
 function pushEvent(pool, ref, reason, cooldownMs, type) {
   const ev = { at: Date.now(), ref, reason: String(reason ?? 'UNKNOWN'), cooldownMs, type: type ?? 'fail' };
@@ -183,12 +190,16 @@ export const Config = Schema.object({
   rateLimitThreshold: Schema.number().default(0.1),
   rpmLimit: Schema.number().default(0),
   webhookActionToken: Schema.string().default(''),
+  expiryWarnDays: Schema.number().default(7),
   providers: Schema.array(Schema.object({
     provider: Schema.string().required(),
     keys: Schema.array(Schema.string()).default([]),
     weights: Schema.array(Schema.number()).default([]),
     expiresAt: Schema.array(Schema.union([Schema.number(), Schema.string()])).default([]),
     tags: Schema.array(Schema.string()).default([]),
+    costBudgetDaily: Schema.number(),
+    costBudgetWeekly: Schema.number(),
+    pauseOnBudget: Schema.boolean().default(false),
     models: Schema.dict(Schema.object({
       keys: Schema.array(Schema.string()).default([]),
       weights: Schema.array(Schema.number()).default([]),
@@ -542,6 +553,56 @@ export function apply(ctx, config = {}) {
       }
       const n = sweepExpired(poolState, now);
       if (n > 0) console.warn(`[dsh-key-rotation] sweep: cleared ${n} expired cooldown(s)`);
+      // #207 expiry pre-warning + #208 cost budget - piggybacked on this timer,
+      // deduped to one notification per key/window per day (shouldNotifyDaily).
+      try {
+        const runtime = buildRuntime();
+        const seen = new Set();
+        for (const pool of runtime.poolByRef.values()) {
+          if (seen.has(pool.base)) continue;
+          seen.add(pool.base);
+          // #207: keys expiring within expiryWarnDays -> one webhook per key/day
+          for (const { ref, expiresInDays } of expiringSoon(pool, runtime.expiryWarnDays, now)) {
+            if (!shouldNotifyDaily(expiryNotifiedAt, pool.base + ':' + ref, now)) continue;
+            console.warn(`[dsh-key-rotation] ${pool.base}: key ${ref} expires in ~${expiresInDays}d`);
+            if (runtime.notifyWebhook) {
+              webhookSender.send(runtime.notifyWebhook, {
+                title: `Key expiring soon: ${pool.base}`,
+                text: `${ref} expires in ~${expiresInDays} day(s)`,
+                provider: pool.base,
+                kind: 'expiry',
+                keys: [ref],
+              });
+            }
+          }
+          // #208: daily/weekly budget -> warn webhook, optional 1-day pause at 100%
+          const budget = runtime.providerBudgets.get(pool.base);
+          if (!budget) continue;
+          const daily = costForDay(pool.state.costDays);
+          const weekly = costForWeek(pool.state.costDays, now);
+          const verdict = budgetVerdict(daily, budget.costBudgetDaily);
+          const wVerdict = budgetVerdict(weekly, budget.costBudgetWeekly);
+          const hit = verdict.warn || wVerdict.warn;
+          if (hit && shouldNotifyDaily(budgetNotifiedAt, pool.base + ':budget', now)) {
+            console.warn(`[dsh-key-rotation] ${pool.base}: cost budget - day $${daily.toFixed(2)}/$${budget.costBudgetDaily} week $${weekly.toFixed(2)}/$${budget.costBudgetWeekly}`);
+            if (runtime.notifyWebhook) {
+              webhookSender.send(runtime.notifyWebhook, {
+                title: `Cost budget: ${pool.base}`,
+                text: `day $${daily.toFixed(2)} of $${budget.costBudgetDaily} · week $${weekly.toFixed(2)} of $${budget.costBudgetWeekly}` + (verdict.exceeded || wVerdict.exceeded ? ' · EXCEEDED' : ''),
+                provider: pool.base,
+                kind: 'budget',
+                spend: { daily, weekly },
+              });
+            }
+          }
+          if ((verdict.exceeded || wVerdict.exceeded) && budget.pauseOnBudget) {
+            const until = now + DAY_MS;
+            for (const ref of pool.refs) {
+              if ((pool.state.failedUntil.get(ref) ?? 0) < until) pool.state.failedUntil.set(ref, until);
+            }
+          }
+        }
+      } catch (_) { /* maintenance must never crash the sweep */ }
     }, 30000);
     return () => clearInterval(id);
   }, 'dsh-key-rotation: sweep expired cooldowns');
@@ -674,10 +735,15 @@ export function apply(ctx, config = {}) {
     }
     // #195: provider -> tags (metadata, surfaced in status)
     const providerTags = new Map();
+    // #208: provider -> { costBudgetDaily, costBudgetWeekly, pauseOnBudget }
+    const providerBudgets = new Map();
     for (const p of cfg.providers ?? []) {
       if (Array.isArray(p.tags) && p.tags.length > 0) providerTags.set(p.provider, p.tags);
+      const daily = typeof p.costBudgetDaily === 'number' ? p.costBudgetDaily : 0;
+      const weekly = typeof p.costBudgetWeekly === 'number' ? p.costBudgetWeekly : 0;
+      if (daily > 0 || weekly > 0) providerBudgets.set(p.provider, { costBudgetDaily: daily, costBudgetWeekly: weekly, pauseOnBudget: p.pauseOnBudget ?? false });
     }
-    return { switchCodes, cooldownMs, maxCooldownMs, notifyWebhook, notifyThreshold, incidentThreshold, concurrencyLimit, canaryProbingEnabled, canaryIntervalMs, cascade, quotaResetWindow, backupDir, backupIntervalMs, backupKeep, rotationScheduleDays, rateLimitThreshold, rpmLimit, webhookActionToken, providerTags, poolByRef, providerToPool, modelPoolByProvider, cloneIds };
+    return { switchCodes, cooldownMs, maxCooldownMs, notifyWebhook, notifyThreshold, incidentThreshold, concurrencyLimit, canaryProbingEnabled, canaryIntervalMs, cascade, quotaResetWindow, backupDir, backupIntervalMs, backupKeep, rotationScheduleDays, rateLimitThreshold, rpmLimit, webhookActionToken, expiryWarnDays: cfg.expiryWarnDays ?? 7, providerTags, providerBudgets, poolByRef, providerToPool, modelPoolByProvider, cloneIds };
   }
 
   // ── patch credentials.resolve: pool refs resolve to the next healthy key ──
@@ -888,6 +954,12 @@ export function apply(ctx, config = {}) {
                 if (!isNaN(c)) {
                   if (!pool.state.costPerKey) pool.state.costPerKey = new Map();
                   pool.state.costPerKey.set(pool.state.lastUsed, (pool.state.costPerKey.get(pool.state.lastUsed) ?? 0) + c);
+                  // #208: cost per day per key (mirrors usageDays) for budget checks
+                  if (!pool.state.costDays) pool.state.costDays = new Map();
+                  const cday = new Date().toISOString().slice(0, 10);
+                  const cMap = pool.state.costDays.get(pool.state.lastUsed) || new Map();
+                  cMap.set(cday, (cMap.get(cday) ?? 0) + c);
+                  pool.state.costDays.set(pool.state.lastUsed, cMap);
                 }
               }
               // Usage by day (#119)
@@ -987,7 +1059,7 @@ export function apply(ctx, config = {}) {
         json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: status is local-only' } });
         return;
       }
-      const { poolByRef, providerTags } = buildRuntime();
+      const { poolByRef, providerTags, providerBudgets } = buildRuntime();
       const base = ctx.get('credentials');
       const now = Date.now();
       const seen = new Set();
@@ -995,6 +1067,7 @@ export function apply(ctx, config = {}) {
       for (const pool of poolByRef.values()) {
         if (seen.has(pool.base)) continue;
         seen.add(pool.base);
+        try {
         const keys = [];
         for (const ref of pool.refs) {
           let present = false;
@@ -1032,6 +1105,8 @@ export function apply(ctx, config = {}) {
             writable,
             active: pool.state.lastUsed === ref,
             cooldownMsLeft: until !== undefined && until > now ? until - now : 0,
+            // #210: RPM capacity snapshot (null when rpmLimit is off)
+            rpm: bucketInfo(pool.state.rpmWindows, ref, pool.rpmLimit, now),
             usage: pool.state.usageCounts?.get(ref) ?? 0,
             byModel: pool.state.byModel?.get(ref) ? Object.fromEntries(pool.state.byModel.get(ref)) : {},
             usageDays: pool.state.usageDays?.get(ref) ? Object.fromEntries(pool.state.usageDays.get(ref)) : {},
@@ -1054,12 +1129,59 @@ export function apply(ctx, config = {}) {
           totalUsage: [...(pool.state.usageCounts?.values() ?? [])].reduce((a, b) => a + b, 0),
           events: (pool.state.events ?? []).slice(-50),
           healthScore: computeHealthScore(pool.state),
+          // #208: today/week spend + configured budget for the card
+          todayCost: costForDay(pool.state.costDays),
+          weeklyCost: costForWeek(pool.state.costDays, now),
+          budgetDaily: providerBudgets.get(pool.base)?.costBudgetDaily ?? 0,
+          budgetWeekly: providerBudgets.get(pool.base)?.costBudgetWeekly ?? 0,
+          pauseOnBudget: providerBudgets.get(pool.base)?.pauseOnBudget ?? false,
         });
+        } catch (e) {
+          console.warn(`[dsh-key-rotation] status: pool ${pool.base} failed: ${String(e?.message ?? e)} ${e?.stack ?? ''}`);
+          providers.push({ provider: pool.base, keys: [], statusError: String(e?.message ?? e) });
+        }
       }
       json(res, 200, { providers });
     },
   }), 'dsh-key-rotation: status route');
 
+  // #209: usage report - per-key requests/cost over the last N days.
+  // ?format=csv returns text/csv; ?days=N window (1..90, default 7).
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: USAGE_PATH,
+    handler: (req, res) => {
+      if (req.method !== 'GET') { json(res, 405, { error: { code: 'method', message: 'GET only' } }); return; }
+      if (!isTrustedBridgeRequest(req)) { json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: usage is local-only' } }); return; }
+      const url = new URL(req.url ?? USAGE_PATH, 'http://localhost');
+      const days = Math.min(90, Math.max(1, Number(url.searchParams.get('days')) || 7));
+      const csv = url.searchParams.get('format') === 'csv';
+      const provider = url.searchParams.get('provider') ?? '';
+      const runtime = buildRuntime();
+      const now = Date.now();
+      const seen = new Set();
+      const report = [];
+      for (const pool of runtime.poolByRef.values()) {
+        if (seen.has(pool.base)) continue;
+        seen.add(pool.base);
+        if (provider && pool.base !== provider) continue;
+        report.push({ provider: pool.base, rows: usageRows(pool, days, now) });
+      }
+      if (csv) {
+        res.writeHead(200, { 'content-type': 'text/csv; charset=utf-8', 'content-disposition': 'attachment; filename="dsh-key-rotation-usage.csv"' });
+        const parts = [];
+        for (const p of report) {
+          if (parts.length > 0) parts.push('');
+          parts.push('# ' + p.provider);
+          parts.push(usageCsv(p.rows));
+        }
+        res.end(parts.join('\n') + '\n');
+        return;
+      }
+      json(res, 200, { at: now, days, providers: report });
+    },
+  }), 'dsh-key-rotation: usage route');
+
   // ── key route: store a key value without leaving the rotation card ──
   //
   // Adding a key used to mean two screens: create the credential elsewhere,

package/lib/maintenance.js

@@ -0,0 +1,64 @@
+// lib/maintenance.js - pure helpers for #207 (expiry pre-warning) and
+// #208 (cost budget). No I/O; the timers in index.js call these and decide
+// whether to send webhooks.
+
+const DAY_MS = 86400000;
+
+/**
+ * #207: keys of `pool` whose expiresAt falls within the next `warnDays`.
+ * Returns [{ ref, expiresInDays, expiresAt }], soonest first.
+ */
+export function expiringSoon(pool, warnDays, now = Date.now()) {
+  if (!pool || !pool.expiresAt) return [];
+  const horizon = now + Math.max(1, warnDays ?? 7) * 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);
+}
+
+/** #207 dedupe: true when a day-level notification for `key` is due. */
+export function shouldNotifyDaily(lastNotified, key, now = Date.now()) {
+  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;
+}
+
+/**
+ * #208: 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;
+}
+
+/** #208: 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;
+}
+
+/**
+ * #208 budget verdict for a pool: { spend, budget, ratio, warn, exceeded }.
+ * budget <= 0 -> never warn.
+ */
+export function budgetVerdict(spend, budget) {
+  if (!budget || budget <= 0) return { spend, budget: 0, ratio: 0, warn: false, exceeded: false };
+  const ratio = spend / budget;
+  // warn from 80%, exceeded at 100%
+  return { spend, budget, ratio, warn: ratio >= 0.8, exceeded: ratio >= 1 };
+}

package/lib/usage-report.js

@@ -0,0 +1,49 @@
+// lib/usage-report.js - #209 usage report rows from pool state. Pure helpers.
+const DAY_MS = 86400000;
+
+/**
+ * Build per-key usage rows for the last `days` ISO days (default 7).
+ * Returns [{ ref, requests, cost, active, usageByDay: {day: n} }].
+ */
+export function usageRows(pool, days = 7, now = Date.now()) {
+  const out = [];
+  const dayKeys = [];
+  for (let i = 0; i < Math.max(1, days); i++) dayKeys.push(new Date(now - i * DAY_MS).toISOString().slice(0, 10));
+  const refs = pool?.refs ?? [];
+  for (const ref of refs) {
+    const daysMap = pool.state.usageDays?.get(ref) ?? new Map();
+    const costMap = pool.state.costDays?.get(ref) ?? new Map();
+    let requests = 0, cost = 0;
+    const usageByDay = {};
+    for (const d of dayKeys) {
+      const r = daysMap.get(d) ?? 0;
+      const c = costMap.get(d) ?? 0;
+      requests += r;
+      cost += c;
+      usageByDay[d] = r;
+    }
+    out.push({
+      ref,
+      requests,
+      cost: Math.round(cost * 100) / 100,
+      active: pool.state.lastUsed === ref,
+      usageByDay,
+    });
+  }
+  return out;
+}
+
+/** CSV of usage rows: ref,requests,cost,active + per-day columns. */
+export function usageCsv(rows) {
+  const dayCols = [...new Set(rows.flatMap((r) => Object.keys(r.usageByDay)))].sort();
+  const head = ['ref', 'requests', 'cost', 'active', ...dayCols];
+  const esc = (v) => {
+    const s = String(v ?? '');
+    return /[",\n]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+  };
+  const lines = [head.join(',')];
+  for (const r of rows) {
+    lines.push([esc(r.ref), r.requests, r.cost, r.active ? 'yes' : 'no', ...dayCols.map((d) => r.usageByDay[d] ?? 0)].join(','));
+  }
+  return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.7.27",
+  "version": "0.7.28",
   "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": [
     "deepseek-harness",