surf-skill 2.0.0

package/src/lib/api/research.mjs

@@ -0,0 +1,96 @@
+// Library wrappers for research (sync + async start/poll).
+
+import { dispatch } from '../dispatch.mjs';
+import { buildInMemoryState } from '../../env.mjs';
+import { setSilent } from '../progress.mjs';
+import { providerFromRequestId } from '../providers/index.mjs';
+
+const SLEEP = ms => new Promise(r => setTimeout(r, ms));
+
+/**
+ * Start an async deep research job. Returns immediately with a request_id.
+ * Use researchPoll(id) to check status / get result.
+ *
+ * @param {string} input - the research question
+ * @param {object} [opts]
+ * @param {'mini'|'auto'|'pro'|'ultra'} [opts.model='auto']
+ * @returns {Promise<object>} envelope with data.request_id, data.status
+ */
+export async function researchStart(input, opts = {}) {
+  if (opts.quiet !== false) setSilent(true);
+  if (!input || typeof input !== 'string') throw new Error('researchStart: input required');
+
+  const state = await buildInMemoryState(opts);
+  return dispatch(
+    'research-start',
+    {
+      input,
+      model: opts.model || 'auto',
+      citationFormat: opts.citationFormat || 'numbered',
+      outputSchema: opts.outputSchema,
+      processor: opts.processor,
+    },
+    {
+      provider: opts.provider,
+      'no-fallback': opts.noFallback,
+      'confirm-expensive': true,
+    },
+    { state }
+  );
+}
+
+/**
+ * Poll a research job by request_id. The id encodes the originating provider
+ * (e.g. 'tvly:abc' or 'pllx:abc'), so no provider hint is needed.
+ *
+ * @param {string} requestId
+ * @returns {Promise<object>} envelope with data.status + data.content when completed
+ */
+export async function researchPoll(requestId, opts = {}) {
+  if (opts.quiet !== false) setSilent(true);
+  if (!requestId || typeof requestId !== 'string') throw new Error('researchPoll: requestId required');
+
+  const decoded = providerFromRequestId(requestId);
+  if (!decoded) throw new Error(`unknown request_id prefix in '${requestId}'`);
+
+  const state = await buildInMemoryState(opts);
+  return dispatch(
+    'research-poll',
+    {},
+    { ...opts, __requestId: requestId, 'confirm-expensive': true },
+    { state }
+  );
+}
+
+/**
+ * Synchronous research wrapper. Refuses model=pro/ultra (those are too slow).
+ * Polls every 5s up to 50s; if not finished, returns the in-progress envelope
+ * with request_id so caller can poll later.
+ */
+export async function research(input, opts = {}) {
+  if (opts.quiet !== false) setSilent(true);
+  const model = opts.model || 'mini';
+  if (model === 'pro' || model === 'ultra') {
+    throw new Error(`research: model=${model} too slow for sync. Use researchStart + researchPoll.`);
+  }
+
+  const start = await researchStart(input, { ...opts, model });
+  const requestId = start.data.request_id;
+  const deadline = Date.now() + (opts.timeoutMs || 50_000);
+
+  while (Date.now() < deadline) {
+    await SLEEP(5000);
+    const poll = await researchPoll(requestId, opts);
+    if (poll.data.status === 'completed' || poll.data.status === 'failed') {
+      return poll;
+    }
+  }
+  return {
+    operation: 'research',
+    data: {
+      request_id: requestId,
+      status: 'pending',
+      hint: `Use researchPoll('${requestId}') to continue.`,
+    },
+  };
+}

package/src/lib/api/search.mjs

