@providerkit/core 0.8.1 → 0.10.0

package/dist/usage.d.ts

@@ -17,6 +17,11 @@ export interface ModelRate {
 }
 /** Add two usage records. */
 export declare function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
+/**
+ * Subtract usage `b` from `a`, clamping each field at zero.
+ * Used when an optimistic turn or speculative stream is rolled back.
+ */
+export declare function subtractUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
 /**
  * USD for one call.
  *
@@ -38,6 +43,7 @@ export declare class UsageTracker {
      *  Observability only — never billed. */
     private saved;
     add(usage: TokenUsage, rate?: ModelRate): void;
+    subtract(usage: TokenUsage, rate?: ModelRate): void;
     get totals(): TokenUsage;
     get costUsd(): number;
     get cacheSavingsUsd(): number;

package/dist/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;qDACqD;AACrD,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;wEAGoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;0EAEsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,6BAA6B;AAC7B,wBAAgB,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAOjE;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAalE;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAuD;IACpE,OAAO,CAAC,IAAI,CAAK;IACjB;6CACyC;IACzC,OAAO,CAAC,KAAK,CAAK;IAElB,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAQ9C,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;yDAEqD;IACrD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIrC,KAAK,IAAI,IAAI;CAKd"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;qDACqD;AACrD,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;wEAGoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;0EAEsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,6BAA6B;AAC7B,wBAAgB,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAOjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAOtE;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAalE;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAuD;IACpE,OAAO,CAAC,IAAI,CAAK;IACjB;6CACyC;IACzC,OAAO,CAAC,KAAK,CAAK;IAElB,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAQ9C,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAQnD,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;yDAEqD;IACrD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIrC,KAAK,IAAI,IAAI;CAKd"}

package/dist/usage.js

@@ -8,6 +8,18 @@ export function addUsage(a, b) {
         outputTokens: a.outputTokens + b.outputTokens,
     };
 }
