free-coding-models 0.5.88 → 0.5.89

package/src/core/router-v2/breaker-store.js

@@ -0,0 +1,265 @@
+/**
+ * @file breaker-store.js
+ * @description Persisted circuit breakers with a DEGRADED warning state for Router v2.
+ *
+ * @details
+ *   📖 v1 kept circuit breakers in memory only: every daemon restart wiped
+ *   them, and because the probe burst skips models that are still "fresh" in
+ *   the shared probe cache, a model that went bad right before a restart
+ *   happily received live traffic again until it failed three more times.
+ *
+ *   📖 v2 persists breaker state to disk (atomic write, debounced flush) and
+ *   restores it on boot, so cooldowns survive restarts. It also adds two
+ *   refinements:
+ *   - DEGRADED: a warning state at 60% of the failure threshold. A degraded
+ *     model is still routed (ranked below CLOSED models) and the dashboards
+ *     show it amber, so users see trouble BEFORE the breaker trips.
+ *   - Escalating backoff: each model remembers its `tripCount`; the cooldown
+ *     multiplies per trip (capped at 16x the initial cooldown), so a flapping
+ *     model does not re-enter rotation every 30 seconds.
+ *
+ * @functions
+ *   → new BreakerStore({ path, logger }) - Create + load persisted breakers
+ *   → store.ensure(key, initialCooldownMs) - Get or create a breaker entry
+ *   → store.markFailure(key, params) - Apply a failure; may trip the breaker
+ *   → store.markSuccess(key, initialCooldownMs) - Fully reset a breaker
+ *   → store.evaluate(key) - Lazily promote OPEN → HALF_OPEN after cooldown
+ *   → store.snapshot() / store.scheduleFlush() / store.flush()
+ *
+ * @exports BreakerStore
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { atomicWriteJson, safeJsonParse } from '../shared-helpers.js'
+
+const STATE_VERSION = 1
+const FLUSH_DEBOUNCE_MS = 2000
+// 📖 Entries untouched for 30 days are dropped so the file cannot grow forever.
+const ENTRY_TTL_MS = 30 * 24 * 60 * 60 * 1000
+// 📖 cooldown escalation cap: initial * 2^4 = 16x.
+const MAX_ESCALATION_STEPS = 4
+
+function defaultBreaker(initialCooldownMs) {
+  return {
+    state: 'CLOSED',
+    consecutiveFailures: 0,
+    tripCount: 0,
+    cooldownMs: initialCooldownMs,
+    openedAt: null,
+    lastError: null,
+    authError: false,
+    updatedAt: Date.now(),
+  }
+}
+
+function sanitizeEntry(raw, now) {
+  if (!raw || typeof raw !== 'object') return null
+  const state = ['CLOSED', 'DEGRADED', 'OPEN', 'HALF_OPEN'].includes(raw.state) ? raw.state : 'CLOSED'
+  const updatedAt = Number.isFinite(raw.updatedAt) ? raw.updatedAt : now
+  if (now - updatedAt > ENTRY_TTL_MS) return null
+  return {
+    state,
+    consecutiveFailures: Number.isFinite(raw.consecutiveFailures) ? Math.max(0, raw.consecutiveFailures) : 0,
+    tripCount: Number.isFinite(raw.tripCount) ? Math.max(0, raw.tripCount) : 0,
+    cooldownMs: Number.isFinite(raw.cooldownMs) && raw.cooldownMs > 0 ? raw.cooldownMs : 30_000,
+    openedAt: Number.isFinite(raw.openedAt) ? raw.openedAt : null,
+    lastError: typeof raw.lastError === 'string' ? raw.lastError.slice(0, 300) : null,
+    authError: raw.authError === true,
+    updatedAt,
+  }
+}
+
+export class BreakerStore {
+  /**
+   * @param {{ path: string, logger: object }} params
+   *   `path` is the JSON state file; pass a per-test temp path to isolate.
+   */
+  constructor({ path, logger }) {
+    this.path = path
+    this.logger = logger
+    this.breakers = new Map()
+    this.dirty = false
+    this.flushTimer = null
+    this.load()
+  }
+
+  load() {
+    try {
+      if (!existsSync(this.path)) return
+      const parsed = safeJsonParse(readFileSync(this.path, 'utf8'), null)
+      if (!parsed || typeof parsed !== 'object') return
+      const now = Date.now()
+      const entries = parsed.breakers && typeof parsed.breakers === 'object' ? parsed.breakers : {}
+      for (const [key, raw] of Object.entries(entries)) {
+        const entry = sanitizeEntry(raw, now)
+        if (entry) this.breakers.set(key, entry)
+      }
+      this.logger?.debug?.(`Restored ${this.breakers.size} persisted breaker(s)`)
+    } catch (error) {
+      this.logger?.warn?.('Breaker state load failed; starting fresh', { error: error?.message })
+    }
+  }
+
+  ensure(key, initialCooldownMs = 30_000) {
+    let entry = this.breakers.get(key)
+    if (!entry) {
+      entry = defaultBreaker(initialCooldownMs)
+      this.breakers.set(key, entry)
+    }
+    return entry
+  }
+
+  /**
+   * 📖 Lazily promote an OPEN breaker to HALF_OPEN once its cooldown elapsed.
+   * Called right before candidate scoring so no timer is needed.
+   */
+  evaluate(key) {
+    const entry = this.breakers.get(key)
+    if (!entry || entry.state !== 'OPEN') return entry
+    const elapsed = Date.now() - (entry.openedAt || 0)
+    if (elapsed >= entry.cooldownMs) {
+      entry.state = 'HALF_OPEN'
+      entry.updatedAt = Date.now()
+      this.dirty = true
+      this.scheduleFlush()
+    }
+    return entry
+  }
+
+  /**
+   * 📖 Apply a failure to a model breaker.
+   * @returns {{ state: string, opened: boolean, degraded: boolean }}
+   */
+  markFailure(key, {
+    detail = 'unknown',
+    statusCode = null,
+    failureThreshold = 3,
+    initialCooldownMs = 30_000,
+    maxCooldownMs = 300_000,
+    backoffMultiplier = 2,
+    authError = false,
+  } = {}) {
+    const entry = this.ensure(key, initialCooldownMs)
+    const before = entry.state
+    if (authError) {
+      // 📖 Auth problems ride along on the breaker as a sticky flag but never
+      // trip it: a dead key is a config issue, not an unhealthy model.
+      entry.authError = true
+      entry.lastError = detail
+      entry.updatedAt = Date.now()
+      this.dirty = true
+      this.scheduleFlush()
+      return { state: entry.state, opened: false, degraded: false }
+    }
+    entry.authError = false
+    entry.consecutiveFailures += 1
+    entry.lastError = detail
+    entry.updatedAt = Date.now()
+
+    const degradedThreshold = Math.max(1, Math.ceil(failureThreshold * 0.6))
+    let opened = false
+    let degraded = false
+    if (entry.state === 'HALF_OPEN' || entry.consecutiveFailures >= failureThreshold) {
+      entry.state = 'OPEN'
+      entry.openedAt = Date.now()
+      entry.tripCount += 1
+      // 📖 Escalating backoff: each successive trip multiplies the cooldown,
+      // capped so a flapping model can never disappear for hours.
+      const escalation = Math.min(entry.tripCount - 1, MAX_ESCALATION_STEPS)
+      entry.cooldownMs = Math.min(
+        maxCooldownMs,
+        Math.max(initialCooldownMs, initialCooldownMs * Math.pow(backoffMultiplier, escalation)),
+      )
+      opened = true
+    } else if (entry.consecutiveFailures >= degradedThreshold) {
+      if (entry.state === 'CLOSED') degraded = true
+      entry.state = 'DEGRADED'
+    }
+    if (entry.state !== before || opened || degraded) this.dirty = true
+    this.scheduleFlush()
+    return { state: entry.state, opened, degraded }
+  }
+
+  /**
+   * 📖 Full reset after a genuine success (routed traffic or a passing probe).
+   */
+  markSuccess(key, initialCooldownMs = 30_000) {
+    const entry = this.breakers.get(key)
+    if (!entry) return
+    const changed = entry.state !== 'CLOSED' || entry.consecutiveFailures > 0 || entry.authError
+    entry.state = 'CLOSED'
+    entry.consecutiveFailures = 0
+    entry.cooldownMs = initialCooldownMs
+    entry.openedAt = null
+    entry.lastError = null
+    entry.authError = false
+    entry.updatedAt = Date.now()
+    // 📖 tripCount deliberately survives success: it is the escalating-backoff
+    // memory. It decays only via the TTL prune.
+    if (changed) {
+      this.dirty = true
+      this.scheduleFlush()
+    }
+  }
+
+  setFlag(key, flag, value) {
+    const entry = this.breakers.get(key)
+    if (!entry) return
+    entry[flag] = value
+    entry.updatedAt = Date.now()
+    this.dirty = true
+    this.scheduleFlush()
+  }
+
+  get(key) {
+    return this.breakers.get(key) || null
+  }
+
+  delete(key) {
+    if (this.breakers.delete(key)) {
+      this.dirty = true
+      this.scheduleFlush()
+    }
+  }
+
+  /**
+   * 📖 Plain-object projection used by /stats, dashboards and persistence.
+   * `authError`/`stale`/`unsupported` style derived labels are applied by the
+   * caller; this returns the raw breaker fields.
+   */
+  snapshot() {
+    const out = {}
+    for (const [key, entry] of this.breakers.entries()) {
+      out[key] = {
+        state: entry.state,
+        consecutiveFailures: entry.consecutiveFailures,
+        tripCount: entry.tripCount,
+        cooldownMs: entry.cooldownMs,
+        openedAt: entry.openedAt,
+        lastError: entry.lastError,
+        authError: entry.authError,
+      }
+    }
+    return out
+  }
+
+  scheduleFlush() {
+    if (this.flushTimer) return
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null
+      this.flush()
+    }, FLUSH_DEBOUNCE_MS)
+    if (typeof this.flushTimer.unref === 'function') this.flushTimer.unref()
+  }
+
+  flush() {
+    if (!this.dirty) return
+    try {
+      const payload = { version: STATE_VERSION, saved_at: new Date().toISOString(), breakers: this.snapshot() }
+      atomicWriteJson(this.path, payload, 0o600)
+      this.dirty = false
+    } catch (error) {
+      this.logger?.warn?.('Breaker state write failed', { error: error?.message })
+    }
+  }
+}

