@providerkit/core 0.22.0 → 0.24.0

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 {
@@ -133,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;
@@ -140,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;
@@ -181,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;
+      }
     }
   }
 
@@ -216,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");
   }
 }
 
@@ -277,7 +339,9 @@ 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
@@ -385,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 {
@@ -442,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 ?? {}),
@@ -463,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,
@@ -105,6 +107,13 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    *  no sessionId, the provider's own per-instance id rides instead, so the
    *  gateway never sees a call without one. */
   sessionHeader?: string;
+  /** The id `sessionHeader` carries when a call has no `sessionId`. Absent, the
+   *  adapter mints one when it is built. Pass one when something rebuilds the
+   *  adapter (`withKeyPool` and `withToken` build one per attempt): each build
+   *  mints a new id, and a gateway that pins a session to one upstream host
+   *  then treats every call as a new session, re-routes it and misses its
+   *  prompt cache. Ignored without `sessionHeader`. */
+  instanceSessionId?: string;
   /** Send `X-Initiator`: `user` when the last message is the user's, else
    *  `agent`. GitHub Copilot bills a premium request per `user` turn and lets
    *  the agent's own follow-ups (tool results) ride free. */
@@ -328,19 +337,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,
+      });
   }
 }
 
@@ -505,7 +538,9 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
   // `usage.cost` is its field in its unit. Another gateway that sends a
   // `cost` has not said what it means.
   const reportsCost = isOpenRouter(baseUrl);
-  const instanceSessionId = config.sessionHeader ? crypto.randomUUID() : undefined;
+  const instanceSessionId = config.sessionHeader
+    ? (config.instanceSessionId ?? crypto.randomUUID())
+    : undefined;
 
   const provider: Provider = {
     id,
@@ -519,7 +554,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,
@@ -624,6 +661,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: {
@@ -642,16 +682,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
@@ -723,18 +763,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 };
     },
   };
 

package/src/providers/responses.ts

@@ -10,8 +10,11 @@
 // The event names arrive on the SSE `event:` line and are repeated inside each
 // payload's own `type`. The transport yields only `data:` payloads, so this
 // adapter reads `type` — which is what survives, and what gateways agree on.
