@goodandready/dsh-key-rotation 0.8.77 → 0.8.78

package/lib/quota-runway.js

@@ -0,0 +1,222 @@
+// lib/quota-runway.js — Predictive Quota Runway and burn rate estimation (#549).
+// Estimates time to quota exhaustion and preemptively rotates keys before hitting HTTP 429.
+
+export const MINUTE = 60 * 1000;
+export const HOUR = 60 * MINUTE;
+export const DAY = 24 * HOUR;
+
+export const DEFAULT_WINDOW_DURATIONS = {
+  minute: MINUTE,
+  fiveMinute: 5 * MINUTE,
+  hourly: HOUR,
+  daily: DAY,
+  monthly: 30 * DAY,
+};
+
+/**
+ * Bounds percentage value to [0, 100].
+ * @param {number|unknown} value
+ * @returns {number}
+ */
+export function clampPercent(value) {
+  const num = Number(value);
+  return Number.isFinite(num) ? Math.max(0, Math.min(100, num)) : 0;
+}
+
+/**
+ * Estimates when a quota window reaches 100% at the average burn rate observed.
+ *
+ * @param {object|undefined} window
+ * @param {number} window.percentUsed Current percentage used (0..100)
+ * @param {string|number} window.resetsAt ISO timestamp or epoch ms when window resets
+ * @param {number} durationMs Window duration in milliseconds
+ * @param {number} [now] Current epoch timestamp in milliseconds
+ * @returns {{
+ *   etaMs: number,
+ *   resetsAtMs: number,
+ *   exhaustsBeforeReset: boolean,
+ *   burnRatePerSec: number
+ * } | null}
+ */
+export function estimateRunway(window, durationMs, now = Date.now()) {
+  if (!window || window.resetsAt == null || !durationMs || durationMs <= 0) return null;
+
+  const resetsAtMs = typeof window.resetsAt === 'number' ? window.resetsAt : Date.parse(window.resetsAt);
+  if (!Number.isFinite(resetsAtMs) || resetsAtMs <= now) return null;
+
+  const used = clampPercent(window.percentUsed);
+  const timeToReset = resetsAtMs - now;
+
+  // Already 100% or more: exhausts immediately
+  if (used >= 100) {
+    return {
+      etaMs: 0,
+      resetsAtMs,
+      exhaustsBeforeReset: true,
+      burnRatePerSec: 0,
+    };
+  }
+
+  const startedAt = resetsAtMs - durationMs;
+  const elapsed = Math.max(1, now - startedAt);
+  const ratePerMs = used / elapsed;
+
+  if (!Number.isFinite(ratePerMs) || ratePerMs <= 0) {
+    return {
+      etaMs: Number.POSITIVE_INFINITY,
+      resetsAtMs,
+      exhaustsBeforeReset: false,
+      burnRatePerSec: 0,
+    };
+  }
+
+  const remainingPercent = 100 - used;
+  const etaMs = remainingPercent / ratePerMs;
+  const exhaustsBeforeReset = etaMs < timeToReset;
+  const burnRatePerSec = ratePerMs * 1000;
+
+  return {
+    etaMs,
+    resetsAtMs,
+    exhaustsBeforeReset,
+    burnRatePerSec,
+  };
+}
+
+/**
+ * Stateful Quota Runway tracker for credentials and pools.
+ */
+export class QuotaRunway {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.slidingWindowMs]
+   */
+  constructor(options = {}) {
+    this.slidingWindowMs = options.slidingWindowMs ?? (5 * MINUTE);
+    /** @type {Map<string, Array<{ at: number, amount: number }>>} */
+    this.samples = new Map();
+    /** @type {Map<string, { limit: number, remaining: number, resetsAtMs: number, durationMs: number }>} */
+    this.knownLimits = new Map();
+  }
+
+  /**
+   * Records usage tokens or requests for a key.
+   * @param {string} keyRef
+   * @param {number} amount
+   * @param {number} [now]
+   */
+  recordUsage(keyRef, amount, now = Date.now()) {
+    if (!keyRef || !amount || amount <= 0) return;
+    let list = this.samples.get(keyRef);
+    if (!list) {
+      list = [];
+      this.samples.set(keyRef, list);
+    }
+    list.push({ at: now, amount });
+    this._prune(keyRef, now);
+  }
+
+  /**
+   * Updates key limits detected from response headers or provider metadata.
+   * @param {string} keyRef
+   * @param {object} limits
+   * @param {number} [limits.limit]
+   * @param {number} [limits.remaining]
+   * @param {number|string} [limits.resetsAt]
+   * @param {number} [limits.durationMs]
+   * @param {number} [now]
+   */
+  updateLimits(keyRef, limits, now = Date.now()) {
+    if (!keyRef || !limits) return;
+    const limit = Number(limits.tpmLimit ?? limits.rpmLimit ?? limits.limit);
+    const remaining = Number(limits.remainingTokens ?? limits.remainingRequests ?? limits.remaining);
+    const resetSec = Number(limits.resetTokens ?? limits.resetRequests ?? limits.retryAfter);
+
+    let resetsAtMs = NaN;
+    if (Number.isFinite(resetSec)) {
+      resetsAtMs = now + (resetSec * 1000);
+    } else if (limits.resetsAt || limits.resetAt) {
+      const at = limits.resetsAt || limits.resetAt;
+      resetsAtMs = typeof at === 'number' ? at : Date.parse(at);
+    }
+
+    const durationMs = Number(limits.durationMs) || DEFAULT_WINDOW_DURATIONS.minute;
+
+    if (Number.isFinite(limit) && Number.isFinite(remaining) && Number.isFinite(resetsAtMs)) {
+      this.knownLimits.set(keyRef, {
+        limit,
+        remaining,
+        resetsAtMs,
+        durationMs,
+      });
+    }
+  }
+
+  /**
+   * Checks if key is projected to exhaust its quota before the current window resets.
+   * @param {string} keyRef
+   * @param {number} [now]
+   * @returns {boolean}
+   */
+  isExhaustingBeforeReset(keyRef, now = Date.now()) {
+    const assessment = this.assessRunway(keyRef, now);
+    return Boolean(assessment?.exhaustsBeforeReset);
+  }
+
+  /**
+   * Returns complete runway assessment for a key.
+   * @param {string} keyRef
+   * @param {number} [now]
+   * @returns {{
+   *   exhaustsBeforeReset: boolean,
+   *   etaMs: number,
+   *   burnRatePerSec: number,
+   *   timeToResetMs: number
+   * } | null}
+   */
+  assessRunway(keyRef, now = Date.now()) {
+    if (!keyRef) return null;
+
+    const limits = this.knownLimits.get(keyRef);
+    if (!limits || limits.resetsAtMs <= now) {
+      return null;
+    }
+
+    const { limit, remaining, resetsAtMs, durationMs } = limits;
+    if (limit <= 0) return null;
+
+    const used = Math.max(0, limit - remaining);
+    const percentUsed = (used / limit) * 100;
+
+    const estimate = estimateRunway(
+      { percentUsed, resetsAt: resetsAtMs },
+      durationMs,
+      now,
+    );
+
+    if (!estimate) return null;
+
+    return {
+      exhaustsBeforeReset: estimate.exhaustsBeforeReset,
+      etaMs: estimate.etaMs,
+      burnRatePerSec: estimate.burnRatePerSec,
+      timeToResetMs: resetsAtMs - now,
+    };
+  }
+
+  _prune(keyRef, now) {
+    const list = this.samples.get(keyRef);
+    if (!list) return;
+    const cutoff = now - this.slidingWindowMs;
+    while (list.length > 0 && list[0].at < cutoff) {
+      list.shift();
+    }
+  }
+
+  clear() {
+    this.samples.clear();
+    this.knownLimits.clear();
+  }
+}
+
+export const defaultQuotaRunway = new QuotaRunway();

