@providerkit/core 0.1.0 → 0.3.0

package/src/providers/gemini.ts

@@ -0,0 +1,386 @@
+// Gemini adapter — SSE from POST /v1beta/models/{model}:streamGenerateContent.
+//
+// Native Gemini, not its OpenAI-compatible shim: only this endpoint carries
+// thought signatures, and a signature dropped on the way back costs the model
+// 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 { streamError } from "../errors.ts";
+import { parseToolArgs } from "../tool-args.ts";
+import { streamSse, apiUrl } from "../transport.ts";
+import type {
+  ChatMessage,
+  Effort,
+  FinishReason,
+  Provider,
+  ProviderChunk,
+  StreamOptions,
+  ToolCallDelta,
+  ToolChoice,
+  ToolDefinition,
+} from "../types.ts";
+
+export interface GeminiConfig {
+  apiKey: string;
+  model: string;
+  /** Any endpoint speaking the Generative Language REST dialect — a proxy or
+   *  gateway. Defaults to the Generative Language API.
+   *
+   *  Not Vertex: it serves `/v1/projects/…/locations/…/publishers/google/models`
+   *  and authenticates with a Bearer token, and both the path and the
+   *  `x-goog-api-key` header are fixed below. Vertex would be its own adapter. */
+  baseUrl?: string;
+  /** Names the provider in errors and logs. */
+  id?: string;
+  /** Bound default; a per-call `effort` overrides it. */
+  effort?: Effort;
+  maxTokens?: number;
+  fetchImpl?: typeof fetch;
+  headers?: Record<string, string>;
+}
+
+const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com";
+
+/**
+ * Gemini 3's thinking dial. `none` is MINIMAL rather than a 0 budget: the Pro
+ * models reject a hard 0, so the only way to say "think as little as possible"
+ * without a 400 is the lowest level.
+ *
+ * Sent as the REST enum NAMES. The SDK's `ThinkingLevel` members serialize to
+ * exactly these strings, so nothing is lost by writing them out.
+ */
+const THINKING_LEVEL: Record<Effort, string> = {
+  none: "MINIMAL",
+  low: "LOW",
+  medium: "MEDIUM",
+  high: "HIGH",
+  max: "HIGH",
+};
+
+/** A turn in Gemini's history. `model` is its word for the assistant. */
+export interface GeminiContent {
+  role: "user" | "model";
+  parts: unknown[];
+}
+
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Tool-call arguments as the OBJECT Gemini's `functionCall.args` requires.
+ *
+ * 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
+ * double-escaped argument string is salvaged on replay rather than degraded to
+ * `{}`.
+ */
+function parseArgs(json: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(json);
+    if (!isJsonObject(parsed)) return { value: parsed };
+  } catch {
+    // Unparseable — the salvage below is the whole point.
+  }
+  return parseToolArgs(json);
+}
+
+/** Same rule for a tool RESULT, which `functionResponse.response` also requires
+ *  as an object. Plain text (the common case) rides under `output`. */
+function toResponseObject(content: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(content);
+    return isJsonObject(parsed) ? parsed : { output: parsed };
+  } catch {
+    return { output: content };
+  }
+}
+
+/**
+ * Our messages → Gemini contents.
+ *
+ * Three shape differences the rest of the adapter must not have to know about:
+ * system text is lifted out and merged into ONE instruction (Gemini takes a
+ * single one, not a role in the turn list); assistant turns are role `model`
+ * 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.
+ */
+export function toGeminiContents(messages: readonly ChatMessage[]): {
+  system?: string;
+  contents: GeminiContent[];
+} {
+  let system = "";
+  const contents: GeminiContent[] = [];
+
+  for (const message of messages) {
+    switch (message.role) {
+      case "system":
+        system = system ? `${system}\n\n${message.content}` : message.content;
+        break;
+
+      case "user":
+        contents.push({
+          role: "user",
+          parts:
+            typeof message.content === "string"
+              ? [{ text: message.content }]
+              : message.content.map((part) =>
+                  part.type === "text"
+                    ? { text: part.text }
+                    : { inlineData: { mimeType: part.mimeType, data: part.data } },
+                ),
+        });
+        break;
+
+      case "assistant": {
+        const parts: unknown[] = [];
+        if (message.content) parts.push({ text: message.content });
+        for (const call of message.toolCalls ?? []) {
+          parts.push({
+            functionCall: { id: call.id, name: call.name, args: parseArgs(call.arguments) },
+            // Replayed verbatim: this is the model's own reasoning token, and
+            // without it the next turn starts from a chain of thought that
+            // no longer includes the call it just made.
+            ...(call.thoughtSignature ? { thoughtSignature: call.thoughtSignature } : {}),
+          });
+        }
+        // An assistant turn with neither text nor calls has no representation
+        // here, and an empty `parts` is a 400.
+        if (parts.length > 0) contents.push({ role: "model", parts });
+        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 },
+            })),
+          ],
+        });
+        break;
+    }
+  }
+
+  return { ...(system ? { system } : {}), contents };
+}
+
+/**
+ * `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 —
+ * the pin is the allow-list, not the mode.
+ */
+function toToolConfig(choice: ToolChoice | undefined): unknown {
+  if (choice === undefined || choice === "auto") return undefined;
+  if (choice === "none") return { functionCallingConfig: { mode: "NONE" } };
+  if (choice === "required") return { functionCallingConfig: { mode: "ANY" } };
+  return { functionCallingConfig: { mode: "ANY", allowedFunctionNames: [choice.name] } };
+}
+
+function mapFinishReason(reason: string): FinishReason {
+  switch (reason) {
+    case "MAX_TOKENS":
+      return "length";
+    case "SAFETY":
+    case "PROHIBITED_CONTENT":
+      return "content_filter";
+    default:
+      return "stop";
+  }
+}
+
+interface GeminiPart {
+  text?: string;
+  /** Marks the parts that are the model's reasoning. Absent on the answer. */
+  thought?: boolean;
+  thoughtSignature?: string;
+  functionCall?: { id?: string; name?: string; args?: Record<string, unknown> };
+}
+
+/** Google's `google.rpc.Status`: an HTTP `code`, the canonical `status` name,
+ *  and `details` — which is where RetryInfo's `retryDelay` rides. */
+interface GeminiStatus {
+  code?: number;
+  message?: string;
+  status?: string;
+  details?: unknown;
+}
+
+interface GeminiResponse {
+  candidates?: {
+    content?: { parts?: GeminiPart[] };
+    finishReason?: string;
+  }[];
+  usageMetadata?: {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    thoughtsTokenCount?: number;
+    cachedContentTokenCount?: number;
+  };
+  /** Present only on the in-band failure below — never on a real candidate. */
+  error?: GeminiStatus;
+}
+
+export function createGeminiProvider(config: GeminiConfig): Provider {
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+  const id = config.id ?? "gemini";
+
+  return {
+    id,
+    model: config.model,
+
+    async *createStream(
+      messages: ChatMessage[],
+      tools: ToolDefinition[],
+      opts: StreamOptions = {},
+    ): AsyncIterable<ProviderChunk> {
+      const effort = opts.effort ?? config.effort;
+      const maxTokens = opts.maxTokens ?? config.maxTokens;
+      const { system, contents } = toGeminiContents(messages);
+
+      const generationConfig: Record<string, unknown> = {};
+      if (maxTokens !== undefined) generationConfig.maxOutputTokens = maxTokens;
+      if (opts.temperature !== undefined) generationConfig.temperature = opts.temperature;
+      // No effort means the model's own dynamic thinking. Sending MINIMAL 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] };
+      if (opts.json) {
+        generationConfig.responseMimeType = "application/json";
+        // `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;
+      }
+
+      const request: Record<string, unknown> = { contents, generationConfig };
+      // A Content, not the bare string the SDK accepts — REST rejects a string.
+      if (system) request.systemInstruction = { parts: [{ text: system }] };
+      if (tools.length > 0) {
+        request.tools = [
+          {
+            functionDeclarations: tools.map((tool) => ({
+              name: tool.name,
+              description: tool.description,
+              // Same rule as the response schema: `parameters` is the trimmed
+              // dialect, `parametersJsonSchema` is the schema we actually wrote.
+              parametersJsonSchema: tool.inputSchema,
+            })),
+          },
+        ];
+        // Pointless without declarations, and Gemini 400s on a tool config that
+        // names a function it was never given.
+        const toolConfig = toToolConfig(opts.toolChoice);
+        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.
+      let sawFunctionCalls = false;
+      let callIndex = 0;
+
+      for await (const data of streamSse({
+        // Without `?alt=sse` the response is one long JSON array that only
+        // parses once complete, which is not a stream.
+        url: apiUrl(baseUrl, `/v1beta/models/${model}:streamGenerateContent?alt=sse`),
+        headers: { "x-goog-api-key": config.apiKey, ...config.headers },
+        body: request,
+        provider: id,
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
+      })) {
+        let chunk: GeminiResponse;
+        try {
+          chunk = JSON.parse(data) as GeminiResponse;
+        } catch {
+          continue;
+        }
+
+        // `?alt=sse` commits to 200 the moment the headers go out, so a
+        // throttle or an overload landing after that arrives here as a
+        // google.rpc.Status in the body rather than as a status line.
+        if (chunk.error) throw streamError(id, chunk.error);
+
+        if (chunk.usageMetadata) {
+          const usage = chunk.usageMetadata;
+          yield {
+            type: "usage",
+            usage: {
+              inputTokens: usage.promptTokenCount ?? 0,
+              // Thoughts bill as OUTPUT, and Gemini reports them OUTSIDE
+              // candidatesTokenCount — leaving them out undercounts a thinking
+              // turn by most of what it cost.
+              outputTokens: (usage.candidatesTokenCount ?? 0) + (usage.thoughtsTokenCount ?? 0),
+              cachedInputTokens: usage.cachedContentTokenCount ?? 0,
+            },
+          };
+        }
+
+        const candidate = chunk.candidates?.[0];
+        if (!candidate) continue;
+
+        // One chunk can carry several parts of each kind. They are coalesced
+        // per kind so the seam sees one reasoning delta and one content delta
+        // per chunk, in that order, rather than interleaved fragments.
+        let reasoning = "";
+        let content = "";
+        const toolCalls: ToolCallDelta[] = [];
+        for (const part of candidate.content?.parts ?? []) {
+          if (part.text) {
+            if (part.thought) reasoning += part.text;
+            else content += part.text;
+            continue;
+          }
+          const call = part.functionCall;
+          if (!call) continue;
+          const index = callIndex++;
+          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 } : {}),
+            // Whole and already assembled — unlike the OpenAI shape, Gemini
+            // never fragments an argument object across chunks.
+            arguments: JSON.stringify(call.args ?? {}),
+            ...(part.thoughtSignature ? { thoughtSignature: part.thoughtSignature } : {}),
+          });
+        }
+
+        if (reasoning) yield { type: "delta", reasoning };
+        if (content) yield { type: "delta", content };
+        if (toolCalls.length > 0) {
+          sawFunctionCalls = true;
+          yield { type: "delta", toolCalls };
+        }
+
+        if (candidate.finishReason) {
+          yield {
+            type: "finish",
+            // A turn that called tools finishes as tool_calls whatever the
+            // candidate says — Gemini routinely reports STOP there, and a
+            // caller reading that as "done" drops the tool round entirely.
+            finishReason: sawFunctionCalls ? "tool_calls" : mapFinishReason(candidate.finishReason),
+          };
+        }
+      }
+    },
+  };
+}

