@goodandready/dsh-key-rotation 0.8.76 → 0.8.78

package/lib/client-src/60-header-chip.js

@@ -0,0 +1,137 @@
+    // (issue 201, #499) header chip: one dot + counts for all pools. Green = all healthy,
+    // amber = some keys cooling, red = a pool fully exhausted. Click opens quick actions popover.
+    function KeyRotationHeaderChip(props) {
+      const t = resolveT(props);
+      const [snap, setSnap] = React.useState(null);
+      const [open, setOpen] = React.useState(false);
+      const [, setTick] = React.useState(0);
+      const [busy, setBusy] = React.useState(false);
+      const ref = React.useRef(null);
+
+      const load = () => {
+        if (typeof document !== 'undefined' && document.visibilityState !== 'visible') return;
+        fetch('/dsh-key-rotation/health', {
+          headers: { accept: 'application/json' },
+          credentials: 'same-origin',
+          signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(8000) : undefined
+        })
+          .then((r) => (r.ok ? r.json() : null))
+          .then((d) => { if (d) setSnap(d); })
+          .catch((e) => { void e; });
+      };
+
+      React.useEffect(() => {
+        load();
+        const id = setInterval(load, 5000);
+        const onVis = () => { if (typeof document !== 'undefined' && document.visibilityState === 'visible') load(); };
+        if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVis);
+        return () => {
+          clearInterval(id);
+          if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVis);
+        };
+      }, []);
+
+      React.useEffect(() => {
+        if (!props?.settingsSource?.subscribe) return;
+        return props.settingsSource.subscribe(() => {
+          setTick((c) => c + 1);
+        });
+      }, [props?.settingsSource]);
+
+      React.useEffect(() => {
+        if (!open) return;
+        const onDocClick = (e) => {
+          if (ref.current && !ref.current.contains(e.target)) setOpen(false);
+        };
+        document.addEventListener('click', onDocClick);
+        return () => document.removeEventListener('click', onDocClick);
+      }, [open]);
+
+      const runAction = (action, provider, keyRef) => {
+        setBusy(true);
+        fetch('/dsh-key-rotation/quick-action', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', accept: 'application/json' },
+          body: JSON.stringify({ action, provider, ref: keyRef }),
+          credentials: 'same-origin',
+          signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(5000) : undefined,
+        })
+          .then((r) => r.json())
+          .then(() => { load(); })
+          .catch((err) => { void err; })
+          .finally(() => { setBusy(false); });
+      };
+
+      let settingsVal = null;
+      try {
+        const sSnap = props?.settingsSource?.getSnapshot?.()?.service?.getSnapshot?.();
+        settingsVal = sSnap?.value;
+      } catch (e) {
+        void e;
+      }
+      if (settingsVal && settingsVal.showChatHeaderChip === false) return null;
+      if (snap && snap.showChatHeaderChip === false) return null;
+
+      const poolsObj = (snap && snap.pools) || {};
+      const poolEntries = Object.entries(poolsObj);
+      const total = poolEntries.reduce((a, [, p]) => a + (p.total || 0), 0);
+      const healthy = poolEntries.reduce((a, [, p]) => a + (p.healthy || 0), 0);
+      const anyExhausted = poolEntries.some(([, p]) => p.exhausted);
+      const color = !poolEntries.length ? 'var(--dsw-alias-label-tertiary)' : anyExhausted ? 'var(--dsw-alias-state-error-primary)' : healthy < total ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-success-primary)';
+      const label = poolEntries.length ? `${healthy}/${total} rot` : 'rot';
+
+      return h('div', { ref, style: { position: 'relative', display: 'inline-flex' } },
+        h('button', {
+          type: 'button',
+          className: 'krot-header-chip',
+          title: t('title'),
+          onClick: () => setOpen((v) => !v),
+        },
+          h('span', { style: { width: '8px', height: '8px', borderRadius: '50%', background: color, flex: 'none', boxShadow: `0 0 6px ${color}` } }),
+          label,
+          h('span', { style: { fontSize: '9px', opacity: 0.6 } }, open ? '▲' : '▼')
+        ),
+        open ? h('div', { className: 'krot-popover', style: { minWidth: '220px' } },
+          h('div', { className: 'krot-pop-title' }, t('headerPoolsTitle')),
+          !poolEntries.length ? h('div', { style: { fontSize: '12px', color: 'var(--dsw-alias-label-tertiary)' } }, t('noActivePools')) : null,
+          poolEntries.map(([name, p]) => {
+            const c = p.exhausted ? 'var(--dsw-alias-state-error-primary)' : (p.healthy < p.total ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-success-primary)');
+            const provName = p.providerName || name;
+            const tail = p.lastUsedTail;
+            return h('div', { key: name, className: 'krot-pop-row', style: { display: 'flex', flexDirection: 'column', gap: '4px', padding: '6px 0', borderBottom: '1px solid var(--dsw-alias-border-subtle)' } },
+              h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
+                h('div', { className: 'krot-pop-name' },
+                  h('span', { style: { width: '7px', height: '7px', borderRadius: '50%', background: c, flex: 'none' } }),
+                  name,
+                  tail ? h('span', { style: { marginLeft: '6px', fontSize: '11px', color: 'var(--dsw-alias-label-tertiary)', fontFeatureSettings: '"tnum"', fontFamily: 'monospace' } }, `...${tail}`) : null
+                ),
+                h('div', { className: 'krot-pop-count', style: { color: c, fontWeight: 600 } }, `${p.healthy}/${p.total}`)
+              ),
+              h('div', { style: { display: 'flex', gap: '4px', marginTop: '2px' } },
+                h('button', {
+                  type: 'button',
+                  disabled: busy,
+                  onClick: (e) => { e.stopPropagation(); runAction('skip', provName, p.lastUsed); },
+                  title: t('quickSkipTitle'),
+                  style: { padding: '2px 6px', fontSize: '11px', borderRadius: '4px', border: '1px solid var(--dsw-alias-border-subtle)', background: 'transparent', cursor: 'pointer', color: 'inherit' }
+                }, `⏭️ ${t('quickSkip')}`),
+                h('button', {
+                  type: 'button',
+                  disabled: busy,
+                  onClick: (e) => { e.stopPropagation(); runAction('reset', provName, p.lastUsed); },
+                  title: t('quickResetTitle'),
+                  style: { padding: '2px 6px', fontSize: '11px', borderRadius: '4px', border: '1px solid var(--dsw-alias-border-subtle)', background: 'transparent', cursor: 'pointer', color: 'inherit' }
+                }, `🔄 ${t('quickReset')}`),
+                h('button', {
+                  type: 'button',
+                  disabled: busy || !p.lastUsed,
+                  onClick: (e) => { e.stopPropagation(); runAction('pause', provName, p.lastUsed); },
+                  title: t('quickPauseTitle'),
+                  style: { padding: '2px 6px', fontSize: '11px', borderRadius: '4px', border: '1px solid var(--dsw-alias-border-subtle)', background: 'transparent', cursor: 'pointer', color: 'inherit' }
+                }, `⏸️ ${t('quickPause')}`)
+              )
+            );
+          })
+        ) : null
+      );
+    }