+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 { parseRateLimitReset } from "../rate-limit.ts";
+import { settleToolCalls } from "../tool-args.ts";
 import type {
   ChatMessage,
   ContentPart,
@@ -45,6 +48,17 @@ export interface ResponsesConfig extends ProviderFallbackConfig {
   /** Header that carries `StreamOptions.sessionId`. When set and a call has no
    *  sessionId, one stable id for this provider instance rides instead. */
   sessionHeader?: string;
+  /** The id `sessionHeader` carries when a call has no `sessionId`. Absent, the
+   *  adapter mints one when it is built. Pass one when something rebuilds the
+   *  adapter (`withKeyPool` and `withToken` build one per attempt): each build
+   *  mints a new id, and a gateway that pins a session to one upstream host
+   *  then treats every call as a new session, re-routes it and misses its
+   *  prompt cache. Ignored without `sessionHeader`.
+   *
+   *  It is not sent as `prompt_cache_key`, which stays the per-call
+   *  `sessionId`'s: this id names the adapter, so it is shared by every
+   *  conversation the adapter serves, and a minted one never was a cache key. */
+  instanceSessionId?: string;
   /**
    * Where this backend serves the endpoint, when it is not `/v1/responses`.
    * The ChatGPT subscription surface serves it at `/backend-api/codex/responses`
@@ -82,13 +96,26 @@ function reasoningEffort(model: string, effort: Effort): string {
 }
 
 /**
- * `response.incomplete` means the turn was cut short, and the seam has one word
- * for that: "length". `content_filter` is the only other reason this shape
- * documents; anything new stays on "length" rather than reporting a clean stop,
- * because a caller that believes a truncated answer finished will act on it.
+ * The finish an `incomplete` turn stands for. This shape documents two
+ * reasons, and each has its own finish: `max_output_tokens` is the output cap
+ * (`length`) and `content_filter` the filter.
+ *
+ * Any other reason, or none, says only that the turn did not end on purpose.
+ * It used to read as `length`, so an empty turn was told to raise a maxTokens
+ * it never hit. It is thrown as `overload` instead, the transient fault
+ * cc-proxy answers it with (a 503). Nothing about the request is wrong, so it
+ * is retried if nothing was emitted yet; if something was, the error reaches
+ * the caller after it (invariant 1). It is read before reasoning and usage go
+ * out, like a failed terminal, so that retry stays open.
  */
-function mapIncompleteReason(reason: string | undefined): FinishReason {
-  return reason === "content_filter" ? "content_filter" : "length";
+function incompleteFinish(provider: string, reason: string | undefined): FinishReason {
+  if (reason === "max_output_tokens") return "length";
+  if (reason === "content_filter") return "content_filter";
+  throw new ProviderError(
+    provider,
+    "overload",
+    `${provider}: the turn stopped early, reason: ${reason ?? "none given"}`,
+  );
 }
 
 // ── input items ───────────────────────────────────────────────────────────
@@ -282,8 +309,11 @@ interface ResponsesEvent {
   headers?: Record<string, unknown>;
 }
 
+/** One window of the snapshot: the `x-codex-<slot>-*` header numbers as JSON. */
 interface CodexWindow {
   used_percent?: number;
+  window_minutes?: number;
+  reset_at?: number;
   reset_after_seconds?: number;
 }
 
@@ -301,24 +331,42 @@ interface CodexRateLimits {
  * A full window the account's credits cover, or that the backend still
  * `allowed`, lets the turn proceed. It is only the reason when the stream then
  * closes without a response: that close is a spent window, not a dropped
- * socket, and retrying it walks every backup into the same wall. The fuller
- * window binds; cc-proxy took the primary's clock first and told a weekly wall
- * to come back in a few hours.
+ * socket, and retrying it walks every backup into the same wall.
+ *
+ * Which window, and when it lifts, comes from the same parser as the headers
+ * the snapshot mirrors: the fuller window binds, and the later reset when both
+ * are full. cc-proxy took the primary's clock first and told a weekly wall to
+ * come back in a few hours. The window is named so a caller can say "weekly"
+ * instead of "the limit", which reads as the 5-hour one.
  */
 function quotaWall(event: ResponsesEvent, provider: string): ProviderError | undefined {
   const limits = event.rate_limits;
   if (!limits?.limit_reached || limits.allowed) return undefined;
   if (event.credits?.has_credits || event.credits?.unlimited) return undefined;
-  const windows = [limits.primary, limits.secondary].filter((w): w is CodexWindow => !!w);
-  const binding = windows.sort((a, b) => (b.used_percent ?? 0) - (a.used_percent ?? 0))[0];
-  const after = binding?.reset_after_seconds;
-  return new ProviderError(provider, "quota", `${provider}: the usage limit has been reached`, {
-    ...(after !== undefined && after >= 0
-      ? { retryAfterMs: after * 1000, resetAtMs: Date.now() + after * 1000 }
-      : {}),
+  const now = Date.now();
+  const { window, resetAtMs } = parseRateLimitReset(codexHeaders(limits), now);
+  const named = window ? ` (${window} window)` : "";
+  const message = `${provider}: the usage limit has been reached${named}`;
+  return new ProviderError(provider, "quota", message, {
+    ...(resetAtMs !== undefined ? { retryAfterMs: resetAtMs - now, resetAtMs } : {}),
+    window,
   });
 }
 
+/** The snapshot as the `x-codex-*` headers it mirrors, rebuilt the way
+ *  cc-proxy's `event_headers` does, so one parser reads both. */
+function codexHeaders(limits: CodexRateLimits): Headers {
+  const headers = new Headers();
+  for (const slot of ["primary", "secondary"] as const) {
+    for (const [field, value] of Object.entries(limits[slot] ?? {})) {
+      if (typeof value === "number") {
+        headers.set(`x-codex-${slot}-${field.replaceAll("_", "-")}`, String(value));
+      }
+    }
+  }
+  return headers;
+}
+
 function usageChunk(usage: ResponsesUsage): ProviderChunk {
   return {
     type: "usage",
@@ -358,7 +406,9 @@ function unsentTail(snapshot: string, streamed: string): string {
 export function createResponsesProvider(config: ResponsesConfig): Provider {
   const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
   const id = config.id ?? "openai-responses";
-  const instanceSessionId = config.sessionHeader ? crypto.randomUUID() : undefined;
+  const instanceSessionId = config.sessionHeader
+    ? (config.instanceSessionId ?? crypto.randomUUID())
+    : undefined;
 
   const provider: Provider = {
     id,
@@ -373,8 +423,11 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
       const model = opts.model ?? config.model;
       const museContributor = isMuseSparkContributor(model);
       const requestTools = museContributor && opts.toolChoice === "none" ? [] : tools;
+      // Repaired before the images are gated: an orphaned result becomes a user
+      // note that keeps its images, and those must meet the limits too.
+      const sent = repairHistory(messages).messages;
       const { instructions, input } = toResponsesInput(
-        config.imageLimits ? gateImages(messages, config.imageLimits) : messages,
+        config.imageLimits ? gateImages(sent, config.imageLimits) : sent,
         id,
       );
 
@@ -457,9 +510,10 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
       const pendingFor = (itemId?: string, callId?: string) =>
         (itemId ? pending.get(itemId) : undefined) ?? (callId ? pending.get(callId) : undefined);
       let nextIndex = 0;
-      // This shape never states a stop reason on a clean finish, so it is
-      // inferred from whether the turn produced a function call.
-      let sawToolCall = false;
+      // Every call the turn opened, kept past its `.done`. This shape never
+      // states a stop reason on a clean finish, so it is inferred from whether
+      // there are any, and the terminal event checks each one can run.
+      const calls: PendingCall[] = [];
       let wall: ProviderError | undefined;
       let produced = false;
       const reasoningItems: unknown[] = [];
@@ -482,13 +536,9 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
         ...(opts.signal ? { signal: opts.signal } : {}),
         ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
         ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+        ...(opts.onRateLimit ? { onRateLimit: opts.onRateLimit } : {}),
       })) {
-        let event: ResponsesEvent;
-        try {
-          event = JSON.parse(data) as ResponsesEvent;
-        } catch {
-          continue; // a keep-alive or a frame we do not model
-        }
+        const event = parseFrame<ResponsesEvent>(data, id);
         if (event.type?.endsWith(".delta") || event.type === "response.output_item.added") {
           produced = true;
         }
@@ -515,7 +565,6 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
             // turn came back as a nameless call with empty arguments.
             const key = item.id ?? item.call_id;
             if (!key) break;
-            sawToolCall = true;
             const index = nextIndex++;
             // Normally empty here, but a backend that already has the whole
             // call sends it in the skeleton.
@@ -526,6 +575,7 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
               name: item.name ?? "",
               streamed: seeded,
             };
+            calls.push(call);
             pending.set(key, call);
             if (item.call_id) pending.set(item.call_id, call);
             // Only the fields the skeleton actually states. An empty `id` here
@@ -582,20 +632,24 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
 
             if (!known) {
               // A backend that emits neither the skeleton nor the deltas — the
-              // whole call arrives here or not at all. Without a `call_id`
-              // there is nothing to answer it with: the caller's
-              // `function_call_output` would quote `""` and take a 400 reading
-              // "No tool output found for function call" one turn later, so the
-              // call is dropped rather than handed over unrunnable. Dropping is
-              // only possible here, where nothing has been streamed for it yet.
-              if (!item.call_id) break;
-              sawToolCall = true;
+              // whole call arrives here or not at all. A call with no `call_id`
+              // used to be dropped, because the caller's `function_call_output`
+              // would quote `""` and take a 400 one turn later. Dropped, the
+              // model's call silently never happened. It gets an id at the
+              // terminal event instead (`settleToolCalls`).
+              const call: PendingCall = {
+                index: nextIndex++,
+                id: item.call_id ?? "",
+                name: item.name ?? "",
+                streamed: snapshot,
+              };
+              calls.push(call);
               yield {
                 type: "delta",
                 toolCalls: [
                   {
-                    index: nextIndex++,
-                    id: item.call_id,
+                    index: call.index,
+                    ...(item.call_id ? { id: item.call_id } : {}),
                     ...(item.name ? { name: item.name } : {}),
                     arguments: snapshot,
                   },
@@ -617,6 +671,8 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
               ...(item.name && item.name !== known.name ? { name: item.name } : {}),
               ...(tail ? { arguments: tail } : {}),
             };
+            known.id = item.call_id || known.id;
+            known.name = item.name || known.name;
             if (Object.keys(restated).length > 0) {
               yield { type: "delta", toolCalls: [{ index: known.index, ...restated }] };
             }
@@ -635,16 +691,27 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
             if (response?.status === "failed" || response?.error) {
               throw streamError(id, response.error ?? { message: "response failed" });
             }
+            // Any other status (`cancelled`, `queued`, one added later) says
+            // nothing about the answer being whole. Read as a clean stop, it
+            // was a finished turn nobody retried. Theirs, so `overload`.
+            const status = response?.status;
+            if (status !== undefined && status !== "completed" && status !== "incomplete") {
+              throw new ProviderError(id, "overload", `${id} ended the turn as "${status}"`, {
+                code: status,
+              });
+            }
+            let finishReason: FinishReason = calls.length > 0 ? "tool_calls" : "stop";
+            if (status === "incomplete") {
+              finishReason = incompleteFinish(id, response?.incomplete_details?.reason);
+            } else {
+              // Checked on a whole turn only: a cut one may have lost a call's
+              // name to the cut, and nobody runs a cut turn's calls.
+              const minted = settleToolCalls(id, calls);
+              if (minted.length > 0) yield { type: "delta", toolCalls: minted };
+            }
             yield* reasoningChunk();
             if (response?.usage) yield usageChunk(response.usage);
-            if (response?.status === "incomplete") {
-              yield {
-                type: "finish",
-                finishReason: mapIncompleteReason(response.incomplete_details?.reason),
-              };
-              return;
-            }
-            yield { type: "finish", finishReason: sawToolCall ? "tool_calls" : "stop" };
+            yield { type: "finish", finishReason };
             return;
           }
 
@@ -655,13 +722,11 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
           case "response.incomplete": {
             // A turn that ran out of output tokens still billed for its input,
             // and this event carries usage in the same shape as `completed`.
+            const finishReason = incompleteFinish(id, event.response?.incomplete_details?.reason);
             yield* reasoningChunk();
             const usage = event.response?.usage;
             if (usage) yield usageChunk(usage);
-            yield {
-              type: "finish",
-              finishReason: mapIncompleteReason(event.response?.incomplete_details?.reason),
-            };
+            yield { type: "finish", finishReason };
             return;
           }