free-coding-models 0.1.82 → 0.1.84

package/src/analysis.js

@@ -0,0 +1,197 @@
+/**
+ * @file analysis.js
+ * @description Analysis functions for model reliability scoring and dynamic model discovery.
+ *
+ * @details
+ *   This module provides high-level analysis functions:
+ *   - Fiable mode: 10-second reliability analysis to find the most stable model
+ *   - Dynamic OpenRouter model discovery: Fetch free models from OpenRouter API
+ *   - Tier filtering with validation
+ *
+ *   🎯 Key features:
+ *   - Run 10-second reliability analysis across all models
+ *   - Find best model based on uptime, avg latency, and stability
+ *   - Fetch real-time OpenRouter free models (replaces static list)
+ *   - Tier filtering validation with helpful error messages
+ *
+ *   → Functions:
+ *   - `runFiableMode`: Analyze models for 10 seconds and output the most reliable one
+ *   - `filterByTierOrExit`: Filter models by tier, exit with error if tier is invalid
+ *   - `fetchOpenRouterFreeModels`: Fetch live free models from OpenRouter API
+ *
+ *   📦 Dependencies:
+ *   - ../sources.js: MODELS, sources
+ *   - ../src/utils.js: findBestModel, filterByTier, formatCtxWindow, labelFromId
+ *   - ../src/config.js: isProviderEnabled, getApiKey
+ *   - ../src/ping.js: ping
+ *   - chalk: Terminal colors and formatting
+ *   - ../src/constants.js: TIER_LETTER_MAP (for validation)
+ *
+ *   ⚙️ Configuration:
+ *   - Analysis duration: 10 seconds (hardcoded in runFiableMode)
+ *   - OpenRouter tier map: Known SWE-bench scores for popular models (fallback for unknown)
+ *
+ *   @see {@link ../src/utils.js} findBestModel implementation
+ *   @see {@link ../src/ping.js} ping implementation
+ */
+
+import { MODELS, sources } from '../sources.js'
+import { findBestModel, filterByTier, formatCtxWindow, labelFromId, TIER_LETTER_MAP } from '../src/utils.js'
+import { isProviderEnabled, getApiKey } from '../src/config.js'
+import { ping } from '../src/ping.js'
+import chalk from 'chalk'
+
+// 📖 runFiableMode: Analyze models for reliability over 10 seconds, output the best one.
+// 📖 Filters to enabled providers with keys, runs initial pings, then waits.
+// 📖 Uses findBestModel() from utils.js to select based on uptime/avg/stability.
+export async function runFiableMode(config) {
+  console.log(chalk.cyan('  ⚡ Analyzing models for reliability (10 seconds)...'))
+  console.log()
+
+  // 📖 Only include models from enabled providers that have API keys
+  let results = MODELS
+    .filter(([,,,,,providerKey]) => {
+      return isProviderEnabled(config, providerKey) && getApiKey(config, providerKey)
+    })
+    .map(([modelId, label, tier, sweScore, ctx, providerKey], i) => ({
+      idx: i + 1, modelId, label, tier, sweScore, ctx, providerKey,
+      status: 'pending',
+      pings: [],
+      httpCode: null,
+    }))
+
+  const startTime = Date.now()
+  const analysisDuration = 10000 // 10 seconds
+
+  // 📖 Run initial pings using per-provider API key and URL
+  const pingPromises = results.map(r => {
+    const rApiKey = getApiKey(config, r.providerKey)
+    const url = sources[r.providerKey]?.url
+    return ping(rApiKey, r.modelId, r.providerKey, url).then(({ code, ms }) => {
+      r.pings.push({ ms, code })
+      if (code === '200') {
+        r.status = 'up'
+      } else if (code === '000') {
+        r.status = 'timeout'
+      } else {
+        r.status = 'down'
+        r.httpCode = code
+      }
+    })
+  })
+
+  await Promise.allSettled(pingPromises)
+
+  // 📖 Continue pinging for the remaining time
+  const remainingTime = Math.max(0, analysisDuration - (Date.now() - startTime))
+  if (remainingTime > 0) {
+    await new Promise(resolve => setTimeout(resolve, remainingTime))
+  }
+
+  // 📖 Find best model
+  const best = findBestModel(results)
+
+  if (!best) {
+    console.log(chalk.red('  ✖ No reliable model found'))
+    process.exit(1)
+  }
+
+  // 📖 Output in format: providerName/modelId
+  const providerName = sources[best.providerKey]?.name ?? best.providerKey ?? 'nvidia'
+  console.log(chalk.green(`  ✓ Most reliable model:`))
+  console.log(chalk.bold(`    ${providerName}/${best.modelId}`))
+  console.log()
+  console.log(chalk.dim(`  📊 Stats:`))
+  const { getAvg, getUptime } = await import('./utils.js')
+  console.log(chalk.dim(`    Avg ping: ${getAvg(best)}ms`))
+  console.log(chalk.dim(`    Uptime: ${getUptime(best)}%`))
+  console.log(chalk.dim(`    Status: ${best.status === 'up' ? '✅ UP' : '❌ DOWN'}`))
+
+  process.exit(0)
+}
+
+// 📖 filterByTierOrExit: Filter models by tier letter (S/A/B/C).
+// 📖 Wrapper around filterByTier() that exits with error message instead of returning null.
+// 📖 This is used by CLI argument parsing to fail fast on invalid tier input.
+export function filterByTierOrExit(results, tierLetter) {
+  const filtered = filterByTier(results, tierLetter)
+  if (filtered === null) {
+    console.error(chalk.red(`  ✖ Unknown tier "${tierLetter}". Valid tiers: S, A, B, C`))
+    process.exit(1)
+  }
+  return filtered
+}
+
+// ─── Dynamic OpenRouter free model discovery ──────────────────────────────────
+// 📖 Fetches the live list of free models from OpenRouter's public API at startup.
+// 📖 Replaces the static openrouter entries in MODELS with fresh data so new free
+// 📖 models appear automatically without a code update.
+// 📖 Falls back silently to the static list on network failure.
+
+// 📖 Known SWE-bench scores for OpenRouter free models.
+// 📖 Keyed by base model ID (without the :free suffix).
+// 📖 Unknown models default to tier 'B' / '25.0%'.
+const OPENROUTER_TIER_MAP = {
+  'qwen/qwen3-coder':                         ['S+', '70.6%'],
+  'mistralai/devstral-2':                      ['S+', '72.2%'],
+  'stepfun/step-3.5-flash':                    ['S+', '74.4%'],
+  'deepseek/deepseek-r1-0528':                 ['S',  '61.0%'],
+  'qwen/qwen3-next-80b-a3b-instruct':          ['S',  '65.0%'],
+  'openai/gpt-oss-120b':                       ['S',  '60.0%'],
+  'openai/gpt-oss-20b':                        ['A',  '42.0%'],
+  'nvidia/nemotron-3-nano-30b-a3b':            ['A',  '43.0%'],
+  'meta-llama/llama-3.3-70b-instruct':         ['A-', '39.5%'],
+  'mimo-v2-flash':                             ['A',  '45.0%'],
+  'google/gemma-3-27b-it':                     ['A-', '36.0%'],
+  'google/gemma-3-12b-it':                     ['B+', '30.0%'],
+  'google/gemma-3-4b-it':                      ['B',  '22.0%'],
+  'google/gemma-3n-e4b-it':                    ['B',  '22.0%'],
+  'google/gemma-3n-e2b-it':                    ['B',  '18.0%'],
+  'meta-llama/llama-3.2-3b-instruct':          ['B',  '20.0%'],
+  'mistralai/mistral-small-3.1-24b-instruct':  ['A-', '35.0%'],
+  'qwen/qwen3-4b':                             ['B',  '22.0%'],
+  'nousresearch/hermes-3-llama-3.1-405b':      ['A',  '40.0%'],
+  'nvidia/nemotron-nano-9b-v2':                ['B+', '28.0%'],
+  'nvidia/nemotron-nano-12b-v2-vl':            ['B+', '30.0%'],
+  'z-ai/glm-4.5-air':                          ['A-', '38.0%'],
+  'arcee-ai/trinity-large-preview':             ['A',  '40.0%'],
+  'arcee-ai/trinity-mini':                      ['B+', '28.0%'],
+  'upstage/solar-pro-3':                       ['A-', '35.0%'],
+  'cognitivecomputations/dolphin-mistral-24b-venice-edition': ['B+', '28.0%'],
+  'liquid/lfm-2.5-1.2b-thinking':              ['B',  '18.0%'],
+  'liquid/lfm-2.5-1.2b-instruct':              ['B',  '18.0%'],
+}
+
+// 📖 fetchOpenRouterFreeModels: Fetch live free models from OpenRouter API.
+// 📖 Returns array of tuples [modelId, label, tier, sweScore, ctx] or null on failure.
+// 📖 Formats context windows using formatCtxWindow and labels using labelFromId.
+// 📖 Uses OPENROUTER_TIER_MAP for known models; others default to tier 'B'/'25.0%'.
+export async function fetchOpenRouterFreeModels() {
+  try {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), 5000)
+    const res = await fetch('https://openrouter.ai/api/v1/models', {
+      signal: controller.signal,
+      headers: {
+        'HTTP-Referer': 'https://github.com/vava-nessa/free-coding-models',
+        'X-Title': 'free-coding-models',
+      },
+    })
+    clearTimeout(timeout)
+    if (!res.ok) return null
+    const json = await res.json()
+    if (!json.data || !Array.isArray(json.data)) return null
+
+    const freeModels = json.data.filter(m => m.id && m.id.endsWith(':free'))
+
+    return freeModels.map(m => {
+      const baseId = m.id.replace(/:free$/, '')
+      const [tier, swe] = OPENROUTER_TIER_MAP[baseId] || ['B', '25.0%']
+      const ctx = formatCtxWindow(m.context_length)
+      const label = labelFromId(m.id)
+      return [m.id, label, tier, swe, ctx]
+    })
+  } catch {
+    return null
+  }
+}