package/lib/stream-metrics.js

@@ -1,4 +1,4 @@
-// lib/stream-metrics.js — streaming success telemetry, usage, cost and token recording (#512).
+// lib/stream-metrics.js — streaming success telemetry, usage, cost and token recording (#512, #546, #549).
 // Extracted from lib/rotate.js to enforce < 600 line modularity standard.
 
 import { recordSuccess, setSessionSticky, recordFailure, extractRateLimit, isRateLimited } from './pool.js';
@@ -7,6 +7,7 @@ import { recordRequestOutcome } from './ops-analytics.js';
 import { tpmRecord } from './bucket.js';
 import { extractUsageTokens, consumeModelTokens } from './model-quota.js';
 import { extractProviderLimits } from './provider-limits-detector.js';
+import { normalizeUsageTokens } from './transports/tokens.js';
 
 export async function* preserveDispatchContext(iterable, storage, store) {
   if (!storage || typeof storage.getStore !== 'function') {
@@ -68,11 +69,15 @@ export function recordStreamSuccessMetrics(pool, activeRef, options, chunk, deps
     cascaded: Boolean(options.__isCascade),
   }, wallNow);
 
-  // 3. TPM sliding window bucket recording
-  const usedTokens = extractUsageTokens(usagePayload);
+  // 3. TPM sliding window bucket recording & token normalization (#546, #549)
+  const normUsage = normalizeUsageTokens(usagePayload);
+  const usedTokens = normUsage.totalTokens > 0 ? normUsage.totalTokens : extractUsageTokens(usagePayload);
   if (usedTokens && usedTokens > 0) {
     if (!pool.state.tpmWindows) pool.state.tpmWindows = new Map();
     tpmRecord(pool.state.tpmWindows, activeRef, usedTokens, wallNow);
+    if (pool.state.quotaRunway && typeof pool.state.quotaRunway.recordUsage === 'function') {
+      pool.state.quotaRunway.recordUsage(activeRef, usedTokens, wallNow);
+    }
   }
 
   // 4. Local model quota consumption
@@ -91,12 +96,15 @@ export function recordStreamSuccessMetrics(pool, activeRef, options, chunk, deps
     }
   }
 
