@goodandready/dsh-key-rotation 0.8.64 → 0.8.65

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.8.65 - 2026-10-18
+
+### Features
+- **Traffic Smoothing Micro-Queue (#496)**:
+  - Leaky bucket traffic smoother (`lib/traffic-smoother.js`) absorbs short micro-bursts ($\le 1$s) across multi-agent workflows without tripping upstream per-second or per-minute rate limits or triggering cooldown churning.
+  - Configurable `trafficSmoothingBurst` (default 5 or `ceil(rpmLimit/12)`) and `maxQueueWaitMs` (default 800ms).
+  - If scheduled micro-queue delay exceeds `maxQueueWaitMs`, the smoother flags burst overflow, immediately rotating to the next candidate key in the pool.
+  - Live metric `smoothedRequests` exposed on provider status, with `TRAFFIC_SMOOTHED` audit events.
+- **Accurate Dynamic Provider Limits & Canonical Presets (#503)**:
+  - Header limits detector (`lib/provider-limits-detector.js`): extracts dynamic rate limit headers (`x-ratelimit-limit-*`, `x-ratelimit-remaining-*`, `x-ratelimit-reset-*`, `anthropic-ratelimit-*`, `retry-after`) from upstream provider HTTP responses into `pool.state.detectedLimits`.
+  - Canonical provider presets catalog for DeepSeek, Groq, OpenCode, Anthropic, OpenAI, SiliconFlow, Mistral, Gemini, and OpenRouter with standard RPM, TPM, burst capacity, and calendar reset window specifications.
+  - Endpoint `GET/POST /dsh-key-rotation/preset-limits` to query and auto-apply canonical limits to configured providers.
+  - WebUI button `⚡ Preset Limits` for 1-click rate limit configuration and live upstream limits indicator badge (`⚡ 60 RPM · 100k TPM`).
+
 ## 0.8.64 - 2026-10-18
 
 ### Features

package/README.md

@@ -67,6 +67,10 @@
 - **📡 Status extras**: per-provider `circuit` plus `meta.expectedClones` / `meta.notifyQueue`.
 - **🧪 Smoke harness**: scripted 429 → next-key → success path in `test/smoke-rotation-080.test.mjs`.
 
+### 🚀 What's New in v0.8.65
+- **⚡ Leaky Bucket Traffic Smoothing (#496)**: Micro-queue smoothing absorbs rapid multi-agent burst spikes ($\le 1$s) without triggering unnecessary 429 errors or cooldown churning, with zero-delay burst capacity and early failover rotation on queue overflow.
+- **📊 Dynamic Upstream Rate Limits & Presets (#503)**: Dynamic parsing of provider rate limit headers (`x-ratelimit-*`, `anthropic-ratelimit-*`, `retry-after`), live badge display on keys, and 1-click `⚡ Preset Limits` button applying canonical RPM/TPM presets for DeepSeek, Groq, Anthropic, OpenAI, Gemini, and more.
+
 ### 🛠️ What's New in v0.7.33 (Stability & Bugfix Release)
 - **🔍 Resolved Key Probing BaseURL**: Fixed `resolveBaseUrl` to map key credential refs to owning provider pools, restoring live `probeModels` testing.
 - **🛡️ Guarded Cascade Recursion**: Prevented call stack overflow in cross-provider failover when circular cascade chains occur.

package/README.ru.md

@@ -36,6 +36,10 @@
 
 ---
 
+### 🚀 Что нового в v0.8.65
+- **⚡ Сглаживание трафика (Traffic Smoothing Micro-Queue) (#496)**: Микро-очередь leaky bucket сглаживает кратковременные пики нагрузки (<=1с) от мультиагентных вызовов без лишних ошибок 429 и лишних кулдаунов. При превышении таймаута ожидания микро-очереди запрос автоматически переключается на следующий ключ в пуле.
+- **📊 Динамическое определение лимитов провайдеров и пресеты (#503)**: Автоматический парсинг заголовков `x-ratelimit-*`, `anthropic-ratelimit-*`, `retry-after` с отображением актуальных лимитов прямо на карточке ключа, а также кнопка в 1 клик `⚡ Preset Limits` с каноническими пресетами для DeepSeek, Groq, Anthropic, OpenAI, Gemini и др.
+
 ### 🚀 Что нового в v0.8.11 (обновление в один клик и quality gate)
 
 - **Обновление плагина в карточке настроек**: текущая/последняя версия и кнопка установки без выхода из DSH (#307).

package/README.zh.md

@@ -38,6 +38,10 @@
 
 ## ⚡ 概述与核心痛点
 
+### 🚀 v0.8.65 新特性
+- **⚡ 流量平滑微队列 (Traffic Smoothing Micro-Queue) (#496)**: 漏桶微队列平滑多智能体调用中的毫秒级突发并发，避免触发不必要的429限流与冷却流转。队列等待超限时自动轮转至池中下一个候选密钥。
+- **📊 动态上游限制检测与预设规则 (#503)**: 自动提取上游响应头中的限流数据 (`x-ratelimit-*`, `anthropic-ratelimit-*`, `retry-after`)，并在前端展示实时配额状态；支持一键应用 DeepSeek、Groq、Anthropic、OpenAI、Gemini 等官方规范预设限制。
+
 ### 🚀 v0.8.11 新特性（一键更新与质量门禁）
 
 - **设置卡片中的插件更新器**：查看当前/最新版本并一键安装（#307）。

package/lib/client.js

@@ -99,6 +99,11 @@ window.__ModuleLoader__.load({
       keyPaused: 'Paused',
       keyRevoked: 'Revoked (401)',
       keyAuthPaused: 'Auth Paused (401/403)',
+      presetLimitsBtn: '⚡ Preset Limits',
+      presetApplied: 'Applied {prov} preset limits ({rpm} RPM / {tpm} TPM)',
+      presetNone: 'No canonical preset for this provider',
+      detectedLimitsLabel: 'Upstream: {rpm} RPM · {tpm} TPM',
+      trafficSmoothingLabel: 'Traffic Smoothing (Burst)',
       pauseKey: 'Pause key from rotation',
       resumeKey: 'Resume key rotation',
       sparklineTraffic: 'Traffic Trend',
@@ -301,6 +306,11 @@ window.__ModuleLoader__.load({
       keyPaused: '已暂停',
       keyRevoked: '已撤销 (401)',
       keyAuthPaused: '身份验证失败已暂停 (401/403)',
+      presetLimitsBtn: '⚡ 预设限制',
+      presetApplied: '已应用 {prov} 预设限制 ({rpm} RPM / {tpm} TPM)',
+      presetNone: '未找到该提供商预设规则',
+      detectedLimitsLabel: '上游限制：{rpm} RPM · {tpm} TPM',
+      trafficSmoothingLabel: '流量平滑 (突发并发)',
       pauseKey: '暂停此密钥轮换',
       resumeKey: '恢复此密钥轮换',
       sparklineTraffic: '流量趋势',
@@ -1556,6 +1566,31 @@ window.__ModuleLoader__.load({
       };
 
       const [validating, setValidating] = React.useState('');
+      const [presetNotice, setPresetNotice] = React.useState('');
+      const applyPreset = async (pIndex, provName) => {
+        try {
+          const r = await fetch('/dsh-key-rotation/preset-limits?provider=' + encodeURIComponent(provName));
+          const data = await r.json();
+          if (data && data.preset) {
+            setField((cur) => {
+              const providers = [...(cur.providers ?? [])];
+              const ent = { ...providers[pIndex] };
+              if (data.preset.rpmLimit) ent.rpmLimit = data.preset.rpmLimit;
+              if (data.preset.tpmLimit) ent.tpmLimit = data.preset.tpmLimit;
+              providers[pIndex] = ent;
+              return { ...cur, providers };
+            });
+            setPresetNotice(t('presetApplied').replace('{prov}', provName).replace('{rpm}', String(data.preset.rpmLimit)).replace('{tpm}', String(data.preset.tpmLimit)));
+            setTimeout(() => setPresetNotice(''), 4000);
+          } else {
+            setPresetNotice(t('presetNone'));
+            setTimeout(() => setPresetNotice(''), 3000);
+          }
+        } catch (err) {
+          setPresetNotice(String(err?.message || err));
+          setTimeout(() => setPresetNotice(''), 3000);
+        }
+      };
       const [validationResult, setValidationResult] = React.useState({});
       const validateBeforeSave = (ref, value) => {
         setValidating(ref);
@@ -2127,6 +2162,20 @@ window.__ModuleLoader__.load({
           if (info && info.broken) {
             meta.push(h('button', { key: 'rt', className: 'krot-btn', onClick: () => retestBroken(key), title: t('retestBroken') }, t('retestBroken')));
           }
+          if (info && info.detectedLimits) {
+            const dl = info.detectedLimits;
+            const parts = [];
+            if (dl.rpmLimit) parts.push(dl.rpmLimit + ' RPM');
+            if (dl.tpmLimit) parts.push(dl.tpmLimit + ' TPM');
+            if (parts.length > 0) {
+              meta.push(h('span', {
+                key: 'dl',
+                className: 'krot-tail',
+                title: 'Live upstream limits:\n' + JSON.stringify(dl, null, 2),
+                style: { fontSize: '11px', opacity: 0.8, color: 'var(--dsw-alias-brand-primary)' }
+              }, '⚡ ' + parts.join(' · ')));
+            }
+          }
           if (info && info.modelCapabilities && info.modelCapabilities.length > 0) {
             meta.push(h('span', {
               key: 'caps',
@@ -2368,6 +2417,8 @@ window.__ModuleLoader__.load({
               });
             }, { title: t('sortUsage') }),
             h('select', { className: 'krot-in', value: entry.provider, onChange: (e) => setProvider(pIndex, e.target.value) }, options),
+            btn(t('presetLimitsBtn') || '⚡ Preset Limits', () => applyPreset(pIndex, entry.provider), { title: t('presetLimitsBtn') || '⚡ Preset Limits', disabled: !entry.provider.trim() || !stateRef.current.writable }),
+            presetNotice ? h('span', { className: 'krot-badge krot-badge-ok', style: { marginLeft: '4px' } }, presetNotice) : null,
             (() => {
               const ps = status[entry.provider];
               const score = ps && typeof ps.healthScore === 'number' ? ps.healthScore : null;

package/lib/index.js

@@ -33,6 +33,7 @@ import { registerOpsRoutes } from './routes-ops.js';
 import { registerPluginUpdater } from './plugin-updater.js';
 import { notifySwitch, notifyExhaustion, notifyEarlyWarning, pushEvent } from './notify-events.js';
 import { QUOTA_WINDOW_TYPES } from './quota-window.js';
+import { TrafficSmoother } from './traffic-smoother.js';
 import { getLogger } from './logger.js';
 import { createSandboxService } from './sandbox-service.js';
 import { checkBudgetAndHealthAlerts } from './budget-monitor.js';
@@ -198,6 +199,7 @@ export function apply(ctx, config = {}) {
   const webhookSender = new WebhookSender({ fetchImpl: globalThis.fetch });
   const alertDebouncer = new AlertDebouncer({ sender: webhookSender, debounceMs: 2000 });
   const moduleNotifyQueue = new NotifyQueue({ send: (url, payload) => alertDebouncer.enqueue(url, payload) });
+  const trafficSmoother = new TrafficSmoother({ maxQueueWaitMs: 800 });
 
   const sandboxService = createSandboxService({ getRuntime: () => buildRuntime() });
   const { ensureSandboxRunner, probeRef, lastTestCache } = sandboxService;
@@ -355,7 +357,7 @@ export function apply(ctx, config = {}) {
       switchNotifyThrottleMs: cfg.switchNotifyThrottleMs ?? 60000,
       warnBelowHealthy: cfg.warnBelowHealthy ?? 0, latencySloMs: cfg.latencySloMs ?? 0,
       index, pools,
-      breaker: moduleBreaker, notifyQueue: moduleNotifyQueue, concurrencyTracker, quotaStore, latencyHistogram,
+      breaker: moduleBreaker, notifyQueue: moduleNotifyQueue, concurrencyTracker, quotaStore, latencyHistogram, trafficSmoother,
       providerTags, providerBudgets, poolByRef, providerToPool, modelPoolByProvider,
       cloneIds, expectedClones,
       circuitBreakerEnabled: cfg.circuitBreakerEnabled ?? true,
@@ -434,6 +436,7 @@ export function apply(ctx, config = {}) {
     MARKER,
     finishError,
     setRotateStartMs: (v) => { _rotateStartMs = v; },
+    trafficSmoother,
     quotaStore,
     circuitBreaker: moduleBreaker,
     now: nowMono,

package/lib/ops-keys.js

@@ -22,7 +22,9 @@ import {
   DRAIN_PATH,
   DISCOVER_PATH,
   AUTO_IMPORT_PATH,
+  PRESET_LIMITS_PATH,
 } from './ops-paths.js';
+import { lookupPreset, CANONICAL_PROVIDER_PRESETS } from './provider-limits-detector.js';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -539,4 +541,40 @@ ctx.effect(() => ctx.webServer.register({
   },
 }), 'dsh-key-rotation: auto-import route');
 
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: PRESET_LIMITS_PATH,
+    handler: async (req, res) => {
+      if (!isTrustedBridgeRequest(req)) {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'Forbidden' }));
+        return;
+      }
+      if (req.method === 'GET') {
+        const urlObj = new URL(req.url, 'http://127.0.0.1');
+        const prov = urlObj.searchParams.get('provider');
+        if (prov) {
+          const preset = lookupPreset(prov);
+          json(res, 200, { ok: true, provider: prov, preset });
+          return;
+        }
+        json(res, 200, { ok: true, presets: CANONICAL_PROVIDER_PRESETS });
+        return;
+      }
+      if (req.method === 'POST') {
+        const body = await readJson(req);
+        const prov = body?.provider;
+        const preset = lookupPreset(prov);
+        if (!preset) {
+          json(res, 404, { ok: false, error: `No canonical preset found for provider '${prov}'` });
+          return;
+        }
+        json(res, 200, { ok: true, provider: prov, preset });
+        return;
+      }
+      res.writeHead(405, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed' }));
+    },
+  }), 'dsh-key-rotation: preset limits route');
+
 }

package/lib/ops-paths.js

@@ -17,3 +17,4 @@ export const DRAIN_PATH = '/dsh-key-rotation/drain';
 export const TEST_MATRIX_PATH = '/dsh-key-rotation/test-matrix';
 export const DISCOVER_PATH = '/dsh-key-rotation/discover';
 export const AUTO_IMPORT_PATH = '/dsh-key-rotation/auto-import';
+export const PRESET_LIMITS_PATH = '/dsh-key-rotation/preset-limits';

package/lib/ops-status.js

@@ -123,6 +123,7 @@ ctx.effect(() => ctx.webServer.register({
           pauseReason: pool.state.pauseReasons?.get?.(ref) ?? null,
           revoked: isKeyRevoked(pool, ref),
           modelCapabilities: pool.state.modelCapabilities?.get?.(ref) ? [...pool.state.modelCapabilities.get(ref)] : null,
+          detectedLimits: pool.state.detectedLimits?.get?.(ref) ?? null,
           modelQuota,
           modelPools: activeModelPools.map(mp => mp.base),
         });
@@ -172,6 +173,7 @@ ctx.effect(() => ctx.webServer.register({
         pauseOnBudget: (providerBudgets?.get ? providerBudgets.get(pool.base) : providerBudgets?.[pool.base])?.pauseOnBudget ?? false,
         routingStrategy: pool.routingStrategy ?? runtime.routingStrategy ?? 'round-robin',
         proactiveRateLimitGuard: pool.proactiveRateLimitGuard ?? runtime.proactiveRateLimitGuard ?? true,
+        smoothedRequests: pool.state.smoothedRequests ?? 0,
       });
       } 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/pool-builder.js

@@ -37,6 +37,8 @@ export function buildPoolItem({
   labels = null,
   pinnedRef = null,
   useKeyRef = null,
+  trafficSmoothingBurst = null,
+  maxQueueWaitMs = null,
 }) {
   const seen = new Set();
   const indexed = (Array.isArray(keys) ? keys : []).map((key, index) => ({ ref: typeof key === 'string' ? key.trim() : '', index }))
@@ -135,6 +137,12 @@ const weightsMap = {};
     proactiveRateLimitGuard: poolGuard,
     labels: labelsMap,
     pinnedRef: cleanPinned,
+    trafficSmoothingBurst: typeof trafficSmoothingBurst === 'number' && Number.isFinite(trafficSmoothingBurst) && trafficSmoothingBurst > 0
+      ? Math.floor(trafficSmoothingBurst)
+      : (typeof rpmLimit === 'number' && rpmLimit > 0 ? Math.max(2, Math.ceil(rpmLimit / 12)) : 5),
+    maxQueueWaitMs: typeof maxQueueWaitMs === 'number' && Number.isFinite(maxQueueWaitMs) && maxQueueWaitMs >= 0
+      ? Math.floor(maxQueueWaitMs)
+      : 800,
   };
 }
 
@@ -175,6 +183,8 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
       model: null,
       labels: p.labels,
       pinnedRef: p.pinnedRef ?? p.useKeyRef,
+      trafficSmoothingBurst: p.trafficSmoothingBurst ?? cfg.trafficSmoothingBurst,
+      maxQueueWaitMs: p.maxQueueWaitMs ?? cfg.maxQueueWaitMs,
     }, provRpm, provTpm, provConcurrency);
     if (pool) {
       for (const ref of pool.refs) {
@@ -203,6 +213,8 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
         quotas: mp.quotas,
         labels: mp.labels ?? p.labels,
         pinnedRef: mp.pinnedRef ?? mp.useKeyRef ?? p.pinnedRef ?? p.useKeyRef,
+        trafficSmoothingBurst: mp.trafficSmoothingBurst ?? p.trafficSmoothingBurst ?? cfg.trafficSmoothingBurst,
+        maxQueueWaitMs: mp.maxQueueWaitMs ?? p.maxQueueWaitMs ?? cfg.maxQueueWaitMs,
       }, modelRpm, modelTpm, modelConcurrency);
       if (!mpool) continue;
       mpool.basePool = pool;

package/lib/pool-state.js

@@ -3,7 +3,7 @@
 const MAP_FIELDS = [
   'failedUntil', 'failCounts', 'authFailCounts', 'brokenUntil', 'costPerKey',
   'lastUsedAt', 'usageCounts', 'byModel', 'usageDays', 'quotaWindows', 'costDays',
-  'tokenUsage', 'rpmWindows', 'tpmWindows', 'sessionSticky', 'modelCapabilities', 'pauseReasons',
+  'tokenUsage', 'rpmWindows', 'tpmWindows', 'sessionSticky', 'modelCapabilities', 'pauseReasons', 'detectedLimits',
 ];
 
 const SET_FIELDS = ['pausedRefs', 'revokedRefs'];

package/lib/provider-limits-detector.js

@@ -0,0 +1,173 @@
+// lib/provider-limits-detector.js — accurate dynamic provider limits and presets (#503).
+
+export const CANONICAL_PROVIDER_PRESETS = {
+  deepseek: {
+    rpmLimit: 60,
+    tpmLimit: 100000,
+    trafficSmoothingBurst: 5,
+    quotaResetWindow: 'midnight_utc',
+    displayName: 'DeepSeek Official',
+  },
+  groq: {
+    rpmLimit: 30,
+    tpmLimit: 30000,
+    trafficSmoothingBurst: 5,
+    quotaResetWindow: 'per-minute',
+    displayName: 'Groq Cloud',
+  },
+  opencode: {
+    rpmLimit: 120,
+    tpmLimit: 200000,
+    trafficSmoothingBurst: 10,
+    quotaResetWindow: 'midnight_utc',
+    displayName: 'OpenCode Zen',
+  },
+  anthropic: {
+    rpmLimit: 50,
+    tpmLimit: 100000,
+    trafficSmoothingBurst: 5,
+    quotaResetWindow: 'per-minute',
+    displayName: 'Anthropic Claude',
+  },
+  openai: {
+    rpmLimit: 60,
+    tpmLimit: 150000,
+    trafficSmoothingBurst: 10,
+    quotaResetWindow: 'per-minute',
+    displayName: 'OpenAI API',
+  },
+  siliconflow: {
+    rpmLimit: 60,
+    tpmLimit: 100000,
+    trafficSmoothingBurst: 5,
+    quotaResetWindow: 'per-minute',
+    displayName: 'SiliconFlow',
+  },
+  mistral: {
+    rpmLimit: 60,
+    tpmLimit: 100000,
+    trafficSmoothingBurst: 5,
+    quotaResetWindow: 'per-minute',
+    displayName: 'Mistral AI',
+  },
+  gemini: {
+    rpmLimit: 60,
+    tpmLimit: 1000000,
+    trafficSmoothingBurst: 10,
+    quotaResetWindow: 'midnight_pst',
+    displayName: 'Google Gemini',
+  },
+  openrouter: {
+    rpmLimit: 200,
+    tpmLimit: 500000,
+    trafficSmoothingBurst: 15,
+    quotaResetWindow: 'per-minute',
+    displayName: 'OpenRouter',
+  },
+};
+
+/**
+ * Extract rate limit and quota information from HTTP response headers.
+ * @param {Headers|Record<string, string>} rawHeaders
+ * @returns {object|null}
+ */
+export function extractProviderLimits(rawHeaders) {
+  if (!rawHeaders) return null;
+  const headers = {};
+  if (typeof rawHeaders.forEach === 'function') {
+    rawHeaders.forEach((val, key) => { headers[key.toLowerCase()] = String(val); });
+  } else if (typeof rawHeaders === 'object') {
+    for (const [k, v] of Object.entries(rawHeaders)) {
+      if (typeof k === 'string') headers[k.toLowerCase()] = String(v ?? '');
+    }
+  }
+
+  const getNum = (...names) => {
+    for (const name of names) {
+      const val = headers[name];
+      if (val !== undefined && val !== null && val !== '') {
+        const n = Number(val);
+        if (Number.isFinite(n) && n >= 0) return n;
+      }
+    }
+    return undefined;
+  };
+
+  const getSeconds = (...names) => {
+    for (const name of names) {
+      const val = headers[name];
+      if (!val) continue;
+      const str = String(val).trim();
+      // Duration string format "6m0s", "1s", "250ms"
+      const match = /^(\d+(?:\.\d+)?)(s|ms|m|h)?$/i.exec(str);
+      if (match) {
+        const num = parseFloat(match[1]);
+        const unit = (match[2] || 's').toLowerCase();
+        if (unit === 'ms') return Math.max(0.001, num / 1000);
+        if (unit === 's') return num;
+        if (unit === 'm') return num * 60;
+        if (unit === 'h') return num * 3600;
+      }
+      // Check for ISO Date string (e.g., Anthropic reset timestamp)
+      const parsedDate = Date.parse(str);
+      if (Number.isFinite(parsedDate)) {
+        const diffSec = (parsedDate - Date.now()) / 1000;
+        return Math.max(0, diffSec);
+      }
+      const n = Number(str);
+      if (Number.isFinite(n) && n >= 0) return n;
+    }
+    return undefined;
+  };
+
+  const rpmLimit = getNum('x-ratelimit-limit-requests', 'x-ratelimit-limit-rpm', 'ratelimit-limit', 'anthropic-ratelimit-requests-limit');
+  const tpmLimit = getNum('x-ratelimit-limit-tokens', 'x-ratelimit-limit-tpm', 'anthropic-ratelimit-tokens-limit');
+  const remainingRequests = getNum('x-ratelimit-remaining-requests', 'x-ratelimit-remaining', 'anthropic-ratelimit-requests-remaining');
+  const remainingTokens = getNum('x-ratelimit-remaining-tokens', 'anthropic-ratelimit-tokens-remaining');
+  const resetRequests = getSeconds('x-ratelimit-reset-requests', 'x-ratelimit-reset', 'anthropic-ratelimit-requests-reset');
+  const resetTokens = getSeconds('x-ratelimit-reset-tokens', 'anthropic-ratelimit-tokens-reset');
+  const retryAfter = getSeconds('retry-after');
+
+  if (rpmLimit === undefined && tpmLimit === undefined && remainingRequests === undefined && remainingTokens === undefined && resetRequests === undefined && retryAfter === undefined) {
+    return null;
+  }
+
+  const out = {};
+  if (rpmLimit !== undefined) out.rpmLimit = Math.floor(rpmLimit);
+  if (tpmLimit !== undefined) out.tpmLimit = Math.floor(tpmLimit);
+  if (remainingRequests !== undefined) {
+    out.remainingRequests = Math.floor(remainingRequests);
+    out.rpmRemaining = out.remainingRequests;
+  }
+  if (remainingTokens !== undefined) {
+    out.remainingTokens = Math.floor(remainingTokens);
+    out.tpmRemaining = out.remainingTokens;
+  }
+  if (resetRequests !== undefined) {
+    out.resetRequests = resetRequests;
+    out.rpmResetMs = Math.round(resetRequests * 1000);
+  }
+  if (resetTokens !== undefined) {
+    out.resetTokens = resetTokens;
+    out.tpmResetMs = Math.round(resetTokens * 1000);
+  }
+  if (retryAfter !== undefined) {
+    out.retryAfterMs = Math.round(retryAfter * 1000);
+  }
+
+  return out;
+}
+
+/**
+ * Match a configured provider name to canonical preset.
+ * @param {string} providerName
+ * @returns {object|null}
+ */
+export function lookupPreset(providerName) {
+  if (!providerName || typeof providerName !== 'string') return null;
+  const p = providerName.toLowerCase().replace(/[^a-z0-9]/g, '');
+  for (const [key, val] of Object.entries(CANONICAL_PROVIDER_PRESETS)) {
+    if (p.includes(key)) return { ...val, id: key };
+  }
+  return null;
+}

package/lib/rotate.js

@@ -35,6 +35,7 @@ import {
 } from './model-quota.js';
 
 import { LOCAL_POOL_EXHAUSTED_CODE } from './resolver.js';
+import { extractProviderLimits } from './provider-limits-detector.js';
 
 export const LOCAL_QUOTA_CODE = 'LOCAL_MODEL_QUOTA_EXHAUSTED';
 
@@ -79,6 +80,7 @@ export function createRotate(deps) {
     circuitBreaker,
     logger,
     schedulePersist,
+    trafficSmoother,
     now = nowMono,
   } = deps;
 
@@ -318,6 +320,25 @@ export function createRotate(deps) {
       };
 
       for (let attempt = 0; attempt < attemptList.length; attempt++) {
+        const candidateRef = attemptList[attempt];
+        // #496: Traffic smoothing micro-queue
+        const smoother = pool.trafficSmoother ?? runtime0.trafficSmoother ?? trafficSmoother;
+        if (smoother && candidateRef) {
+          const smoothRes = await smoother.acquire(candidateRef, {
+            rpmLimit: pool.rpmLimit,
+            burstLimit: pool.trafficSmoothingBurst,
+            maxQueueWaitMs: pool.maxQueueWaitMs,
+            signal: options.signal,
+          });
+          if (smoothRes.overflow) {
+            logWarn(`[dsh-key-rotation] ${options.provider}: key ${candidateRef} micro-queue burst overflow (${smoothRes.delayMs}ms) — rotating to next candidate`);
+            continue;
+          }
+          if (smoothRes.delayed) {
+            pool.state.smoothedRequests = (pool.state.smoothedRequests ?? 0) + 1;
+            pushEvent(pool, candidateRef, 'TRAFFIC_SMOOTHED', smoothRes.delayMs);
+          }
+        }
         // #464: Check deadline & attempt budget before dispatch
         if (!budget.canAttempt()) {
           const isTimeout = budget.isExpired();
@@ -506,6 +527,15 @@ export function createRotate(deps) {
                   // Proactive rate-limit (#115, #303): if response headers say this key is near
                   // its quota or has retry-after, cool it down so the NEXT request starts on a different key.
                   // We do NOT re-run this (already successful) request — that would double-send.
+                  // #503: Extract provider limits and reset headers
+                  const rawHdrs = chunk?.metadata?.headers ?? chunk?.headers;
+                  if (rawHdrs && activeRef) {
+                    const detected = extractProviderLimits(rawHdrs);
+                    if (detected) {
+                      if (!pool.state.detectedLimits) pool.state.detectedLimits = new Map();
+                      pool.state.detectedLimits.set(activeRef, { ...detected, at: now() });
+                    }
+                  }
                   const guardEnabled = pool.proactiveRateLimitGuard ?? runtime0.proactiveRateLimitGuard ?? true;
                   const rate = extractRateLimit(chunk?.metadata?.headers ?? chunk?.headers);
                   if (guardEnabled && rate && activeRef) {

package/lib/traffic-smoother.js

@@ -0,0 +1,96 @@
+// lib/traffic-smoother.js — leaky bucket micro-queue traffic smoother (#496).
+// Absorbs momentary request bursts without tripping upstream per-second/per-minute rate limits.
+
+export class TrafficSmoother {
+  constructor({ maxQueueWaitMs = 800, now = Date.now, sleep = null } = {}) {
+    this.maxQueueWaitMs = maxQueueWaitMs;
+    this.now = now;
+    this.sleep = sleep || ((ms, signal) => new Promise((resolve, reject) => {
+      if (signal?.aborted) return reject(signal.reason ?? new Error('aborted'));
+      const timer = setTimeout(resolve, ms);
+      if (signal) {
+        signal.addEventListener('abort', () => {
+          clearTimeout(timer);
+          reject(signal.reason ?? new Error('aborted'));
+        }, { once: true });
+      }
+    }));
+    // Map<ref, { lastTime: number, tokens: number, lastUpdate: number }>
+    this._buckets = new Map();
+  }
+
+  /**
+   * Acquire a slot for `ref` given effective RPM or burst limits.
+   * @param {string} ref
+   * @param {object} opts { rpmLimit, burstLimit, maxQueueWaitMs, signal }
+   * @returns {Promise<{ allowed: boolean, delayed: boolean, delayMs: number, overflow: boolean }>}
+   */
+  async acquire(ref, { rpmLimit, burstLimit, maxQueueWaitMs, signal } = {}) {
+    if (!ref) {
+      return { allowed: true, delayed: false, delayMs: 0, overflow: false };
+    }
+    const maxWait = typeof maxQueueWaitMs === 'number' && maxQueueWaitMs >= 0 ? maxQueueWaitMs : this.maxQueueWaitMs;
+    const effectiveRpm = Number(rpmLimit) > 0 ? Number(rpmLimit) : 0;
+    if (effectiveRpm <= 0) {
+      return { allowed: true, delayed: false, delayMs: 0, overflow: false };
+    }
+
+    const capacity = Number(burstLimit) > 0
+      ? Math.floor(burstLimit)
+      : Math.max(2, Math.ceil(effectiveRpm / 12));
+
+    const ratePerSec = effectiveRpm / 60; // tokens per second
+    const intervalMs = Math.max(1, 1000 / ratePerSec); // ms between tokens
+    const curNow = this.now();
+
+    let bucket = this._buckets.get(ref);
+    if (!bucket) {
+      bucket = { tokens: capacity, lastUpdate: curNow, nextSlot: curNow };
+      this._buckets.set(ref, bucket);
+    }
+
+    // Replenish tokens based on elapsed time
+    const elapsed = Math.max(0, curNow - bucket.lastUpdate);
+    const addedTokens = elapsed * (ratePerSec / 1000);
+    bucket.tokens = Math.min(capacity, bucket.tokens + addedTokens);
+    bucket.lastUpdate = curNow;
+
+    if (bucket.tokens >= 1) {
+      bucket.tokens -= 1;
+      bucket.nextSlot = Math.max(curNow, bucket.nextSlot);
+      return { allowed: true, delayed: false, delayMs: 0, overflow: false };
+    }
+
+    // Burst is exhausted: calculate delay required for next available slot
+    const targetSlot = Math.max(curNow, bucket.nextSlot) + intervalMs;
+    const delayMs = Math.max(0, targetSlot - curNow);
+
+    if (delayMs > maxWait) {
+      // Exceeds max micro-queue wait: signal overflow so caller rotates to next candidate
+      return { allowed: false, delayed: false, delayMs, overflow: true };
+    }
+
+    bucket.nextSlot = targetSlot;
+
+    // Wait for the scheduled slot
+    await this.sleep(delayMs, signal);
+
+    return { allowed: true, delayed: true, delayMs, overflow: false };
+  }
+
+  getQueueDepth(ref) {
+    if (!ref) return this._buckets.size;
+    const b = this._buckets.get(ref);
+    if (!b) return 0;
+    const curNow = this.now();
+    const wait = Math.max(0, b.nextSlot - curNow);
+    return wait > 0 ? Math.ceil(wait / 100) : 0;
+  }
+
+  clear(ref) {
+    if (ref) this._buckets.delete(ref);
+    else this._buckets.clear();
+  }
+}
+
+export default TrafficSmoother;

package/package.json

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