@@ -0,0 +1,92 @@
+// Library wrapper for `search`. Wraps dispatch + key discovery.
+
+import { dispatch } from '../dispatch.mjs';
+import { buildInMemoryState } from '../../env.mjs';
+import { setSilent } from '../progress.mjs';
+
+/**
+ * Web search.
+ *
+ * @param {string|string[]} query - single query or array (batch)
+ * @param {object} [opts]
+ * @param {string|string[]} [opts.tavilyKey|opts.tavilyKeys]
+ * @param {string|string[]} [opts.parallelKey|opts.parallelKeys]
+ * @param {'tavily'|'parallel'} [opts.provider] - force a provider (no fallback)
+ * @param {'basic'|'advanced'|'fast'} [opts.depth='advanced']
+ * @param {number} [opts.max=5]
+ * @param {string} [opts.topic] - 'general' | 'news' | 'finance'
+ * @param {string} [opts.time] - 'day' | 'week' | 'month' | 'year'
+ * @param {string|string[]} [opts.domains]
+ * @param {string|string[]} [opts.excludeDomains]
+ * @param {string} [opts.country]
+ * @param {boolean|string} [opts.answer]
+ * @param {boolean|string} [opts.raw]
+ * @param {boolean} [opts.noCache=false]
+ * @param {boolean} [opts.quiet=true] - silence stderr progress logs (library default)
+ * @returns {Promise<object>} normalized envelope { provider, operation, data, usage, latency_ms, raw }
+ */
+export async function search(query, opts = {}) {
+  if (opts.quiet !== false) setSilent(true);
+
+  const queries = Array.isArray(query) ? query : [query];
+  if (queries.length === 0 || queries.some(q => typeof q !== 'string' || !q.trim())) {
+    throw new Error('search: query must be a non-empty string or array of strings');
+  }
+
+  const state = await buildInMemoryState(opts);
+
+  if (queries.length === 1) {
+    return dispatch('search', buildArgs(queries[0], opts), buildFlags(opts), { state });
+  }
+
+  // Batch: run sequentially, return array of envelopes
+  const batches = [];
+  for (const q of queries) {
+    try {
+      const env = await dispatch('search', buildArgs(q, opts), buildFlags(opts), { state });
+      batches.push({ query: q, ok: true, envelope: env });
+    } catch (e) {
+      batches.push({ query: q, ok: false, error: { code: e.code || 'Error', message: e.message } });
+    }
+  }
+  return {
+    operation: 'search-batch',
+    data: { batches },
+    summary: {
+      total: queries.length,
+      succeeded: batches.filter(b => b.ok).length,
+      failed: batches.filter(b => !b.ok).length,
+    },
+  };
+}
+
+function buildArgs(query, opts) {
+  return {
+    query,
+    depth: opts.depth || 'advanced',
+    max: opts.max,
+    topic: opts.topic,
+    time: opts.time,
+    startDate: opts.startDate,
+    endDate: opts.endDate,
+    domains: opts.domains,
+    excludeDomains: opts.excludeDomains,
+    country: opts.country,
+    answer: opts.answer,
+    raw: opts.raw,
+    images: opts.images,
+    auto: opts.auto,
+    exactMatch: opts.exactMatch,
+    processor: opts.processor,
+  };
+}
+
+function buildFlags(opts) {
+  return {
+    provider: opts.provider,
+    'no-fallback': opts.noFallback,
+    'no-cache': opts.noCache,
+    timeout: opts.timeout,
+    'confirm-expensive': true, // library callers know what they're doing
+  };
+}

package/src/lib/audit.mjs

@@ -0,0 +1,34 @@
+// Append-only audit log and usage ledger. Never logs API keys — only provider
+// name and key index.
+
+import { appendFile, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CACHE_DIR, ensureCacheDir } from './state.mjs';
+
+export const AUDIT_LOG = join(CACHE_DIR, 'audit.log');
+export const USAGE_LOG = join(CACHE_DIR, 'usage.jsonl');
+
+async function appendJsonl(path, entry) {
+  await ensureCacheDir();
+  await appendFile(path, JSON.stringify({ ts: new Date().toISOString(), ...entry }) + '\n');
+}
+
+export async function audit(event) {
+  await appendJsonl(AUDIT_LOG, event);
+}
+
+export async function recordUsage(event) {
+  await appendJsonl(USAGE_LOG, event);
+}
+
+export async function readUsage() {
+  if (!existsSync(USAGE_LOG)) return [];
+  const raw = await readFile(USAGE_LOG, 'utf8');
+  return raw
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean)
+    .map(line => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean);
+}

package/src/lib/cache.mjs

