@providerkit/core 0.9.0 → 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.9.0",
+  "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",
@@ -48,6 +48,7 @@
     "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/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);
   }
 
@@ -293,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,
@@ -310,6 +359,7 @@ const ENTITLEMENT_PATTERNS: readonly RegExp[] = [
   /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,
@@ -356,6 +406,7 @@ const AUTH_PATTERNS: readonly RegExp[] = [
   /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[] = [
@@ -363,6 +414,11 @@ const CONTENT_PATTERNS: readonly RegExp[] = [
   /content policy/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,
 ];
 
 /**
@@ -511,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.
  *

package/src/presets.ts

@@ -177,6 +177,13 @@ export const PROVIDER_PRESETS = {
     defaultModel: "MiniMax-M3",
     models: ["MiniMax-M3", "MiniMax-M2.7", "MiniMax-M2.5"],
   },
+  "minimax-openai": {
+    shape: "openai",
+    baseUrl: "https://api.minimax.io/v1",
+    auth: "key",
+    defaultModel: "MiniMax-M3",
+    models: ["MiniMax-M3", "MiniMax-M2.7", "MiniMax-M2.5"],
+  },
 
   // ── Popular gateways & cloud providers ──────────────────────────────────
   nvidia: {
@@ -284,6 +291,14 @@ export const PROVIDER_PRESETS = {
     // (`z-ai/glm-5.3-flash`) answers 400 [1211] Unknown Model.
     explicitNone: true,
   },
+  "zai-openai": {
+    shape: "openai",
+    baseUrl: "https://api.z.ai/api/paas/v4",
+    path: "/chat/completions",
+    auth: "key",
+    defaultModel: "glm-5.3-flash",
+    models: ["glm-5.3-flash", "glm-5.3", "glm-5.2"],
+  },
   kimi: {
     shape: "anthropic",
     baseUrl: "https://api.kimi.ai/coding",
@@ -291,6 +306,13 @@ export const PROVIDER_PRESETS = {
     defaultModel: "kimi-for-coding",
     models: ["kimi-for-coding", "kimi-for-coding-highspeed", "k3", "k3-256k"],
   },
+  "kimi-openai": {
+    shape: "openai",
+    baseUrl: "https://api.moonshot.ai/v1",
+    auth: "key",
+    defaultModel: "kimi-k2.7-code",
+    models: ["kimi-k2.7-code", "kimi-k2.7-code-highspeed", "kimi-k3"],
+  },
   /** Alibaba's dashscope coding plan — OpenAI-compatible per its registry. */
   "alibaba-coding-plan": {
     shape: "openai",
@@ -307,6 +329,30 @@ export const PROVIDER_PRESETS = {
     defaultModel: "qwen3.8-max",
     models: ["qwen3.8-max", "qwen3.8-flash", "qwen3.6-flash"],
   },
+  /** QwenCloud's token plan — OpenAI-compatible endpoint. */
+  "qwen-token-plan-openai": {
+    shape: "openai",
+    baseUrl: "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
+    auth: "bearer",
+    defaultModel: "qwen3.8-max",
+    models: ["qwen3.8-max", "qwen3.8-flash", "qwen3.6-flash"],
+  },
+  /** Alibaba DashScope Platform API — standard pay-as-you-go API key. */
+  alibaba: {
+    shape: "openai",
+    baseUrl: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
+    auth: "bearer",
+    defaultModel: "qwen-max",
+    models: ["qwen-max", "qwen-plus", "qwen-turbo", "qwen-flash"],
+  },
+  /** Alias for alibaba (DashScope platform API). */
+  "qwen-api": {
+    shape: "openai",
+    baseUrl: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
+    auth: "bearer",
+    defaultModel: "qwen-max",
+    models: ["qwen-max", "qwen-plus", "qwen-turbo", "qwen-flash"],
+  },
 
   // ── Local runtimes ──────────────────────────────────────────────────────
   ollama: {

package/src/providers/anthropic.ts

@@ -1,6 +1,6 @@
 // Anthropic-shape adapter — SSE from POST /v1/messages.
 import { streamError } from "../errors.ts";
-import { schemaPrompt } from "../schema.ts";
+import { schemaPrompt, toAnthropicToolSchema } from "../schema.ts";
 import { parseToolArgs } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
 import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
@@ -249,7 +249,7 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
         request.tools = tools.map((tool) => ({
           name: tool.name,
           description: tool.description,
-          input_schema: tool.inputSchema,
+          input_schema: toAnthropicToolSchema(tool.inputSchema),
         }));
       }
       if (opts.toolChoice && opts.toolChoice !== "auto") {

package/src/providers/gemini.ts

@@ -6,7 +6,7 @@
 // wire rather than @google/genai, because this package ships zero dependencies
 // and the SDK is a Node-shaped one.
 import { streamError } from "../errors.ts";
-import { schemaPrompt } from "../schema.ts";
+import { schemaPrompt, toGeminiToolSchema } from "../schema.ts";
 import { parseToolArgs } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
 import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
@@ -69,6 +69,19 @@ const THINKING_LEVEL: Record<Effort, string> = {
   max: "HIGH",
 };
 
+/**
+ * Gemini 2.x thinking budget dial (tokens).
+ * Gemini 2.5 uses `thinkingBudget` (0 disables thinking), while Gemini 3+ uses
+ * `thinkingLevel` (MINIMAL, LOW, MEDIUM, HIGH).
+ */
+const GEMINI_2_THINKING_BUDGET: Record<Effort, number> = {
+  none: 0,
+  low: 1024,
+  medium: 4096,
+  high: 8192,
+  max: 16384,
+};
+
 /** A turn in Gemini's history. `model` is its word for the assistant. */
 export interface GeminiContent {
   role: "user" | "model";
@@ -261,15 +274,27 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
       const maxTokens = opts.maxTokens ?? config.maxTokens;
       const { system, contents } = toGeminiContents(messages);
 
+      // A model id copied out of Gemini's docs is often already `models/…`, and
+      // the doubled segment 404s as "model not found" — a confusing way to
+      // learn about a prefix.
+      const model = (opts.model ?? config.model).replace(/^models\//, "");
+      const isGemini3 = /gemini-3/i.test(model);
+
       const generationConfig: Record<string, unknown> = {};
       if (maxTokens !== undefined) generationConfig.maxOutputTokens = maxTokens;
       if (opts.temperature !== undefined) generationConfig.temperature = opts.temperature;
       if (opts.topP !== undefined) generationConfig.topP = opts.topP;
       if (opts.stopSequences?.length) generationConfig.stopSequences = opts.stopSequences;
-      // No effort means the model's own dynamic thinking. Sending MINIMAL here
+      // No effort means the model's own dynamic thinking. Sending MINIMAL / 0 here
       // would switch that off for a caller who never asked, which is the whole
       // reason the seam treats an absent effort as "never sent".
-      if (effort) generationConfig.thinkingConfig = { thinkingLevel: THINKING_LEVEL[effort] };
+      // Gemini 3 uses thinkingLevel (MINIMAL..HIGH), while Gemini 2.5 uses
+      // thinkingBudget (0 tokens disables thinking, positive numbers set budget).
+      if (effort) {
+        generationConfig.thinkingConfig = isGemini3
+          ? { thinkingLevel: THINKING_LEVEL[effort] }
+          : { thinkingBudget: GEMINI_2_THINKING_BUDGET[effort] };
+      }
       // A schema that shares its call with tools pins the decoder, and a pinned
       // decoder cannot emit a functionCall — the model narrates the call it
       // could not make and the turn ends, with nothing logged. See
@@ -281,7 +306,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
         // `responseJsonSchema` takes JSON Schema as written; `responseSchema`
         // is Gemini's own trimmed dialect and rejects most of what a real
         // schema carries.
-        generationConfig.responseJsonSchema = opts.json.schema;
+        generationConfig.responseJsonSchema = toGeminiToolSchema(opts.json.schema);
       }
 
       const request: Record<string, unknown> = { contents, generationConfig };
@@ -302,7 +327,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
               description: tool.description,
               // Same rule as the response schema: `parameters` is the trimmed
               // dialect, `parametersJsonSchema` is the schema we actually wrote.
-              parametersJsonSchema: tool.inputSchema,
+              parametersJsonSchema: toGeminiToolSchema(tool.inputSchema),
             })),
           },
         ];
@@ -312,11 +337,6 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
         if (toolConfig) request.toolConfig = toolConfig;
       }
 
