@goodandready/dsh-key-rotation 0.8.85 → 0.8.86

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.8.86 (2026-11-03)
+
+### Pre-emptive Token & Request Yield before 429 (Block 13 Release)
+- **Pre-emptive Yield Module (Issue #571)**: Introduced `src/preemptive-yield.js` to evaluate active token and request headroom across provider keys using upstream `x-ratelimit-remaining-tokens`, `x-ratelimit-remaining-requests`, and reset window headers (`x-ratelimit-reset-tokens`).
+- **Zero-Round-Trip Proactive Rotation**: Keys with low token balance (`< preemptiveSafetyMarginTokens`, default: 4000) or low request count (`<= preemptiveSafetyMarginRequests`, default: 2) yield execution priority to candidate keys with ample quota before any HTTP `429 Too Many Requests` or `insufficient_quota` failure occurs.
+- **Graceful Degradation & Reset Recovery**: When upstream reset windows expire, capacity automatically restores to full priority. If all candidate keys in a pool are running on low quota, requests proceed using the key with highest remaining tokens or soonest reset time, avoiding false exhaustion.
+- **Config & Schemastery Support**: Added `preemptiveRotationEnabled`, `preemptiveSafetyMarginTokens`, and `preemptiveSafetyMarginRequests` across Schemastery configuration, pool builders, and TypeScript types.
+
 ## 0.8.85 (2026-11-03)
 
 ### Inter-Token Stall & Zombie Stream Detector (Block 12 Release)

package/lib/index.js

@@ -140,6 +140,9 @@ const SettingsSchema = Schema.object({
   stallDetectionEnabled: Schema.boolean().default(true),
   stallTimeoutMs: Schema.number().default(15000),
   stallInitialTimeoutMs: Schema.number().default(30000),
+  preemptiveRotationEnabled: Schema.boolean().default(true),
+  preemptiveSafetyMarginTokens: Schema.number().default(4000),
+  preemptiveSafetyMarginRequests: Schema.number().default(2),
   providers: Schema.array(Schema.object({
     provider: Schema.string().required(),
     keys: Schema.array(Schema.string()).default([]),
@@ -172,6 +175,9 @@ const SettingsSchema = Schema.object({
     stallDetectionEnabled: Schema.boolean(),
     stallTimeoutMs: Schema.number(),
     stallInitialTimeoutMs: Schema.number(),
+    preemptiveRotationEnabled: Schema.boolean(),
+    preemptiveSafetyMarginTokens: Schema.number(),
+    preemptiveSafetyMarginRequests: Schema.number(),
   })).default([...DEFAULT_PROVIDERS]),
 });
 

package/lib/pool-builder.js

@@ -44,6 +44,9 @@ export function buildPoolItem({
   stallDetectionEnabled = true,
   stallTimeoutMs = 15000,
   stallInitialTimeoutMs = 30000,
+  preemptiveRotationEnabled = true,
+  preemptiveSafetyMarginTokens = 4000,
+  preemptiveSafetyMarginRequests = 2,
 }) {
   const seen = new Set();
   const indexed = (Array.isArray(keys) ? keys : []).map((key, index) => ({ ref: typeof key === 'string' ? key.trim() : '', index }))
@@ -157,6 +160,12 @@ const weightsMap = {};
     stallDetectionEnabled: stallDetectionEnabled ?? true,
     stallTimeoutMs: typeof stallTimeoutMs === 'number' && Number.isFinite(stallTimeoutMs) && stallTimeoutMs > 0 ? Math.floor(stallTimeoutMs) : 15000,
     stallInitialTimeoutMs: typeof stallInitialTimeoutMs === 'number' && Number.isFinite(stallInitialTimeoutMs) && stallInitialTimeoutMs > 0 ? Math.floor(stallInitialTimeoutMs) : 30000,
+    preemptiveRotationEnabled: preemptiveRotationEnabled ?? true,
+    preemptiveSafetyMarginTokens: typeof preemptiveSafetyMarginTokens === 'number' && Number.isFinite(preemptiveSafetyMarginTokens) && preemptiveSafetyMarginTokens >= 0 ? Math.floor(preemptiveSafetyMarginTokens) : 4000,
+    preemptiveSafetyMarginRequests: typeof preemptiveSafetyMarginRequests === 'number' && Number.isFinite(preemptiveSafetyMarginRequests) && preemptiveSafetyMarginRequests >= 0 ? Math.floor(preemptiveSafetyMarginRequests) : 2,
+    preemptiveRotationEnabled: preemptiveRotationEnabled ?? true,
+    preemptiveSafetyMarginTokens: typeof preemptiveSafetyMarginTokens === 'number' && Number.isFinite(preemptiveSafetyMarginTokens) && preemptiveSafetyMarginTokens >= 0 ? Math.floor(preemptiveSafetyMarginTokens) : 4000,
+    preemptiveSafetyMarginRequests: typeof preemptiveSafetyMarginRequests === 'number' && Number.isFinite(preemptiveSafetyMarginRequests) && preemptiveSafetyMarginRequests >= 0 ? Math.floor(preemptiveSafetyMarginRequests) : 2,
   };
 }
 
@@ -207,6 +216,12 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
       stallDetectionEnabled: p.stallDetectionEnabled ?? cfg.stallDetectionEnabled ?? true,
       stallTimeoutMs: p.stallTimeoutMs ?? cfg.stallTimeoutMs ?? 15000,
       stallInitialTimeoutMs: p.stallInitialTimeoutMs ?? cfg.stallInitialTimeoutMs ?? 30000,
+      preemptiveRotationEnabled: p.preemptiveRotationEnabled ?? cfg.preemptiveRotationEnabled ?? true,
+      preemptiveSafetyMarginTokens: p.preemptiveSafetyMarginTokens ?? cfg.preemptiveSafetyMarginTokens ?? 4000,
+      preemptiveSafetyMarginRequests: p.preemptiveSafetyMarginRequests ?? cfg.preemptiveSafetyMarginRequests ?? 2,
+      preemptiveRotationEnabled: p.preemptiveRotationEnabled ?? cfg.preemptiveRotationEnabled ?? true,
+      preemptiveSafetyMarginTokens: p.preemptiveSafetyMarginTokens ?? cfg.preemptiveSafetyMarginTokens ?? 4000,
+      preemptiveSafetyMarginRequests: p.preemptiveSafetyMarginRequests ?? cfg.preemptiveSafetyMarginRequests ?? 2,
     }, provRpm, provTpm, provConcurrency);
     if (pool) {
       for (const ref of pool.refs) {
@@ -242,6 +257,12 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
         stallDetectionEnabled: mp.stallDetectionEnabled ?? p.stallDetectionEnabled ?? cfg.stallDetectionEnabled ?? true,
         stallTimeoutMs: mp.stallTimeoutMs ?? p.stallTimeoutMs ?? cfg.stallTimeoutMs ?? 15000,
         stallInitialTimeoutMs: mp.stallInitialTimeoutMs ?? p.stallInitialTimeoutMs ?? cfg.stallInitialTimeoutMs ?? 30000,
+        preemptiveRotationEnabled: mp.preemptiveRotationEnabled ?? p.preemptiveRotationEnabled ?? cfg.preemptiveRotationEnabled ?? true,
+        preemptiveSafetyMarginTokens: mp.preemptiveSafetyMarginTokens ?? p.preemptiveSafetyMarginTokens ?? cfg.preemptiveSafetyMarginTokens ?? 4000,
+        preemptiveSafetyMarginRequests: mp.preemptiveSafetyMarginRequests ?? p.preemptiveSafetyMarginRequests ?? cfg.preemptiveSafetyMarginRequests ?? 2,
+        preemptiveRotationEnabled: mp.preemptiveRotationEnabled ?? p.preemptiveRotationEnabled ?? cfg.preemptiveRotationEnabled ?? true,
+        preemptiveSafetyMarginTokens: mp.preemptiveSafetyMarginTokens ?? p.preemptiveSafetyMarginTokens ?? cfg.preemptiveSafetyMarginTokens ?? 4000,
+        preemptiveSafetyMarginRequests: mp.preemptiveSafetyMarginRequests ?? p.preemptiveSafetyMarginRequests ?? cfg.preemptiveSafetyMarginRequests ?? 2,
       }, modelRpm, modelTpm, modelConcurrency);
       if (!mpool) continue;
       mpool.basePool = pool;