package/lib/client-src/90-apply.js

@@ -0,0 +1,69 @@
+    function apply(ctx) {
+      const settingsSource = createSettingsSource(ctx);
+      ctx.effect(() => ctx.locale.register(NS, { en, zh }), 'dsh-key-rotation: dictionaries');
+      // Header chip (#201): status dot in the session header utilities slot,
+      // same slot dsh-gitea / dsh-subscriptions use for their header widgets.
+      ctx.effect(() => {
+        if (!ctx.slots) return;
+        try {
+          ctx.slots.inject('conversation.session.header.utilities', () =>
+            ctx.slots.register(
+              { name: 'conversation.session.header.utilities', id: 'dsh-key-rotation-header-chip', order: 6, locale: NS, inject: () => ({ ctx, settingsSource }) },
+              KeyRotationHeaderChip,
+            ));
+        } catch { /* slot not available in this build */ }
+      }, 'dsh-key-rotation: header chip');
+
+      function useLocale() {
+        return useActiveLocale(ctx);
+      }
+      // Collapsible card in Settings -> Plugins -> Plugin settings
+      // (settings.plugin.item), matching Model Sync / Spendmeter / Vision Bridge.
+      // key MUST equal the settings namespace (NS), else the tab silently skips it.
+      
+  function KeyRotationCard(props) {
+        const locale = useLocale();
+        const t = resolveT(props);
+        const page = !!(props && props.view === 'page');
+        const [open, setOpen] = React.useState(!!page);
+        // Row seat (plugins.row.config): the host page draws title/icon/crumb and the
+        // padding, so the summary is a one-liner and the page drops our card chrome.
+        if (props && props.view === 'summary') {
+          return h('span', { className: 'krot-card-description' }, t('subtitle'));
+        }
+        return h(page ? 'div' : 'div', { className: page ? 'krot-page' : 'krot-card' + (open ? ' krot-card-open' : '') },
+          h('button', { type: 'button', className: 'krot-card-header', style: page ? { display: 'none' } : undefined, 'aria-expanded': page ? true : open, onClick: () => setOpen((v) => !v) },
+            h('span', { className: 'krot-card-head-text' },
+              h('span', { className: 'krot-card-name' }, t('title')),
+              h('span', { className: 'krot-card-description' }, t('subtitle'))),
+            h('span', { className: 'krot-card-chevron' + (open ? ' krot-card-chevron-open' : ''), 'aria-hidden': 'true' },
+              h('svg', { width: 14, height: 14, viewBox: '0 0 14 14', fill: 'none', stroke: 'currentColor', strokeWidth: 1.5, style: { display: 'block' } },
+                h('path', { d: 'M3.5 5.25L7 8.75L10.5 5.25' })))),
+          (page || open) ? h('div', { className: 'krot-card-body' }, h(KeyRotationErrorBoundary, null, h(KeyRotationSection, { ...props, locale }))) : null);
+      }
+      // Register each available seat independently. A missing legacy seat must
+      // not prevent the current bundle or row seat from registering.
+      for (const [name, key] of [
+        ['plugins.bundle.config', PKG],
+        ['plugins.row.config', ROW_CONFIG_KEY],
+        ['settings.plugin.item', NS],
+      ]) {
+        try {
+          ctx.slots.inject(name, () => ctx.slots.register(
+            { name, key, locale: NS, inject: () => ({ ctx, settingsSource }) }, KeyRotationCard,
+          ));
+        } catch (error) {
+          bestEffort('slots.register.log', () => { console.error('[dsh-key-rotation] settings seat unavailable', name, error); });
+        }
+      }
+    }
+
+    module.exports = { apply, inject: ['slots', 'locale'] };
+    if (typeof globalThis !== 'undefined') {
+      globalThis.__dshKeyRotationClientInternals = {
+        quotaMapOf, withQuotas, modelEntriesOf, isValidModelId, formatCountdown, validatePoolDraft,
+      };
+    }
+    return module.exports;
+  },
+});