package/{lib → src}/config.js

@@ -85,6 +85,9 @@
  *   → loadConfig() — Read ~/.free-coding-models.json; auto-migrate old plain-text config if needed
  *   → saveConfig(config) — Write config to ~/.free-coding-models.json with 0o600 permissions
  *   → getApiKey(config, providerKey) — Get effective API key (env var override > config > null)
+ *   → addApiKey(config, providerKey, key) — Append a key (string→array); ignores empty/duplicate
+ *   → removeApiKey(config, providerKey, index?) — Remove key at index (or last); collapses array-of-1 to string; deletes when empty
+ *   → listApiKeys(config, providerKey) — Return all keys for a provider as normalized array
  *   → isProviderEnabled(config, providerKey) — Check if provider is enabled (defaults true)
  *   → saveAsProfile(config, name) — Snapshot current apiKeys/providers/favorites/settings into a named profile
  *   → loadProfile(config, name) — Apply a named profile's values onto the live config
@@ -95,6 +98,7 @@
  *   → _emptyProfileSettings() — Default TUI settings for a profile
  *
  * @exports loadConfig, saveConfig, getApiKey, isProviderEnabled
+ * @exports addApiKey, removeApiKey, listApiKeys — multi-key management helpers
  * @exports saveAsProfile, loadProfile, listProfiles, deleteProfile
  * @exports getActiveProfileName, setActiveProfile
  * @exports CONFIG_PATH — path to the JSON config file