package/src/core/router-v2/constants.js

@@ -0,0 +1,108 @@
+/**
+ * @file constants.js
+ * @description Shared constants + helpers for Router v2 (ports, state files, model pinning).
+ *
+ * @details
+ *   📖 Router v2 runs BETA alongside v1: own default port range (19380-19389
+ *   production, 29380-29389 dev), own PID/port/log/state files with a `-v2`
+ *   suffix, so both daemons can run on the same machine without clashing.
+ *   Both daemons share the same `~/.free-coding-models.json` config (sets,
+ *   keys, favorites); v2 never writes router sets (v1 owns config healing
+ *   while v2 is in beta), it only reads + reloads.
+ *
+ *   📖 Pinned-model syntax: `model: "fcm:@provider/modelId"` routes to that
+ *   exact model with failover disabled. It is what "test via router" uses to
+ *   exercise ONE model through the FULL routing chain (normalization, pre
+ *   prompt, response gate) instead of around it.
+ *
+ * @functions
+ *   → getRouterV2PortRange() - Effective port range (dev vs production)
+ *   → getRouterV2PidPath/PortPath/LogPath/StateDir() - Runtime file paths
+ *   → parseFcmModel(model) - Resolve `fcm` | `fcm:<set>` | `fcm:@provider/model`
+ *
+ * @exports ROUTER_V2_DEFAULT_PORT, ROUTER_V2_MAX_PORT, ROUTER_V2_DEFAULT_PORT_DEV
+ * @exports ROUTER_V2_MAX_PORT_DEV, getRouterV2PortRange, getRouterV2PidPath
+ * @exports getRouterV2PortPath, getRouterV2LogPath, getRouterV2StateDir
+ * @exports parseFcmModel, FCM_V2_LOCAL_API_KEY
+ */
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export const ROUTER_V2_DEFAULT_PORT = 19380
+export const ROUTER_V2_MAX_PORT = 19389
+export const ROUTER_V2_DEFAULT_PORT_DEV = 29380
+export const ROUTER_V2_MAX_PORT_DEV = 29389
+
+// 📖 Placeholder API key coding tools send when the router needs no real key.
+// Kept identical to v1 so switching a tool from v1 to v2 is a base-URL edit.
+export const FCM_V2_LOCAL_API_KEY = 'fcm-local'
+
+function isDev() {
+  return typeof process.env.FCM_DEV !== 'undefined' ? !!process.env.FCM_DEV : false
+}
+
+export function getRouterV2PortRange() {
+  return isDev()
+    ? { defaultPort: ROUTER_V2_DEFAULT_PORT_DEV, maxPort: ROUTER_V2_MAX_PORT_DEV }
+    : { defaultPort: ROUTER_V2_DEFAULT_PORT, maxPort: ROUTER_V2_MAX_PORT }
+}
+
+export function getRouterV2PidPath() {
+  return join(homedir(), `.free-coding-models-daemon-v2${isDev() ? '-dev' : ''}.pid`)
+}
+
+export function getRouterV2PortPath() {
+  return join(homedir(), `.free-coding-models-daemon-v2${isDev() ? '-dev' : ''}.port`)
+}
+
+export function getRouterV2LogPath() {
+  return join(homedir(), `.free-coding-models-daemon-v2${isDev() ? '-dev' : ''}.log`)
+}
+
+/**
+ * 📖 Directory holding v2 runtime state (breaker store, request history,
+ * token counters). Kept next to the classic config file so backups and
+ * `--fix-permissions` cover the whole family.
+ */
+export function getRouterV2StateDir() {
+  return homedir()
+}
+
+export function getRouterV2BreakersPath() {
+  return join(getRouterV2StateDir(), '.free-coding-models-router-v2-breakers.json')
+}
+
+export function getRouterV2HistoryPath() {
+  return join(getRouterV2StateDir(), '.free-coding-models-router-v2-history.json')
+}
+
+export function getRouterV2TokensPath() {
+  return join(getRouterV2StateDir(), `.free-coding-models-tokens-v2${isDev() ? '-dev' : ''}.json`)
+}
+
+/**
+ * 📖 Resolve the `model` field of an incoming request.
+ * @param {string} model - raw model string from the client
+ * @returns {{ kind: 'default', set: null, pinned: null }
+ *           | { kind: 'set', set: string, pinned: null }
+ *           | { kind: 'pinned', set: null, pinned: { provider: string, model: string } }
+ *           | { kind: 'unknown' }}
+ */
+export function parseFcmModel(model) {
+  if (typeof model !== 'string' || !model.trim()) return { kind: 'unknown', set: null, pinned: null }
+  const value = model.trim()
+  if (value === 'fcm' || value === 'fcm:default') return { kind: 'default', set: null, pinned: null }
+  if (value.startsWith('fcm:@')) {
+    const rest = value.slice(5)
+    const slashIdx = rest.indexOf('/')
+    if (slashIdx <= 0 || slashIdx === rest.length - 1) return { kind: 'unknown', set: null, pinned: null }
+    return { kind: 'pinned', set: null, pinned: { provider: rest.slice(0, slashIdx), model: rest.slice(slashIdx + 1) } }
+  }
+  if (value.startsWith('fcm:')) {
+    const setName = value.slice(4).trim()
+    if (!setName) return { kind: 'default', set: null, pinned: null }
+    return { kind: 'set', set: setName, pinned: null }
+  }
+  return { kind: 'unknown', set: null, pinned: null }
+}