package/lib/error-taxonomy.js

@@ -1,13 +1,35 @@
-import { SOFT_FAILURE_CODES } from './pool.js';
-// lib/error-taxonomy.js — complete failure classification (#267).
+// lib/error-taxonomy.js — complete failure classification (#267, #547).
 // action: 'switch' | 'surface' | 'cooldown'
 
+import { SOFT_FAILURE_CODES } from './pool.js';
+import {
+  classifyResponseError,
+  parseErrorBody,
+  retryAfterMs,
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  QUOTA_EXCEEDED_CODE,
+  ACCOUNT_QUOTA_EXCEEDED_CODE,
+  EMPTY_RESPONSE_CODE,
+  INVALID_CREDENTIAL_CODE,
+} from './errors.js';
+
+export {
+  classifyResponseError,
+  parseErrorBody,
+  retryAfterMs,
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  QUOTA_EXCEEDED_CODE,
+  ACCOUNT_QUOTA_EXCEEDED_CODE,
+  EMPTY_RESPONSE_CODE,
+  INVALID_CREDENTIAL_CODE,
+};
+
 const SWITCH_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
 const SURFACE_STATUS = new Set([400, 404, 422]);
 const AUTH_STATUS = new Set([401, 403]);
 
 const SWITCH_CODES = new Set([
-  'QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE',
+  'QUOTA', 'ACCOUNT_QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE',
   'UNKNOWN_MODEL', 'AUTH', 'RESOURCE_EXHAUSTED', 'UNAVAILABLE', 'INTERNAL',
   'DEADLINE_EXCEEDED', 'UNAUTHENTICATED', 'PERMISSION_DENIED', 'ABORTED',
 ]);