-      // A model id copied out of Gemini's docs is often already `models/…`, and
-      // the doubled segment 404s as "model not found" — a confusing way to
-      // learn about a prefix.
-      const model = (opts.model ?? config.model).replace(/^models\//, "");
-
       // Gemini reports the finish reason on a candidate that can arrive AFTER
       // the chunk carrying the function calls, so a turn's tool use has to be
       // remembered rather than read off the final chunk.

package/src/providers/openai.ts

@@ -83,10 +83,56 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    * not a lock.
    */
   providerOrder?: string[];
+  /**
+   * Automatically pin OpenRouter calls to the first-party model vendor's host
+   * when hitting openrouter.ai and providerOrder is not passed. Defaults to true.
+   */
+  pinHost?: boolean;
 }
 
 const DEFAULT_BASE_URL = "https://api.openai.com";
 
+/**
+ * Known first-party host slugs on OpenRouter for route pinning.
+ * Pinning keeps consecutive turns on the vendor's own endpoint, preserving
+ * the server-side KV prompt cache across rounds.
+ */
+const OPENROUTER_HOSTS: Record<string, string> = {
+  anthropic: "anthropic",
+  "arcee-ai": "arcee-ai",
+  cohere: "cohere",
+  deepseek: "deepseek",
+  google: "google-ai-studio",
+  meta: "meta",
+  minimax: "minimax",
+  mistralai: "mistral",
+  moonshotai: "moonshotai",
+  morph: "morph",
+  openai: "openai",
+  perplexity: "perplexity",
+  qwen: "alibaba",
+  stepfun: "stepfun",
+  tencent: "tencent",
+  upstage: "upstage",
+  "x-ai": "xai",
+  "z-ai": "z-ai",
+  zai: "z-ai",
+};
+
+export function openRouterHostFor(baseUrl: string, model: string): string | undefined {
+  let host: string;
+  try {
+    host = new URL(baseUrl).hostname;
+  } catch {
+    return undefined;
+  }
+  if (!host.includes("openrouter.ai")) return undefined;
+  const slash = model.indexOf("/");
+  if (slash <= 0) return undefined;
+  const vendor = model.slice(0, slash).toLowerCase();
+  return OPENROUTER_HOSTS[vendor];
+}
+
 /** The spellings of "think this hard" across the dialects that share this
  *  adapter. `off` sends nothing and leaves the model on its own default. */
 export type EffortDialect = "openai" | "openrouter" | "deepseek" | "off";