package/src/core/router-v2/decision-trace.js

@@ -0,0 +1,134 @@
+/**
+ * @file decision-trace.js
+ * @description Per-request routing decision trace for Router v2.
+ *
+ * @details
+ *   📖 v1's request log had a single boolean `failover` tag: users could see
+ *   THAT something switched, never WHY, and never which candidates were
+ *   skipped (circuit open? quota pause? dead key?). v2 records an ordered
+ *   trace for every request:
+ *     - `skipped`: candidates excluded before any attempt, with the reason
+ *     - `attempts`: what was actually dispatched, with status/latency/error
+ *     - `served`: the model that produced the final answer
+ *   The trace is attached to the response via short `x-fcm-v2-*` headers so
+ *   agents can see routing decisions without opening a dashboard, and it is
+ *   persisted to the request history for the TUI + web views.
+ *
+ *   📖 Privacy contract: traces carry routing metadata only (model keys,
+ *   statuses, timings, error KIND strings). No prompts, no response bodies,
+ *   no API keys, no upstream URLs.
+ *
+ * @functions
+ *   → createDecisionTrace(input) - New trace object for a request
+ *   → traceSkip(trace, model, reason) - Record a pre-dispatch skip
+ *   → traceAttempt(trace, model, result) - Record a dispatch attempt
+ *   → finishTrace(trace, result) - Close the trace with the final outcome
+ *   → decisionHeaderValue(trace) - Compact single-line header value
+ *   → traceSummary(trace) - Human-facing summary for logs and dashboards
+ *
+ * @exports createDecisionTrace, traceSkip, traceAttempt, finishTrace
+ * @exports decisionHeaderValue, traceSummary
+ */
+
+import { randomUUID } from 'node:crypto'
+
+/**
+ * 📖 Create the trace object for one routed request.
+ * @param {{ requestId?: string, set?: string, protocol?: 'openai'|'anthropic',
+ *           modelRequested?: string, pinnedModel?: string|null }} input
+ */
+export function createDecisionTrace({ requestId = null, set = null, protocol = 'openai', modelRequested = null, pinnedModel = null } = {}) {
+  return {
+    request_id: requestId || `req-${randomUUID()}`,
+    at: new Date().toISOString(),
+    set,
+    protocol,
+    model_requested: modelRequested,
+    pinned_model: pinnedModel,
+    skipped: [],
+    attempts: [],
+    served_model: null,
+    last_resort_used: false,
+    outcome: null,
+    wall_ms: null,
+    tokens: 0,
+  }
+}
+
+/**
+ * 📖 Record that a candidate was excluded BEFORE any dispatch, with the
+ * machine-readable reason (`circuit_open`, `quota_paused`, `auth_error`,
+ * `stale`, `missing_key`, `provider_blocked`, ...).
+ */
+export function traceSkip(trace, model, reason) {
+  if (!trace) return
+  trace.skipped.push({ model, reason, at: new Date().toISOString() })
+}
+
+/**
+ * 📖 Record a dispatch attempt. `result` mirrors the proxy functions' return
+ * shape: `{ status, latencyMs, error }` where error is a failure KIND string.
+ */
+export function traceAttempt(trace, model, { status = null, latencyMs = null, error = null } = {}) {
+  if (!trace) return
+  trace.attempts.push({
+    model,
+    status,
+    latency_ms: latencyMs,
+    error: error || null,
+    at: new Date().toISOString(),
+  })
+  trace.total_attempts = trace.attempts.length
+}
+
+/**
+ * 📖 Close the trace. `outcome` is one of: 'served' | 'all_failed' |
+ * 'client_aborted' | 'rejected' | 'overloaded'.
+ */
+export function finishTrace(trace, { outcome, servedModel = null, wallMs = null, lastResort = false, tokens = 0 } = {}) {
+  if (!trace) return null
+  trace.outcome = outcome
+  trace.served_model = servedModel
+  trace.wall_ms = wallMs
+  trace.last_resort_used = lastResort === true
+  trace.tokens = tokens
+  return trace
+}
+
+/**
+ * 📖 Compact single-line value for the `x-fcm-v2-decision` response header.
+ * Format: `servedModel!outcome|attempt1:status->attempt2:status|skips=N`.
+ * Header values must be ASCII one-liners, so model keys are already safe
+ * (provider/model ids) and everything else is bounded and truncated.
+ *
+ * @returns {string}
+ */
+export function decisionHeaderValue(trace) {
+  if (!trace) return 'unknown'
+  const attempts = (trace.attempts || [])
+    .map((a) => `${a.model}:${a.status ?? a.error ?? 'ERR'}`)
+    .join('->')
+    .slice(0, 300)
+  const parts = [
+    `${trace.served_model || 'none'}!${trace.outcome || 'pending'}`,
+    attempts || 'no-attempts',
+    `skips=${(trace.skipped || []).length}`,
+  ]
+  return parts.join('|').slice(0, 480)
+}
+
+/**
+ * 📖 Human-facing one-liner for logs, TUI overlays and history tables.
+ * @returns {string}
+ */
+export function traceSummary(trace) {
+  if (!trace) return ''
+  const chain = (trace.attempts || [])
+    .map((a) => `${a.model}${a.error ? `(${a.error})` : a.status ? `(${a.status})` : ''}`)
+    .join(' -> ')
+  const skips = (trace.skipped || []).length
+  const base = chain || 'no candidate dispatched'
+  const suffix = skips > 0 ? ` [${skips} skipped]` : ''
+  const lastResort = trace.last_resort_used ? ' [last-resort]' : ''
+  return `${base}${suffix}${lastResort}`
+}