+/**
+ * Subtract usage `b` from `a`, clamping each field at zero.
+ * Used when an optimistic turn or speculative stream is rolled back.
+ */
+export function subtractUsage(a, b) {
+    return {
+        inputTokens: Math.max(0, a.inputTokens - b.inputTokens),
+        cachedInputTokens: Math.max(0, a.cachedInputTokens - b.cachedInputTokens),
+        cacheWriteTokens: Math.max(0, (a.cacheWriteTokens ?? 0) - (b.cacheWriteTokens ?? 0)),
+        outputTokens: Math.max(0, a.outputTokens - b.outputTokens),
+    };
+}
 /**
  * USD for one call.
  *
@@ -47,6 +59,14 @@ export class UsageTracker {
         const cached = Math.min(Math.max(0, usage.cachedInputTokens), Math.max(0, usage.inputTokens));
         this.saved += (cached * (rate.input - rate.cacheRead)) / 1_000_000;
     }
+    subtract(usage, rate) {
+        this.usage = subtractUsage(this.usage, usage);
+        if (!rate)
+            return;
+        this.cost = Math.max(0, this.cost - costUsd(usage, rate));
+        const cached = Math.min(Math.max(0, usage.cachedInputTokens), Math.max(0, usage.inputTokens));
+        this.saved = Math.max(0, this.saved - (cached * (rate.input - rate.cacheRead)) / 1_000_000);
+    }
     get totals() {
         return { ...this.usage };
     }

package/dist/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@providerkit/core",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "The layer under your agent loop: one seam for every LLM provider, plus the failure handling you only learn in production.",
   "type": "module",
   "license": "MIT",
@@ -47,6 +47,8 @@
     "test:watch": "vitest",
     "lint": "eslint src test",
     "format": "prettier --write .",
+    "check:presets": "bun run scripts/refresh-presets.ts",
+    "probe:model": "bun run scripts/probe-model.ts",
     "sync:docs": "cp ../README.md ../LICENSE .",
     "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build && bun run sync:docs",
     "release": "bun publish --access public",

package/src/capability.ts

@@ -139,3 +139,160 @@ export async function probeJsonWithTools(
   // than the equal.
   return { use: SHAPES.find((shape) => calls[shape] === samples) ?? null, calls, samples };
 }
+
+// ── Model capability resolution ──────────────────────────────────────────
+
+export interface ModelCapabilities {
+  /** Canonical model identifier. */
+  id: string;
+  /** Human-readable model display name. */
+  name?: string;
+  /** Total context window in tokens. */
+  contextWindow?: number;
+  /** Maximum generation/output tokens. */
+  maxOutput?: number;
+  /** Whether the model natively supports tool / function calling. */
+  supportsTools?: boolean;
+  /** Whether the model natively supports JSON schema / structured output. */
+  supportsStructuredOutput?: boolean;
+  /** Whether the model can receive image inputs. */
+  supportsVision?: boolean;
+  /** Whether the model has extended thinking / reasoning capability. */
+  supportsReasoning?: boolean;
+}
+
+export interface ResolveModelOptions {
+  /** Custom catalog URL. Defaults to https://models.dev/api.json */
+  catalogUrl?: string;
+  /** Pre-loaded catalog object (useful for tests or offline execution). */
+  catalog?: Record<string, unknown>;
+  /** Custom fetch implementation (for proxies, custom headers, or tests). */
+  fetchImpl?: typeof fetch;
+  /** Max cache age in ms. Defaults to 24 hours (86_400_000 ms). */
+  maxAgeMs?: number;
+}
+
+interface RawModelEntry {
+  id?: string;
+  name?: string;
+  tool_call?: boolean;
+  structured_output?: boolean;
+  reasoning?: boolean;
+  attachment?: boolean;
+  modalities?: {
+    input?: string[];
+    output?: string[];
+  };
+  limit?: {
+    context?: number;
+    output?: number;
+  };
+}
+
+interface RawProviderEntry {
+  models?: Record<string, RawModelEntry>;
+}
+
+const DEFAULT_CATALOG_URL = "https://models.dev/api.json";
+const DEFAULT_MAX_AGE_MS = 86_400_000; // 24 hours
+
+let cachedCatalog: { timestamp: number; data: Record<string, RawProviderEntry> } | null = null;
+
+function normalizeId(id: string): string {
+  // Strip gateway prefixes (z-ai/, deepseek/, openai/, accounts/fireworks/models/, etc.)
+  const bare = id.replace(/^(?:accounts\/[^/]+\/models\/|[^/]+\/)/, "");
+  // Normalize punctuation variations like 5p3 -> 5.3 or v4p1 -> v4.1
+  return bare.replace(/([a-z0-9])p([0-9])/gi, "$1.$2").toLowerCase();
+}
+
+/**
+ * Resolve model capabilities (context window, tool calling, vision, reasoning)
+ * by looking up the model in a live or cached models.dev catalog.
+ *
+ * Normalizes model identifiers across gateway spellings:
+ * - `z-ai/glm-5.3-flash` matches `glm-5.3-flash`
+ * - `deepseek/deepseek-v4.1-flash` matches `deepseek-v4.1-flash`
+ * - `accounts/fireworks/models/glm-5p3-flash` matches `glm-5.3-flash`
+ *
+ * Never throws — if the catalog cannot be retrieved or the model is unknown,
+ * returns `undefined` so capability lookups never break caller execution.
+ */
+export async function resolveModelCapabilities(
+  modelId: string,
+  options: ResolveModelOptions = {},
+): Promise<ModelCapabilities | undefined> {
+  if (!modelId) return undefined;
+
+  let catalogData: Record<string, RawProviderEntry>;
+
+  if (options.catalog) {
+    catalogData = options.catalog as Record<string, RawProviderEntry>;
+  } else {
+    const maxAge = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const now = Date.now();
+
+    if (cachedCatalog && now - cachedCatalog.timestamp < maxAge) {
+      catalogData = cachedCatalog.data;
+    } else {
+      try {
+        const fetcher = options.fetchImpl ?? fetch;
+        const res = await fetcher(options.catalogUrl ?? DEFAULT_CATALOG_URL);
+        if (!res.ok) return undefined;
+        catalogData = (await res.json()) as Record<string, RawProviderEntry>;
+        cachedCatalog = { timestamp: now, data: catalogData };
+      } catch {
+        // Degrade gracefully if offline or request failed
+        if (cachedCatalog) return extractCapabilities(modelId, cachedCatalog.data);
+        return undefined;
+      }
+    }
+  }
+
+  return extractCapabilities(modelId, catalogData);
+}
+
+function extractCapabilities(
+  modelId: string,
+  catalog: Record<string, RawProviderEntry>,
+): ModelCapabilities | undefined {
+  const targetNorm = normalizeId(modelId);
+  let bestMatch: RawModelEntry | undefined;
+
+  // Pass 1: exact match
+  for (const provider of Object.values(catalog)) {
+    if (!provider?.models) continue;
+    if (provider.models[modelId]) {
+      bestMatch = provider.models[modelId];
+      break;
+    }
+  }
+
+  // Pass 2: normalized match across vendor prefixes and punctuation
+  if (!bestMatch) {
+    for (const provider of Object.values(catalog)) {
+      if (!provider?.models) continue;
+      for (const [key, entry] of Object.entries(provider.models)) {
+        if (normalizeId(key) === targetNorm) {
+          bestMatch = entry;
+          break;
+        }
+      }
+      if (bestMatch) break;
+    }
+  }
+
+  if (!bestMatch) return undefined;
+
+  const inputs = bestMatch.modalities?.input ?? [];
+  return {
+    id: bestMatch.id ?? modelId,
+    name: bestMatch.name,
+    contextWindow: bestMatch.limit?.context,
+    maxOutput: bestMatch.limit?.output,
+    supportsTools: bestMatch.tool_call === true,
+    supportsStructuredOutput: bestMatch.structured_output === true,
+    supportsVision: inputs.includes("image") || bestMatch.attachment === true,
+    supportsReasoning: bestMatch.reasoning === true,
+  };
+}
+