@@ -239,6 +243,124 @@ export function getApiKey(config, providerKey) {
   return null
 }
 
+/**
+ * addApiKey: Append a new API key for a provider.
+ *
+ * - If the provider has no key yet, sets it as a plain string.
+ * - If the provider already has one string key, converts to array [existing, new].
+ * - If the provider already has an array, pushes the new key.
+ * - Ignores empty/whitespace keys.
+ * - Ignores exact duplicates (same string already present).
+ *
+ * @param {object} config — Live config object (will be mutated)
+ * @param {string} providerKey — Provider identifier (e.g. 'groq')
+ * @param {string} key — New API key to add
+ * @returns {boolean} true if added, false if ignored (empty or duplicate)
+ */
+export function addApiKey(config, providerKey, key) {
+  const trimmed = typeof key === 'string' ? key.trim() : ''
+  if (!trimmed) return false
+  if (!config.apiKeys) config.apiKeys = {}
+  const current = config.apiKeys[providerKey]
+  if (!current) {
+    config.apiKeys[providerKey] = trimmed
+    return true
+  }
+  if (typeof current === 'string') {
+    if (current === trimmed) return false // duplicate
+    config.apiKeys[providerKey] = [current, trimmed]
+    return true
+  }
+  if (Array.isArray(current)) {
+    if (current.includes(trimmed)) return false // duplicate
+    current.push(trimmed)
+    return true
+  }
+  // unknown shape — replace
+  config.apiKeys[providerKey] = trimmed
+  return true
+}
+
+/**
+ * removeApiKey: Remove an API key for a provider by index, or remove the last one.
+ *
+ * - Removes the key at `index` if provided, else removes the last key.
+ * - If only one key remains after removal, collapses array to string.
+ * - If the last key is removed, deletes the provider entry entirely.
+ *
+ * @param {object} config — Live config object (will be mutated)
+ * @param {string} providerKey — Provider identifier (e.g. 'groq')
+ * @param {number} [index] — 0-based index to remove; omit to remove last
+ * @returns {boolean} true if a key was removed, false if nothing to remove
+ */
+export function removeApiKey(config, providerKey, index) {
+  if (!config.apiKeys) return false
+  const current = config.apiKeys[providerKey]
+  if (!current) return false
+
+  if (typeof current === 'string') {
+    // Only one key — remove it
+    delete config.apiKeys[providerKey]
+    return true
+  }
+
+  if (Array.isArray(current)) {
+    const idx = (index !== undefined && index >= 0 && index < current.length) ? index : current.length - 1
+    current.splice(idx, 1)
+    if (current.length === 0) {
+      delete config.apiKeys[providerKey]
+    } else if (current.length === 1) {
+      config.apiKeys[providerKey] = current[0] // collapse array-of-1 to string
+    }
+    return true
+  }
+
+  return false
+}
+
+/**
+ * listApiKeys: Return all configured API keys for a provider as a normalized array.
+ * Empty when no key is configured.
+ *
+ * @param {object} config
+ * @param {string} providerKey
+ * @returns {string[]}
+ */
+export function listApiKeys(config, providerKey) {
+  return resolveApiKeys(config, providerKey)
+}
+
+/**
+ * Resolve all API keys for a provider as an array.
+ * Handles: string → [string], string[] → string[], missing → []
+ * Filters empty strings. Falls back to envVarName if no config key.
+ */
+export function resolveApiKeys(config, providerKey, envVarName) {
+  const raw = config?.apiKeys?.[providerKey]
+  let keys = []
+  if (Array.isArray(raw)) {
+    keys = raw
+  } else if (typeof raw === 'string' && raw.length > 0) {
+    keys = [raw]
+  } else if (envVarName && process.env[envVarName]) {
+    keys = [process.env[envVarName]]
+  }
+  return keys.filter(k => typeof k === 'string' && k.length > 0)
+}
+
+/**
+ * Normalize config for disk persistence.
+ * Single-element arrays collapse to string. Multi-element arrays stay.
+ */
+export function normalizeApiKeyConfig(config) {
+  if (!config?.apiKeys) return
+  for (const [key, val] of Object.entries(config.apiKeys)) {
+    if (Array.isArray(val) && val.length === 1) {
+      config.apiKeys[key] = val[0]
+    }
+  }
+}
+
 /**
  * 📖 isProviderEnabled: Check if a provider is enabled in config.
  *

package/src/constants.js

@@ -0,0 +1,116 @@
+/**
+ * @file constants.js
+ * @description Pure terminal/TUI constants extracted from bin/free-coding-models.js.
+ *
+ * @details
+ *   This module centralises every "magic number" and escape-sequence constant that
+ *   the TUI rendering pipeline depends on.  Having them here means:
+ *   - They are importable by unit tests without pulling in the entire CLI entry point.
+ *   - A single source of truth for column widths, timing values, overlay colours, etc.
+ *   - `msCell` and `spinCell` live here too because they only depend on `CELL_W`,
+ *     `FRAMES`, and chalk — all of which are available at module scope.
+ *
+ *   ⚙️ Key configuration:
+ *   - `PING_TIMEOUT` / `PING_INTERVAL` control how aggressive the health-check loop is.
+ *   - `FPS` controls animation frame rate (braille spinner).
+ *   - `COL_MODEL` / `COL_MS` control legacy ping-column widths (retained for compat).
+ *   - `CELL_W` is derived from `COL_MS` and used by `msCell` / `spinCell`.
+ *   - `TABLE_HEADER_LINES` + `TABLE_FOOTER_LINES` = `TABLE_FIXED_LINES` must stay in sync
+ *     with the actual number of lines rendered by `renderTable()` in bin/.
+ *   - Overlay background colours (chalk.bgRgb) make each overlay panel visually distinct.
+ *
+ * @functions
+ *   → msCell(ms)       — Formats a latency value into a fixed-width coloured cell string
+ *   → spinCell(f, o)   — Returns a braille spinner cell at frame f with optional offset o
+ *
+ * @exports
+ *   ALT_ENTER, ALT_LEAVE, ALT_HOME,
+ *   PING_TIMEOUT, PING_INTERVAL,
+ *   FPS, COL_MODEL, COL_MS, CELL_W,
+ *   FRAMES, TIER_CYCLE,
+ *   SETTINGS_OVERLAY_BG, HELP_OVERLAY_BG, RECOMMEND_OVERLAY_BG, LOG_OVERLAY_BG,
+ *   OVERLAY_PANEL_WIDTH,
+ *   TABLE_HEADER_LINES, TABLE_FOOTER_LINES, TABLE_FIXED_LINES,
+ *   msCell, spinCell
+ *
+ * @see bin/free-coding-models.js  — main entry point that imports these constants
+ * @see src/tier-colors.js         — TIER_COLOR map (chalk-dependent, separate module)
+ */
+
+import chalk from 'chalk'
+
+// 📖 Alternate screen ANSI escape sequences used to enter/leave the TUI buffer.
+// 📖 \x1b[?1049h = enter alt screen  \x1b[?1049l = leave alt screen
+// 📖 \x1b[?25l   = hide cursor        \x1b[?25h   = show cursor
+// 📖 \x1b[H      = cursor to top
+// 📖 \x1b[?7l disables auto-wrap so wide rows clip at the right edge instead of
+// 📖 wrapping to the next line (which would double the row height and overflow).
+export const ALT_ENTER = '\x1b[?1049h\x1b[?25l\x1b[?7l'
+export const ALT_LEAVE = '\x1b[?7h\x1b[?1049l\x1b[?25h'
+export const ALT_HOME  = '\x1b[H'
+
+// 📖 Timing constants — control how fast the health-check loop runs.
+export const PING_TIMEOUT  = 15_000  // 📖 15s per attempt before abort
+export const PING_INTERVAL = 3_000   // 📖 3s between pings for fast model selection feedback
+
+// 📖 Animation and column-width constants.
+export const FPS       = 12
+export const COL_MODEL = 22
+// 📖 COL_MS = dashes in hline per ping column = visual width including 2 padding spaces.
+// 📖 Max value: 12001ms = 7 chars. padStart(COL_MS-2) fits content, +2 spaces = COL_MS dashes.
+export const COL_MS    = 11
+
+// 📖 CELL_W = visual content width of a single ms/spinner cell (COL_MS minus 2 border spaces).
+export const CELL_W = COL_MS - 2  // 📖 9 chars of content per ms cell
+
+// 📖 Braille spinner frames for the "pinging..." animation.
+export const FRAMES = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏']
+
+// 📖 TIER_CYCLE: ordered list of tier-filter states cycled by the T key.
+// 📖 Index 0 = no filter (show all), then each tier name in descending quality order.
+export const TIER_CYCLE = [null, 'S+', 'S', 'A+', 'A', 'A-', 'B+', 'B', 'C']
+
+// 📖 Overlay background chalk functions — each overlay panel has a distinct tint
+// 📖 so users can tell Settings, Help, Recommend, and Log panels apart at a glance.
+export const SETTINGS_OVERLAY_BG  = chalk.bgRgb(14, 20, 30)
+export const HELP_OVERLAY_BG      = chalk.bgRgb(24, 16, 32)
+export const RECOMMEND_OVERLAY_BG = chalk.bgRgb(10, 25, 15)  // 📖 Green tint for Smart Recommend
+export const LOG_OVERLAY_BG       = chalk.bgRgb(10, 20, 26)  // 📖 Dark blue-green tint for Log page
+
+// 📖 OVERLAY_PANEL_WIDTH: fixed character width of all overlay panels so background
+// 📖 tint fills the panel consistently regardless of content length.
+export const OVERLAY_PANEL_WIDTH = 116
+
+// 📖 Table row-budget constants — must stay in sync with renderTable()'s actual output.
+// 📖 If this drifts, model rows overflow and can push the title row out of view.
+export const TABLE_HEADER_LINES = 4  // 📖 title, spacer, column headers, separator
+export const TABLE_FOOTER_LINES = 5  // 📖 spacer, hints line 1, hints line 2, spacer, credit+links
+export const TABLE_FIXED_LINES  = TABLE_HEADER_LINES + TABLE_FOOTER_LINES
+
+// ─── Small cell-formatting helpers ────────────────────────────────────────────
+
+/**
+ * 📖 msCell: Renders a latency measurement into a right-padded coloured cell.
+ * 📖 null  → dim dash (not yet pinged)
+ * 📖 'TIMEOUT' → red TIMEOUT text
+ * 📖 <500ms → bright green, <1500ms → yellow, else red
+ * @param {number|string|null} ms
+ * @returns {string}
+ */
+export const msCell = (ms) => {
+  if (ms === null) return chalk.dim('—'.padStart(CELL_W))
+  const str = String(ms).padStart(CELL_W)
+  if (ms === 'TIMEOUT') return chalk.red(str)
+  if (ms < 500)  return chalk.greenBright(str)
+  if (ms < 1500) return chalk.yellow(str)
+  return chalk.red(str)
+}
+
+/**
+ * 📖 spinCell: Returns a braille spinner character padded to CELL_W.
+ * 📖 f = current frame index, o = row offset so each row animates differently.
+ * @param {number} f - global frame counter
+ * @param {number} [o=0] - per-row offset to stagger animation
+ * @returns {string}
+ */
+export const spinCell = (f, o = 0) => chalk.dim.yellow(FRAMES[(f + o) % FRAMES.length].padEnd(CELL_W))