@@ -316,10 +362,11 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
       opts: StreamOptions = {},
     ): AsyncIterable<ProviderChunk> {
       const effort = opts.effort ?? config.effort;
+      const model = opts.model ?? config.model;
 
       const body = toOpenAIMessages(messages);
       const request: Record<string, unknown> = {
-        model: opts.model ?? config.model,
+        model,
         messages: body,
         stream: true,
         // Without this the usage record never arrives and every call costs
@@ -398,8 +445,17 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
           body.push({ role: "system", content: schemaPrompt(opts.json.schema) });
         }
       }
-      if (config.providerOrder?.length) {
-        request.provider = { order: config.providerOrder, allow_fallbacks: true };
+      const pinOrder = config.providerOrder?.length
+        ? config.providerOrder
+        : config.pinHost !== false
+          ? (() => {
+              const pinned = openRouterHostFor(baseUrl, model);
+              return pinned ? [pinned] : undefined;
+            })()
+          : undefined;
+
+      if (pinOrder?.length) {
+        request.provider = { order: pinOrder, allow_fallbacks: true };
       }
 
       const defaultPath = /\/v\d+[^/]*$/i.test(baseUrl.replace(/\/+$/, ""))

package/src/retry.ts

@@ -13,7 +13,13 @@
 //
 //  3. Honour the provider's own number. When it says `Retry-After: 30`, a
 //     one-second backoff is three wasted attempts before the same wait.
-import { classify, isBackupEligible, isTransient, parseRetryAfterMs, ProviderError } from "./errors.ts";
+import {
+  classify,
+  isBackupEligible,
+  isRetryable,
+  parseRetryAfterMs,
+  ProviderError,
+} from "./errors.ts";
 
 export interface RetryOptions {
   /** Total attempts including the first. Default 3. */
@@ -83,7 +89,7 @@ function delayFor(err: unknown, attempt: number, opts: RetryOptions): number | n
   return backoffMs(attempt, opts.baseDelayMs ?? DEFAULT_BASE_DELAY_MS, cap);
 }
 
-const defaultShouldRetry = (err: unknown): boolean => isTransient(classify(err));
+const defaultShouldRetry = (err: unknown, _attempt: number): boolean => isRetryable(err);
 
 /**
  * Run `fn`, retrying transient failures with backoff. For one-shot calls —