@providerkit/core 0.21.1 → 0.23.0

package/src/providers/factory.ts

@@ -47,7 +47,7 @@ export interface PresetProviderConfig extends ProviderFallbackConfig {
    *  preset's static protocol headers. */
   headers?: Record<string, string>;
   /**
-   * App attribution for OpenRouter's rankings — the site URL rides as
+   * App attribution for OpenRouter's rankings. The site URL rides as
    * `HTTP-Referer`, the app name as `X-Title`. Public, not secret. Sent on
    * the OpenAI-compatible and Anthropic shapes (OpenRouter reads them for app
    * attribution); the Gemini and Responses shapes ignore them. An explicit
@@ -60,7 +60,7 @@ export interface PresetProviderConfig extends ProviderFallbackConfig {
   siteName?: string;
   /** OpenRouter-only: preferred upstream hosts, in order. OpenRouter's cache
    *  lives on the upstream host's account and default routing hops hosts
-   *  between rounds — pinning keeps a conversation's rounds (and their cache)
+   *  between rounds. Pinning keeps a conversation's rounds (and their cache)
    *  on one host. Empty/absent = default routing. */
   providerOrder?: string[];
   /** Default `service_tier` for every call on the OpenAI and Responses shapes;
@@ -92,7 +92,7 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
   }
   const model = chain?.[0] ?? config.model ?? preset.defaultModel;
   if (!model) {
-    throw new Error(`[providerkit] Preset "${id}" has no defaultModel — pass a model.`);
+    throw new Error(`[providerkit] Preset "${id}" has no defaultModel. Pass a model.`);
   }
   const wire = wireFor(preset, model);
   if (config.serviceTier && (wire.shape === "anthropic" || wire.shape === "gemini")) {
@@ -149,6 +149,7 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
         ...(config.providerOrder ? { providerOrder: config.providerOrder } : {}),
         ...(preset.sessionHeader ? { sessionHeader: preset.sessionHeader } : {}),
         ...(preset.initiatorHeader ? { initiatorHeader: true } : {}),
+        ...(preset.noSampling ? { noSampling: true } : {}),
         fetchImpl: config.fetchImpl,
       });
       break;

package/src/providers/gemini.ts

@@ -5,9 +5,10 @@
 // its own chain of thought on the next turn. Written straight against the REST
 // wire rather than @google/genai, because this package ships zero dependencies
 // and the SDK is a Node-shaped one.
-import { ProviderError, streamCut, streamError } from "../errors.ts";
+import { repairHistory } from "../context.ts";
+import { ProviderError, streamCut, streamError, type ErrorKind } from "../errors.ts";
 import { schemaPrompt, toGeminiToolSchema } from "../schema.ts";
-import { parseToolArgs } from "../tool-args.ts";
+import { parseToolArgs, settleToolCalls } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
 import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
 import type {
@@ -26,7 +27,7 @@ import type {
 export interface GeminiConfig extends ProviderFallbackConfig {
   apiKey: string;
   model: string;
-  /** Any endpoint speaking the Generative Language REST dialect — a proxy or
+  /** Any endpoint speaking the Generative Language REST dialect, including a proxy or
    *  gateway. Defaults to the Generative Language API.
    *
    *  Not Vertex: it serves `/v1/projects/…/locations/…/publishers/google/models`
@@ -39,7 +40,7 @@ export interface GeminiConfig extends ProviderFallbackConfig {
   effort?: Effort;
   /**
    * How the schema rides on a call that also carries tools. See
-   * {@link JsonWithTools} — and note that it is the MODEL's answer, not the
+   * {@link JsonWithTools}. Note that it is the model's answer, not the
    * endpoint's: measured 2026-09-07, `gemini-3.5-flash` and
    * `gemini-3.5-flash-lite` called their tool under `responseJsonSchema` every
    * time, while `gemini-3.8-flash` managed 3/10. `probeJsonWithTools` asks the
@@ -70,9 +71,10 @@ const THINKING_LEVEL: Record<Effort, string> = {
 };
 
 /**
- * Gemini 2.x thinking budget dial (tokens).
- * Gemini 2.5 uses `thinkingBudget` (0 disables thinking), while Gemini 3+ uses
- * `thinkingLevel` (MINIMAL, LOW, MEDIUM, HIGH).
+ * Gemini 2.x thinking budget dial (tokens). Gemini 2.5 takes `thinkingBudget`
+ * (0 disables thinking) and has no level. Every newer model takes
+ * `thinkingLevel`, and Google has said the next ones answer a budget with a
+ * 400 instead of remapping it.
  */
 const GEMINI_2_THINKING_BUDGET: Record<Effort, number> = {
   none: 0,
@@ -95,7 +97,7 @@ function isJsonObject(value: unknown): value is Record<string, unknown> {
 /**
  * Tool-call arguments as the OBJECT Gemini's `functionCall.args` requires.
  *
- * A bare JSON scalar or array is wrapped rather than rejected — the shared
+ * A bare JSON scalar or array is wrapped rather than rejected. The shared
  * `parseToolArgs` drops a non-object as a protocol violation, which is right
  * for reading a fresh tool call and wrong here, where replaying `{}` deletes an
  * argument the model did send. Everything else defers to it, so a truncated or
@@ -132,6 +134,12 @@ function toResponseObject(content: string): Record<string, unknown> {
  * and carry tool calls as `functionCall` parts with the thought signature
  * beside them; tool results are role `user` with a `functionResponse` part
  * naming the FUNCTION, since Gemini pairs a result to its call by name.
+ *
+ * A run of results is ONE user turn: Gemini answers a model turn's parallel
+ * calls with every response together, and spread over several turns it 400s
+ * that the response count does not match the call count. The responses go
+ * first, in call order, and the run's images follow them all, the way the
+ * OpenAI dialect places them.
  */
 export function toGeminiContents(messages: readonly ChatMessage[]): {
   system?: string;
@@ -139,8 +147,11 @@ export function toGeminiContents(messages: readonly ChatMessage[]): {
 } {
   let system = "";
   const contents: GeminiContent[] = [];
+  // The open run of tool results: its parts, and how many lead with a response.
+  let results: { parts: unknown[]; responses: number } | undefined;
 
   for (const message of messages) {
+    if (message.role === "user" || message.role === "assistant") results = undefined;
     switch (message.role) {
       case "system":
         system = system ? `${system}\n\n${message.content}` : message.content;
@@ -180,23 +191,24 @@ export function toGeminiContents(messages: readonly ChatMessage[]): {
         break;
       }
 
-      case "tool":
-        contents.push({
-          role: "user",
-          parts: [
-            {
-              functionResponse: {
-                id: message.toolCallId,
-                name: message.name,
-                response: toResponseObject(message.content),
-              },
-            },
-            ...(message.images ?? []).map((image) => ({
-              inlineData: { mimeType: image.mimeType, data: image.data },
-            })),
-          ],
+      case "tool": {
+        if (!results) {
+          results = { parts: [], responses: 0 };
+          contents.push({ role: "user", parts: results.parts });
+        }
+        results.parts.splice(results.responses, 0, {
+          functionResponse: {
+            id: message.toolCallId,
+            name: message.name,
+            response: toResponseObject(message.content),
+          },
         });
+        results.responses += 1;
+        for (const image of message.images ?? []) {
+          results.parts.push({ inlineData: { mimeType: image.mimeType, data: image.data } });
+        }
         break;
+      }
     }
   }
 
@@ -205,7 +217,7 @@ export function toGeminiContents(messages: readonly ChatMessage[]): {
 
 /**
  * `auto` and an absent choice are Gemini's own default, so the field is omitted
- * rather than sent as AUTO. `required` and a pinned tool are both mode ANY —
+ * rather than sent as AUTO. `required` and a pinned tool are both mode ANY:
  * the pin is the allow-list, not the mode.
  */
 function toToolConfig(choice: ToolChoice | undefined): unknown {
@@ -215,15 +227,66 @@ function toToolConfig(choice: ToolChoice | undefined): unknown {
   return { functionCallingConfig: { mode: "ANY", allowedFunctionNames: [choice.name] } };
 }
 
-function mapFinishReason(reason: string): FinishReason {
+/**
+ * Every finish reason Gemini documents (the generate-content reference, read
+ * 2026-10-19), decided one by one. Anything this switch did not name used to
+ * read as `stop`, so a call the model botched (`MALFORMED_FUNCTION_CALL`) or a
+ * turn that ended for no stated reason (`OTHER`) came back as a finished, empty
+ * answer. After a tool result, `requireContent` takes an empty `stop` as the
+ * model choosing to say nothing, so nothing retried it.
+ */
+function mapFinishReason(provider: string, reason: string): FinishReason {
+  const fail = (kind: ErrorKind, why: string): never => {
+    throw new ProviderError(provider, kind, `${provider} ended the turn on ${reason}: ${why}`, {
+      code: reason,
+    });
+  };
   switch (reason) {
+    case "STOP":
+      return "stop";
+    // The output cap. CONTINUATION is the same cap with a token to carry on,
+    // which this adapter never sends back.
     case "MAX_TOKENS":
+    case "CONTINUATION":
       return "length";
+    // A filter on what was said or drawn. The text so far stands and the
+    // finish says why it ended, as `content_filter` does on every wire. A
+    // retry would mostly meet the same filter.
     case "SAFETY":
     case "PROHIBITED_CONTENT":
+    case "BLOCKLIST":
+    case "SPII":
+    case "RECITATION":
+    case "LANGUAGE":
+    case "ESCALATION":
+    case "IMAGE_SAFETY":
+    case "IMAGE_PROHIBITED_CONTENT":
+    case "IMAGE_RECITATION":
       return "content_filter";
+    // The request lost a thought signature, and the same request loses it
+    // again. A bug in what was sent, so nothing retries it.
+    case "MISSING_THOUGHT_SIGNATURE":
+      return fail("invalid", "the request is missing a thought signature");
+    // The account was limited for a policy violation. Benched like a refused
+    // key, so a key pool moves to another project.
+    case "PUP_LIMITED_DISABLED":
+      return fail("auth", "the account is limited or disabled");
+    // The model broke its own turn: a call it could not form, one with no tool
+    // offered, too many in a row, a malformed reply, an image it never made.
+    // The same request usually works on the next try.
+    case "MALFORMED_FUNCTION_CALL":
+    case "UNEXPECTED_TOOL_CALL":
+    case "TOO_MANY_TOOL_CALLS":
+    case "MALFORMED_RESPONSE":
+    case "NO_IMAGE":
+      return fail("overload", "the model broke its own turn");
+    // These say nothing about why, and a reason added after this list says
+    // nothing we can read. Neither proves the answer is whole.
+    case "OTHER":
+    case "IMAGE_OTHER":
+    case "FINISH_REASON_UNSPECIFIED":
     default:
-      return "stop";
+      return fail("overload", "it gave no reason that shows the answer is complete");
   }
 }
 
@@ -236,7 +299,7 @@ interface GeminiPart {
 }
 
 /** Google's `google.rpc.Status`: an HTTP `code`, the canonical `status` name,
- *  and `details` — which is where RetryInfo's `retryDelay` rides. */
+ *  and `details`, which is where RetryInfo's `retryDelay` rides. */
 interface GeminiStatus {
   code?: number;
   message?: string;
@@ -255,7 +318,7 @@ interface GeminiResponse {
     thoughtsTokenCount?: number;
     cachedContentTokenCount?: number;
   };
-  /** Present only on the in-band failure below — never on a real candidate. */
+  /** Present only on the in-band failure below. Never on a real candidate. */
   error?: GeminiStatus;
   /** A prompt Gemini refused outright: no candidate at all, just the reason. */
   promptFeedback?: { blockReason?: string };
@@ -276,28 +339,32 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
     ): AsyncIterable<ProviderChunk> {
       const effort = opts.effort ?? config.effort;
       const maxTokens = opts.maxTokens ?? config.maxTokens;
-      const { system, contents } = toGeminiContents(messages);
+      // Repaired first: a result with no call, or a call with no result, is a
+      // 400 that loses the turn. See repairHistory.
+      const { system, contents } = toGeminiContents(repairHistory(messages).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);
+      // Not `!isGemini3`: `gemini-flash-latest` and models newer than 3 are not
+      // Gemini 3 either, and they must get a level.
+      const isGemini2 = /gemini-2/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;
+      // `temperature` and `topP` are never sent: Gemini 3.6 Flash and later ignore
+      // them and the next models reject them. Dropping them, rather than refusing,
+      // keeps a fallback chain that shares one set of options working.
       if (opts.stopSequences?.length) generationConfig.stopSequences = opts.stopSequences;
       // 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".
-      // 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] };
+        generationConfig.thinkingConfig = isGemini2
+          ? { thinkingBudget: GEMINI_2_THINKING_BUDGET[effort] }
+          : { thinkingLevel: THINKING_LEVEL[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
@@ -382,6 +449,11 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
         ...(opts.signal ? { signal: opts.signal } : {}),
         ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
         ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+        ...(opts.onRateLimit ? { onRateLimit: opts.onRateLimit } : {}),
+        // This wire has no terminal event to stop at, so the finish reason is
+        // the end: a read that dies after it can cost a late usage record, never
+        // the answer.
+        finished: () => finished,
       })) {
         let chunk: GeminiResponse;
         try {
@@ -439,12 +511,14 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
           const call = part.functionCall;
           if (!call) continue;
           const index = callIndex++;
+          const identity = { index, id: call.id ?? "", name: call.name ?? "" };
+          // The part is the whole call, so it is settled here: one with no
+          // name can't run, and one with no id gets one the way the other
+          // three wires mint it. Gemini omits the id on a single-call turn, and
+          // the seam's consumers pair a result back to its call by id.
+          settleToolCalls(id, [identity]);
           toolCalls.push({
-            index,
-            // Gemini omits the id on a single-call turn, and the seam's
-            // consumers pair a result back to its call by id.
-            id: call.id ?? `call_${index}`,
-            ...(call.name ? { name: call.name } : {}),
+            ...identity,
             // Whole and already assembled — unlike the OpenAI shape, Gemini
             // never fragments an argument object across chunks.
             arguments: JSON.stringify(call.args ?? {}),
@@ -460,13 +534,16 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
         }
 
         if (candidate.finishReason) {
+          // Mapped first: a reason that throws must not be dressed as tool_calls.
+          const finishReason = mapFinishReason(id, candidate.finishReason);
           finished = true;
           yield {
             type: "finish",
-            // A turn that called tools finishes as tool_calls whatever the
-            // candidate says — Gemini routinely reports STOP there, and a
+            // Gemini routinely reports STOP on a turn that called tools, and a
             // caller reading that as "done" drops the tool round entirely.
-            finishReason: sawFunctionCalls ? "tool_calls" : mapFinishReason(candidate.finishReason),
+            // Only STOP is promoted, as on the other three wires: a length cut
+            // or a filter may be what broke the call (invariant 10).
+            finishReason: sawFunctionCalls && finishReason === "stop" ? "tool_calls" : finishReason,
           };
         }
       }

package/src/providers/openai.ts

@@ -3,8 +3,10 @@
 // This is the dialect most gateways speak, so one adapter serves OpenAI,
 // OpenRouter, DeepSeek, GLM, Kimi, Groq, Together, vLLM, Ollama and LM Studio.
 // Their divergences are small and named where they appear.
+import { repairHistory } from "../context.ts";
 import { fileRefused, ProviderError, streamCut, streamError } from "../errors.ts";
-import { streamSse, apiUrl } from "../transport.ts";
+import { streamSse, apiUrl, parseFrame } from "../transport.ts";
+import { settleToolCalls, type ToolCallIdentity } from "../tool-args.ts";
 import { attributionHeaders } from "../attribution.ts";
 import type {
   ChatMessage,
@@ -31,7 +33,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    *  /chat/completions when the base already includes the API version, such as
    *  a gateway using /v4 rather than /v1. */
   path?: string;
-  /** Names the provider in errors and logs — "openrouter", "deepseek", … It
+  /** Names the provider in errors and logs ("openrouter", "deepseek", …). It
    *  also picks the effort dialect below, unless `effortDialect` overrides. */
   id?: string;
   effort?: Effort;
@@ -50,7 +52,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
   /**
    * How a json request rides when the SAME call also carries tools.
    *
-   * `response_format` — the default — sends both, which is what the shape
+   * `response_format` (the default) sends both, which is what the shape
    * documents and what most models honour. `prompt` drops the response format
    * from those calls only and sends the schema as prompt instead: the shape the
    * Anthropic adapter has always used, and the reason this failure cannot
@@ -58,7 +60,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    *
    * It needs a knob because a model that cannot serve both does not say so. Its
    * decoder is pinned to the schema, the tool call has nowhere to go, and the
-   * model writes the announcement instead — "let me look that up for you" — and
+   * model writes the announcement instead ("let me look that up for you") and
    * the turn ends looking like a model with no initiative rather than a request
    * that made the call impossible. Nothing is logged, because nothing failed.
    *
@@ -70,7 +72,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    * No default is right for everyone, which is why this stays a setting rather
    * than becoming a rule: the same run put `qwen3.8-flash` at 1/6 with the
    * schema in the prompt against 6/6 with the response format. Don't guess it
-   * from the model card — `probeJsonWithTools` asks the model itself, in one
+   * from the model card. `probeJsonWithTools` asks the model itself, in one
    * call. `StreamOptions.jsonWithTools` overrides this per call.
    */
   jsonWithTools?: JsonWithTools;
@@ -78,7 +80,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
   fetchImpl?: typeof fetch;
   headers?: Record<string, string>;
   /**
-   * App attribution for OpenRouter's rankings — the site URL rides as
+   * App attribution for OpenRouter's rankings. The site URL rides as
    * `HTTP-Referer`, the app name as `X-Title`. Public, not secret. Sent
    * whenever set (other vendors ignore unknown headers); an explicit entry
    * in `headers` always wins.
@@ -91,7 +93,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
   /**
    * Pin OpenRouter to preferred upstream hosts so the PROMPT CACHE stays warm
    * across rounds. The cache lives on the upstream host's account and default
-   * routing hops between them, and every hop is a cold cache — worse latency
+   * routing hops between them. Every hop is a cold cache, with worse latency
    * and higher effective input cost. Fallbacks stay on: this is a preference,
    * not a lock.
    */
@@ -109,6 +111,9 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    *  `agent`. GitHub Copilot bills a premium request per `user` turn and lets
    *  the agent's own follow-ups (tool results) ride free. */
   initiatorHeader?: boolean;
+  /** Never send `temperature` or `top_p`. For an endpoint that fixes its own
+   *  sampling and rejects the fields (Gemini's OpenAI-compatible route). */
+  noSampling?: boolean;
   /** Default `service_tier` for every call; `StreamOptions.serviceTier` wins. */
   serviceTier?: ServiceTier;
 }
@@ -215,14 +220,14 @@ const OPENROUTER_NONE: ReadonlyMap<string, "low" | "minimal" | "none"> = new Map
  *   MiMo v2.6 Flash takes one, and DeepSeek V4 Flash thinks at `low` and not
  *   with the field omitted. So `none` is said per model, from
  *   `OPENROUTER_NONE`, which also says why an unlisted model gets nothing.
- *   Naming a level raises it — the accepted values are `low`, `high` and
+ *   Naming a level raises it. The accepted values are `low`, `high` and
  *   `max` (`medium` and `xhigh` are accepted too, but our vocabulary has no
  *   use for them).
  * - **DeepSeek V4 defaults thinking ON** on its own API, so `none` has to be an
  *   explicit refusal there. The same word is a different request on each
  *   dialect, and on OpenRouter on each model: the spelling belongs to the
  *   endpoint, never to the caller.
- * - **OpenAI** takes `reasoning_effort`, and `none` is one of its values — not
+ * - **OpenAI** takes `reasoning_effort`, and `none` is one of its values, not
  *   the absence of the field. GPT-5.1 both accepted `none` and made it the
  *   default; everything from GPT-5 back still defaults to `medium`. So sending
  *   nothing is NOT a way to say "do not think": on every model released before
@@ -325,19 +330,43 @@ function dialectFor(id: string): EffortDialect {
   return "openai";
 }
 
-function mapFinishReason(reason: string | null | undefined): FinishReason | undefined {
+/**
+ * A stated finish, or a throw for one this dialect does not document. An
+ * unknown reason used to end the stream as a clean success with no finish at
+ * all, so DeepSeek's `insufficient_system_resource`, Z.ai's `network_error` and
+ * OpenRouter's `error` each read as a finished answer. Nothing says the answer
+ * ended on purpose, so it is `overload`: theirs, and worth a retry (cc-proxy
+ * answers it the same way).
+ */
+function mapFinishReason(provider: string, reason: string): FinishReason {
   switch (reason) {
+    // A natural end under another name, from servers on this wire: Together's
+    // `eos`, Hugging Face TGI's `eos_token` and `stop_sequence`. Thrown as
+    // unknown, each would fail an answer that was already whole.
     case "stop":
+    case "eos":
+    case "eos_token":
+    case "stop_sequence":
       return "stop";
+    // Z.ai's `model_context_window_exceeded` and Mistral's `model_length`: the
+    // context window filled before the answer did. Cut short, and a retry fills
+    // it the same way.
     case "length":
+    case "model_context_window_exceeded":
+    case "model_length":
       return "length";
     case "tool_calls":
     case "function_call":
       return "tool_calls";
+    // `sensitive` is Z.ai's name for its safety stop. A retry meets the same
+    // filter.
     case "content_filter":
+    case "sensitive":
       return "content_filter";
     default:
-      return undefined;
+      throw new ProviderError(provider, "overload", `${provider} ended the turn on "${reason}"`, {
+        code: reason,
+      });
   }
 }
 
@@ -351,7 +380,7 @@ function partsToOpenAI(content: string | ContentPart[], provider: string): unkno
 }
 
 /**
- * Assistant turns carry `reasoning_content` when the history has it — thinking
+ * Assistant turns carry `reasoning_content` when the history has it. Thinking
  * providers require the prior turn's chain-of-thought replayed on a turn that
  * made a tool call. A caller running a turn with thinking OFF must strip it
  * first (`stripReasoning`); the two cannot be mixed.
@@ -454,7 +483,7 @@ interface OpenAIChunk {
     is_byok?: boolean;
     cost_details?: { upstream_inference_cost?: unknown } | null;
   } | null;
-  /** Present only on the in-band failure below — never beside a choice.
+  /** Present only on the in-band failure below. Never beside a choice.
    *  `code` is the numeric HTTP status on the gateways, a slug on OpenAI. */
   error?: { message?: string; code?: string | number; type?: string };
 }
@@ -516,7 +545,9 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
       const effort = opts.effort ?? config.effort;
       const model = opts.model ?? config.model;
 
-      const body = toOpenAIMessages(messages, id);
+      // Repaired first: a result with no call, or a call with no result, is a
+      // 400 that loses the turn. See repairHistory.
+      const body = toOpenAIMessages(repairHistory(messages).messages, id);
       const request: Record<string, unknown> = {
         model,
         messages: body,
@@ -527,8 +558,10 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
       };
       const maxTokens = opts.maxTokens ?? config.maxTokens;
       if (maxTokens !== undefined) request.max_tokens = maxTokens;
-      if (opts.temperature !== undefined) request.temperature = opts.temperature;
-      if (opts.topP !== undefined) request.top_p = opts.topP;
+      if (!config.noSampling) {
+        if (opts.temperature !== undefined) request.temperature = opts.temperature;
+        if (opts.topP !== undefined) request.top_p = opts.topP;
+      }
       if (opts.stopSequences?.length) request.stop = opts.stopSequences;
       const serviceTier = opts.serviceTier ?? config.serviceTier;
       if (serviceTier) request.service_tier = serviceTier;
@@ -619,6 +652,9 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
         : "/v1/chat/completions";
 
       let ended = false;
+      // Each call as its deltas named it, by index. The finish checks them
+      // before it goes out, and they are what says the turn called a tool.
+      const calls = new Map<number, ToolCallIdentity>();
       for await (const data of streamSse({
         url: apiUrl(baseUrl, config.path ?? defaultPath),
         headers: {
@@ -637,16 +673,16 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
         ...(opts.signal ? { signal: opts.signal } : {}),
         ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
         ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+        ...(opts.onRateLimit ? { onRateLimit: opts.onRateLimit } : {}),
         onDone: () => {
           ended = true;
         },
+        // Usage comes AFTER the finish on this shape, so the reader keeps going
+        // to `[DONE]` (invariant 5). But a read that dies in between costs only
+        // the usage frame: the answer is whole once its finish is stated.
+        finished: () => ended,
       })) {
-        let chunk: OpenAIChunk;
-        try {
-          chunk = JSON.parse(data) as OpenAIChunk;
-        } catch {
-          continue;
-        }
+        const chunk = parseFrame<OpenAIChunk>(data, id);
 
         // A failure the backend reports after its headers went out. The
         // gateways speaking this dialect — OpenRouter above all — report a
@@ -718,18 +754,35 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
                 ? { arguments: call.function.arguments }
                 : {}),
             }));
+            for (const call of out.toolCalls) {
+              const seen = calls.get(call.index) ?? { index: call.index, id: "", name: "" };
+              if (call.id) seen.id = call.id;
+              if (call.name) seen.name = call.name;
+              calls.set(call.index, seen);
+            }
             has = true;
           }
           if (has) yield out;
         }
 
-        if (choice.finish_reason) ended = true;
-        const finishReason = mapFinishReason(choice.finish_reason);
-        if (finishReason) yield { type: "finish", finishReason };
+        if (choice.finish_reason) {
+          const stated = mapFinishReason(id, choice.finish_reason);
+          const minted = settleToolCalls(id, calls.values());
+          if (minted.length > 0) yield { type: "delta", toolCalls: minted };
+          ended = true;
+          // Several gateways end a turn that called a tool on `stop`, and a
+          // caller reading that as done never runs the tool. Only `stop` is
+          // promoted: a length cut or a filter may be what broke the call.
+          const finishReason = stated === "stop" && calls.size > 0 ? "tool_calls" : stated;
+          yield { type: "finish", finishReason };
+        }
       }
       // Either proof will do: some gateways send `[DONE]` with no finish, and
       // some a finish with no `[DONE]`. Neither means the socket closed early.
       if (!ended) throw streamCut(id);
+      // A `[DONE]` with no finish stated still owes its calls the same check.
+      const minted = settleToolCalls(id, calls.values());
+      if (minted.length > 0) yield { type: "delta", toolCalls: minted };
     },
   };