package/src/error-classifier.js

@@ -0,0 +1,154 @@
+/**
+ * Error types:
+ * - QUOTA_EXHAUSTED: Skip account until quota resets
+ * - RATE_LIMITED: Backoff, try another account
+ * - MODEL_CAPACITY: Server overloaded, retry after delay
+ * - SERVER_ERROR: Backoff, count toward circuit breaker
+ * - AUTH_ERROR: Disable account permanently
+ * - NETWORK_ERROR: Connection failure, try another
+ * - MODEL_NOT_FOUND: Provider does not have/serve this model; skip and try next account
+ * - UNKNOWN: Generic, no retry
+ */
+export const ErrorType = {
+  QUOTA_EXHAUSTED: 'QUOTA_EXHAUSTED',
+  RATE_LIMITED: 'RATE_LIMITED',
+  MODEL_CAPACITY: 'MODEL_CAPACITY',
+  SERVER_ERROR: 'SERVER_ERROR',
+  AUTH_ERROR: 'AUTH_ERROR',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  MODEL_NOT_FOUND: 'MODEL_NOT_FOUND',
+  UNKNOWN: 'UNKNOWN',
+}
+
+const QUOTA_KEYWORDS = ['quota', 'limit exceeded', 'billing', 'insufficient_quota', 'exceeded your']
+const CAPACITY_KEYWORDS = ['overloaded', 'capacity', 'busy', 'unavailable']
+/**
+ * Keywords that indicate a provider-level 404/410 means the model is not
+ * available on *this account/provider*, not a generic routing 404.
+ * These trigger rotation to the next provider rather than forwarding the error.
+ */
+const MODEL_NOT_FOUND_KEYWORDS = [
+  'model not found',
+  'inaccessible',
+  'not deployed',
+  'model is not available',
+  'model unavailable',
+  'no such model',
+]
+
+/**
+ * Classify the confidence level for a 429 response.
+ *
+ * Returns:
+ * - 'quota_exhaustion_likely' — body contains keywords indicating the account's quota is depleted
+ * - 'generic_rate_limit'      — plain rate-limit with no quota-specific signal (or non-429 status)
+ *
+ * @param {number} statusCode
+ * @param {string} body
+ * @param {Object} headers
+ * @returns {'quota_exhaustion_likely'|'generic_rate_limit'}
+ */
+export function rateLimitConfidence(statusCode, body, headers) {
+  if (statusCode !== 429) return 'generic_rate_limit'
+  const bodyLower = (body || '').toLowerCase()
+  const isQuota = QUOTA_KEYWORDS.some(kw => bodyLower.includes(kw))
+  return isQuota ? 'quota_exhaustion_likely' : 'generic_rate_limit'
+}
+
+/**
+ * Classify an HTTP error response.
+ * @param {number} statusCode - 0 for network errors
+ * @param {string} body - Response body text or error message
+ * @param {Object} headers - Response headers (lowercased keys)
+ * @returns {{ type: string, retryAfterSec: number|null, shouldRetry: boolean, skipAccount: boolean, rateLimitConfidence?: string }}
+ */
+export function classifyError(statusCode, body, headers) {
+  const bodyLower = (body || '').toLowerCase()
+  const retryAfter = headers?.['retry-after']
+  const retryAfterSec = retryAfter ? parseInt(retryAfter, 10) || null : null
+
+  // Network/connection errors
+  if (statusCode === 0 || statusCode === undefined) {
+    return { type: ErrorType.NETWORK_ERROR, retryAfterSec: 5, shouldRetry: true, skipAccount: false }
+  }
+
+  if (statusCode === 401 || statusCode === 403) {
+    return { type: ErrorType.AUTH_ERROR, retryAfterSec: null, shouldRetry: false, skipAccount: true }
+  }
+
+  // Provider-level 404/410: model not found / inaccessible / not deployed on this account.
+  // These are NOT generic routing 404s — they mean this specific provider doesn't serve
+  // the requested model. Rotate to the next account rather than forwarding the error.
+  if (statusCode === 404 || statusCode === 410) {
+    const isModelNotFound = MODEL_NOT_FOUND_KEYWORDS.some(kw => bodyLower.includes(kw))
+    if (isModelNotFound) {
+      return { type: ErrorType.MODEL_NOT_FOUND, retryAfterSec: null, shouldRetry: true, skipAccount: true }
+    }
+    // Generic 404 (wrong URL, endpoint not found, etc.) — not retryable
+    return { type: ErrorType.UNKNOWN, retryAfterSec: null, shouldRetry: false, skipAccount: false }
+  }
+
+  if (statusCode === 429) {
+    const isQuota = QUOTA_KEYWORDS.some(kw => bodyLower.includes(kw))
+    const confidence = isQuota ? 'quota_exhaustion_likely' : 'generic_rate_limit'
+    if (isQuota) {
+      return { type: ErrorType.QUOTA_EXHAUSTED, retryAfterSec, shouldRetry: true, skipAccount: true, rateLimitConfidence: confidence }
+    }
+    return { type: ErrorType.RATE_LIMITED, retryAfterSec, shouldRetry: true, skipAccount: false, rateLimitConfidence: confidence }
+  }
+
+  if (statusCode === 503 || statusCode === 502) {
+    return { type: ErrorType.MODEL_CAPACITY, retryAfterSec: retryAfterSec || 5, shouldRetry: true, skipAccount: false }
+  }
+
+  if (statusCode >= 500) {
+    return { type: ErrorType.SERVER_ERROR, retryAfterSec: retryAfterSec || 10, shouldRetry: true, skipAccount: false }
+  }
+
+  return { type: ErrorType.UNKNOWN, retryAfterSec: null, shouldRetry: false, skipAccount: false }
+}
+
+/**
+ * Circuit breaker: CLOSED → OPEN (after threshold failures) → HALF_OPEN (after cooldown) → CLOSED (on success) or → OPEN (on failure)
+ */
+export class CircuitBreaker {
+  constructor({ threshold = 5, cooldownMs = 60000 } = {}) {
+    this.threshold = threshold
+    this.cooldownMs = cooldownMs
+    this.consecutiveFailures = 0
+    this.openedAt = null
+    this.state = 'CLOSED'
+  }
+
+  recordFailure() {
+    this.consecutiveFailures++
+    if (this.consecutiveFailures >= this.threshold || this.state === 'HALF_OPEN') {
+      this.state = 'OPEN'
+      this.openedAt = Date.now()
+    }
+  }
+
+  recordSuccess() {
+    this.consecutiveFailures = 0
+    this.state = 'CLOSED'
+    this.openedAt = null
+  }
+
+  isOpen() {
+    if (this.state === 'CLOSED') return false
+    if (this.state === 'OPEN' && Date.now() - this.openedAt >= this.cooldownMs) {
+      this.state = 'HALF_OPEN'
+      return false
+    }
+    if (this.state === 'HALF_OPEN') return false
+    return true
+  }
+
+  isHalfOpen() { return this.state === 'HALF_OPEN' }
+
+  reset() {
+    this.consecutiveFailures = 0
+    this.state = 'CLOSED'
+    this.openedAt = null
+  }
+}