@providerkit/core 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@providerkit/core",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -23,6 +23,9 @@
     "LICENSE"
   ],
   "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/errors.ts

@@ -325,7 +325,10 @@ const RATE_PATTERNS: readonly RegExp[] = [
 const OVERLOAD_PATTERNS: readonly RegExp[] = [
   /overloaded|overloaded_error/i,
   /\bunavailable\b|UNAVAILABLE/,
-  /internal error|INTERNAL/,
+  /internal error/i,
+  // Google's status enum, which is upper-case by contract — kept exact so it
+  // does not swallow the word in ordinary prose.
+  /\bINTERNAL\b/,
   /\bcapacity\b/i,
   /"code"\s*:\s*5\d\d/,
 ];
@@ -356,6 +359,15 @@ export function classifyHttp(status: number | undefined, body: string): ErrorKin
 }
 
 export function classify(err: unknown, status?: number, body?: string): ErrorKind {
+  // An error this package already classified knows its own kind, and nothing is
+  // learned by deriving it a second time from a status and a body it never had.
+  //
+  // This is not a shortcut, it is a correctness fix. The watchdog's own idle
+  // timeout is a ProviderError carrying kind "timeout" and no HTTP status, so
+  // re-deriving it landed on "unknown" — not transient, therefore never
+  // retried, which is the exact opposite of the reason the watchdog exists
+  // (invariant 2). A wedged stream aborted at 60s and then failed for good.
+  if (err instanceof ProviderError) return err.kind;
   if (isAbort(err)) return "aborted";
   if (isTransportFailure(err)) return "network";
 
@@ -381,7 +393,9 @@ export function classify(err: unknown, status?: number, body?: string): ErrorKin
   if (matches(CONTENT_PATTERNS, text)) return "content";
   // 529 is Anthropic's own "overloaded". 409 is how several gateways say
   // "the model is still loading" — both are worth another attempt.
-  if (code === 529 || code === 409) return "overload";
+  // 425 Too Early: the upstream is asking us to replay, not telling us we were
+  // wrong. Left as a plain 4xx it reads as `invalid` and is never retried.
+  if (code === 529 || code === 409 || code === 425) return "overload";
   if (code !== undefined && code >= 500) return "overload";
   if (matches(RATE_PATTERNS, text)) return "rate";
   if (matches(OVERLOAD_PATTERNS, text)) return "overload";

package/src/providers/anthropic.ts

@@ -3,6 +3,7 @@ import { streamError } from "../errors.ts";
 import { parseToolArgs } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
 import type {
+  JsonOutput,
   ChatMessage,
   ContentPart,
   Effort,
@@ -87,8 +88,47 @@ function partsToAnthropic(content: string | ContentPart[]): unknown[] {
  * turns carrying `tool_result` blocks — not as a role of their own. Consecutive
  * tool results are merged into one user turn, which the API requires.
  */
+/**
+ * The system prompt as ONE cached block.
+ *
+ * Anthropic's prompt caching is opt-in PER BLOCK — a plain string system prompt
+ * is never cached, however many times it is re-sent. An agent loop re-sends this
+ * every single turn, and it is the largest stable prefix in the request, so
+ * without the breakpoint the whole thing bills at the full input rate on every
+ * round instead of a tenth of it on all but the first.
+ *
+ * Unconditional. Below the model's minimum cacheable length the field is
+ * ignored rather than rejected, and above it the one-time 1.25× write is repaid
+ * by the second turn — which, in the loop this package sits under, always comes.
+ */
+function systemBlocks(text: string): unknown[] | undefined {
+  return text ? [{ type: "text", text, cache_control: { type: "ephemeral" } }] : undefined;
+}
+
+/**
+ * The schema, as an extra system block — Anthropic has no native schema mode,
+ * and the seam promises that a provider without one gets the schema in the
+ * prompt instead. Without this an `opts.json` request went out carrying
+ * nothing at all: the model answered in prose, the caller's `JSON.parse` threw,
+ * and the turn failed on the happy path where no retry looks.
+ *
+ * It rides AFTER the cached block, and that order is load-bearing. A cache
+ * breakpoint caches everything before it, so folding a per-call schema into the
+ * cached block would change the cached prefix on every turn whose schema
+ * differs and throw the whole system prompt's cache away — paying for the
+ * schema with the most expensive thing in an agent loop.
+ */
+function jsonBlock(json: JsonOutput): unknown {
+  return {
+    type: "text",
+    text:
+      "Respond with a single JSON object matching this schema. No prose, no code fence:\n" +
+      JSON.stringify(json.schema),
+  };
+}
+
 export function toAnthropicMessages(messages: readonly ChatMessage[]): {
-  system?: string;
+  system?: unknown[];
   messages: unknown[];
 } {
   const system = messages
@@ -141,7 +181,8 @@ export function toAnthropicMessages(messages: readonly ChatMessage[]): {
     if (blocks.length > 0) pushBlocks("assistant", blocks);
   }
 
-  return { ...(system ? { system } : {}), messages: out };
+  const blocks = systemBlocks(system);
+  return { ...(blocks ? { system: blocks } : {}), messages: out };
 }
 
 interface AnthropicEvent {
@@ -191,8 +232,11 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
         messages: body,
         stream: true,
       };
-      if (system) request.system = system;
+      const systemBody = opts.json ? [...(system ?? []), jsonBlock(opts.json)] : system;
+      if (systemBody?.length) request.system = systemBody;
       if (opts.temperature !== undefined) request.temperature = opts.temperature;
+      if (opts.topP !== undefined) request.top_p = opts.topP;
+      if (opts.stopSequences?.length) request.stop_sequences = opts.stopSequences;
       if (tools.length > 0) {
         request.tools = tools.map((tool) => ({
           name: tool.name,
@@ -213,6 +257,7 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
         request.thinking = { type: "enabled", budget_tokens: budget };
         // Thinking and sampling are mutually exclusive on this shape.
         delete request.temperature;
+        delete request.top_p;
       }
 
       // Anthropic reports cache reads and writes as fields of their OWN,

package/src/providers/gemini.ts

@@ -252,6 +252,8 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
       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
       // would switch that off for a caller who never asked, which is the whole
       // reason the seam treats an absent effort as "never sent".

package/src/providers/openai.ts

@@ -16,15 +16,29 @@ import type {
   ToolDefinition,
 } from "../types.ts";
 import { toDataUri } from "../types.ts";
+import { isStrictSchema } from "../schema.ts";
 
 export interface OpenAIConfig {
   apiKey: string;
   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>;
@@ -40,6 +54,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":
@@ -72,33 +144,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 {
@@ -107,6 +208,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;
@@ -119,6 +222,9 @@ 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. */
@@ -151,7 +257,9 @@ 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;
+      if (opts.topP !== undefined) request.top_p = opts.topP;
+      if (opts.stopSequences?.length) request.stop = opts.stopSequences;
+      Object.assign(request, effortParams(config.effortDialect ?? dialectFor(id), effort));
       if (tools.length > 0) {
         request.tools = tools.map((tool) => ({
           type: "function",
@@ -169,10 +277,23 @@ 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: opts.json.strict ?? isStrictSchema(opts.json.schema),
+                },
+              }
+            : // 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 };
@@ -204,7 +325,14 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
         // 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: {
@@ -235,6 +363,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.

package/src/providers/responses.ts

@@ -24,6 +24,7 @@ import type {
   ToolDefinition,
 } from "../types.ts";
 import { toDataUri } from "../types.ts";
+import { isStrictSchema } from "../schema.ts";
 
 export interface ResponsesConfig {
   apiKey: string;
@@ -250,6 +251,9 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
       const maxTokens = opts.maxTokens ?? config.maxTokens;
       if (maxTokens !== undefined) request.max_output_tokens = maxTokens;
       if (opts.temperature !== undefined) request.temperature = opts.temperature;
+      if (opts.topP !== undefined) request.top_p = opts.topP;
+      // No stop sequences on this shape — it has no equivalent field, and
+      // inventing one would 400 the request rather than shorten the answer.
       if (effort && effort !== "none") {
         // `summary` is what switches the reasoning stream ON. Without it this
         // shape emits no reasoning_summary_text events at all, and a caller
@@ -279,7 +283,7 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
             type: "json_schema",
             name: opts.json.name,
             schema: opts.json.schema,
-            strict: true,
+            strict: opts.json.strict ?? isStrictSchema(opts.json.schema),
           },
         };
       }

package/src/schema.ts

@@ -65,3 +65,44 @@ export function clampToSchema(value: unknown, node: unknown): unknown {
 
   return value;
 }
+
+/**
+ * Whether OpenAI's `strict` schema mode will accept this schema.
+ *
+ * Strict is the only JSON mode that actually guarantees the shape, so it is
+ * worth having — but it demands more than JSON Schema does: every property an
+ * object lists must ALSO be required, and every object must close itself with
+ * `additionalProperties: false`, all the way down. A schema with one optional
+ * field is not "mostly strict"; it is a flat 400 naming a nested path rather
+ * than the rule it broke.
+ *
+ * That trap is the reason this exists. An agent's response schema grows
+ * optional fields naturally — a `data` block only some flows fill, the fields
+ * one step collects — and a caller who adds one wants their answer, not a
+ * lecture about a mode they never asked for. So the OpenAI-shape adapters ask
+ * this and drop to plain (unenforced) schema mode instead of failing the turn.
+ *
+ * Anything it cannot verify — a `$ref`, a composed `allOf` — answers false:
+ * the cost of guessing wrong that way is unenforced output, and the cost of
+ * guessing wrong the other way is a request that cannot succeed at all.
+ */
+export function isStrictSchema(node: unknown): boolean {
+  if (!node || typeof node !== "object") return false;
+  const schema = node as SchemaNode;
+
+  if (schema.$ref !== undefined || schema.allOf !== undefined) return false;
+
+  const union = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(union)) return union.every(isStrictSchema);
+
+  // A leaf (string, number, boolean, enum) carries no strict obligations.
+  if (schema.type === "array") return schema.items === undefined || isStrictSchema(schema.items);
+  if (schema.properties === undefined) return true;
+
+  if (schema.additionalProperties !== false) return false;
+  const properties = schema.properties as Record<string, unknown>;
+  const required = new Set(Array.isArray(schema.required) ? (schema.required as string[]) : []);
+  return Object.entries(properties).every(
+    ([key, value]) => required.has(key) && isStrictSchema(value),
+  );
+}

package/src/types.ts

@@ -71,6 +71,16 @@ export type ChatMessage =
        * unsupported. `stripReasoning` below is that rule, once.
        */
       reasoning?: string;
+      /**
+       * OpenRouter's normalized reasoning payload, arriving on the stream and
+       * riding back UNMODIFIED on the next turn's assistant message.
+       *
+       * Opaque on purpose — the same contract as Gemini's `thoughtSignature`,
+       * and for the same reason: it is the provider's own record of how it got
+       * here, and reading, reshaping or dropping it costs the model its
+       * continuity across a tool round. Absent on every other dialect.
+       */
+      reasoningDetails?: unknown[];
       toolCalls?: ToolCall[];
     }
   | {
@@ -131,6 +141,9 @@ export interface ProviderChunk {
   type: "delta" | "usage" | "finish";
   content?: string;
   reasoning?: string;
+  /** OpenRouter's normalized reasoning payload — hand it back on the next
+   *  turn's assistant message verbatim. See ChatMessage.reasoningDetails. */
+  reasoningDetails?: unknown[];
   toolCalls?: ToolCallDelta[];
   usage?: TokenUsage;
   finishReason?: FinishReason;
@@ -148,6 +161,13 @@ export type ToolChoice = "auto" | "none" | "required" | { name: string };
 export interface JsonOutput {
   name: string;
   schema: JsonObjectSchema;
+  /**
+   * Force OpenAI's strict schema mode on or off. Left unset, the adapters ask
+   * `isStrictSchema` and enforce whenever the schema actually qualifies —
+   * which is what keeps an optional field from turning a working call into a
+   * 400. Set it only to overrule that reading.
+   */
+  strict?: boolean;
 }
 
 export interface StreamOptions {
@@ -159,6 +179,20 @@ export interface StreamOptions {
    *  silently truncated mid-argument. */
   maxTokens?: number;
   temperature?: number;
+  /**
+   * Nucleus sampling. Set this OR `temperature`, not both — the vendors all
+   * document them as alternatives and some reject the pair outright.
+   */
+  topP?: number;
+  /**
+   * Strings that end the turn when generated. The only four-shape sampling
+   * field beyond these two; `top_k`, `metadata` and the rest are one vendor's
+   * each and stay off the seam, where a caller reaching for them is asking for
+   * that vendor rather than for a provider.
+   *
+   * Not sent on the Responses shape, which has no equivalent.
+   */
+  stopSequences?: string[];
   signal?: AbortSignal;
   toolChoice?: ToolChoice;
   json?: JsonOutput;
@@ -177,6 +211,8 @@ export interface Provider {
 export interface Completion {
   text: string;
   reasoning: string;
+  /** Present only where the provider sent one. See ChatMessage.reasoningDetails. */
+  reasoningDetails?: unknown[];
   usage: TokenUsage;
   finishReason: FinishReason | null;
   model: string;
@@ -190,19 +226,32 @@ export async function drainStream(
 ): Promise<Completion> {
   let text = "";
   let reasoning = "";
+  // Not concatenated: this half of the record is a payload the provider owns,
+  // and it arrives whole on one delta rather than in fragments. Dropped here,
+  // a drained turn replays only half its own reasoning on the next round —
+  // which is the failure `reasoningDetails` exists to prevent.
+  let reasoningDetails: unknown[] | undefined;
   let usage: TokenUsage = EMPTY_USAGE;
   let finishReason: FinishReason | null = null;
   for await (const chunk of stream) {
     if (chunk.type === "delta") {
       if (chunk.content) text += chunk.content;
       if (chunk.reasoning) reasoning += chunk.reasoning;
+      if (chunk.reasoningDetails?.length) reasoningDetails = chunk.reasoningDetails;
     } else if (chunk.type === "usage" && chunk.usage) {
       usage = chunk.usage;
     } else if (chunk.type === "finish" && chunk.finishReason) {
       finishReason = chunk.finishReason;
     }
   }
-  return { text, reasoning, usage, finishReason, model };
+  return {
+    text,
+    reasoning,
+    ...(reasoningDetails ? { reasoningDetails } : {}),
+    usage,
+    finishReason,
+    model,
+  };
 }
 
 /**
@@ -219,8 +268,12 @@ export async function drainStream(
  */
 export function stripReasoning(messages: readonly ChatMessage[]): ChatMessage[] {
   return messages.map((message) => {
-    if (message.role !== "assistant" || message.reasoning === undefined) return message;
-    const { reasoning: _dropped, ...rest } = message;
+    if (message.role !== "assistant") return message;
+    if (message.reasoning === undefined && message.reasoningDetails === undefined) return message;
+    // Both halves go. `reasoningDetails` is the same chain of thought in the
+    // provider's own words, so leaving it behind carries into a thinking-off
+    // turn exactly what stripping `reasoning` was meant to keep out.
+    const { reasoning: _text, reasoningDetails: _payload, ...rest } = message;
     return rest;
   });
 }