-  // 5. Provider rate limit headers detection (#503)
+  // 5. Provider rate limit headers detection & predictive runway (#503, #549)
   if (rawHdrs) {
     const detected = extractProviderLimits(rawHdrs);
     if (detected) {
       if (!pool.state.detectedLimits) pool.state.detectedLimits = new Map();
       pool.state.detectedLimits.set(activeRef, { ...detected, at: nowMs });
+      if (pool.state.quotaRunway && typeof pool.state.quotaRunway.updateLimits === 'function') {
+        pool.state.quotaRunway.updateLimits(activeRef, detected, wallNow);
+      }
     }
   }
 
@@ -130,4 +138,4 @@ export function recordStreamSuccessMetrics(pool, activeRef, options, chunk, deps
   if (rate && Number.isFinite(rate.remaining) && quotaStore) {
     quotaStore.set(activeRef, { remaining: rate.remaining, limit: rate.limit, reset: rate.reset, at: nowMs });
   }
-}
+}

package/lib/transports/anthropic.js

@@ -0,0 +1,125 @@
+// lib/transports/anthropic.js — Anthropic Claude Messages wire protocol parsing (#546).
+// Handles event discrimination, text/thinking deltas, and split-event usage accumulation.
+
+import { normalizeUsageTokens } from './tokens.js';
+
+/**
+ * Parses an Anthropic event payload.
+ * @param {string|object} data
+ * @returns {object|null}
+ */
+export function parseAnthropicEvent(data) {
+  if (!data) return null;
+  if (typeof data === 'object') return data;
+  if (typeof data !== 'string') return null;
+
+  const trimmed = data.trim();
+  if (!trimmed) return null;
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extracts content or reasoning delta from an Anthropic event.
+ * @param {object} event
+ * @returns {{
+ *   type: string,
+ *   text: string|null,
+ *   thinking: string|null,
+ *   partialJson: string|null,
+ *   stopReason: string|null
+ * }}
+ */
+export function extractAnthropicDelta(event) {
+  if (!event || typeof event !== 'object') {
+    return { type: 'unknown', text: null, thinking: null, partialJson: null, stopReason: null };
+  }
+
+  const type = event.type || 'unknown';
+
+  if (type === 'content_block_delta') {
+    const delta = event.delta || {};
+    const deltaType = delta.type;
+    return {
+      type,
+      text: deltaType === 'text_delta' && typeof delta.text === 'string' ? delta.text : null,
+      thinking: deltaType === 'thinking_delta' && typeof delta.thinking === 'string' ? delta.thinking : null,
+      partialJson: deltaType === 'input_json_delta' && typeof delta.partial_json === 'string' ? delta.partial_json : null,
+      stopReason: null,
+    };
+  }
+
+  if (type === 'message_delta') {
+    return {
+      type,
+      text: null,
+      thinking: null,
+      partialJson: null,
+      stopReason: event.delta?.stop_reason ?? null,
+    };
+  }
+
+  return { type, text: null, thinking: null, partialJson: null, stopReason: null };
+}
+
+/**
+ * Creates an accumulator for Anthropic streaming usage.
+ * Anthropic provides input tokens at `message_start` and output tokens at `message_delta`.
+ *
+ * @returns {{
+ *   accumulate: (event: object) => void,
+ *   getUsage: () => object,
+ *   reset: () => void
+ * }}
+ */
+export function createAnthropicUsageAccumulator() {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheWriteTokens = 0;
+  let rawStart = null;
+  let rawDelta = null;
+
+  function accumulate(event) {
+    if (!event || typeof event !== 'object') return;
+
+    if (event.type === 'message_start' && event.message?.usage) {
+      rawStart = event.message.usage;
+      const norm = normalizeUsageTokens(rawStart);
+      inputTokens = norm.inputTokens;
+      cacheReadTokens = norm.cacheReadTokens;
+      cacheWriteTokens = norm.cacheWriteTokens;
+    } else if (event.type === 'message_delta' && event.usage) {
+      rawDelta = event.usage;
+      const norm = normalizeUsageTokens(rawDelta);
+      outputTokens = norm.outputTokens;
+    }
+  }
+
+  function getUsage() {
+    const total = inputTokens + outputTokens;
+    return {
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+      cacheWriteTokens,
+      totalTokens: total,
+      raw: { start: rawStart, delta: rawDelta },
+    };
+  }
+
+  function reset() {
+    inputTokens = 0;
+    outputTokens = 0;
+    cacheReadTokens = 0;
+    cacheWriteTokens = 0;
+    rawStart = null;
+    rawDelta = null;
+  }
+
+  return { accumulate, getUsage, reset };
+}

package/lib/transports/index.js

@@ -0,0 +1,23 @@
+// lib/transports/index.js — Unified network transports and token normalization layer (#546).
+
+export {
+  normalizeUsageTokens,
+  extractTotalTokens,
+} from './tokens.js';
+
+export {
+  createSseDecoder,
+  parseSseStream,
+} from './sse.js';
+
+export {
+  parseOpenAiChunk,
+  extractOpenAiDelta,
+  extractOpenAiUsage,
+} from './openai.js';
+
+export {
+  parseAnthropicEvent,
+  extractAnthropicDelta,
+  createAnthropicUsageAccumulator,
+} from './anthropic.js';

package/lib/transports/openai.js

@@ -0,0 +1,93 @@
+// lib/transports/openai.js — OpenAI wire protocol parsing (#546).
+// Handles JSON deltas, reasoning streams, tool calls, and usage payloads.
+
+import { normalizeUsageTokens } from './tokens.js';
+
+/**
+ * Parses an OpenAI streaming JSON data chunk.
+ * @param {string|object} data
+ * @returns {object|null}
+ */
+export function parseOpenAiChunk(data) {
+  if (!data) return null;
+  if (typeof data === 'object') return data;
+  if (typeof data !== 'string') return null;
+
+  const trimmed = data.trim();
+  if (!trimmed || trimmed === '[DONE]') return null;
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extracts content delta, reasoning delta, and tool calls from an OpenAI chunk.
+ * @param {object} chunk
+ * @returns {{
+ *   content: string|null,
+ *   reasoningContent: string|null,
+ *   toolCalls: Array<object>|null,
+ *   finishReason: string|null
+ * }}
+ */
+export function extractOpenAiDelta(chunk) {
+  if (!chunk || typeof chunk !== 'object') {
+    return {
+      content: null,
+      reasoningContent: null,
+      toolCalls: null,
+      finishReason: null,
+    };
+  }
+
+  const choice = Array.isArray(chunk.choices) ? chunk.choices[0] : null;
+  if (!choice) {
+    return {
+      content: null,
+      reasoningContent: null,
+      toolCalls: null,
+      finishReason: null,
+    };
+  }
+
+  const delta = choice.delta ?? {};
+  const finishReason = choice.finish_reason ?? null;
+
+  const content = typeof delta.content === 'string' ? delta.content : null;
+
+  // Support reasoning fields: DeepSeek reasoning_content, OpenAI thought/reasoning
+  const reasoningContent =
+    typeof delta.reasoning_content === 'string'
+      ? delta.reasoning_content
+      : typeof delta.reasoning === 'string'
+        ? delta.reasoning
+        : typeof delta.thought === 'string'
+          ? delta.thought
+          : null;
+
+  const toolCalls = Array.isArray(delta.tool_calls) && delta.tool_calls.length > 0
+    ? delta.tool_calls
+    : null;
+
+  return {
+    content,
+    reasoningContent,
+    toolCalls,
+    finishReason,
+  };
+}
+
+/**
+ * Extracts and normalizes usage from an OpenAI chunk (e.g. stream_options.include_usage).
+ * @param {object} chunk
+ * @returns {object|null}
+ */
+export function extractOpenAiUsage(chunk) {
+  if (!chunk || typeof chunk !== 'object') return null;
+  const usage = chunk.usage;
+  if (!usage || typeof usage !== 'object') return null;
+  return normalizeUsageTokens(usage);
+}

package/lib/transports/sse.js

@@ -0,0 +1,160 @@
+// lib/transports/sse.js — Server-Sent Events stream decoder (#546).
+// Zero-dependency streaming parser with buffering, multi-line data support, and AbortSignal awareness.
+
+/**
+ * Creates a stateful SSE stream decoder.
+ * @param {object} [options]
+ * @param {(event: { event: string, data: string, id?: string, retry?: number }) => void} [options.onEvent]
+ * @param {(err: Error) => void} [options.onError]
+ * @returns {{ feed: (chunk: string | Uint8Array | Buffer) => void, flush: () => void, reset: () => void }}
+ */
+export function createSseDecoder(options = {}) {
+  const { onEvent, onError } = options;
+  let buffer = '';
+  let eventType = 'message';
+  let dataLines = [];
+  let eventId = undefined;
+  let retry = undefined;
+
+  function dispatchCurrent() {
+    if (dataLines.length === 0) return;
+    const dataStr = dataLines.join('\n');
+    eventType = eventType || 'message';
+
+    // Discard standard SSE end-of-stream signal
+    if (dataStr.trim() !== '[DONE]' && typeof onEvent === 'function') {
+      try {
+        onEvent({
+          event: eventType,
+          data: dataStr,
+          id: eventId,
+          retry,
+        });
+      } catch (err) {
+        if (typeof onError === 'function') onError(err);
+      }
+    }
+
+    eventType = 'message';
+    dataLines = [];
+  }
+
+  function processLine(rawLine) {
+    let line = rawLine;
+    if (line.endsWith('\r')) line = line.slice(0, -1);
+
+    // Empty line signals dispatch of current event buffer
+    if (!line) {
+      dispatchCurrent();
+      return;
+    }
+
+    // Comment line: ignored per SSE spec
+    if (line.startsWith(':')) return;
+
+    const colonIdx = line.indexOf(':');
+    let field = line;
+    let value = '';
+
+    if (colonIdx !== -1) {
+      field = line.slice(0, colonIdx);
+      value = line.slice(colonIdx + 1);
+      if (value.startsWith(' ')) value = value.slice(1);
+    }
+
+    if (field === 'event') {
+      eventType = value;
+    } else if (field === 'data') {
+      dataLines.push(value);
+    } else if (field === 'id') {
+      eventId = value;
+    } else if (field === 'retry') {
+      const parsed = parseInt(value, 10);
+      if (Number.isFinite(parsed) && parsed >= 0) retry = parsed;
+    }
+  }
+
+  function feed(chunk) {
+    if (chunk == null) return;
+    const str = typeof chunk === 'string'
+      ? chunk
+      : (chunk instanceof Uint8Array || Buffer.isBuffer(chunk)
+        ? Buffer.from(chunk).toString('utf-8')
+        : String(chunk));
+
+    buffer += str;
+    let newlineIdx;
+    while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newlineIdx);
+      buffer = buffer.slice(newlineIdx + 1);
+      processLine(line);
+    }
+  }
+
+  function flush() {
+    if (buffer.length > 0) {
+      const line = buffer;
+      buffer = '';
+      processLine(line);
+    }
+    dispatchCurrent();
+  }
+
+  function reset() {
+    buffer = '';
+    eventType = 'message';
+    dataLines = [];
+    eventId = undefined;
+    retry = undefined;
+  }
+
+  return { feed, flush, reset };
+}
+
+/**
+ * Async generator that consumes an async iterable of chunks and yields parsed SSE event objects.
+ * Handles AbortSignal cleanly.
+ *
+ * @param {AsyncIterable<Uint8Array | string>} asyncIterable
+ * @param {AbortSignal} [signal]
+ * @returns {AsyncGenerator<{ event: string, data: string, id?: string, retry?: number }>}
+ */
+export async function* parseSseStream(asyncIterable, signal) {
+  if (!asyncIterable) return;
+
+  const queue = [];
+  let error = null;
+
+  const decoder = createSseDecoder({
+    onEvent: (evt) => queue.push(evt),
+    onError: (err) => { error = err; },
+  });
+
+  const checkAbort = () => {
+    if (signal?.aborted) {
+      const abortError = new Error(signal.reason?.message ?? 'SSE stream aborted');
+      abortError.name = 'AbortError';
+      throw abortError;
+    }
+  };
+
+  try {
+    for await (const chunk of asyncIterable) {
+      checkAbort();
+      decoder.feed(chunk);
+      if (error) throw error;
+      while (queue.length > 0) {
+        checkAbort();
+        yield queue.shift();
+      }
+    }
+    decoder.flush();
+    if (error) throw error;
+    while (queue.length > 0) {
+      checkAbort();
+      yield queue.shift();
+    }
+  } finally {
+    decoder.reset();
+  }
+}