package/src/errors.ts

@@ -53,6 +53,17 @@ const TRANSIENT: ReadonlySet<ErrorKind> = new Set<ErrorKind>([
  *  overload are per-model-endpoint; nothing else on this list is. */
 const BACKUP_ELIGIBLE: ReadonlySet<ErrorKind> = new Set<ErrorKind>(["overload", "rate"]);
 
+/** Kinds that a retry on the same endpoint can never resolve. */
+const NON_RETRYABLE_KINDS: ReadonlySet<ErrorKind> = new Set<ErrorKind>([
+  "quota",
+  "context",
+  "model",
+  "entitlement",
+  "content",
+  "invalid",
+  "aborted",
+]);
+
 export function isTransient(kind: ErrorKind): boolean {
   return TRANSIENT.has(kind);
 }
@@ -61,6 +72,35 @@ export function isBackupEligible(kind: ErrorKind): boolean {
   return BACKUP_ELIGIBLE.has(kind);
 }
 
+/**
+ * Decides whether any failure (ProviderError, thrown Error, TypeError, HTTP response)
+ * is worth a retry.
+ *
+ * Checks in order:
+ * 1. Caller aborts are never retryable.
+ * 2. An explicit `shouldRetry` directive on ProviderError (e.g. from server `x-should-retry`)
+ * 3. Non-retryable kinds (quota, context, model, entitlement, content, invalid) return false.
+ * 4. Excessive retry-after waits (exceeding `maxWaitMs`) return false — long waits belong to fallbacks.
+ * 5. Transient kinds (rate, overload, network, timeout) return true.
+ * 6. Transport-level network faults (fetch failed, connection lost, SSL blips) return true.
+ */
+export function isRetryable(err: unknown, maxWaitMs = 60_000): boolean {
+  if (isAbort(err)) return false;
+
+  if (err instanceof ProviderError) {
+    if (err.shouldRetry !== undefined) return err.shouldRetry;
+    if (NON_RETRYABLE_KINDS.has(err.kind)) return false;
+    if (err.retryAfterMs !== undefined && err.retryAfterMs > maxWaitMs) return false;
+    return err.isTransient;
+  }
+
+  if (isTransportFailure(err)) return true;
+
+  const kind = classify(err);
+  if (NON_RETRYABLE_KINDS.has(kind)) return false;
+  return isTransient(kind);
+}
+
 export class ProviderError extends Error {
   readonly provider: string;
   readonly kind: ErrorKind;
@@ -72,6 +112,8 @@ export class ProviderError extends Error {
   /** Absolute reset of the binding limit. Can be days beyond Retry-After. */
   readonly resetAtMs?: number;
   readonly window?: RateLimitWindow;
+  /** Explicit server directive (`x-should-retry`), overriding default classification. */
+  readonly shouldRetry?: boolean;
   /** The provider's own response body, truncated — the actual reason, which is
    *  otherwise lost behind "400 status code (no body)". */
   readonly body?: string;
@@ -86,6 +128,7 @@ export class ProviderError extends Error {
       retryAfterMs?: number;
       resetAtMs?: number;
       window?: RateLimitWindow;
+      shouldRetry?: boolean;
       body?: string;
       cause?: unknown;
     } = {},
@@ -99,10 +142,12 @@ export class ProviderError extends Error {
     this.retryAfterMs = opts.retryAfterMs;
     this.resetAtMs = opts.resetAtMs;
     this.window = opts.window;
+    this.shouldRetry = opts.shouldRetry;
     this.body = opts.body;
   }
 
   get isTransient(): boolean {
+    if (this.shouldRetry !== undefined) return this.shouldRetry;
     return isTransient(this.kind);
   }
 
@@ -143,15 +188,23 @@ function readString(err: unknown, key: string): string | undefined {
   return typeof value === "string" ? value : undefined;
 }
 
+function sanitizeHtmlError(text: string): string {
+  if (/^\s*<!doctype|^\s*<html/i.test(text) || text.includes("<title>")) {
+    const match = text.match(/<title>([^<]+)<\/title>/i);
+    if (match?.[1]) return match[1].trim();
+  }
+  return text;
+}
+
 export function messageOf(err: unknown): string {
-  if (err instanceof Error) return err.message;
-  if (typeof err === "string") return err;
+  if (err instanceof Error) return sanitizeHtmlError(err.message);
+  if (typeof err === "string") return sanitizeHtmlError(err);
   const message = readString(err, "message");
-  if (message !== undefined) return message;
+  if (message !== undefined) return sanitizeHtmlError(message);
   try {
-    return JSON.stringify(err) ?? String(err);
+    return sanitizeHtmlError(JSON.stringify(err) ?? String(err));
   } catch {
-    return String(err);
+    return sanitizeHtmlError(String(err));
   }
 }
 
@@ -190,15 +243,28 @@ const TRANSPORT_CODES: ReadonlySet<string> = new Set([
   "EHOSTUNREACH",
   "EAI_AGAIN",
   "ERR_STREAM_PREMATURE_CLOSE",
+  // SSL/TLS connection codes (Node, Bun, corporate proxies/firewalls)
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "UNABLE_TO_GET_ISSUER_CERT",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  "CERT_SIGNATURE_FAILURE",
+  "CERT_HAS_EXPIRED",
+  "CERT_NOT_YET_VALID",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+  "HOSTNAME_MISMATCH",
+  "ERR_SSL_WRONG_VERSION_NUMBER",
 ]);
 
 /**
  * The same faults when only a message survives. Engine wordings differ:
  * Chromium says "Failed to fetch", Firefox "NetworkError when attempting to
- * fetch resource", Safari "Load failed", Node/Bun "fetch failed".
+ * fetch resource", Safari "Load failed", Node/Bun "fetch failed", WebKit/macOS
+ * "The network connection was lost".
  */
 const TRANSPORT_MESSAGES =
-  /failed to fetch|fetch failed|network\s?error|load failed|unable to connect|socket hang up|socket (?:connection )?(?:was )?closed|connection (?:error|closed|refused|reset)|premature close|stream (?:ended|closed) unexpectedly|und_err/i;
+  /failed to fetch|fetch failed|network\s?error|network connection (?:was )?lost|load failed|unable to connect|socket hang up|socket (?:connection )?(?:was )?closed|connection (?:error|closed|refused|reset|lost)|premature close|stream (?:ended|closed) unexpectedly|und_err/i;
 
 /** How far up the `cause` chain to look before giving up. */
 const CAUSE_DEPTH = 5;
@@ -206,7 +272,20 @@ const CAUSE_DEPTH = 5;
 function isAbort(err: unknown): boolean {
   const name = readString(err, "name");
   const code = readString(err, "code");
-  return name === "AbortError" || name === "APIUserAbortError" || code === "ABORT_ERR";
+  if (name === "AbortError" || name === "APIUserAbortError" || code === "ABORT_ERR") return true;
+  const msg = readString(err, "message")?.toLowerCase();
+  if (msg) {
+    if (
+      msg.includes("client closed request") ||
+      msg.includes("client cancelled request") ||
+      msg.includes("client canceled request") ||
+      msg.includes("request canceled by client") ||
+      msg.includes("request cancelled by client")
+    ) {
+      return true;
+    }
+  }
+  return false;
 }
 
 /**
@@ -259,6 +338,10 @@ const CONTEXT_PATTERNS: readonly RegExp[] = [
   /input is too long/i,
   /too many (?:input )?tokens/i,
   /reduce the length of the (?:messages|prompt|input)/i,
+  // Anthropic's exact wording when input + max_tokens overflows context limit:
+  // "input length and `max_tokens` exceed context limit: 188059 + 20000 > 200000"
+  /input length and `?max_tokens`? exceed context limit/i,
+  /exceed(?:s|ed)? (?:the )?context limit/i,
   // Scoped to the thing that overflowed: a bare "exceeds the maximum" also
   // covers image counts and per-minute token rates, which compaction can't fix.
   /exceeds? the (?:model'?s? )?maximum (?:input |prompt |context )?(?:tokens?|length|context)/i,
@@ -271,7 +354,15 @@ const ENTITLEMENT_PATTERNS: readonly RegExp[] = [
   /plan does(?:n't| not) (?:include|support)/i,
   /not included (?:in|with) your .{0,40}plan/i,
   /upgrade to [\w ]{1,30}(?:or higher|plan)/i,
+  /requires? (?:the |a |an )?[\w\s]{1,30}plan/i,
+  /requires? (?:a )?subscription/i,
+  /subscription[_\s]?required/i,
+  /upgrade for access/i,
   /no api access/i,
+  /OAuth authentication is currently not allowed for this organization/i,
+  // The ChatGPT backend's error code, which arrives with no prose at all.
+  /usage_not_included/i,
+  /usage not included/i,
 ];
 
 // Balance or usage window used up. Chinese-market providers report it in
@@ -281,7 +372,8 @@ const QUOTA_PATTERNS: readonly RegExp[] = [
   /exceeded your current quota/i,
   /insufficient (?:balance|credits?)/i,
   /credit balance is too low/i,
-  /(?:no|out of) credits/i,
+  /(?:no|any|out of) credits/i,
+  /(?:credits?|balance) depleted/i,
   // Both word orders occur in the wild.
   /usage limits? (?:reached|exceeded|hit)/i,
   /reached your (?:usage|weekly|monthly|daily) limit/i,
@@ -290,6 +382,11 @@ const QUOTA_PATTERNS: readonly RegExp[] = [
   /upgrade your plan/i,
   /quota\b[^.]{0,40}\b(?:exhausted|exceeded|will be refreshed)/i,
   /balance (?:is )?(?:too low|not enough|insufficient)/i,
+  // The OpenAI-shape `type` field for billing failures, serialized into the
+  // scanned text — a quota signal with no prose wording at all (codex-router).
+  /billing_error/i,
+  // Alibaba intl's English spelling of 欠费.
+  /\barrears?\b/i,
   /余额不足/,
   /欠费/,
   /额度(?:不足|已用完)/,
@@ -302,17 +399,26 @@ const MODEL_PATTERNS: readonly RegExp[] = [
 ];
 
 const AUTH_PATTERNS: readonly RegExp[] = [
-  /invalid (?:x-api-key|api[ _-]?key|token|credentials?)/i,
+  /invalid[_\s]?(?:x-api-key|api[ _-]?key|token|credentials?)/i,
   /api[ _-]?key (?:is )?(?:not valid|invalid|incorrect)/i,
   /unauthorized|UNAUTHENTICATED|PERMISSION_DENIED/i,
   /authentication[_\s](?:failed|invalid|error)/i,
   /account (?:disabled|suspended|deactivated|banned)/i,
+  /unrecognizedclient|unauthorizedexception|accessdeniedexception/i,
+  /expired[_\s]?token/i,
+  /OAuth token has been revoked/i,
 ];
 
 const CONTENT_PATTERNS: readonly RegExp[] = [
   /content[_\s]filter/i,
   /content policy/i,
-  /safety|PROHIBITED_CONTENT|blocked|refusal/i,
+  /cyber[_\s]policy/i,
+  /safety|PROHIBITED_CONTENT|blocked|refusal|policy violation|misalignment/i,
+  // Document and media boundary violations
+  /maximum of \d+ PDF pages/i,
+  /PDF specified is password protected/i,
+  /image(?:s)? exceed(?:s)? .* maximum/i,
+  /image dimensions exceed/i,
 ];
 
 /**
@@ -326,8 +432,19 @@ const CONTENT_PATTERNS: readonly RegExp[] = [
  */
 const RATE_PATTERNS: readonly RegExp[] = [
   /rate[_\s-]?limit/i,
-  /too many requests/i,
-  /RESOURCE_EXHAUSTED/,
+  // Spaces, snake and kebab all occur in the wild — opencode's list carries
+  // the snake form for providers that forward Google/gRPC error codes raw.
+  /too[_\s-]?many[_\s-]?requests/i,
+  // Google's quota code, upper-case in the status enum and snake_case in the
+  // type field (codex-router reads the latter) — a per-minute quota is a
+  // throttle, so it lands on rate, not quota.
+  /resource[_\s]?exhausted/i,
+  // AWS Bedrock throttles by exception name (ThrottlingException); the bare
+  // word also arrives alone.
+  /throttl(?:e|ed|ing)/i,
+  // A per-minute window named without the word "rate" — Anthropic's TPM prose
+  // ("Limit 30000 tokens per min") and gateway RPM counters.
+  /(?:requests?|tokens?) per (?:second|sec|minute|min)\b/i,
 ];
 
 /** Theirs and temporary, said in words rather than a status. Gemini reports
@@ -340,7 +457,11 @@ const OVERLOAD_PATTERNS: readonly RegExp[] = [
   // does not swallow the word in ordinary prose.
   /\bINTERNAL\b/,
   /\bcapacity\b/i,
+  /server is busy/i,
+  /high demand/i,
   /"code"\s*:\s*5\d\d/,
+  // OpenAI's 5xx wording, often forwarded by gateways with the status lost.
+  /(?:try|retry) your request again/i,
 ];
 
 const matches = (patterns: readonly RegExp[], text: string): boolean =>
@@ -446,6 +567,53 @@ export function parseRetryAfterMs(err: unknown, body?: string): number | undefin
   return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
 }
 
+export interface ContextOverflowInfo {
+  inputTokens?: number;
+  maxTokens?: number;
+  contextLimit: number;
+  excessTokens: number;
+}
+
+/**
+ * Extracts context overflow details from provider error messages.
+ *
+ * Covers:
+ * - Anthropic / Bedrock: `input length and \`max_tokens\` exceed context limit: 188059 + 20000 > 200000`
+ * - Standard / Gateway: `prompt is too long: 137500 tokens > 135000 maximum`
+ */
+export function parseContextOverflow(err: unknown, body?: string): ContextOverflowInfo | undefined {
+  const text = body ?? bodyTextOf(err) ?? messageOf(err);
+  if (!text) return undefined;
+
+  // Anthropic / Bedrock: "input length and `max_tokens` exceed context limit: 188059 + 20000 > 200000"
+  const m1 = /(?:input length and [`']?max_tokens[`']? exceed context limit|exceeds context limit):\s*(\d+)\s*\+\s*(\d+)\s*>\s*(\d+)/i.exec(text);
+  if (m1) {
+    const input = parseInt(m1[1]!, 10);
+    const max = parseInt(m1[2]!, 10);
+    const limit = parseInt(m1[3]!, 10);
+    return {
+      inputTokens: input,
+      maxTokens: max,
+      contextLimit: limit,
+      excessTokens: input + max - limit,
+    };
+  }
+
+  // "prompt is too long: 137500 tokens > 135000 maximum"
+  const m2 = /(?:prompt is too long|context length exceeded|maximum context length is \d+ tokens?)[^:]*:\s*(\d+)\s*(?:tokens)?\s*>\s*(\d+)/i.exec(text);
+  if (m2) {
+    const actual = parseInt(m2[1]!, 10);
+    const limit = parseInt(m2[2]!, 10);
+    return {
+      inputTokens: actual,
+      contextLimit: limit,
+      excessTokens: actual - limit,
+    };
+  }
+
+  return undefined;
+}
+
 /**
  * A failure the backend reports INSIDE an already-200 stream.
  *