@goodandready/dsh-key-rotation 0.7.26 → 0.7.28

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 dsh-key-rotation contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 dsh-key-rotation contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,118 +1,157 @@
-# dsh-key-rotation
-
-**Per-provider API key rotation** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh). Instead of failing on a quota/rate-limit error, the plugin transparently retries the request on the **next healthy key** in a per-provider pool.
-
-> Hermes-style rotation: every configured provider has a key pool; when a key's limit is exhausted, the request is retried on the next key. Exhausted keys stay in cooldown and return to rotation after `cooldownMs`.
-
-## What it does
-
-- **Key pools per provider** — list the API keys (as credential/env names) that a provider may rotate through.
-- **The provider you picked stays the provider** — rotation swaps the key, never the route, so a multi-call turn does not break. Legacy clone routes remain registered but are hidden from the model dropdown.
-- **Transparent on-failure rotation** — on a switchable error (`QUOTA`, `RATE_LIMIT`, `AUTH`/`INVALID`…) the request is retried on the next key.
-- **Cooldown** — an exhausted key is skipped for `cooldownMs`, then returns.
-- **Dead/revoked key handling** — an auth/invalid key rotates to the next pool key instead of erroring out.
-- **Settings GUI** — a **Settings → Key Rotation** section to manage everything without touching config files:
-  - **add a key in one place** — press *Add key*, paste the value, done. The credential name is generated for you (`<PROVIDER>_API_KEY`, then `_2`, `_3`, …) and shown only on hover; the card lists keys as *Key 1*, *Key 2*.
-  - **live key status** — per key: in use / ready / cooling down with a countdown / **no such credential**, which is what catches a mistyped name that would otherwise fail silently.
-  - **rotation counter** — how many times a provider switched key, on which failure, and how long ago.
-  - **key order** — ↑/↓ buttons; the order of keys is the order they are tried.
-  - **switch codes as checkboxes** instead of a comma-separated string.
-  - **Exponential backoff** — repeated failures on the same key double its cooldown (base → ×2 → ×4 → cap ×8), so a dead key is not retried every window.
-  - **Reset cooldown** — a *Reset cooldown* button in the card clears a provider's cooldown immediately (also via `POST /dsh-key-rotation/reset`).
-  - **Env bootstrap** — if a pool ref (e.g. `MYPROVIDER_API_KEY`) is already set in `process.env`, it is treated as a transient credential without needing a DSH credential first.
-  - **Per-provider cooldown** — override `cooldownMs` (and `maxCooldownMs`) per provider, fallback to the global values.
-  - **Exhaustion warning** — when every key is cooling, a red warning appears in the card and `lastExhaustionAt`/`exhaustionCount` are exposed via `GET /dsh-key-rotation/status`.
-  - **Failure log** — last 20 failures per provider (`at`, `ref`, `reason`, `cooldownMs`) via `/status` and a collapsible *Recent failures* list.
-  - **Non-stream safety net** — an `agent/request-error` hook retries sync calls (embeddings, batch) with the next key when the error is switchable.
-  - **Search/filter providers** — a search box above the list filters providers by id.
-  - **Bulk edit cooldown** — checkboxes per provider + a cooldown input + *Apply to selected*.
-  - **Undo delete** — after removing a key or provider, an *Undo* bar appears for 5 seconds.
-  - **Per-key last used** — `lastUsedAt` shown as "ago" next to each key.
-  - **Total requests badge** — sum of usage across a provider's keys, shown in its header.
-  - **Export single provider** — ⬇ button exports just that provider's entry.
-  - **Import from .env** — pick a `.env` file; `KEY=val` names are added to the first pool.
-  - **Copy key name** — click a *Key N* label to copy its ref name.
-  - **Sort by usage** — ⇅ sorts a provider's keys by usage (desc).
-  - **Probe history** — health-probe events appear greyed in *Recent failures*.
-
-## Install
-
-```bash
-# From npm after publishing:
-dsh plugin --profile web add @goodandready/dsh-key-rotation
-
-# From GitHub:
-dsh plugin --profile web add github:GooDAnDReaDY/dsh-key-rotation
-
-# Locally from a checkout:
-dsh plugin --profile web add /path/to/dsh-key-rotation
-```
-
-Restart the Web UI afterwards.
-
-## Configure
-
-### Web GUI (recommended)
-
-Open **Settings → Key Rotation** and, for each provider, list the credential names of its keys. The plugin stores this in the `dsh-key-rotation` settings namespace (same place as `settings.yaml`).
-
-### `settings.yaml`
-
-```yaml
-dsh-key-rotation:
-  switchCodes: [QUOTA, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, EMPTY_RESPONSE, UNKNOWN_MODEL]
-  cooldownMs: 60000
-  providers:
-    # `provider` is the id of a provider registered with dsh, as it appears
-    # in Settings -> Models. `keys` are CREDENTIAL NAMES, never key values.
-    - provider: my-provider
-      keys: [MY_PROVIDER_API_KEY, MY_PROVIDER_API_KEY_2, MY_PROVIDER_API_KEY_3]
-    - provider: another-provider
-      keys: [ANOTHER_PROVIDER_API_KEY, ANOTHER_PROVIDER_API_KEY_2]
-```
-
-| Field | Default | Description |
-|---|---|---|
-| `switchCodes` | `[QUOTA, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, EMPTY_RESPONSE, UNKNOWN_MODEL]` | Error codes that trigger a key switch. |
-| `cooldownMs` | `60000` | How long an exhausted key stays out of rotation. |
-| `providers` | — | `[{ provider, keys: [envName, ...] }]`. `keys` are credential/env **names**, not the key values themselves. |
-
-### 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.
-
-A key typed into the Key Rotation card is written to that same credentials store: the value travels to the host once and is never sent back to the browser. Only its **last 5 characters** are, so two keys can be told apart in the UI. A key supplied by the launching environment is shown as read-only, because overwriting it here would be shadowed anyway.
-
-## How it works
-
-```
-request ──► {provider: rotation} clone route ──► pick next healthy key in pool
-        ┌────────┐   on switchable failure retry with next key, stay in cooldown
-        └─────────┘
-```
-
-- The plugin patches `ctx.credentials.resolve` so a pool reference resolves to the current healthy key (round-robin, skipping keys in cooldown).
-- It intercepts `llm/stream` to retry the request on the next key after a switchable failure, instead of surfacing the error to the caller. The hook is deliberately **not** `async`: the loop iterates its result directly, and returning a promise breaks every turn.
-- The provider identity never changes — only the resolved key does — which keeps the adapter's replay state consistent across a multi-call turn.
-
-Two local-only routes back the card: `GET /dsh-key-rotation/status` (key state, rotation counters, last 5 characters of each key) and `PUT|DELETE /dsh-key-rotation/key` (store or drop one key value). Both refuse anything that is not a same-origin request from loopback.
-
-## Structure
-
-```
-dsh-key-rotation/
-├── package.json            # dsh bundle/plugin metadata + peerDependencies
-├── cordis.patch.yml        # bundle layer: registers the virtual route "rotation"
-├── lib/index.js            # host: pools, credentials.resolve patch, stream retry
-├── lib/client.js           # browser: Settings → Key Rotation panel
-└── README.md
-```
-
-## Security notes
-
-- Key **values** never leave your Credentials store; the plugin config only holds env/credential **names**.
-- `switchCodes` are error classification strings, not expressions — no secrets involved.
-
-## License
-
-MIT
+# dsh-key-rotation
+
+**Per-provider API key rotation** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh). Instead of failing on a quota/rate-limit error, the plugin transparently retries the request on the **next healthy key** in a per-provider pool.
+
+> Hermes-style rotation: every configured provider has a key pool; when a key's limit is exhausted, the request is retried on the next key. Exhausted keys stay in cooldown and return to rotation after `cooldownMs`.
+
+## What it does
+
+- **Key pools per provider** — list the API keys (as credential/env names) that a provider may rotate through.
+- **The provider you picked stays the provider** — rotation swaps the key, never the route, so a multi-call turn does not break. Legacy clone routes remain registered but are hidden from the model dropdown.
+- **Transparent on-failure rotation** — on a switchable error (`QUOTA`, `RATE_LIMIT`, `AUTH`/`INVALID`…) the request is retried on the next key.
+- **Cooldown** — an exhausted key is skipped for `cooldownMs`, then returns.
+- **Dead/revoked key handling** — an auth/invalid key rotates to the next pool key instead of erroring out.
+- **Settings GUI** — a **Settings → Key Rotation** section to manage everything without touching config files:
+  - **add a key in one place** — press *Add key*, paste the value, done. The credential name is generated for you (`<PROVIDER>_API_KEY`, then `_2`, `_3`, …) and shown only on hover; the card lists keys as *Key 1*, *Key 2*.
+  - **live key status** — per key: in use / ready / cooling down with a countdown / **no such credential**, which is what catches a mistyped name that would otherwise fail silently.
+  - **rotation counter** — how many times a provider switched key, on which failure, and how long ago.
+  - **key order** — ↑/↓ buttons; the order of keys is the order they are tried.
+  - **switch codes as checkboxes** instead of a comma-separated string.
+  - **Exponential backoff** — repeated failures on the same key double its cooldown (base → ×2 → ×4 → cap ×8), so a dead key is not retried every window.
+  - **Reset cooldown** — a *Reset cooldown* button in the card clears a provider's cooldown immediately (also via `POST /dsh-key-rotation/reset`).
+  - **Env bootstrap** — if a pool ref (e.g. `MYPROVIDER_API_KEY`) is already set in `process.env`, it is treated as a transient credential without needing a DSH credential first.
+  - **Per-provider cooldown** — override `cooldownMs` (and `maxCooldownMs`) per provider, fallback to the global values.
+  - **Exhaustion warning** — when every key is cooling, a red warning appears in the card and `lastExhaustionAt`/`exhaustionCount` are exposed via `GET /dsh-key-rotation/status`.
+  - **Failure log** — last 20 failures per provider (`at`, `ref`, `reason`, `cooldownMs`) via `/status` and a collapsible *Recent failures* list.
+  - **Non-stream safety net** — an `agent/request-error` hook retries sync calls (embeddings, batch) with the next key when the error is switchable.
+  - **Search/filter providers** — a search box above the list filters providers by id.
+  - **Bulk edit cooldown** — checkboxes per provider + a cooldown input + *Apply to selected*.
+  - **Undo delete** — after removing a key or provider, an *Undo* bar appears for 5 seconds.
+  - **Per-key last used** — `lastUsedAt` shown as "ago" next to each key.
+  - **Total requests badge** — sum of usage across a provider's keys, shown in its header.
+  - **Export single provider** — ⬇ button exports just that provider's entry.
+  - **Import from .env** — pick a `.env` file; `KEY=val` names are added to the first pool.
+  - **Copy key name** — click a *Key N* label to copy its ref name.
+  - **Sort by usage** — ⇅ sorts a provider's keys by usage (desc).
+  - **Probe history** — health-probe events appear greyed in *Recent failures*.
+  - **RPM token bucket** (added in 0.7.27) — optional `rpmLimit` caps requests per minute **per key**: a key that hit the cap is skipped pre-emptively (before a real request is sent) and returns when its sliding 60s window frees up. `0` (default) disables it.
+  - **Tier/model-aware routing** (added in 0.7.27) — a pool defined for a model also serves model versions in its family: an exact model pool wins, then the longest name-prefix match (a pool for `gpt-4o` serves `gpt-4o-mini-2024`), then the provider base pool. Provider `tags` are free-form labels surfaced in `/status` for grouping.
+  - **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
+
+```bash
+# From npm after publishing:
+dsh plugin --profile web add @goodandready/dsh-key-rotation
+
+# From GitHub:
+dsh plugin --profile web add github:GooDAnDReaDY/dsh-key-rotation
+
+# Locally from a checkout:
+dsh plugin --profile web add /path/to/dsh-key-rotation
+```
+
+Restart the Web UI afterwards.
+
+## Configure
+
+### Web GUI (recommended)
+
+Open **Settings → Key Rotation** and, for each provider, list the credential names of its keys. The plugin stores this in the `dsh-key-rotation` settings namespace (same place as `settings.yaml`).
+
+### `settings.yaml`
+
+```yaml
+dsh-key-rotation:
+  switchCodes: [QUOTA, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, EMPTY_RESPONSE, UNKNOWN_MODEL]
+  cooldownMs: 60000
+  providers:
+    # `provider` is the id of a provider registered with dsh, as it appears
+    # in Settings -> Models. `keys` are CREDENTIAL NAMES, never key values.
+    - provider: my-provider
+      keys: [MY_PROVIDER_API_KEY, MY_PROVIDER_API_KEY_2, MY_PROVIDER_API_KEY_3]
+    - provider: another-provider
+      keys: [ANOTHER_PROVIDER_API_KEY, ANOTHER_PROVIDER_API_KEY_2]
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `switchCodes` | `[QUOTA, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, EMPTY_RESPONSE, UNKNOWN_MODEL]` | Error codes that trigger a key switch. |
+| `cooldownMs` | `60000` | How long an exhausted key stays out of 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)
+
+When `webhookActionToken` is set, the exhaustion webhook payload is formatted per platform (Telegram / Discord / Slack, detected from the URL) with two buttons. A button POSTs to the plugin route:
+
+```bash
+curl -X POST http://127.0.0.1:3080/dsh-key-rotation/webhook-action \
+  -H "Authorization: Bearer <webhookActionToken>" \
+  -H "content-type: application/json" \
+  -d '{"action": "reset-my-provider"}'
+```
+
+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.
+
+A key typed into the Key Rotation card is written to that same credentials store: the value travels to the host once and is never sent back to the browser. Only its **last 5 characters** are, so two keys can be told apart in the UI. A key supplied by the launching environment is shown as read-only, because overwriting it here would be shadowed anyway.
+
+## How it works
+
+```
+request ──► {provider: rotation} clone route ──► pick next healthy key in pool
+        ┌────────┐   on switchable failure retry with next key, stay in cooldown
+        └─────────┘
+```
+
+- The plugin patches `ctx.credentials.resolve` so a pool reference resolves to the current healthy key (round-robin, skipping keys in cooldown).
+- It intercepts `llm/stream` to retry the request on the next key after a switchable failure, instead of surfacing the error to the caller. The hook is deliberately **not** `async`: the loop iterates its result directly, and returning a promise breaks every turn.
+- The provider identity never changes — only the resolved key does — which keeps the adapter's replay state consistent across a multi-call turn.
+
+Two local-only routes back the card: `GET /dsh-key-rotation/status` (key state, rotation counters, last 5 characters of each key) and `PUT|DELETE /dsh-key-rotation/key` (store or drop one key value). Both refuse anything that is not a same-origin request from loopback.
+
+## Structure
+
+```
+dsh-key-rotation/
+├── package.json            # dsh bundle/plugin metadata + peerDependencies
+├── cordis.patch.yml        # bundle layer: registers the virtual route "rotation"
+├── lib/index.js            # host: pools, credentials.resolve patch, stream retry
+├── lib/client.js           # browser: Settings → Key Rotation panel
+└── README.md
+```
+
+## Security notes
+
+- Key **values** never leave your Credentials store; the plugin config only holds env/credential **names**.
+- `switchCodes` are error classification strings, not expressions — no secrets involved.
+- The leak detector (0.7.27) rejects config saves that carry a live-looking key outside the credential fields; only the credential **type** and a short preview are ever reported, never the value.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -1,7 +1,7 @@
-# dsh-key-rotation bundle layer.
-# Registers the virtual provider route "rotation"; the adapter delegates each
-# request to the configured clone routes of the matching backend and rotates
-# them on switchable failures (QUOTA / RATE_LIMIT / ...).
-- insert:
-    - id: dsh-key-rotation
+# dsh-key-rotation bundle layer.
+# Registers the virtual provider route "rotation"; the adapter delegates each
+# request to the configured clone routes of the matching backend and rotates
+# them on switchable failures (QUOTA / RATE_LIMIT / ...).
+- insert:
+    - id: dsh-key-rotation
       name: '@goodandready/dsh-key-rotation'

package/lib/agent-budget.js

@@ -1,68 +1,68 @@
-// lib/agent-budget.js — per-agent rate cap.
-// ponytail: in-memory counter per (agent, window), thread-safe-ish via timer map.
-
-export const AGENT_BUDGET_DEFAULT_WINDOW_MS = 3600_000; // 1h
-export const AGENT_BUDGET_DEFAULT_LIMIT = 0;             // 0 = disabled
-export const AGENT_BUDGET_MAX = 50000;                  // hard ceiling per agent
-
-export class AgentBudget {
-  constructor({ windowMs = AGENT_BUDGET_DEFAULT_WINDOW_MS, limit = AGENT_BUDGET_DEFAULT_LIMIT } = {}) {
-    const w = Number.isFinite(windowMs) && windowMs > 0 ? Math.floor(windowMs) : AGENT_BUDGET_DEFAULT_WINDOW_MS;
-    const l = Number.isFinite(limit) && limit >= 0 ? Math.min(AGENT_BUDGET_MAX, Math.floor(limit)) : 0;
-    this._windowMs = w;
-    this._limit = l;
-    this._state = new Map(); // agent -> { hits: number[], windowStart: epochMs }
-  }
-
-  isEnabled() {
-    return this._limit > 0;
-  }
-
-  // Decide if request from this agent is allowed. Returns { allowed, remaining, resetAt }.
-  // Records the hit only when allowed.
-  check(agentId, now = Date.now()) {
-    if (!this.isEnabled()) return { allowed: true, remaining: Infinity, resetAt: null };
-    if (!agentId || typeof agentId !== 'string') return { allowed: false, remaining: 0, resetAt: now };
-    let s = this._state.get(agentId);
-    if (!s) {
-      s = { hits: [], windowStart: now };
-      this._state.set(agentId, s);
-    }
-    // Window: prune hits older than windowStart + windowMs
-    const cutoff = now - this._windowMs;
-    while (s.hits.length > 0 && s.hits[0] < cutoff) s.hits.shift();
-    s.windowStart = s.hits.length ? s.hits[0] : now;
-    if (s.hits.length >= this._limit) {
-      const resetAt = s.hits[0] + this._windowMs;
-      return { allowed: false, remaining: 0, resetAt };
-    }
-    s.hits.push(now);
-    return { allowed: true, remaining: this._limit - s.hits.length, resetAt: now + this._windowMs };
-  }
-
-  // Reset single agent or all
-  reset(agentId) {
-    if (agentId) this._state.delete(agentId);
-    else this._state.clear();
-  }
-
-  // Inspect-only: return remaining without recording.
-  peek(agentId, now = Date.now()) {
-    if (!this.isEnabled()) return { remaining: Infinity, resetAt: null };
-    const s = this._state.get(agentId);
-    if (!s) return { remaining: this._limit, resetAt: null };
-    const cutoff = now - this._windowMs;
-    let count = 0;
-    for (let i = 0; i < s.hits.length; i++) {
-      if (s.hits[i] >= cutoff) count += 1;
-    }
-    const oldest = s.hits[0];
-    return { remaining: this._limit - count, resetAt: oldest ? oldest + this._windowMs : null };
-  }
-
-  snapshot() {
-    const out = {};
-    for (const [k, v] of this._state) out[k] = { hits: v.hits.length };
-    return out;
-  }
-}
+// lib/agent-budget.js — per-agent rate cap.
+// ponytail: in-memory counter per (agent, window), thread-safe-ish via timer map.
+
+export const AGENT_BUDGET_DEFAULT_WINDOW_MS = 3600_000; // 1h
+export const AGENT_BUDGET_DEFAULT_LIMIT = 0;             // 0 = disabled
+export const AGENT_BUDGET_MAX = 50000;                  // hard ceiling per agent
+
+export class AgentBudget {
+  constructor({ windowMs = AGENT_BUDGET_DEFAULT_WINDOW_MS, limit = AGENT_BUDGET_DEFAULT_LIMIT } = {}) {
+    const w = Number.isFinite(windowMs) && windowMs > 0 ? Math.floor(windowMs) : AGENT_BUDGET_DEFAULT_WINDOW_MS;
+    const l = Number.isFinite(limit) && limit >= 0 ? Math.min(AGENT_BUDGET_MAX, Math.floor(limit)) : 0;
+    this._windowMs = w;
+    this._limit = l;
+    this._state = new Map(); // agent -> { hits: number[], windowStart: epochMs }
+  }
+
+  isEnabled() {
+    return this._limit > 0;
+  }
+
+  // Decide if request from this agent is allowed. Returns { allowed, remaining, resetAt }.
+  // Records the hit only when allowed.
+  check(agentId, now = Date.now()) {
+    if (!this.isEnabled()) return { allowed: true, remaining: Infinity, resetAt: null };
+    if (!agentId || typeof agentId !== 'string') return { allowed: false, remaining: 0, resetAt: now };
+    let s = this._state.get(agentId);
+    if (!s) {
+      s = { hits: [], windowStart: now };
+      this._state.set(agentId, s);
+    }
+    // Window: prune hits older than windowStart + windowMs
+    const cutoff = now - this._windowMs;
+    while (s.hits.length > 0 && s.hits[0] < cutoff) s.hits.shift();
+    s.windowStart = s.hits.length ? s.hits[0] : now;
+    if (s.hits.length >= this._limit) {
+      const resetAt = s.hits[0] + this._windowMs;
+      return { allowed: false, remaining: 0, resetAt };
+    }
+    s.hits.push(now);
+    return { allowed: true, remaining: this._limit - s.hits.length, resetAt: now + this._windowMs };
+  }
+
+  // Reset single agent or all
+  reset(agentId) {
+    if (agentId) this._state.delete(agentId);
+    else this._state.clear();
+  }
+
+  // Inspect-only: return remaining without recording.
+  peek(agentId, now = Date.now()) {
+    if (!this.isEnabled()) return { remaining: Infinity, resetAt: null };
+    const s = this._state.get(agentId);
+    if (!s) return { remaining: this._limit, resetAt: null };
+    const cutoff = now - this._windowMs;
+    let count = 0;
+    for (let i = 0; i < s.hits.length; i++) {
+      if (s.hits[i] >= cutoff) count += 1;
+    }
+    const oldest = s.hits[0];
+    return { remaining: this._limit - count, resetAt: oldest ? oldest + this._windowMs : null };
+  }
+
+  snapshot() {
+    const out = {};
+    for (const [k, v] of this._state) out[k] = { hits: v.hits.length };
+    return out;
+  }
+}

package/lib/bucket.js

@@ -0,0 +1,52 @@
+// lib/bucket.js - per-key RPM token bucket (#192).
+// ponytail: RPM only - true token counts are not visible before the stream
+// starts; wire TPM in when pi-ai surfaces usage on the resolve path.
+const WINDOW_MS = 60000;
+
+/** Sliding-window check: true if `ref` is under `limit` requests/min. */
+export function bucketAllow(windows, ref, limit, now = Date.now()) {
+  if (!limit || limit <= 0) return true;
+  const cut = now - WINDOW_MS;
+  const hits = (windows.get(ref) ?? []).filter((t) => t > cut);
+  if (hits.length >= limit) {
+    windows.set(ref, hits);
+    return false;
+  }
+  hits.push(now);
+  windows.set(ref, hits);
+  return true;
+}
+
+/** Record a hit without checking (use after a successful resolve). */
+export function bucketHit(windows, ref, now = Date.now()) {
+  const cut = now - WINDOW_MS;
+  const hits = (windows.get(ref) ?? []).filter((t) => t > cut);
+  hits.push(now);
+  windows.set(ref, hits);
+}
+
+/** ms until `ref` may retry again (0 = now). */
+export function bucketRetryMs(windows, ref, limit, now = Date.now()) {
+  if (!limit || limit <= 0) return 0;
+  const hits = (windows.get(ref) ?? []).filter((t) => t > now - WINDOW_MS);
+  if (hits.length < limit) return 0;
+  return Math.max(0, hits[0] + WINDOW_MS - now);
+}
+
+/** Drop state for refs that no longer exist. */
+export function bucketSweep(windows, liveRefs) {
+  for (const ref of [...windows.keys()]) {
+    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,
+  };
+}