package/lib/preemptive-yield.js

@@ -0,0 +1,129 @@
+// src/preemptive-yield.js — Pre-emptive Token & Request Yield before 429 (#571).
+// Pure module: zero runtime dependencies, strictly < 600 lines.
+
+export const DEFAULT_PREEMPTIVE_SAFETY_MARGIN_TOKENS = 4000;
+export const DEFAULT_PREEMPTIVE_SAFETY_MARGIN_REQUESTS = 2;
+
+/**
+ * Evaluates whether a key has low remaining quota and should yield to other candidates.
+ * @param {object} pool - Pool definition carrying state
+ * @param {string} ref - Key reference
+ * @param {object} [options]
+ * @param {number} [options.now] - Current timestamp in ms
+ * @param {number} [options.safetyMarginTokens]
+ * @param {number} [options.safetyMarginRequests]
+ * @param {boolean} [options.enabled]
+ * @returns {{ yielding: boolean, reason?: string, remainingTokens?: number, remainingRequests?: number, resetInMs?: number }}
+ */
+export function isPreemptiveYielding(pool, ref, options = {}) {
+  const enabled = options.enabled ?? pool?.preemptiveRotationEnabled ?? true;
+  if (!enabled || !pool || !ref) return { yielding: false };
+
+  const limits = pool.state?.detectedLimits?.get?.(ref);
+  if (!limits) return { yielding: false };
+
+  const now = options.now ?? Date.now();
+  const recordedAt = limits.at || now;
+
+  // Window reset calculation
+  const resetMs = limits.tpmResetMs || limits.rpmResetMs || (typeof limits.resetTokens === 'number' ? limits.resetTokens * 1000 : (typeof limits.resetRequests === 'number' ? limits.resetRequests * 1000 : 0));
+
+  if (resetMs > 0 && now >= recordedAt + resetMs) {
+    // Window has already passed and refreshed upstream
+    return { yielding: false };
+  }
+
+  const remainingTokens = limits.remainingTokens ?? limits.tpmRemaining;
+  const remainingRequests = limits.remainingRequests ?? limits.rpmRemaining;
+
+  const marginTokens = options.safetyMarginTokens ?? pool.preemptiveSafetyMarginTokens ?? DEFAULT_PREEMPTIVE_SAFETY_MARGIN_TOKENS;
+  const marginRequests = options.safetyMarginRequests ?? pool.preemptiveSafetyMarginRequests ?? DEFAULT_PREEMPTIVE_SAFETY_MARGIN_REQUESTS;
+
+  const lowTokens = typeof remainingTokens === 'number' && remainingTokens < marginTokens;
+  const lowRequests = typeof remainingRequests === 'number' && remainingRequests <= marginRequests;
+
+  if (lowTokens || lowRequests) {
+    const resetInMs = resetMs > 0 ? Math.max(0, (recordedAt + resetMs) - now) : 0;
+    return {
+      yielding: true,
+      reason: lowTokens ? `LOW_REMAINING_TOKENS (${remainingTokens} < ${marginTokens})` : `LOW_REMAINING_REQUESTS (${remainingRequests} <= ${marginRequests})`,
+      remainingTokens,
+      remainingRequests,
+      resetInMs,
+    };
+  }
+
+  return { yielding: false, remainingTokens, remainingRequests };
+}
+
+/**
+ * Reorders candidate attempts list so that keys with ample token/request headroom
+ * are attempted first, while yielding keys yield priority.
+ * Gracefully degrades if all candidate keys are low on headroom.
+ * @param {string[]} attemptList
+ * @param {object} pool
+ * @param {object} [options]
+ * @returns {string[]}
+ */
+export function applyPreemptiveYield(attemptList, pool, options = {}) {
+  if (!Array.isArray(attemptList) || attemptList.length <= 1 || !pool) {
+    return (attemptList ?? []).slice();
+  }
+
+  const enabled = options.enabled ?? pool.preemptiveRotationEnabled ?? true;
+  if (!enabled) return attemptList.slice();
+
+  const now = options.now ?? Date.now();
+  const ample = [];
+  const yielding = [];
+
+  for (const ref of attemptList) {
+    // Pinned keys stay first if explicitly configured and not overridden
+    if (ref === pool.pinnedRef && options.preservePinned !== false) {
+      ample.push({ ref, info: { yielding: false } });
+      continue;
+    }
+
+    const info = isPreemptiveYielding(pool, ref, { ...options, now });
+    if (info.yielding) {
+      yielding.push({ ref, info });
+      if (options.trace && typeof options.trace.addStep === 'function') {
+        options.trace.addStep(ref, 'DEPRIORITIZED', 'PREEMPTIVE_YIELD', info.reason);
+      }
+      if (options.pushEvent && typeof options.pushEvent === 'function') {
+        options.pushEvent(pool, ref, 'PREEMPTIVE_YIELD', info);
+      }
+    } else {
+      ample.push({ ref, info });
+    }
+  }
+
+  if (yielding.length === 0) {
+    return attemptList.slice();
+  }
+
+  // Record yield counter in pool state
+  if (pool.state) {
+    pool.state.preemptiveYields = (pool.state.preemptiveYields ?? 0) + yielding.length;
+  }
+
+  // Sort yielding keys among themselves: highest remaining tokens first, then soonest reset
+  yielding.sort((a, b) => {
+    const ta = a.info.remainingTokens ?? -1;
+    const tb = b.info.remainingTokens ?? -1;
+    if (ta !== tb) return tb - ta; // Descending tokens
+    const ra = a.info.resetInMs ?? Infinity;
+    const rb = b.info.resetInMs ?? Infinity;
+    return ra - rb; // Ascending reset duration (soonest reset first)
+  });
+
+  if (ample.length === 0) {
+    // Graceful degradation: all keys are yielding; pick the best yielding key first
+    if (options.logWarn && typeof options.logWarn === 'function') {
+      options.logWarn(`[dsh-key-rotation] ${pool.provider ?? '-'}: all candidate keys are yielding (low quota) — proceeding with highest remaining headroom`);
+    }
+    return yielding.map(y => y.ref);
+  }
+
+  return ample.map(a => a.ref).concat(yielding.map(y => y.ref));
+}

