@cohortapp/agent-sdk 2.3.0

package/lib/model-router/taxonomy.mjs

@@ -0,0 +1,893 @@
+/**
+ * lib/model-router/taxonomy.mjs — FailoverReason taxonomy + classifiers.
+ *
+ * The closed, 16-value `FAILOVER_REASONS` enum and its `DISPOSITION` table are
+ * the *contract* between every outcome-producing surface (CLI stream-json,
+ * result-json subtype, stderr, direct-api HTTP) and `failover.mjs`. The
+ * disposition column semantics — retrySame, failoverNext, cooldownScope,
+ * cooldownMs|stepped, opensBreaker — encode the load-bearing rules from the
+ * router SPEC §4.5 *as data*, not as branching code, so the failover engine is
+ * a pure table-walk.
+ *
+ * Four classifiers map representative real-world inputs onto a FailoverReason:
+ *   - classifyCliEvent(ev)        — the closed `claude -p` stream-json
+ *                                   system/api_retry enum, mapped 1:1.
+ *   - classifyResultSubtype(s)    — the result-json terminal subtype.
+ *   - classifyStderr(text)        — extends rate-guard.classifyStderr with the
+ *                                   context-overflow + content-policy signals.
+ *   - classifyHttp(status, body)  — direct-api HTTP status + body-pattern
+ *                                   pipeline (billing-vs-rate-limit lists,
+ *                                   OpenRouter nested metadata.raw unwrap),
+ *                                   ported from Hermes error_classifier.py and
+ *                                   collapsed onto the closed 16-reason enum.
+ *
+ * House style (cadence-bus / rate-guard / model-router): ESM, Node built-ins
+ * only, pure functions, never throw on bad input — an unclassifiable signal
+ * falls through to `unknown` (retry-with-backoff), never an exception.
+ *
+ * NOTE: an export named `classifyResultالالسubtype` appears in the brief as a
+ * mojibake'd spelling of `classifyResultSubtype`; we export the clean ASCII
+ * name and an alias under that exact byte sequence so either spelling resolves.
+ */
+
+import { classifyStderr as rateGuardClassifyStderr } from "../rate-guard.mjs";
+
+// ---------------------------------------------------------------------------
+// The closed 16-value enum. Order is the SPEC §4.5 order; do not reorder
+// without updating every fixture corpus that asserts membership.
+// ---------------------------------------------------------------------------
+
+/** @typedef {(
+ *   "auth"|"auth_permanent"|"billing"|"rate_limit"|"overloaded"|"server_error"|
+ *   "timeout"|"model_not_found"|"context_overflow"|"payload_too_large"|
+ *   "content_policy"|"provider_policy"|"format"|"empty_response"|"network"|"unknown"
+ * )} FailoverReason */
+
+export const FAILOVER_REASONS = Object.freeze([
+  "auth",
+  "auth_permanent",
+  "billing",
+  "rate_limit",
+  "overloaded",
+  "server_error",
+  "timeout",
+  "model_not_found",
+  "context_overflow",
+  "payload_too_large",
+  "content_policy",
+  "provider_policy",
+  "format",
+  "empty_response",
+  "network",
+  "unknown",
+]);
+
+const REASON_SET = new Set(FAILOVER_REASONS);
+
+/** True iff `r` is a member of the closed enum. */
+export function isFailoverReason(r) {
+  return REASON_SET.has(r);
+}
+
+/** Coerce an arbitrary value to a FailoverReason, defaulting to `unknown`. */
+export function asFailoverReason(r) {
+  return REASON_SET.has(r) ? r : "unknown";
+}
+
+// ---------------------------------------------------------------------------
+// Cooldown step ladders (ms). `rate_limit` is stepped 30s → 1m → 5m, indexed
+// by the breaker's strike count; `overloaded`/`server_error` use a flat 60s.
+// Exported so failover.mjs + health.mjs agree on the exact ladder.
+// ---------------------------------------------------------------------------
+
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+
+/** rate_limit cooldown ladder: 30s → 1m → 5m, then sticks at 5m. */
+export const RATE_LIMIT_STEPS_MS = Object.freeze([30 * SECOND, 1 * MINUTE, 5 * MINUTE]);
+
+/**
+ * Resolve a stepped cooldown for `reason` at a given (0-based) strike count.
+ * Returns null for reasons whose cooldown is not stepped (callers read the
+ * flat `cooldownMs` instead). Non-stepped / no-cooldown reasons → null.
+ *
+ * @param {FailoverReason} reason
+ * @param {number} [strike=0]  0-based count of prior consecutive hits for this key.
+ * @returns {number|null}  cooldown ms, or null if this reason isn't stepped.
+ */
+export function steppedCooldownMs(reason, strike = 0) {
+  const d = DISPOSITION[reason];
+  if (!d || !Array.isArray(d.stepped) || d.stepped.length === 0) return null;
+  const i = Math.max(0, Math.min(d.stepped.length - 1, Math.floor(strike)));
+  return d.stepped[i];
+}
+
+/**
+ * The effective cooldown (ms) for a reason at a given strike count. Prefers the
+ * stepped ladder when present, else the flat `cooldownMs`. 0 ⇒ no cooldown.
+ * Operator-gated reasons (`auth_permanent`) return Infinity — they cool only on
+ * an explicit operator clear, never on a wall-clock timer.
+ *
+ * @param {FailoverReason} reason
+ * @param {number} [strike=0]
+ * @returns {number}  ms (0 = none, Infinity = until-operator)
+ */
+export function cooldownMsFor(reason, strike = 0) {
+  const d = DISPOSITION[reason];
+  if (!d) return 0;
+  if (d.cooldownMs === Infinity) return Infinity;
+  const stepped = steppedCooldownMs(reason, strike);
+  if (stepped != null) return stepped;
+  return d.cooldownMs || 0;
+}
+
+// ---------------------------------------------------------------------------
+// DISPOSITION — the contract, encoded as data (SPEC §4.5 disposition table).
+//
+// Per reason:
+//   retrySame      — may we retry the SAME candidate? false | true (=once)
+//                    | "jittered" (once, jittered) | "backoff" (once, backoff)
+//                    | "cli" (the CLI already retried server_error ≤10× internally;
+//                            we do not re-retry the same candidate ourselves).
+//   failoverNext   — may we advance to the next candidate in the chain?
+//   cooldownScope  — which breaker key cools: none | backend | backend:model |
+//                    model-id | operator
+//   cooldownMs     — flat cooldown ms (0 = none, Infinity = until operator)
+//   stepped        — when present, a ms ladder indexed by strike count; takes
+//                    precedence over cooldownMs.
+//   opensBreaker   — does a hit open / advance the breaker for cooldownScope?
+//
+// Load-bearing invariants (asserted in the tests, cell-by-cell):
+//   - context_overflow: NEVER fails over, no cooldown, no breaker.
+//   - network: NEVER fails over, no cooldown, opensBreaker=false (DEFER-style;
+//              burns no retry budget — the chain is left intact and re-queued).
+//   - payload_too_large: no failover (shrink path), no cooldown.
+//   - content_policy: no failover on the SAME content (one Anthropic-only
+//              re-route is permitted by failover.mjs, governed by opts, not here).
+//   - rate_limit: cooldownScope backend:model (Haiku flows while Sonnet is dry),
+//              stepped 30s→1m→5m.
+//   - billing: disambiguated from rate_limit by the classifier pattern lists;
+//              cools the whole backend for 6h.
+//   - auth_permanent: cools until operator (Infinity).
+// ---------------------------------------------------------------------------
+
+export const DISPOSITION = Object.freeze({
+  auth: Object.freeze({
+    retrySame: false,
+    failoverNext: true,
+    cooldownScope: "backend",
+    cooldownMs: 5 * MINUTE,
+    opensBreaker: true,
+  }),
+  auth_permanent: Object.freeze({
+    retrySame: false,
+    failoverNext: true,
+    cooldownScope: "operator",
+    cooldownMs: Infinity, // until an operator clears it
+    opensBreaker: true,
+  }),
+  billing: Object.freeze({
+    retrySame: false,
+    failoverNext: true,
+    cooldownScope: "backend",
+    cooldownMs: 6 * HOUR,
+    opensBreaker: true,
+  }),
+  rate_limit: Object.freeze({
+    retrySame: false,
+    failoverNext: true,
+    cooldownScope: "backend:model", // model-scoped: Haiku flows while Sonnet is dry
+    cooldownMs: RATE_LIMIT_STEPS_MS[0],
+    stepped: RATE_LIMIT_STEPS_MS, // 30s → 1m → 5m
+    opensBreaker: true,
+  }),
+  overloaded: Object.freeze({
+    retrySame: "jittered", // once, jittered
+    failoverNext: true,
+    cooldownScope: "backend:model", // 529 is per-model capacity
+    cooldownMs: 60 * SECOND,
+    opensBreaker: true,
+  }),
+  server_error: Object.freeze({
+    retrySame: "cli", // CLI retries ≤10× internally; we don't re-retry, just failover after
+    failoverNext: true,
+    cooldownScope: "backend:model",
+    cooldownMs: 60 * SECOND,
+    opensBreaker: true,
+  }),
+  timeout: Object.freeze({
+    retrySame: true, // once
+    failoverNext: true,
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false,
+  }),
+  model_not_found: Object.freeze({
+    retrySame: false,
+    failoverNext: true,
+    cooldownScope: "model-id", // catalog-drift signal → doctor warning
+    cooldownMs: Infinity, // permanent for this model id until catalog fix
+    opensBreaker: true,
+  }),
+  context_overflow: Object.freeze({
+    retrySame: false,
+    failoverNext: false, // NEVER fails over — smaller-ctx fallback fails worse
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false,
+  }),
+  payload_too_large: Object.freeze({
+    retrySame: false,
+    failoverNext: false, // shrink path; failover to another model won't help
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false,
+  }),
+  content_policy: Object.freeze({
+    retrySame: false,
+    failoverNext: false, // deterministic refusal sticky across resume (same content)
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false,
+  }),
+  provider_policy: Object.freeze({
+    retrySame: false,
+    failoverNext: true,
+    cooldownScope: "backend",
+    cooldownMs: 1 * HOUR,
+    opensBreaker: true,
+  }),
+  format: Object.freeze({
+    retrySame: false,
+    failoverNext: true, // compat bug — logged with compat-flag context
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false,
+  }),
+  empty_response: Object.freeze({
+    retrySame: true, // once
+    failoverNext: true,
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false,
+  }),
+  network: Object.freeze({
+    retrySame: false,
+    failoverNext: false, // DEFER-style: offline; re-queued, burns no retry budget
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false, // breaker NOT opened
+  }),
+  unknown: Object.freeze({
+    retrySame: "backoff", // once, backoff
+    failoverNext: true,
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false,
+  }),
+});
+
+// Frozen, so a buggy consumer cannot mutate the contract at runtime.
+Object.freeze(DISPOSITION);
+
+// ---------------------------------------------------------------------------
+// 1. CLI stream-json classifier — closed `claude -p` system/api_retry enum.
+//    Mapped 1:1 onto the FailoverReason enum. This is free signal the
+//    dispatcher currently discards (SPEC §4.5 source 1).
+// ---------------------------------------------------------------------------
+
+/**
+ * The closed CLI api_retry/error enum → FailoverReason, 1:1.
+ *   authentication_failed → auth
+ *   oauth_org_not_allowed → auth_permanent
+ *   billing_error         → billing
+ *   rate_limit            → rate_limit
+ *   overloaded            → overloaded
+ *   invalid_request       → format
+ *   model_not_found       → model_not_found
+ *   server_error          → server_error
+ *   max_output_tokens     → context_overflow (output hit the model ceiling)
+ *   unknown               → unknown
+ */
+const CLI_EVENT_MAP = Object.freeze({
+  authentication_failed: "auth",
+  oauth_org_not_allowed: "auth_permanent",
+  billing_error: "billing",
+  rate_limit: "rate_limit",
+  overloaded: "overloaded",
+  invalid_request: "format",
+  model_not_found: "model_not_found",
+  server_error: "server_error",
+  max_output_tokens: "context_overflow",
+  unknown: "unknown",
+});
+
+/**
+ * Classify a `claude -p --output-format stream-json` event. Accepts either the
+ * raw event object (`{type:"system", subtype:"api_retry", error:"rate_limit"}`)
+ * or a bare enum string. Unknown event shapes → null (caller may fall through
+ * to stderr/result-subtype classification); a recognized-but-unmapped enum
+ * value → `unknown`.
+ *
+ * @param {object|string} ev
+ * @returns {FailoverReason|null}
+ */
+export function classifyCliEvent(ev) {
+  if (ev == null) return null;
+  let code = null;
+  if (typeof ev === "string") {
+    code = ev;
+  } else if (typeof ev === "object") {
+    // The api_retry event carries the reason in `error` (or `reason`/`code`);
+    // a result event uses `subtype`. An explicit api_error event may nest the
+    // code under error.type / error.code. Prefer scalar fields, then unwrap a
+    // nested error object.
+    if (typeof ev.error === "string") code = ev.error;
+    else if (typeof ev.reason === "string") code = ev.reason;
+    else if (typeof ev.code === "string") code = ev.code;
+    else if (ev.error && typeof ev.error === "object") {
+      code = ev.error.type || ev.error.code || null;
+    }
+  }
+  if (typeof code !== "string" || !code) return null;
+  const key = code.trim().toLowerCase();
+  if (Object.prototype.hasOwnProperty.call(CLI_EVENT_MAP, key)) {
+    return CLI_EVENT_MAP[key];
+  }
+  // A recognized api_retry event with an out-of-enum code is still a failure
+  // signal — bucket it as unknown rather than dropping it.
+  if (
+    typeof ev === "object" &&
+    (ev.subtype === "api_retry" || ev.subtype === "api_error" || ev.type === "system")
+  ) {
+    return "unknown";
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// 2. Result-json subtype classifier (SPEC §4.5 source 2).
+//    error_max_turns / error_max_budget_usd → resumable budget stops; we map
+//    those to `unknown` for failover purposes (the caller resumes rather than
+//    failing over — these are not provider faults). The exported export name is
+//    duplicated under the brief's mojibake spelling for resolve-lane safety.
+// ---------------------------------------------------------------------------
+
+const RESULT_SUBTYPE_MAP = Object.freeze({
+  success: "ok",
+  error_max_turns: "unknown", // resumable budget stop — not a provider fault
+  error_max_budget_usd: "unknown", // resumable budget stop
+  error_during_execution: "server_error",
+  error_max_output_tokens: "context_overflow",
+});
+
+/**
+ * Classify a result-json terminal `subtype`. Returns "ok" for the success
+ * subtype (so callers can branch without a separate success path), a
+ * FailoverReason for the error subtypes, or null when the subtype is unknown.
+ *
+ * @param {string} subtype
+ * @returns {FailoverReason|"ok"|null}
+ */
+export function classifyResultSubtype(subtype) {
+  if (typeof subtype !== "string" || !subtype) return null;
+  const key = subtype.trim().toLowerCase();
+  if (Object.prototype.hasOwnProperty.call(RESULT_SUBTYPE_MAP, key)) {
+    return RESULT_SUBTYPE_MAP[key];
+  }
+  // Any other `error_*` subtype is a real failure of unknown kind.
+  if (key.startsWith("error")) return "unknown";
+  return null;
+}
+
+// Alias under the exact (mojibake) byte sequence used in the component brief,
+// so the resolve lane resolves either spelling. Both point at the same fn.
+export { classifyResultSubtype as classifyResultالالسubtype };
+
+// ---------------------------------------------------------------------------
+// 3. stderr classifier — extends rate-guard.classifyStderr (SPEC §4.5 source 3)
+//    "Prompt is too long"        → context_overflow
+//    usage-policy refusal        → content_policy
+//    (rate-guard's 429/overload) → rate_limit
+// ---------------------------------------------------------------------------
+
+const STDERR_CONTEXT_OVERFLOW = [
+  "prompt is too long",
+  "prompt exceeds max length",
+  "context length exceeded",
+  "maximum context",
+  "too many tokens",
+  "input is too long",
+  "exceeds the context window",
+];
+
+const STDERR_CONTENT_POLICY = [
+  "violates our usage policies",
+  "violates anthropic's usage policies",
+  "your request was flagged by",
+  "prompt was flagged by our safety",
+  "responses cannot be generated due to safety",
+  "usage policy",
+  "content_filter",
+];
+
+const STDERR_AUTH = [
+  "invalid api key",
+  "invalid x-api-key",
+  "authentication_error",
+  "could not resolve authentication",
+  "oauth token",
+  "401 unauthorized",
+];
+
+const STDERR_BILLING = [
+  "credit balance is too low",
+  "insufficient credits",
+  "payment required",
+  "billing",
+  "exceeded your current quota",
+];
+
+const STDERR_NETWORK = [
+  "getaddrinfo enotfound",
+  "econnrefused",
+  "econnreset",
+  "etimedout",
+  "network is unreachable",
+  "socket hang up",
+  "enetdown",
+  "enetunreach",
+  "ehostunreach",
+  "failed to fetch",
+  "fetch failed",
+];
+
+/**
+ * Classify a captured stderr/text blob. Extends `rate-guard.classifyStderr`
+ * (which returns a boolean for the 429/overload family) into the full enum.
+ * Returns null when nothing matches (caller may fall through to other sources).
+ *
+ * Order matters: content-overflow and content-policy are checked before the
+ * coarse rate-guard match so a 429 string that also says "prompt is too long"
+ * resolves to the more actionable reason.
+ *
+ * @param {string} text
+ * @returns {FailoverReason|null}
+ */
+export function classifyStderr(text) {
+  if (typeof text !== "string" || !text) return null;
+  const t = text.toLowerCase();
+
+  if (STDERR_CONTEXT_OVERFLOW.some((p) => t.includes(p))) return "context_overflow";
+  if (STDERR_CONTENT_POLICY.some((p) => t.includes(p))) return "content_policy";
+  if (STDERR_AUTH.some((p) => t.includes(p))) return "auth";
+  if (STDERR_BILLING.some((p) => t.includes(p))) return "billing";
+  if (STDERR_NETWORK.some((p) => t.includes(p))) return "network";
+
+  // Defer to the shared rate-guard breaker for the 429 / overloaded family so
+  // one pattern set covers every spawn source.
+  if (rateGuardClassifyStderr(text)) {
+    // "overloaded" is per-model capacity; a bare 429/rate-limit is rate_limit.
+    if (/\boverloaded\b|529/i.test(text)) return "overloaded";
+    return "rate_limit";
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// 4. Direct-api HTTP classifier — ported from Hermes error_classifier.py and
+//    collapsed onto the closed 16-reason enum (SPEC §4.5 source 4).
+//
+//    Mapping of Hermes' finer-grained reasons onto our enum:
+//      image_too_large / multimodal_tool_content / invalid_encrypted /
+//        thinking_signature / format_error / *_validation       → format
+//      provider_policy_blocked                                   → provider_policy
+//      content_policy_blocked                                    → content_policy
+//      long_context_tier                                         → rate_limit
+//      (everything else maps to the same-named reason)
+// ---------------------------------------------------------------------------
+
+const BILLING_PATTERNS = [
+  "insufficient credits",
+  "insufficient_quota",
+  "insufficient balance",
+  "credit balance",
+  "credit balance is too low",
+  "credits exhausted",
+  "credits have been exhausted",
+  "no usable credits",
+  "top up your credits",
+  "payment required",
+  "billing hard limit",
+  "exceeded your current quota",
+  "account is deactivated",
+  "plan does not include",
+  "out of funds",
+  "run out of funds",
+  "balance_depleted",
+  "model_not_supported_on_free_tier",
+  "not available on the free tier",
+  "key limit exceeded",
+  "spending limit",
+];
+
+const RATE_LIMIT_PATTERNS = [
+  "rate limit",
+  "rate_limit",
+  "too many requests",
+  "throttled",
+  "requests per minute",
+  "tokens per minute",
+  "requests per day",
+  "try again in",
+  "please retry after",
+  "resource_exhausted",
+  "rate increased too quickly",
+  "throttlingexception",
+  "too many concurrent requests",
+  "servicequotaexceededexception",
+];
+
+const USAGE_LIMIT_PATTERNS = ["usage limit", "quota", "limit exceeded", "key limit exceeded"];
+const USAGE_LIMIT_TRANSIENT = [
+  "try again",
+  "retry",
+  "resets at",
+  "reset in",
+  "wait",
+  "requests remaining",
+  "periodic",
+  "window",
+];
+
+const CONTEXT_OVERFLOW_PATTERNS = [
+  "context length",
+  "context size",
+  "maximum context",
+  "token limit",
+  "too many tokens",
+  "reduce the length",
+  "exceeds the limit",
+  "context window",
+  "prompt is too long",
+  "prompt exceeds max length",
+  "maximum number of tokens",
+  "exceeds the max_model_len",
+  "max_model_len",
+  "input is too long",
+  "maximum model length",
+  "context length exceeded",
+  "context_length_exceeded",
+  "max_tokens_exceeded",
+];
+
+const MODEL_NOT_FOUND_PATTERNS = [
+  "is not a valid model",
+  "invalid model",
+  "model not found",
+  "model_not_found",
+  "model_not_available",
+  "does not exist",
+  "no such model",
+  "unknown model",
+  "unsupported model",
+];
+
+const REQUEST_VALIDATION_PATTERNS = [
+  "unknown parameter",
+  "unsupported parameter",
+  "unrecognized request argument",
+  "unknown_parameter",
+  "unsupported_parameter",
+];
+
+const PROVIDER_POLICY_PATTERNS = [
+  "no endpoints available matching your guardrail",
+  "no endpoints available matching your data policy",
+  "no endpoints found matching your data policy",
+];
+
+const CONTENT_POLICY_PATTERNS = [
+  "flagged for possible cybersecurity risk",
+  "trusted access for cyber",
+  "violates our usage policies",
+  "violates openai's usage policies",
+  "your request was flagged by",
+  "prompt was flagged by our safety",
+  "responses cannot be generated due to safety",
+  "content_filter",
+  "responsibleaipolicyviolation",
+];
+
+const AUTH_PATTERNS = [
+  "invalid api key",
+  "invalid_api_key",
+  "authentication",
+  "unauthorized",
+  "forbidden",
+  "invalid token",
+  "token expired",
+  "token revoked",
+  "access denied",
+];
+
+const PAYLOAD_TOO_LARGE_PATTERNS = [
+  "request entity too large",
+  "payload too large",
+  "error code: 413",
+];
+
+const NETWORK_PATTERNS = [
+  "getaddrinfo enotfound",
+  "econnrefused",
+  "econnreset",
+  "etimedout",
+  "network is unreachable",
+  "socket hang up",
+  "enetdown",
+  "enetunreach",
+  "ehostunreach",
+  "fetch failed",
+  "failed to fetch",
+  "connection refused",
+  "connection reset",
+];
+
+const TIMEOUT_PATTERNS = [
+  "timed out",
+  "turn timed out",
+  "request timed out",
+  "deadline exceeded",
+  "operation timed out",
+  "upstream timed out",
+];
+
+const EMPTY_RESPONSE_PATTERNS = [
+  "empty response",
+  "no content returned",
+  "no completion returned",
+  "received an empty",
+];
+
+const hasAny = (text, list) => list.some((p) => text.includes(p));
+
+/**
+ * Flatten an HTTP error body (object or string) into one lowercased string,
+ * unwrapping OpenRouter's nested `error.metadata.raw` JSON so the real upstream
+ * message (e.g. "context length exceeded") is matched even when OpenRouter
+ * wraps it as `{"error":{"message":"Provider returned error","metadata":{"raw":"…"}}}`.
+ *
+ * @param {object|string|null} body
+ * @returns {{ text: string, code: string }}
+ */
+export function flattenHttpBody(body) {
+  const parts = [];
+  let code = "";
+  if (body == null) return { text: "", code: "" };
+  if (typeof body === "string") {
+    parts.push(body);
+    return { text: parts.join(" ").toLowerCase(), code: "" };
+  }
+  if (typeof body !== "object") return { text: String(body).toLowerCase(), code: "" };
+
+  const err = body.error && typeof body.error === "object" ? body.error : null;
+  if (err) {
+    if (typeof err.message === "string") parts.push(err.message);
+    if (typeof err.code === "string") code ||= err.code;
+    else if (typeof err.type === "string") code ||= err.type;
+    // OpenRouter nested metadata.raw unwrap.
+    const meta = err.metadata && typeof err.metadata === "object" ? err.metadata : null;
+    if (meta && typeof meta.raw === "string" && meta.raw.trim()) {
+      parts.push(meta.raw); // include the raw string itself
+      try {
+        const inner = JSON.parse(meta.raw);
+        const innerErr = inner && typeof inner === "object" ? inner.error : null;
+        if (innerErr && typeof innerErr === "object") {
+          if (typeof innerErr.message === "string") parts.push(innerErr.message);
+          if (!code && typeof innerErr.code === "string") code = innerErr.code;
+        } else if (inner && typeof inner.message === "string") {
+          parts.push(inner.message);
+        }
+      } catch {
+        /* raw wasn't JSON — the string is already in parts */
+      }
+    }
+  }
+  if (typeof body.message === "string") parts.push(body.message);
+  if (!code && typeof body.code === "string") code = body.code;
+  if (!code && typeof body.error_code === "string") code = body.error_code;
+
+  return { text: parts.join(" ").toLowerCase(), code: String(code || "").toLowerCase() };
+}
+
+// Unambiguous throttling phrases — when present, the signal is a rate limit
+// regardless of a co-occurring generic "limit exceeded" usage phrase.
+const UNAMBIGUOUS_RATE_LIMIT = [
+  "rate limit",
+  "rate_limit",
+  "too many requests",
+  "throttled",
+  "throttlingexception",
+  "requests per minute",
+  "tokens per minute",
+  "requests per day",
+];
+
+/**
+ * Disambiguate a usage/payment signal: a transient "try again in 5m" usage
+ * limit is rate_limit, a confirmed balance/credit exhaustion is billing. An
+ * unambiguous throttling phrase ("rate limit", "too many requests") always
+ * wins over the generic usage-limit family (which also matches "limit
+ * exceeded", a substring of "rate limit exceeded").
+ */
+function disambiguateBilling(text) {
+  if (hasAny(text, UNAMBIGUOUS_RATE_LIMIT)) return "rate_limit";
+  const usage = hasAny(text, USAGE_LIMIT_PATTERNS);
+  const transient = hasAny(text, USAGE_LIMIT_TRANSIENT);
+  if (usage && transient) return "rate_limit";
+  if (hasAny(text, BILLING_PATTERNS)) return "billing";
+  if (usage) return "billing"; // usage limit without a transient signal ⇒ exhaustion
+  return null;
+}
+
+/**
+ * Classify a direct-api HTTP outcome onto the closed 16-reason enum.
+ *
+ * @param {number|null|undefined} status  HTTP status (null when transport-level)
+ * @param {object|string|null} [body]     parsed JSON body or raw text
+ * @returns {FailoverReason}
+ */
+export function classifyHttp(status, body) {
+  const { text, code } = flattenHttpBody(body);
+  const st = Number.isFinite(status) ? Number(status) : null;
+
+  // ── 1. Body-pattern signals that override status (deterministic refusals,
+  //        OpenRouter policy blocks, content policy) ─────────────────────────
+  if (hasAny(text, CONTENT_POLICY_PATTERNS)) return "content_policy";
+  if (hasAny(text, PROVIDER_POLICY_PATTERNS)) return "provider_policy";
+
+  // Structured error codes (highest-confidence signal in the body).
+  if (code) {
+    if (["resource_exhausted", "throttled", "rate_limit_exceeded"].includes(code))
+      return "rate_limit";
+    if (
+      [
+        "insufficient_quota",
+        "billing_not_active",
+        "payment_required",
+        "insufficient_credits",
+        "no_usable_credits",
+        "balance_depleted",
+        "model_not_supported_on_free_tier",
+      ].includes(code)
+    )
+      return "billing";
+    if (["model_not_found", "model_not_available", "invalid_model"].includes(code))
+      return "model_not_found";
+    if (["context_length_exceeded", "max_tokens_exceeded"].includes(code))
+      return "context_overflow";
+  }
+
+  // ── 2. Status-code classification with message-aware refinement ───────────
+  if (st != null) {
+    if (st === 401) return "auth";
+    if (st === 403) {
+      // OpenRouter 403 "key limit exceeded" is billing, not auth.
+      if (disambiguateBilling(text) === "billing") return "billing";
+      if (hasAny(text, BILLING_PATTERNS)) return "billing";
+      return "auth";
+    }
+    if (st === 402) {
+      return disambiguateBilling(text) || "billing";
+    }
+    if (st === 404) {
+      if (hasAny(text, BILLING_PATTERNS)) return "billing";
+      if (hasAny(text, MODEL_NOT_FOUND_PATTERNS)) return "model_not_found";
+      // Generic 404 (often a misconfigured endpoint) — surface as unknown,
+      // not a misleading model_not_found that silently fails over.
+      return "unknown";
+    }
+    if (st === 413) return "payload_too_large";
+    if (st === 429) return "rate_limit";
+    if (st === 400) return classify400(text, code);
+    if (st === 408) return "timeout";
+    if (st === 500 || st === 502) {
+      // Some gateways return request-validation errors as 5xx — fail fast.
+      if (hasAny(text, REQUEST_VALIDATION_PATTERNS) || code === "invalid_request_error")
+        return "format";
+      return "server_error";
+    }
+    if (st === 503 || st === 529) return "overloaded";
+    if (st >= 400 && st < 500) return "format";
+    if (st >= 500 && st < 600) return "server_error";
+  }
+
+  // ── 3. Message-only classification (transport-level, no status) ───────────
+  const m = classifyByMessage(text);
+  if (m) return m;
+
+  // ── 4. Fallback ───────────────────────────────────────────────────────────
+  return "unknown";
+}
+
+/** 400-body refinement, mirroring Hermes _classify_400 collapsed to our enum. */
+function classify400(text, code) {
+  // Request-validation (unsupported/unknown parameter) is deterministic format
+  // error — must be checked before context_overflow because "max_tokens" is in
+  // both pattern families.
+  const reqVal = REQUEST_VALIDATION_PATTERNS.filter((p) => p !== "invalid_request_error");
+  if (hasAny(text, reqVal) || code === "unknown_parameter" || code === "unsupported_parameter")
+    return "format";
+  if (hasAny(text, CONTEXT_OVERFLOW_PATTERNS)) return "context_overflow";
+  if (hasAny(text, PROVIDER_POLICY_PATTERNS)) return "provider_policy";
+  if (hasAny(text, MODEL_NOT_FOUND_PATTERNS)) return "model_not_found";
+  if (hasAny(text, RATE_LIMIT_PATTERNS)) return "rate_limit";
+  if (hasAny(text, BILLING_PATTERNS)) return "billing";
+  return "format";
+}
+
+/** Pure message-pattern classification (no status code present). */
+function classifyByMessage(text) {
+  if (!text) return null;
+  if (hasAny(text, PAYLOAD_TOO_LARGE_PATTERNS)) return "payload_too_large";
+  const bill = disambiguateBilling(text);
+  if (bill) return bill;
+  if (hasAny(text, RATE_LIMIT_PATTERNS)) return "rate_limit";
+  if (hasAny(text, CONTEXT_OVERFLOW_PATTERNS)) return "context_overflow";
+  if (hasAny(text, AUTH_PATTERNS)) return "auth";
+  if (hasAny(text, PROVIDER_POLICY_PATTERNS)) return "provider_policy";
+  if (hasAny(text, MODEL_NOT_FOUND_PATTERNS)) return "model_not_found";
+  if (hasAny(text, NETWORK_PATTERNS)) return "network";
+  if (hasAny(text, TIMEOUT_PATTERNS)) return "timeout";
+  if (hasAny(text, EMPTY_RESPONSE_PATTERNS)) return "empty_response";
+  return null;
+}
+
+/**
+ * Classify a thrown transport-level error (no HTTP response). Recognizes
+ * Node fetch/undici/dns error codes as `network`, AbortError/timeouts as
+ * `timeout`, else falls through to message classification → unknown.
+ *
+ * @param {Error|object} err
+ * @returns {FailoverReason}
+ */
+export function classifyTransportError(err) {
+  if (!err) return "unknown";
+  const code = String(err.code || err.errno || "").toUpperCase();
+  const name = String(err.name || "");
+  const msg = String(err.message || err).toLowerCase();
+  const NET_CODES = new Set([
+    "ENOTFOUND",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENETDOWN",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "EAI_AGAIN",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CONNECT_TIMEOUT",
+  ]);
+  if (code === "ETIMEDOUT" || code === "UND_ERR_CONNECT_TIMEOUT") return "timeout";
+  if (NET_CODES.has(code)) return "network";
+  if (name === "AbortError" || name === "TimeoutError" || hasAny(msg, TIMEOUT_PATTERNS))
+    return "timeout";
+  if (hasAny(msg, NETWORK_PATTERNS)) return "network";
+  const m = classifyByMessage(msg);
+  return m || "unknown";
+}
+
+export const _internals = {
+  CLI_EVENT_MAP,
+  RESULT_SUBTYPE_MAP,
+  BILLING_PATTERNS,
+  RATE_LIMIT_PATTERNS,
+  CONTEXT_OVERFLOW_PATTERNS,
+  CONTENT_POLICY_PATTERNS,
+  PROVIDER_POLICY_PATTERNS,
+  classify400,
+  classifyByMessage,
+  disambiguateBilling,
+};