@@ -0,0 +1,46 @@
+// Response cache keyed by (provider, endpoint, body).
+
+import { readFile, writeFile, readdir, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { CACHE_DIR, ensureCacheDir } from './state.mjs';
+
+export const TTL_MS = (Number(process.env.SURF_CACHE_TTL || process.env.TAVILY_CACHE_TTL) || 21600) * 1000;
+
+export function cacheKey(provider, endpoint, body) {
+  return createHash('sha256')
+    .update(`${provider}:${endpoint}:${JSON.stringify(body || {})}`)
+    .digest('hex')
+    .slice(0, 24);
+}
+
+export async function cacheGet(key) {
+  const f = join(CACHE_DIR, key + '.json');
+  if (!existsSync(f)) return null;
+  try {
+    const raw = JSON.parse(await readFile(f, 'utf8'));
+    if (Date.now() - raw.ts > TTL_MS) return null;
+    return raw.data;
+  } catch {
+    return null;
+  }
+}
+
+export async function cacheSet(key, data) {
+  await ensureCacheDir();
+  await writeFile(join(CACHE_DIR, key + '.json'), JSON.stringify({ ts: Date.now(), data }));
+}
+
+export async function cacheClear() {
+  if (!existsSync(CACHE_DIR)) return 0;
+  const files = await readdir(CACHE_DIR);
+  let n = 0;
+  for (const f of files) {
+    if (f.endsWith('.json')) {
+      await unlink(join(CACHE_DIR, f));
+      n++;
+    }
+  }
+  return n;
+}

package/src/lib/cost.mjs

@@ -0,0 +1,90 @@
+// Credit estimation. We model both providers on the same "credit" scale that
+// Tavily uses (since that's the only published one). Parallel costs are
+// estimated coarsely from documented processor tiers.
+
+import { clamp, ceilDiv } from './flags.mjs';
+
+const EXPENSIVE_OK = process.env.SURF_ALLOW_EXPENSIVE === '1'
+  || process.env.TAVILY_ALLOW_EXPENSIVE === '1';
+
+// Tavily — matches the public credit table.
+function estimateTavily(op, args) {
+  switch (op) {
+    case 'search':
+      return (args.depth === 'advanced' || args.auto) ? 2 : 1;
+    case 'extract': {
+      const urls = Array.isArray(args.urls) ? args.urls.length : 1;
+      const rate = args.depth === 'advanced' ? 2 : 1;
+      return ceilDiv(Math.max(urls, 1), 5) * rate;
+    }
+    case 'map': {
+      const limit = clamp(Number(args.limit) || 50, 1, 500);
+      const rate = args.instructions ? 2 : 1;
+      return ceilDiv(limit, 10) * rate;
+    }
+    case 'crawl': {
+      const limit = clamp(Number(args.limit) || 50, 1, 200);
+      const mapRate = args.instructions ? 2 : 1;
+      const exRate = args.extractDepth === 'advanced' ? 2 : 1;
+      return ceilDiv(limit, 10) * mapRate + ceilDiv(limit, 5) * exRate;
+    }
+    case 'research':
+    case 'research-start': {
+      const model = args.model || (op === 'research' ? 'mini' : 'auto');
+      if (model === 'mini') return 15;
+      return 50;
+    }
+    default:
+      return 0;
+  }
+}
+
+// Parallel — approximate, since public per-request pricing is opaque.
+// Tier mapping: lite ≈ 1, base ≈ 2, core/pro ≈ 5, ultra ≈ 25, ultra8x ≈ 200.
+function tierCredits(p) {
+  return { lite: 1, base: 2, core: 5, pro: 8, ultra: 25, ultra8x: 200 }[p] || 2;
+}
+
+function estimateParallel(op, args) {
+  switch (op) {
+    case 'search': {
+      const proc = args.processor || (args.depth === 'advanced' ? 'base' : 'lite');
+      return tierCredits(proc);
+    }
+    case 'extract': {
+      const urls = Array.isArray(args.urls) ? args.urls.length : 1;
+      return Math.max(1, ceilDiv(urls, 5));
+    }
+    case 'research':
+    case 'research-start': {
+      const proc = args.processor || ({ mini: 'lite', auto: 'base', pro: 'pro', ultra: 'ultra' }[args.model || 'auto']) || 'base';
+      return tierCredits(proc);
+    }
+    case 'crawl':
+    case 'map':
+      return Infinity; // not supported, won't be chosen
+    default:
+      return 0;
+  }
+}
+
+export function estimateCreditsForChain(operation, args, chain) {
+  let worst = 0;
+  for (const p of chain) {
+    const est = p === 'tavily' ? estimateTavily(operation, args) : estimateParallel(operation, args);
+    if (Number.isFinite(est) && est > worst) worst = est;
+  }
+  return worst;
+}
+
+export function guardExpensive(operation, args, chain, flags) {
+  if (EXPENSIVE_OK || flags['confirm-expensive']) return;
+  const estimate = estimateCreditsForChain(operation, args, chain);
+  if (estimate > 10) {
+    const err = new Error(
+      `This '${operation}' is estimated at ~${estimate} credits across providers. Re-run with --confirm-expensive (or set SURF_ALLOW_EXPENSIVE=1) after user approval.`
+    );
+    err.code = 'EXPENSIVE_BLOCKED';
+    throw err;
+  }
+}

package/src/lib/dispatch.mjs

@@ -0,0 +1,320 @@
+// Central dispatch: provider+key fallback for every operation. The CLI never
+// talks to provider adapters directly — it always goes through dispatch().
+
+import {
+  loadState, saveStateAtomic, markBurned, providerHasUsableKey,
+  nextUsableKeyIndex, PROVIDERS as PROVIDER_NAMES,
+} from './state.mjs';
+import { audit, recordUsage } from './audit.mjs';
+import { cacheKey, cacheGet, cacheSet } from './cache.mjs';
+import { getProvider, capabilityMap, providerFromRequestId } from './providers/index.mjs';
+import { guardExpensive } from './cost.mjs';
+import { sleep } from './flags.mjs';
+import { progress } from './progress.mjs';
+
+const CACHEABLE = new Set(['search', 'extract', 'map']);
+const VERSION = '1.0.0';
+
+// Detect the agent harness's bash timeout from env vars. The number is the
+// total time (ms) the harness will allow our process to live before SIGTERM.
+// We use this to abort early with an actionable error instead of being killed
+// silently.
+export function detectHarnessBudgetMs() {
+  if (process.env.SURF_AGENT_BUDGET_MS) {
+    const n = Number(process.env.SURF_AGENT_BUDGET_MS);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  if (process.env.BASH_DEFAULT_TIMEOUT_MS) {
+    const n = Number(process.env.BASH_DEFAULT_TIMEOUT_MS);
+    if (Number.isFinite(n) && n > 0) return n; // Claude Code
+  }
+  if (process.env.PI_BASH_DEFAULT_TIMEOUT_SECONDS) {
+    const n = Number(process.env.PI_BASH_DEFAULT_TIMEOUT_SECONDS);
+    if (Number.isFinite(n) && n > 0) return n * 1000; // Pi
+  }
+  if (process.env.OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS) {
+    const n = Number(process.env.OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  // Unknown harness — assume worst case (Copilot CLI without per-project hook).
+  return 30_000;
+}
+
+export function detectHarnessName() {
+  if (process.env.SURF_AGENT_BUDGET_MS) return 'override';
+  if (process.env.BASH_DEFAULT_TIMEOUT_MS) return 'claude-code';
+  if (process.env.PI_BASH_DEFAULT_TIMEOUT_SECONDS) return 'pi';
+  if (process.env.OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS) return 'opencode';
+  return 'unknown (assuming 30s — likely GH Copilot CLI without hook)';
+}
+
+export class DispatchError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'DispatchError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function buildChain(operation, state, flags) {
+  if (operation === 'research-poll') {
+    const decoded = providerFromRequestId(flags.__requestId);
+    if (!decoded) throw new DispatchError('BAD_REQUEST_ID', `unknown request_id prefix in '${flags.__requestId}'`);
+    if (!providerHasUsableKey(state, decoded.provider)) {
+      throw new DispatchError(
+        'NoUsableKeyForRequestId',
+        `request_id belongs to provider '${decoded.provider}', which has no usable keys; run "surf-skill keys add --provider ${decoded.provider} <key>" and retry`
+      );
+    }
+    return { chain: [decoded.provider], pinned: true, decoded };
+  }
+
+  if (operation === 'usage') {
+    const provider = flags.provider;
+    if (!provider) throw new DispatchError('UsageNeedsProvider', `'usage' requires --provider tavily|parallel`);
+    if (!providerHasUsableKey(state, provider)) {
+      throw new DispatchError('NoUsableKey', `provider '${provider}' has no usable keys`);
+    }
+    return { chain: [provider], pinned: true };
+  }
+
+  const baseChain = capabilityMap[operation];
+  if (!Array.isArray(baseChain)) {
+    throw new DispatchError('UnknownOperation', `operation '${operation}' is not registered`);
+  }
+
+  let chain = baseChain.filter(p => providerHasUsableKey(state, p));
+
+  if (flags.provider) {
+    if (!baseChain.includes(flags.provider)) {
+      throw new DispatchError('NotCapable',
+        `provider '${flags.provider}' does not support '${operation}' (supported: ${baseChain.join(', ')})`);
+    }
+    if (!providerHasUsableKey(state, flags.provider)) {
+      throw new DispatchError('NoUsableKey', `provider '${flags.provider}' has no usable keys for '${operation}'`);
+    }
+    return { chain: [flags.provider], pinned: true };
+  }
+
+  if (chain.length === 0) {
+    throw new DispatchError(
+      'NoProviderAvailable',
+      `operation '${operation}' requires one of [${baseChain.join(', ')}]; run "surf-skill keys add --provider <name> <key>"`
+    );
+  }
+
+  // Promote last_ok_provider to the front when it is still in the filtered chain.
+  if (state.last_ok_provider && chain.includes(state.last_ok_provider)) {
+    chain = [state.last_ok_provider, ...chain.filter(x => x !== state.last_ok_provider)];
+  }
+
+  if (flags['no-fallback'] || flags.noFallback) {
+    return { chain: [chain[0]], pinned: true };
+  }
+
+  return { chain, pinned: false };
+}
+
+function backoff(attempt) {
+  return Math.min(1500 * (attempt + 1) ** 2, 8000);
+}
+
+export async function dispatch(operation, args, flags = {}, runCtx = {}) {
+  const startTs = Date.now();
+  const harnessBudget = detectHarnessBudgetMs();
+  const harnessName = detectHarnessName();
+  // Reserve a cushion so we surface the error before the harness kills us.
+  const cushion = Math.min(2000, Math.floor(harnessBudget * 0.1));
+
+  // Library mode: caller can pass an in-memory state object to avoid touching
+  // ~/.config/surf/keys.json. State mutations (last_ok_provider, burned) stay
+  // in-memory and don't get persisted when runCtx.state._inMemory is true.
+  const state = runCtx.state || await loadState();
+  const persistState = !state._inMemory;
+  let cachedHit = null;
+  let cKey = null;
+
+  // Cache lookup (only for cacheable, only when not forced/raw/no-cache).
+  if (CACHEABLE.has(operation) && !flags['no-cache'] && !flags['raw-json'] && !flags.provider) {
+    cKey = cacheKey('any', operation, args);
+    cachedHit = await cacheGet(cKey);
+    if (cachedHit) {
+      await audit({ op: operation, cache: 'hit', provider: cachedHit.provider });
+      await recordUsage({ op: operation, provider: cachedHit.provider, credits: 0, cached: true });
+      progress.success(`${operation} cache hit (${cachedHit.provider})`);
+      return cachedHit;
+    }
+  }
+
+  const { chain, pinned, decoded } = buildChain(operation, state, flags);
+
+  // Cost guard runs AFTER chain build, so NoProviderAvailable and
+  // bad-input errors surface before users see a misleading credit warning.
+  if (operation !== 'research-poll' && operation !== 'usage') {
+    guardExpensive(operation, args, chain, flags);
+  }
+
+  const errors = [];
+
+  for (const providerName of chain) {
+    const provider = getProvider(providerName);
+    if (!provider) {
+      errors.push(`${providerName}: provider not registered`);
+      continue;
+    }
+    if (operation !== 'research-poll' && !provider.supports[operation]) {
+      errors.push(`${providerName}: does not support '${operation}'`);
+      continue;
+    }
+
+    let attempted = new Set();
+    let providerExhausted = false;
+
+    while (!providerExhausted) {
+      const keyIdx = (() => {
+        const p = state[providerName];
+        if (!p || !p.keys.length) return -1;
+        const burnedIdx = new Set(p.burned.map(b => b.index));
+        const n = p.keys.length;
+        const start = Math.max(0, Math.min(p.current || 0, n - 1));
+        for (let off = 0; off < n; off++) {
+          const i = (start + off) % n;
+          if (attempted.has(i)) continue;
+          if (burnedIdx.has(i)) continue;
+          return i;
+        }
+        return -1;
+      })();
+
+      if (keyIdx === -1) { providerExhausted = true; break; }
+      attempted.add(keyIdx);
+      progress.start(`${operation} → ${providerName} (key #${keyIdx})`);
+
+      // Self-budget check: abort BEFORE the harness SIGTERMs us.
+      const elapsed = Date.now() - startTs;
+      const remaining = harnessBudget - elapsed - cushion;
+      if (remaining <= 1000) {
+        throw new DispatchError(
+          'LikelyAgentTimeout',
+          `Operation '${operation}' would likely exceed the agent's bash timeout ` +
+          `(~${Math.round(harnessBudget / 1000)}s detected, harness=${harnessName}). ` +
+          `Run 'surf-skill project-config' in this project to raise the limit, ` +
+          `or use 'research-start' + 'research-poll' for long jobs.`,
+          { harness: harnessName, budgetMs: harnessBudget, elapsedMs: elapsed },
+        );
+      }
+
+      const ctx = {
+        key: state[providerName].keys[keyIdx],
+        // Constrain HTTP timeout to whatever's left in our budget so we don't
+        // sit waiting beyond what the harness will allow.
+        timeout: Math.min(
+          flags.timeout ? Number(flags.timeout) : Infinity,
+          remaining,
+        ),
+        version: VERSION,
+      };
+
+      const callArgs = operation === 'research-poll' && decoded
+        ? { ...args, providerRunId: decoded.providerRunId }
+        : args;
+
+      let consecutive5xx = 0;
+      let consecutive429 = 0;
+      let consecutiveNetwork = 0;
+      let success = null;
+
+      for (let attempt = 0; attempt < 3 && !success; attempt++) {
+        try {
+          const result = await provider[operation](callArgs, ctx);
+          success = result;
+          break;
+        } catch (e) {
+          const kind = e.kind || 'caller_4xx';
+          await audit({
+            op: operation, provider: providerName, key_index: keyIdx,
+            kind, status: e.statusCode, message: (e.message || '').slice(0, 200),
+          });
+
+          if (kind === 'caller_4xx' || kind === 'not_supported') {
+            // Don't retry, don't fallback. Bad input.
+            throw e;
+          }
+          if (kind === 'rate_limit_429') {
+            consecutive429++;
+            if (attempt < 2) {
+              progress.retry(`${providerName} 429 — backoff ${backoff(attempt)}ms (attempt ${attempt + 1}/3)`);
+              await sleep(backoff(attempt)); continue;
+            }
+            break; // exhausted retries -> next key
+          }
+          if (kind === 'network') {
+            consecutiveNetwork++;
+            if (attempt < 2) {
+              progress.retry(`${providerName} network error — backoff ${Math.round(backoff(attempt) / 2)}ms`);
+              await sleep(backoff(attempt) / 2); continue;
+            }
+            break; // exhausted retries -> next key
+          }
+          if (kind === 'auth') {
+            progress.warn(`${providerName} key #${keyIdx} burned (${e.statusCode || 'auth'})`);
+            markBurned(state, providerName, keyIdx, String(e.statusCode || 'auth'));
+            if (persistState) await saveStateAtomic(state);
+            break; // next key
+          }
+          if (kind === 'server_5xx') {
+            consecutive5xx++;
+            if (consecutive5xx >= 3) {
+              progress.warn(`${providerName} key #${keyIdx} burned (5xx x3)`);
+              markBurned(state, providerName, keyIdx, '5xx');
+              if (persistState) await saveStateAtomic(state);
+              break; // next key
+            }
+            if (attempt < 2) {
+              progress.retry(`${providerName} 5xx — backoff ${backoff(attempt)}ms`);
+              await sleep(backoff(attempt)); continue;
+            }
+            break;
+          }
+          // Unknown kind — treat as caller error to avoid masking bugs.
+          throw e;
+        }
+      }
+
+      if (success) {
+        state.last_ok_provider = providerName;
+        state[providerName].current = keyIdx;
+        if (persistState) await saveStateAtomic(state);
+        await recordUsage({
+          op: operation,
+          provider: providerName,
+          key_index: keyIdx,
+          credits: success.usage && success.usage.credits,
+          cached: false,
+          latency_ms: success.latency_ms,
+        });
+        if (cKey && CACHEABLE.has(operation)) {
+          await cacheSet(cKey, success);
+        }
+        const credits = success.usage && success.usage.credits;
+        progress.success(
+          `${operation} ${providerName} ${success.latency_ms}ms` +
+          (credits != null ? ` (${credits} credits)` : '')
+        );
+        return success;
+      }
+
+      // No success on this key; record summary and loop to next key.
+      errors.push(`${providerName}#${keyIdx}: ${consecutive5xx ? '5xx' : consecutive429 ? '429' : consecutiveNetwork ? 'network' : 'auth'}`);
+    }
+
+    if (pinned) break;
+  }
+
+  throw new DispatchError(
+    'AllProvidersExhausted',
+    `operation '${operation}' failed on every provider/key${errors.length ? ': ' + errors.join('; ') : ''}`,
+    { errors },
+  );
+}