package/lib/resolver.js

@@ -11,6 +11,7 @@
 import { bucketAllow, bucketRetryMs, tpmAllow, tpmRetryMs } from './bucket.js';
 import { envValue, sortAttemptList, isKeyPaused, isKeyRevoked, isKeyBroken, costForDay, costForWeek, budgetVerdict, getSessionSticky, setSessionSticky } from './pool.js';
 import { decryptSecret } from './crypto-storage.js';
+import { applyPreemptiveYield } from './preemptive-yield.js';
 import { resolveRefPool, isQuotaManagedRequest, providerOfBase, basePoolForBase } from './pool-index.js';
 import {
   isModelQuotaAvailable,
@@ -132,6 +133,8 @@ export function createResolver({
         lastUsed: pool.state.lastUsed,
       });
     }
+    // Issue #571: Pre-emptive Token & Request Yield before 429
+    list = applyPreemptiveYield(list, pool, { now: Date.now() });
     // Fail closed: when this request is managed by a model pool that has local
     // token budgets, an exhausted candidate may not be dispatched and the
     // original credential must never be used as a bypass. Decided once, before

package/lib/rotate.js

@@ -27,6 +27,7 @@ import {
 import { LOCAL_POOL_EXHAUSTED_CODE, resolveKeyDirectly } from './resolver.js';
 import { recordStreamSuccessMetrics, preserveDispatchContext } from './stream-metrics.js';
 import { withStreamWatchdog, StreamStallError } from './stream-watchdog.js';
+import { applyPreemptiveYield } from './preemptive-yield.js';
 import { penalizeKey } from './rotate-penalty.js';
 import { recordPromptCache } from './prompt-cache.js';
 import { recordRequestOutcome, recordFailureCategory } from './ops-analytics.js';
@@ -203,6 +204,14 @@ export function createRotate(deps) {
         }
       }
 
+      // Issue #571: Pre-emptive Token & Request Yield before 429
+      attemptList = applyPreemptiveYield(attemptList, pool, {
+        now: wallNow,
+        trace,
+        pushEvent,
+        logWarn,
+      });
+
       const penalizeRef = (targetRef, errCode, errMsg, rawHeaders) => {
         penalizeKey(targetRef, errCode, errMsg, rawHeaders, {
           pool,

package/package.json

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