package/src/providers/openai.ts

@@ -3,6 +3,7 @@
 // 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 { streamError } from "../errors.ts";
 import { streamSse, apiUrl } from "../transport.ts";
 import type {
   ChatMessage,
@@ -21,9 +22,22 @@ export interface OpenAIConfig {
   model: string;
   /** Any OpenAI-compatible endpoint. Defaults to OpenAI itself. */
   baseUrl?: string;
-  /** Names the provider in errors and logs — "openrouter", "deepseek", … */
+  /** Names the provider in errors and logs — "openrouter", "deepseek", … It
+   *  also picks the effort dialect below, unless `effortDialect` overrides. */
   id?: string;
   effort?: Effort;
+  /**
+   * Which spelling of "think this hard" this endpoint accepts. Inferred from
+   * `id`; set it when the gateway is not named after its dialect, or to `off`
+   * for one that rejects the field outright.
+   */
+  effortDialect?: EffortDialect;
+  /**
+   * `schema` sends a `json_schema` response format, `object` plain JSON mode.
+   * Defaults to `schema` for OpenAI itself and `object` everywhere else, which
+   * is the only setting every gateway accepts.
+   */
+  jsonMode?: "schema" | "object";
   maxTokens?: number;
   fetchImpl?: typeof fetch;
   headers?: Record<string, string>;
@@ -39,6 +53,64 @@ export interface OpenAIConfig {
 
 const DEFAULT_BASE_URL = "https://api.openai.com";
 
+/** 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";
+
+/**
+ * Effort → the request fields THIS endpoint accepts.
+ *
+ * One knob, three incompatible spellings, and the differences are not cosmetic:
+ *
+ * - **OpenRouter has no off switch.** `reasoning.enabled: false` is refused by
+ *   models that always think — GLM 5.3 Flash answers `400 "Reasoning is
+ *   mandatory for this endpoint and cannot be disabled."` — so `none` is
+ *   floored at `low` rather than sent. Named rather than omitted, because
+ *   letting the endpoint pick leaves cost and latency unpinned on exactly the
+ *   tasks that asked for neither. Measured against the live endpoint, and it
+ *   cost one app its onboarding read before it was.
+ * - **DeepSeek V4 defaults thinking ON**, so `none` has to be an explicit
+ *   refusal. That is the case proving OpenRouter's floor is a constraint and
+ *   not a preference for always thinking.
+ * - **OpenAI** takes `reasoning_effort` and nothing at all for `none`.
+ *
+ * An absent effort sends nothing on every dialect: the seam's rule is that a
+ * knob the caller never touched is a knob the provider still owns.
+ */
+export function effortParams(
+  dialect: EffortDialect,
+  effort: Effort | undefined,
+): Record<string, unknown> {
+  if (!effort) return {};
+  const level = effort === "max" ? "high" : effort === "none" ? null : effort;
+  switch (dialect) {
+    case "deepseek":
+      if (level === null) return { thinking: { type: "disabled" } };
+      // A graded level rides only when it asks for LESS. DeepSeek auto-bumps a
+      // complex agent or tool request past its own default, and naming the top
+      // tier here caps exactly the turns that most need the bump — so `high`
+      // and `max` say "on" and leave the ceiling where DeepSeek puts it, while
+      // `low` and `medium` mean what they say.
+      return level === "high"
+        ? { thinking: { type: "enabled" } }
+        : { thinking: { type: "enabled" }, reasoning_effort: level };
+    case "openrouter":
+      return { reasoning: { effort: level ?? "low" } };
+    case "openai":
+      return level === null ? {} : { reasoning_effort: level };
+    case "off":
+      return {};
+  }
+}
+
+/** Gateways named after their dialect get it for free; everything else keeps
+ *  the dialect this adapter is named for. */
+function dialectFor(id: string): EffortDialect {
+  if (id === "openrouter") return "openrouter";
+  if (id === "deepseek") return "deepseek";
+  return "openai";
+}
+
 function mapFinishReason(reason: string | null | undefined): FinishReason | undefined {
   switch (reason) {
     case "stop":
@@ -71,33 +143,62 @@ function partsToOpenAI(content: string | ContentPart[]): unknown {
  * first (`stripReasoning`); the two cannot be mixed.
  */
 export function toOpenAIMessages(messages: readonly ChatMessage[]): unknown[] {
-  return messages.map((message) => {
+  const out: unknown[] = [];
+  for (const message of messages) {
     switch (message.role) {
       case "system":
-        return { role: "system", content: message.content };
+        out.push({ role: "system", content: message.content });
+        break;
+
       case "user":
-        return { role: "user", content: partsToOpenAI(message.content) };
+        out.push({ role: "user", content: partsToOpenAI(message.content) });
+        break;
+
       case "tool":
-        return { role: "tool", tool_call_id: message.toolCallId, content: message.content };
+        out.push({ role: "tool", tool_call_id: message.toolCallId, content: message.content });
+        // This dialect has no image slot on a tool message — a `tool` role takes
+        // text and nothing else. A screenshot a tool hands back therefore
+        // follows as its own user message, which is the only way the model ever
+        // sees it. Dropped instead, the turn reads as a tool that returned
+        // words about a picture nobody was shown.
+        if (message.images?.length) {
+          out.push({
+            role: "user",
+            content: message.images.map((image) => ({
+              type: "image_url",
+              image_url: { url: toDataUri(image) },
+            })),
+          });
+        }
+        break;
+
       case "assistant": {
-        const out: Record<string, unknown> = {
+        const assistant: Record<string, unknown> = {
           role: "assistant",
           // Nullable content beside tool_calls is what this shape expects, but
           // several gateways reject a bare null — "" satisfies both.
           content: message.content || "",
         };
-        if (message.reasoning) out.reasoning_content = message.reasoning;
+        if (message.reasoning) assistant.reasoning_content = message.reasoning;
+        // Verbatim, under the name the gateway gave it. Reshaped or dropped, the
+        // model loses its own record of how it reached the tool round it is
+        // being asked to continue.
+        if (message.reasoningDetails?.length) {
+          assistant.reasoning_details = message.reasoningDetails;
+        }
         if (message.toolCalls?.length) {
-          out.tool_calls = message.toolCalls.map((call) => ({
+          assistant.tool_calls = message.toolCalls.map((call) => ({
             id: call.id,
             type: "function",
             function: { name: call.name, arguments: call.arguments },
           }));
         }
-        return out;
+        out.push(assistant);
+        break;
       }
     }
-  });
+  }
+  return out;
 }
 
 interface OpenAIChunk {
@@ -106,6 +207,8 @@ interface OpenAIChunk {
       content?: string | null;
       reasoning_content?: string | null;
       reasoning?: string | null;
+      /** OpenRouter's normalized reasoning payload, on the final delta. */
+      reasoning_details?: unknown[];
       tool_calls?: {
         index?: number;
         id?: string;
@@ -118,7 +221,13 @@ interface OpenAIChunk {
     prompt_tokens?: number;
     completion_tokens?: number;
     prompt_tokens_details?: { cached_tokens?: number };
+    /** DeepSeek's native API reports the cache-hit count here instead of in
+     *  `prompt_tokens_details`, and it is absent from every OpenAI SDK type. */
+    prompt_cache_hit_tokens?: number;
   } | null;
+  /** 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 };
 }
 
 export function createOpenAIProvider(config: OpenAIConfig): Provider {
@@ -147,7 +256,7 @@ 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 (effort && effort !== "none") request.reasoning_effort = effort;
+      Object.assign(request, effortParams(config.effortDialect ?? dialectFor(id), effort));
       if (tools.length > 0) {
         request.tools = tools.map((tool) => ({
           type: "function",
@@ -165,10 +274,19 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
             : { type: "function", function: { name: opts.toolChoice.name } };
       }
       if (opts.json) {
-        request.response_format = {
-          type: "json_schema",
-          json_schema: { name: opts.json.name, schema: opts.json.schema, strict: true },
-        };
+        request.response_format =
+          (config.jsonMode ?? (id === "openai" ? "schema" : "object")) === "schema"
+            ? {
+                type: "json_schema",
+                json_schema: { name: opts.json.name, schema: opts.json.schema, strict: true },
+              }
+            : // Everything else gets plain JSON mode. Schema ENFORCEMENT is
+              // OpenAI's; the gateways and the vendors behind them offer JSON
+              // mode at best, and several answer a flat 400 to a `json_schema`
+              // block. The seam's rule makes this safe either way: a provider's
+              // "guaranteed" JSON is not one, so the caller validates
+              // regardless — this only decides whether the request is accepted.
+              { type: "json_object" };
       }
       if (config.providerOrder?.length) {
         request.provider = { order: config.providerOrder, allow_fallbacks: true };
@@ -189,10 +307,25 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
           continue;
         }
 
+        // A failure the backend reports after its headers went out. The
+        // gateways speaking this dialect — OpenRouter above all — report a
+        // throttle or an upstream outage this way rather than as a status
+        // line, and a frame carrying `error` carries no choices: unread, it
+        // falls through both branches below and the turn ends as a successful
+        // zero-token completion nobody retries.
+        if (chunk.error) throw streamError(id, chunk.error);
+
         // A usage-only frame carries no choices — this shape sends it last.
         if (chunk.usage) {
           const input = chunk.usage.prompt_tokens ?? 0;
-          const cached = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
+          // Two spellings for the same subset. DeepSeek's native endpoint uses
+          // its own field, and reading only the standard one bills every cached
+          // token at the full input rate — on an agent loop, where the re-sent
+          // prefix is overwhelmingly hits, that overstates a run by up to 10×.
+          const cached =
+            chunk.usage.prompt_tokens_details?.cached_tokens ??
+            chunk.usage.prompt_cache_hit_tokens ??
+            0;
           yield {
             type: "usage",
             usage: {
@@ -223,6 +356,10 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
             out.reasoning = reasoning;
             has = true;
           }
+          if (delta.reasoning_details?.length) {
+            out.reasoningDetails = delta.reasoning_details;
+            has = true;
+          }
           if (delta.tool_calls?.length) {
             out.toolCalls = delta.tool_calls.map((call, position) => ({
               // Some gateways omit `index` entirely on single-tool turns.