@@ -19,7 +41,7 @@ const SOCKET_SWITCH = new Set([
 /**
  * Classify a failure for rotation.
  * @param {any} failureOrPayload
- * @returns {{ action: 'switch'|'surface'|'cooldown', code: string, soft: boolean, reason: string }}
+ * @returns {{ action: 'switch'|'surface'|'cooldown', code: string, soft: boolean, reason: string, retryAfterMs?: number }}
  */
 export function classifyFailure(failureOrPayload) {
   if (!failureOrPayload) {
@@ -29,18 +51,46 @@ export function classifyFailure(failureOrPayload) {
   const status = Number(failure.status ?? failure.statusCode ?? failure.httpStatus ?? 0);
   const code = String(failure.code ?? failure.reason ?? failure.name ?? '').toUpperCase();
   const message = String(failure.message ?? failureOrPayload.message ?? '');
+  const headers = failure.headers ?? failureOrPayload.headers ?? failure.response?.headers;
+  const retryMs = retryAfterMs(headers);
+
+  // Check structured body/error through classifyResponseError if available
+  if (status || failure.body || (code && code !== 'ERROR')) {
+    const typed = classifyResponseError(status, failure.body ?? message, headers);
+    if (typed.code === CONTEXT_WINDOW_EXCEEDED_CODE) {
+      return { action: 'surface', code: CONTEXT_WINDOW_EXCEEDED_CODE, soft: false, reason: 'context_window' };
+    }
+  }
 
-  if (AUTH_STATUS.has(status) || code === 'AUTH' || code === 'UNAUTHENTICATED' || code === 'PERMISSION_DENIED') {
-    return { action: 'switch', code: status ? String(status) : (code || 'AUTH'), soft: false, reason: 'auth' };
+  if (AUTH_STATUS.has(status) || code === 'AUTH' || code === 'UNAUTHENTICATED' || code === 'PERMISSION_DENIED' || code === INVALID_CREDENTIAL_CODE) {
+    return {
+      action: 'switch',
+      code: status ? String(status) : (code || 'AUTH'),
+      soft: false,
+      reason: 'auth',
+      ...(retryMs !== undefined ? { retryAfterMs: retryMs } : {}),
+    };
   }
-  if (status === 429 || code === 'RATE_LIMIT' || code === 'RESOURCE_EXHAUSTED' || code === 'QUOTA') {
-    return { action: 'switch', code: status ? '429' : (code || 'RATE_LIMIT'), soft: false, reason: 'quota' };
+  if (status === 429 || code === 'RATE_LIMIT' || code === 'RESOURCE_EXHAUSTED' || code === 'QUOTA' || code === 'ACCOUNT_QUOTA' || code === QUOTA_EXCEEDED_CODE) {
+    return {
+      action: 'switch',
+      code: status ? '429' : (code || 'RATE_LIMIT'),
+      soft: false,
+      reason: 'quota',
+      ...(retryMs !== undefined ? { retryAfterMs: retryMs } : {}),
+    };
   }
   const numCode = Number(code);
   if (SWITCH_STATUS.has(status) || (numCode > 0 && SWITCH_STATUS.has(numCode)) || SOFT_FAILURE_CODES.has(code)) {
     const effCode = status ? String(status) : (numCode > 0 ? String(numCode) : code);
     const soft = SOFT_FAILURE_CODES.has(effCode);
-    return { action: 'switch', code: effCode, soft, reason: 'http' };
+    return {
+      action: 'switch',
+      code: effCode,
+      soft,
+      reason: 'http',
+      ...(retryMs !== undefined ? { retryAfterMs: retryMs } : {}),
+    };
   }
   if (SURFACE_STATUS.has(status)) {
     return { action: 'surface', code: String(status), soft: false, reason: 'client' };
@@ -63,4 +113,3 @@ export function classifyFailure(failureOrPayload) {
   return { action: 'surface', code: code || 'UNKNOWN', soft: false, reason: 'unclassified' };
 }
 
-/** True when classification says switch to next key. */

package/lib/errors.js

@@ -0,0 +1,302 @@
+// lib/errors.js — Canonical error classification and taxonomy for DeepSeek Harness (#547).
+// Unifies error shapes across OpenAI, Anthropic, Gemini, Ollama, Groq and OpenCode into standard LlmError.
+
+import {
+  HarnessError as DshHarnessError,
+  LlmError as DshLlmError,
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  QUOTA_EXCEEDED_CODE,
+  ACCOUNT_QUOTA_EXCEEDED_CODE,
+  EMPTY_RESPONSE_CODE,
+  INVALID_CREDENTIAL_CODE,
+  isContextWindowExceededError,
+  isQuotaExceededError,
+} from '@deepseek-ai/dsh-llm';
+
+export {
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  QUOTA_EXCEEDED_CODE,
+  ACCOUNT_QUOTA_EXCEEDED_CODE,
+  EMPTY_RESPONSE_CODE,
+  INVALID_CREDENTIAL_CODE,
+  isContextWindowExceededError,
+  isQuotaExceededError,
+};
+
+// Fallback HarnessError and LlmError if ever decoupled from runtime
+export class HarnessError extends (DshHarnessError || Error) {
+  constructor(message, code, options) {
+    super(message, code, options);
+    this.code = code;
+    this.name = this.constructor.name;
+  }
+}
+
+export class LlmError extends (DshLlmError || HarnessError) {
+  constructor(message, code, options) {
+    super(message, code, options);
+    this.status = options?.status;
+    this.providerRetryAfterMs = options?.providerRetryAfterMs;
+    this.code = code;
+    this.name = this.constructor.name;
+  }
+}
+
+/**
+ * Robust parser for structured error bodies (JSON, object, text).
+ * Handles OpenAI, Anthropic, Gemini, Groq, Ollama envelopes.
+ *
+ * @param {unknown} body
+ * @returns {{ message?: string, type?: string, code?: string, status?: number, raw?: unknown }}
+ */
+export function parseErrorBody(body) {
+  if (!body) return {};
+  if (typeof body === 'object') {
+    return extractErrorFields(body);
+  }
+  if (typeof body === 'string') {
+    const trimmed = body.trim();
+    if (!trimmed) return {};
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        return extractErrorFields(parsed);
+      } catch {
+        // Not valid JSON, return as plain message
+      }
+    }
+    return { message: trimmed.slice(0, 1000) };
+  }
+  return { message: String(body).slice(0, 1000) };
+}
+
+function extractErrorFields(obj) {
+  if (!obj || typeof obj !== 'object') return {};
+  const outer = obj;
+  const nested = outer.error;
+
+  let message = outer.message;
+  let type = outer.type;
+  let code = outer.code;
+  let status = outer.status;
+
+  if (typeof nested === 'string') {
+    message = nested;
+  } else if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+    if (typeof nested.message === 'string') message = nested.message;
+    if (typeof nested.type === 'string') type = nested.type;
+    if (nested.code !== undefined && nested.code !== null) code = String(nested.code);
+    if (typeof nested.status === 'number' || typeof nested.status === 'string') {
+      const s = Number(nested.status);
+      if (Number.isFinite(s)) status = s;
+    }
+  }
+
+  // Handle gRPC style status object: { code: 8, message: "Resource exhausted", details: [...] }
+  if (outer.details && Array.isArray(outer.details) && outer.details.length > 0) {
+    const firstDetail = outer.details[0];
+    if (firstDetail && typeof firstDetail === 'object') {
+      if (!message && typeof firstDetail.message === 'string') message = firstDetail.message;
+      if (!type && typeof firstDetail.reason === 'string') type = firstDetail.reason;
+    }
+  }
+
+  return {
+    ...(message ? { message: String(message) } : {}),
+    ...(type ? { type: String(type) } : {}),
+    ...(code !== undefined && code !== null ? { code: String(code) } : {}),
+    ...(typeof status === 'number' ? { status } : {}),
+    raw: obj,
+  };
+}
+
+/**
+ * Parse Retry-After value from Headers, headers object, or string into milliseconds.
+ *
+ * @param {Headers | Record<string, string | string[]> | string | null | undefined} headers
+ * @param {number} [now=Date.now()]
+ * @returns {number | undefined}
+ */
+export function retryAfterMs(headers, now = Date.now()) {
+  if (!headers) return undefined;
+  let raw = '';
+  if (typeof headers === 'string') {
+    const m = headers.match(/retry-after\s*[:=]\s*(.+)/i);
+    raw = m ? m[1].trim().split(/[\n\r;]/)[0].trim() : headers.trim();
+  } else if (typeof headers.get === 'function') {
+    raw = headers.get('retry-after') || headers.get('x-ratelimit-reset-after') || '';
+  } else if (typeof headers === 'object') {
+    for (const [k, v] of Object.entries(headers)) {
+      if (k.toLowerCase() === 'retry-after' || k.toLowerCase() === 'x-ratelimit-reset-after') {
+        raw = Array.isArray(v) ? v[0] : String(v || '');
+        break;
+      }
+    }
+  }
+
+  raw = String(raw).trim();
+  if (!raw) return undefined;
+
+  // 1. Seconds format: integer or float
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0 && seconds <= 86400 * 7) {
+    return Math.trunc(seconds * 1000);
+  }
+
+  // 2. HTTP-Date format: RFC 1123 / RFC 850
+  const parsedTs = Date.parse(raw);
+  if (Number.isFinite(parsedTs)) {
+    const diff = parsedTs - now;
+    return diff > 0 && diff < 86400 * 7 * 1000 ? Math.trunc(diff) : 0;
+  }
+
+  return undefined;
+}
+
+/**
+ * Determine if text/detail indicates quota or balance exhaustion.
+ *
+ * @param {string} detail
+ * @returns {boolean}
+ */
+export function isQuotaDetail(detail) {
+  if (!detail) return false;
+  if (isQuotaExceededError(detail)) return true;
+  const d = detail.toLowerCase();
+  return (
+    d.includes('insufficient_quota') ||
+    d.includes('insufficient balance') ||
+    d.includes('insufficient credits') ||
+    d.includes('out of credits') ||
+    d.includes('out of budget') ||
+    d.includes('quota exceeded') ||
+    d.includes('usage limit exceeded') ||
+    d.includes('resource_exhausted') ||
+    d.includes('credit balance') ||
+    d.includes('monthly limit') ||
+    d.includes('weekly limit') ||
+    d.includes('payment required')
+  );
+}
+
+/**
+ * Canonical classifier translating status, body and headers into typed LlmError (#547).
+ *
+ * @param {number} status HTTP status code
+ * @param {unknown} body Response body (string, object, buffer)
+ * @param {Headers | Record<string, unknown> | null | undefined} headers Response headers
+ * @param {{ now?: number }} [options]
+ * @returns {LlmError}
+ */
+export function classifyResponseError(status, body, headers, options = {}) {
+  const now = options.now ?? Date.now();
+  const parsed = parseErrorBody(body);
+  const type = parsed.type ?? '';
+  const message = parsed.message ?? (status ? `HTTP ${status}` : 'Unknown upstream error');
+  const code = (parsed.code ?? '').toUpperCase();
+  const detail = `${type} ${code} ${message}`.trim();
+  const retryMs = retryAfterMs(headers, now);
+
+  const validStatus = Number.isInteger(status) && status >= 100 && status <= 599 ? status : undefined;
+  const errorOptions = {
+    ...(validStatus !== undefined ? { status: validStatus } : {}),
+    ...(retryMs !== undefined ? { providerRetryAfterMs: retryMs } : {}),
+    ...(parsed.raw ? { cause: parsed.raw } : {}),
+  };
+
+  // 1. Context window exceeded
+  if (code === CONTEXT_WINDOW_EXCEEDED_CODE || isContextWindowExceededError(detail)) {
+    return new LlmError(message, CONTEXT_WINDOW_EXCEEDED_CODE, errorOptions);
+  }
+
+  // 2. Authentication & Credentials (401, 403, invalid_api_key)
+  if (
+    status === 401 ||
+    status === 403 ||
+    code === 'INVALID_API_KEY' ||
+    code === 'UNAUTHENTICATED' ||
+    code === 'PERMISSION_DENIED' ||
+    type === 'authentication_error' ||
+    type === 'permission_denied'
+  ) {
+    const isMalformed = /malformed|invalid|bad|incorrect/i.test(detail);
+    return new LlmError(
+      message,
+      isMalformed ? INVALID_CREDENTIAL_CODE : 'AUTH',
+      errorOptions
+    );
+  }
+
+  // 3. Quota & Balance exhaustion (429 or 402 with quota phrasing)
+  if (
+    status === 402 ||
+    code === 'QUOTA' ||
+    code === 'RESOURCE_EXHAUSTED' ||
+    code === 'INSUFFICIENT_QUOTA' ||
+    isQuotaDetail(detail)
+  ) {
+    const isAccount = /account|billing|subscription|replenish/i.test(detail);
+    return new LlmError(
+      message,
+      isAccount ? ACCOUNT_QUOTA_EXCEEDED_CODE : QUOTA_EXCEEDED_CODE,
+      errorOptions
+    );
+  }
+
+  // 4. Rate Limiting (429 without quota exhaustion, concurrency limits)
+  if (
+    status === 429 ||
+    code === 'RATE_LIMIT' ||
+    code === 'RATE_LIMIT_EXCEEDED' ||
+    type === 'rate_limit_error' ||
+    /rate[\s_-]?limit|too many requests|concurrency[\s_-]+limit|rpm|tpm/i.test(detail)
+  ) {
+    return new LlmError(message, 'RATE_LIMIT', errorOptions);
+  }
+
+  // 5. Unknown Model (explicit model_not_found or invalid_model)
+  if (
+    code === 'MODEL_NOT_FOUND' ||
+    code === 'UNKNOWN_MODEL' ||
+    type === 'invalid_model' ||
+    /model[_\s]+not[_\s]+found|unknown[_\s]+model/i.test(detail)
+  ) {
+    return new LlmError(message, 'UNKNOWN_MODEL', errorOptions);
+  }
+
+  // 6. Timeouts (408, 504, DEADLINE_EXCEEDED)
+  if (
+    status === 408 ||
+    status === 504 ||
+    code === 'TIMEOUT' ||
+    code === 'DEADLINE_EXCEEDED' ||
+    /timeout|timed[\s_-]?out/i.test(detail)
+  ) {
+    return new LlmError(message, 'TIMEOUT', errorOptions);
+  }
+
+  // 7. Server Errors (500, 502, 503)
+  if (
+    (status >= 500 && status <= 503) ||
+    code === 'SERVER' ||
+    code === 'INTERNAL' ||
+    code === 'UNAVAILABLE' ||
+    type === 'server_error' ||
+    type === 'api_error'
+  ) {
+    return new LlmError(message, 'SERVER', errorOptions);
+  }
+
+  // 8. Empty response
+  if (code === EMPTY_RESPONSE_CODE || (!message && status === 200)) {
+    return new LlmError(message || 'Upstream returned empty completion', EMPTY_RESPONSE_CODE, errorOptions);
+  }
+
+  // 9. Default client error (400, 422) or generic provider error
+  if (status >= 400 && status < 500) {
+    return new LlmError(message, code || String(status), errorOptions);
+  }
+
+  return new LlmError(message, code || 'PROVIDER_ERROR', errorOptions);
+}
+

package/lib/index.js

@@ -57,6 +57,12 @@ export const name = '@goodandready/dsh-key-rotation';
 export const inject = ['llm', 'webServer', 'settings', 'credentials'];
 export { keyTail, KEY_TAIL_CHARS, KEY_TAIL_PLACEHOLDER, isLoopbackAddress, isTrustedBridgeRequest, isDesktopShellRequest, DEFAULT_SWITCH_CODES, isSwitchableError, formatExhaustionMessage, getRuntime };
 export { notifySwitch, notifyExhaustion, notifyEarlyWarning };
+export { classifyResponseError } from './errors.js';
+export { SessionRouter, defaultSessionRouter, unstickFailedKey } from './session-router.js';
+export { isContentChunk } from './rotate.js';
+export { ModelCatalog, defaultModelCatalog } from './model-catalog.js';
+export { QuotaRunway, defaultQuotaRunway, estimateRunway } from './quota-runway.js';
+export * as transports from './transports/index.js';
 
 const NS = 'dsh-key-rotation';