@providerkit/core 0.12.2 → 0.13.0

package/src/providers/anthropic.ts

@@ -1,5 +1,5 @@
 // Anthropic-shape adapter — SSE from POST /v1/messages.
-import { streamError } from "../errors.ts";
+import { fileRefused, streamError } from "../errors.ts";
 import { schemaPrompt, toAnthropicToolSchema } from "../schema.ts";
 import { parseToolArgs } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
@@ -55,9 +55,10 @@ export interface AnthropicConfig extends ProviderFallbackConfig {
    *  where an absent field means the MODEL's default, not off — Z.ai's coding
    *  endpoint reads silence as thinking ON for reasoning-mandatory models like
    *  GLM 5.3 Flash (measured 2026-09-13: omit → thinking block; disabled →
-   *  none), and it accepts the marker natively. Native Anthropic has no such
-   *  marker and defaults to off when the field is absent, so leave this unset
-   *  there. */
+   *  none), and it accepts the marker natively. Ignored for a Claude id that
+   *  thinks adaptively (4.6 and later): each has its own spelling of none (see
+   *  `CLAUDE_THINKING`), and several reject this marker outright. Claude 4.5
+   *  and older accept it, and get it. */
   explicitNone?: boolean;
 }
 
@@ -67,9 +68,10 @@ const DEFAULT_VERSION = "2023-06-01";
 const DEFAULT_MAX_TOKENS = 8_192;
 
 /**
- * Thinking budgets, in output tokens. Thinking and the answer SHARE
- * `max_tokens`, so a budget is always left below the ceiling — a budget at or
- * above it leaves no room to answer, and the turn ends mid-thought.
+ * Thinking budgets, in output tokens, for extended thinking — Claude 4.5 and
+ * older, and every non-Claude endpoint on this wire. Thinking and the answer
+ * SHARE `max_tokens`, so a budget is always left below the ceiling — a budget
+ * at or above it leaves no room to answer, and the turn ends mid-thought.
  */
 const THINKING_BUDGET: Record<Exclude<Effort, "none">, number> = {
   low: 2_048,
@@ -78,6 +80,98 @@ const THINKING_BUDGET: Record<Exclude<Effort, "none">, number> = {
   max: 32_768,
 };
 
+/** How one Claude model that thinks adaptively takes `effort`. */
+interface ClaudeThinking {
+  /** How `effort: "none"` is said: nothing, an explicit off, or the lowest
+   *  effort where there is no off to ask for. */
+  none: "omit" | "disabled" | "low";
+  /** Whether a non-default temperature or top_p survives while thinking is off. */
+  sampling: boolean;
+}
+
+const ALWAYS_ON: ClaudeThinking = { none: "low", sampling: false };
+
+/**
+ * Claude models that take adaptive thinking, keyed by id. A graded effort is
+ * said the same way on all of them — `thinking: { type: "adaptive" }` plus
+ * `output_config.effort` — which every one accepts, and which the docs say to
+ * use wherever a model also takes `budget_tokens`. What differs is `none`,
+ * because what each model does when told nothing differs. Documented (Anthropic per-model table, read
+ * 2026-09-27: platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting);
+ * none of it was measured live.
+ *
+ * `sampling: false` marks the models where a non-default temperature, top_p or
+ * top_k is a 400 on every request, thinking or not. Documented on the same date
+ * (…/build-with-claude/thinking, "Sampling parameters").
+ */
+const CLAUDE_THINKING: ReadonlyMap<string, ClaudeThinking> = new Map([
+  // Always on: `enabled` and `disabled` are both 400s (Mythos Preview still
+  // takes `enabled`), so there is no off to ask for. `none` is the lowest
+  // effort rather than silence, because silence runs the model's own default —
+  // `high`, or `medium` on Opus 5.5 — which is the request `none` exists to
+  // refuse (invariant 12).
+  ["claude-fable-5-1", ALWAYS_ON],
+  ["claude-mythos-5-1", ALWAYS_ON],
+  ["claude-fable-5", ALWAYS_ON],
+  ["claude-mythos-5", ALWAYS_ON],
+  ["claude-mythos-preview", ALWAYS_ON],
+  ["claude-opus-5-5", ALWAYS_ON],
+  // On by default, and `disabled` is accepted at effort high or below. `none`
+  // still says `low`: with thinking disabled, Opus 5 occasionally writes a tool
+  // call into its visible text instead of a tool_use block, most often on
+  // tool-heavy work (documented, same page). That call never runs and nothing
+  // errors, so the turn reads as a clean answer — a failure on the happy path,
+  // in exactly the loop this package sits under. Anthropic's own advice is to
+  // keep thinking on and lower effort; at `low` the model can still skip
+  // thinking on a turn it judges simple.
+  ["claude-opus-5", ALWAYS_ON],
+  // On by default; `disabled` is accepted, with no such warning attached.
+  ["claude-sonnet-5", { none: "disabled", sampling: false }],
+  // Off by default, so saying nothing already is none.
+  ["claude-opus-4-8", { none: "omit", sampling: false }],
+  ["claude-opus-4-7", { none: "omit", sampling: false }],
+  // These still take `budget_tokens`, deprecated. Adaptive is the mode the docs
+  // say to use where both exist, and it drops extended mode's rule that the
+  // final assistant turn open with a thinking block — which this adapter,
+  // replaying no thinking, can never satisfy.
+  ["claude-opus-4-6", { none: "omit", sampling: true }],
+  ["claude-sonnet-4-6", { none: "omit", sampling: true }],
+]);
+
+/** Claude 4.5 and everything before it: extended thinking only (`adaptive` is
+ *  a 400), off by default. The budget dialect below was written for these. */
+const CLAUDE_EXTENDED_ONLY = /^claude-(3-|(opus|sonnet|haiku)-4(-[0-5])?$)/;
+
+/**
+ * The adaptive-thinking rule for a Claude id, or `undefined` for every id that
+ * keeps the budget dialect: Claude 4.5 and older, and every other vendor's
+ * model on this wire (their endpoints' dialects are their own).
+ *
+ * An id that starts with `claude-` but is in neither list is a Claude newer
+ * than this table, and it is treated as always on. Every Claude since Opus 4.7
+ * rejects `enabled`; the newest reject `disabled` too; and `output_config.effort`
+ * is accepted by every model that thinks adaptively. So an unknown id gets the
+ * one request none of them has refused, and no sampling fields, since every
+ * Claude since Opus 4.7 answers a non-default one with a 400. A model that
+ * turns out to differ will say so with a 400 of its own, and earn a row.
+ */
+function claudeThinking(model: string): ClaudeThinking | undefined {
+  if (!model.startsWith("claude-")) return undefined;
+  const family = model.replace(/-\d{8}$/, ""); // a dated snapshot is its family
+  if (CLAUDE_EXTENDED_ONLY.test(family)) return undefined;
+  return CLAUDE_THINKING.get(family) ?? ALWAYS_ON;
+}
+
+/** Whether a request continues a tool loop: its last assistant message made
+ *  tool calls, so the request carries their results inside the same turn. */
+function continuesToolLoop(messages: readonly ChatMessage[]): boolean {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role === "assistant") return (message.toolCalls?.length ?? 0) > 0;
+  }
+  return false;
+}
+
 function mapStopReason(reason: string | undefined): FinishReason | undefined {
   switch (reason) {
     case "end_turn":
@@ -94,16 +188,16 @@ function mapStopReason(reason: string | undefined): FinishReason | undefined {
   }
 }
 
-function partsToAnthropic(content: string | ContentPart[]): unknown[] {
+function partsToAnthropic(content: string | ContentPart[], provider: string): unknown[] {
   if (typeof content === "string") return [{ type: "text", text: content }];
-  return content.map((part) =>
-    part.type === "text"
-      ? { type: "text", text: part.text }
-      : {
-          type: "image",
-          source: { type: "base64", media_type: part.mimeType, data: part.data },
-        },
-  );
+  return content.map((part) => {
+    if (part.type === "text") return { type: "text", text: part.text };
+    if (part.type === "file") throw fileRefused(provider, "Anthropic", part);
+    return {
+      type: "image",
+      source: { type: "base64", media_type: part.mimeType, data: part.data },
+    };
+  });
 }
 
 /**
@@ -145,7 +239,10 @@ function jsonBlock(json: JsonOutput): unknown {
   return { type: "text", text: schemaPrompt(json.schema) };
 }
 
-export function toAnthropicMessages(messages: readonly ChatMessage[]): {
+export function toAnthropicMessages(
+  messages: readonly ChatMessage[],
+  provider = "anthropic",
+): {
   system?: unknown[];
   messages: unknown[];
 } {
@@ -164,7 +261,7 @@ export function toAnthropicMessages(messages: readonly ChatMessage[]): {
   for (const message of messages) {
     if (message.role === "system") continue;
     if (message.role === "user") {
-      pushBlocks("user", partsToAnthropic(message.content));
+      pushBlocks("user", partsToAnthropic(message.content, provider));
       continue;
     }
     if (message.role === "tool") {
@@ -243,8 +340,8 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
     ): AsyncIterable<ProviderChunk> {
       const model = opts.model ?? config.model;
       const maxTokens = opts.maxTokens ?? config.maxTokens ?? DEFAULT_MAX_TOKENS;
-      const effort = opts.effort ?? config.effort ?? "none";
-      const { system, messages: body } = toAnthropicMessages(messages);
+      const effort = opts.effort ?? config.effort;
+      const { system, messages: body } = toAnthropicMessages(messages, id);
 
       const request: Record<string, unknown> = {
         model,
@@ -272,15 +369,47 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
               ? { type: "any" }
               : { type: "tool", name: opts.toolChoice.name };
       }
-      if (effort !== "none") {
+      const claude = claudeThinking(model);
+      // Extended mode, which is all Claude 4.5 and older have, can't think on
+      // two kinds of request this adapter sends, so those run without thinking.
+      // Documented (Anthropic Thinking page, read 2026-09-27):
+      // - One that continues a tool loop. A thinking request's final assistant
+      //   turn must open with a thinking block, and this adapter sends none back
+      //   (see toAnthropicMessages). Turning thinking off mid-turn is documented
+      //   not to error, and the next user turn thinks again.
+      // - One whose tool choice forces a tool: `any` or `tool` "results in an
+      //   error because these options force tool use, which is incompatible with
+      //   manual extended thinking." The caller asked for the tool, so it wins.
+      // ponytail: every loop step after the first goes unthought on these
+      // models. The upgrade is replaying the signed thinking blocks.
+      const forcesTool = opts.toolChoice === "required" || typeof opts.toolChoice === "object";
+      const unthought =
+        !claude && model.startsWith("claude-") && (forcesTool || continuesToolLoop(messages));
+      if (claude) {
+        // An effort the caller never set sends nothing: the model keeps its own
+        // default, which on most of these is thinking ON.
+        if (effort === "none") {
+          if (claude.none === "disabled") request.thinking = { type: "disabled" };
+          if (claude.none === "low") request.output_config = { effort: "low" };
+        } else if (effort) {
+          request.thinking = { type: "adaptive" };
+          request.output_config = { effort };
+        }
+        const thinking = effort !== undefined && effort !== "none";
+        if (thinking || !claude.sampling) {
+          delete request.temperature;
+          delete request.top_p;
+        }
+      } else if (effort && effort !== "none" && !unthought) {
         const budget = Math.min(THINKING_BUDGET[effort], Math.floor(maxTokens * 0.8));
         request.thinking = { type: "enabled", budget_tokens: budget };
         // Thinking and sampling are mutually exclusive on this shape.
         delete request.temperature;
         delete request.top_p;
       } else if (config.explicitNone) {
-        // The one dialect where silence means the model default — which is ON
-        // for a reasoning-mandatory model — so "none" has to be said out loud.
+        // Z.ai's coding endpoint: silence means the model default — which is
+        // ON for a reasoning-mandatory model — so "none" has to be said out
+        // loud. An effort nobody set reads as none here, as it always has.
         request.thinking = { type: "disabled" };
       }
 

package/src/providers/gemini.ts

@@ -147,6 +147,8 @@ export function toGeminiContents(messages: readonly ChatMessage[]): {
         break;
 
       case "user":
+        // An image and a file ride the same way, as bytes and their media
+        // type. This is the one wire that takes a file.
         contents.push({
           role: "user",
           parts:

package/src/providers/openai.ts

@@ -3,7 +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 { fileRefused, streamError } from "../errors.ts";
 import { streamSse, apiUrl } from "../transport.ts";
 import { attributionHeaders } from "../attribution.ts";
 import type {
@@ -152,12 +152,46 @@ export function openRouterHostFor(baseUrl: string, model: string): string | unde
 export type EffortDialect = "openai" | "openrouter" | "deepseek" | "off";
 
 /**
- * OpenRouter model ids that refuse every explicit reasoning off and, on most
- * of the hosts that serve them, think when `reasoning` is omitted. `none` is
- * said to them as `low`. Add an id only after measuring both halves on it:
- * what omitting the field does, and what `low` does.
+ * How `none` is said on OpenRouter, per model id: the `reasoning.effort` that
+ * turns the model's thinking off, or the lowest measured one where every off
+ * is refused.
+ *
+ * An id that is not listed sends nothing, and that default is the point. An
+ * explicit off is a 400 on a model whose reasoning is mandatory: GLM 5.3 Flash
+ * and gpt-5-mini both answer "Reasoning is mandatory for this endpoint and
+ * cannot be disabled." So a universal off would break every call to one. An
+ * omitted field only costs reasoning tokens, and only on a model that thinks by
+ * default. So an id gets a row once it is measured both ways: with the field
+ * omitted, and with the spelling in its row.
+ *
+ * An adopter's matrix, 2026-09-27: one pinned host per model
+ * (`allow_fallbacks: false`), two runs per cell, reasoning tokens with the
+ * field omitted and with each of three offs (top-level `reasoning_effort:
+ * "none"`, `reasoning.effort: "none"`, `reasoning.enabled: false`).
+ *
+ * - GLM 5.3 Flash @Together: 516, and 2,000 (cut off at `max_tokens`), with
+ *   the field omitted. Every off was a 400. In the 2026-09-26 sweep (a
+ *   production classify body sent to each of 28 hosts alone), 18 hosts thought
+ *   with the field omitted (a 2026-09-14 reading, host unknown, saw no
+ *   thinking), and `low` gave 0 reasoning tokens on every host that answered
+ *   it but Sail Research (1) and Wafer (inverted: about 420 with `low`, 1
+ *   omitted).
+ * - gpt-5-mini @OpenAI: 320 and 320 with the field omitted, and every off was
+ *   a 400. A follow-up the same day, same host, two runs: `minimal` gave 0 and
+ *   0 (48 and 50 output tokens), `low` 64 and 64. So `minimal` is its floor.
+ *   Only this exact id: gpt-5 and gpt-5-nano were not measured.
+ * - MiMo v2.6 Flash @Xiaomi: 57 and 47 with the field omitted (103–151
+ *   @DeepInfra in the 2026-09-26 sweep), 0 with every off. Its row names
+ *   `none`, so the table varies one field.
+ * - Not listed, on purpose. DeepSeek V4 Flash @DeepInfra: 0 in every cell, and
+ *   the 2026-09-26 sweep saw it think at `low`. Gemini 2.5 Flash and Flash
+ *   Lite @AI Studio: 0 in every cell.
  */
-const OPENROUTER_REASONING_MANDATORY: ReadonlySet<string> = new Set(["z-ai/glm-5.3-flash"]);
+const OPENROUTER_NONE: ReadonlyMap<string, "low" | "minimal" | "none"> = new Map([
+  ["z-ai/glm-5.3-flash", "low"],
+  ["openai/gpt-5-mini", "minimal"],
+  ["xiaomi/mimo-v2.6-flash", "none"],
+]);
 
 /**
  * Effort → the request fields THIS endpoint accepts.
@@ -165,20 +199,14 @@ const OPENROUTER_REASONING_MANDATORY: ReadonlySet<string> = new Set(["z-ai/glm-5
  * One knob, three incompatible spellings, and the differences are not cosmetic:
  *
  * - **On OpenRouter, "do not think" has no spelling that works on every
- *   model.** GLM 5.3 Flash answers
- *   `400 "Reasoning is mandatory for this endpoint and cannot be disabled."`
- *   to `reasoning.effort: "none"` and to `reasoning.enabled: false` alike, and
- *   whether it thinks with the field omitted depends on the host. Sending a
- *   production classify body to each host alone on 2026-09-26, 18 of 28 hosts
- *   thought with the field omitted (a 2026-09-14 reading, host unknown, saw no
- *   thinking), while `reasoning.effort: "low"` gave 0 reasoning tokens on
- *   every host that answered it but Sail Research (1) and Wafer (inverted:
- *   about 420 with `low`, 1 omitted). So for the ids in
- *   `OPENROUTER_REASONING_MANDATORY`, `none` sends `low`. DeepSeek V4 Flash
- *   measured the reverse the same day (0 omitted, thinking at `low`), so every
- *   other model keeps the omitted field. 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).
+ *   model.** GLM 5.3 Flash and gpt-5-mini answer every explicit off with
+ *   `400 "Reasoning is mandatory for this endpoint and cannot be disabled."`,
+ *   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
+ *   `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
@@ -194,8 +222,8 @@ const OPENROUTER_REASONING_MANDATORY: ReadonlySet<string> = new Set(["z-ai/glm-5
  * An absent effort sends nothing on every dialect and for every model: the
  * seam's rule is that a knob the caller never touched is a knob the provider
  * still owns. On OpenRouter that makes `none` and "never asked" the same
- * request for every model outside `OPENROUTER_REASONING_MANDATORY`, and a
- * different one for the models in it.
+ * request for every model outside `OPENROUTER_NONE`, and a different one for
+ * the models in it.
  *
  * `model` is the id the request names. Without it, `none` on OpenRouter sends
  * nothing, as it always has.
@@ -219,20 +247,21 @@ export function effortParams(
         ? { thinking: { type: "enabled" } }
         : { thinking: { type: "enabled" }, reasoning_effort: level };
     case "openrouter":
-      // `none` is said per model (see above): the cheapest named level for a
-      // model that thinks when the field is omitted and refuses every explicit
-      // off, nothing for the rest. Naming a level RAISES it: the accepted
-      // values are low, high and max (`medium` and `xhigh` exist on the wire
-      // too). The refusal that once looked like "OpenRouter cannot be told not
-      // to think" was `reasoning.enabled: false` — never sent (pinned by the
-      // test below).
+      // `none` is said per model (see OPENROUTER_NONE): an explicit off where
+      // one was measured to work, the lowest measured level where every off is
+      // a 400, and nothing for a model nobody measured. Naming a level RAISES
+      // it: the accepted values are low, high and max (`medium`, `xhigh` and
+      // `minimal` exist on the wire too; `minimal` rides only as a row's none).
+      // The refusal that once looked like "OpenRouter cannot be told not to
+      // think" was `reasoning.enabled: false` — never sent (pinned by the test
+      // below).
       //
       // `max` rides verbatim here — the enum clamp below is DeepSeek/OpenAI's
       // shape (DeepSeek auto-bumps past its own top, OpenAI's top IS high);
       // OpenRouter takes `max` as named (measured live 2026-09-14).
       if (effort !== "none") return { reasoning: { effort } };
-      return model !== undefined && OPENROUTER_REASONING_MANDATORY.has(model)
-        ? { reasoning: { effort: "low" } }
+      return model !== undefined && OPENROUTER_NONE.has(model)
+        ? { reasoning: { effort: OPENROUTER_NONE.get(model) } }
         : {};
     case "openai":
       return { reasoning_effort: level ?? "none" };
@@ -265,13 +294,13 @@ function mapFinishReason(reason: string | null | undefined): FinishReason | unde
   }
 }
 
-function partsToOpenAI(content: string | ContentPart[]): unknown {
+function partsToOpenAI(content: string | ContentPart[], provider: string): unknown {
   if (typeof content === "string") return content;
-  return content.map((part) =>
-    part.type === "text"
-      ? { type: "text", text: part.text }
-      : { type: "image_url", image_url: { url: toDataUri(part) } },
-  );
+  return content.map((part) => {
+    if (part.type === "text") return { type: "text", text: part.text };
+    if (part.type === "file") throw fileRefused(provider, "OpenAI", part);
+    return { type: "image_url", image_url: { url: toDataUri(part) } };
+  });
 }
 
 /**
@@ -280,7 +309,7 @@ function partsToOpenAI(content: string | ContentPart[]): unknown {
  * made a tool call. A caller running a turn with thinking OFF must strip it
  * first (`stripReasoning`); the two cannot be mixed.
  */
-export function toOpenAIMessages(messages: readonly ChatMessage[]): unknown[] {
+export function toOpenAIMessages(messages: readonly ChatMessage[], provider = "openai"): unknown[] {
   const out: unknown[] = [];
   for (const message of messages) {
     switch (message.role) {
@@ -289,7 +318,7 @@ export function toOpenAIMessages(messages: readonly ChatMessage[]): unknown[] {
         break;
 
       case "user":
-        out.push({ role: "user", content: partsToOpenAI(message.content) });
+        out.push({ role: "user", content: partsToOpenAI(message.content, provider) });
         break;
 
       case "tool":
@@ -395,8 +424,14 @@ function price(value: unknown): number | undefined {
  * `cost_details.upstream_inference_cost`, so the call cost the two together.
  * Without that second figure there is no whole bill to report, and the
  * caller's rate prices the call instead.
+ *
+ * Exported for the other OpenRouter wire that bills the same way: Jev's.
  */
-function openRouterCostUsd(usage: NonNullable<OpenAIChunk["usage"]>): number | undefined {
+export function openRouterCostUsd(usage: {
+  cost?: unknown;
+  is_byok?: boolean;
+  cost_details?: { upstream_inference_cost?: unknown } | null;
+}): number | undefined {
   const cost = price(usage.cost);
   if (cost === undefined || usage.is_byok !== true) return cost;
   const upstream = price(usage.cost_details?.upstream_inference_cost);
@@ -423,7 +458,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
       const effort = opts.effort ?? config.effort;
       const model = opts.model ?? config.model;
 
-      const body = toOpenAIMessages(messages);
+      const body = toOpenAIMessages(messages, id);
       const request: Record<string, unknown> = {
         model,
         messages: body,

package/src/providers/responses.ts

@@ -10,7 +10,7 @@
 // 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 { streamError } from "../errors.ts";
+import { fileRefused, streamError } from "../errors.ts";
 import { streamSse, apiUrl } from "../transport.ts";
 import type {
   ChatMessage,
@@ -76,13 +76,16 @@ type ResponsesInputItem =
   | { type: "function_call"; call_id: string; name: string; arguments: string }
   | { type: "function_call_output"; call_id: string; output: string | ResponsesContentPart[] };
 
-function partsToResponses(content: string | ContentPart[]): ResponsesContentPart[] {
+function partsToResponses(
+  content: string | ContentPart[],
+  provider: string,
+): ResponsesContentPart[] {
   if (typeof content === "string") return [{ type: "input_text", text: content }];
-  return content.map((part): ResponsesContentPart =>
-    part.type === "text"
-      ? { type: "input_text", text: part.text }
-      : { type: "input_image", image_url: toDataUri(part) },
-  );
+  return content.map((part): ResponsesContentPart => {
+    if (part.type === "text") return { type: "input_text", text: part.text };
+    if (part.type === "file") throw fileRefused(provider, "Responses", part);
+    return { type: "input_image", image_url: toDataUri(part) };
+  });
 }
 
 /** A tool result is a bare string unless it carried images — then the content-
@@ -106,7 +109,10 @@ function toolOutput(
  * become several items (its text, then one `function_call` per tool it asked
  * for), which is why a message maps to a list rather than to one item.
  */
-export function toResponsesInput(messages: readonly ChatMessage[]): {
+export function toResponsesInput(
+  messages: readonly ChatMessage[],
+  provider = "openai-responses",
+): {
   instructions?: string;
   input: unknown[];
 } {
@@ -122,7 +128,11 @@ export function toResponsesInput(messages: readonly ChatMessage[]): {
         break; // lifted into `instructions` above
 
       case "user":
-        input.push({ type: "message", role: "user", content: partsToResponses(message.content) });
+        input.push({
+          type: "message",
+          role: "user",
+          content: partsToResponses(message.content, provider),
+        });
         break;
 
       case "tool":
@@ -237,7 +247,7 @@ export function createResponsesProvider(config: ResponsesConfig): Provider {
       opts: StreamOptions = {},
     ): AsyncIterable<ProviderChunk> {
       const effort = opts.effort ?? config.effort;
-      const { instructions, input } = toResponsesInput(messages);
+      const { instructions, input } = toResponsesInput(messages, id);
 
       const request: Record<string, unknown> = {
         model: opts.model ?? config.model,

package/src/types.ts

@@ -10,7 +10,10 @@
 /**
  * How hard the model thinks before answering. Absent = the provider's own
  * default (never sent). Passed through verbatim on OpenAI-shape
- * (`reasoning_effort`); mapped to thinking budgets on Anthropic-shape.
+ * (`reasoning_effort`). On Anthropic-shape, mapped to adaptive thinking and
+ * `output_config.effort` for current Claude models, where `none` is the lowest
+ * effort on a model that cannot stop thinking; and to thinking budgets for
+ * Claude 4.5 and older and for every other vendor on that wire.
  * Support varies per model — an unsupported level comes back as a clean 400.
  *
  * Ordered least → most; the type derives from the array so the runtime guard
@@ -39,7 +42,31 @@ export interface ImagePart {
   data: string;
 }
 
-export type ContentPart = TextPart | ImagePart;
+/** A file's media type: anything but an image's, because an image is an
+ *  `ImagePart`, which every adapter can send. */
+export type FileMimeType =
+  `application/${string}` | `audio/${string}` | `video/${string}` | `text/${string}`;
+
+/**
+ * A file the model reads — a PDF, a recording, a video — as base64 bytes,
+ * never a URL. Only the Gemini adapter sends one, as `inlineData`, the way it
+ * sends an image. Every other adapter refuses it with an `invalid`
+ * ProviderError before any request goes out, rather than drop it: a dropped
+ * attachment is a model answering about a file it never saw.
+ *
+ * Gemini takes inline data up to 100 MB per request, 50 MB for a PDF (Gemini
+ * API "File input methods", read 2026-09-27). The request carries the base64
+ * text, which is a third larger than the file. Past that limit the documented
+ * route is Gemini's File API, which this package does not wrap. Nothing here
+ * enforces the limit; Gemini answers an oversized request itself.
+ */
+export interface FilePart {
+  type: "file";
+  mimeType: FileMimeType;
+  data: string;
+}
+
+export type ContentPart = TextPart | ImagePart | FilePart;
 
 /**
  * A tool the model asked to run. `arguments` is the RAW JSON string, not a
@@ -182,6 +209,83 @@ export interface JsonOutput {
   strict?: boolean;
 }
 
+/**
+ * Read the JSON out of a model's answer. Models wrap it: a ```json fence, an
+ * unmarked fence, a sentence before it, notes after it. This takes the first
+ * fenced block marked `json` or not marked at all. With no such block, it
+ * takes the text from the first `{` or `[` to the bracket that closes it, and
+ * with no bracket either, the whole answer (a bare number, say). Then it
+ * parses that.
+ *
+ * It returns `unknown` on purpose: parsed is not validated, and a model's JSON
+ * has the schema's shape only once the caller has checked it.
+ *
+ * @throws {JsonAnswerError} when that text is not JSON. The error carries the
+ * answer, so a log shows what the model actually said.
+ */
+export function parseJsonAnswer(text: string): unknown {
+  const candidate = fencedJson(text) ?? bracketed(text);
+  try {
+    return JSON.parse(candidate);
+  } catch (error) {
+    throw new JsonAnswerError(text, error);
+  }
+}
+
+/** An answer `parseJsonAnswer` found no JSON in. `text` is the answer, cut to
+ *  2,000 characters like a provider's error body; `cause` is the SyntaxError. */
+export class JsonAnswerError extends Error {
+  readonly text: string;
+
+  constructor(text: string, cause: unknown) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    super(`The model's answer is not JSON: ${reason}`, { cause });
+    this.name = "JsonAnswerError";
+    this.text = text.slice(0, 2_000);
+  }
+}
+
+/** A fenced block, whose fences count only at the start of a line. A JSON
+ *  string can't hold a raw newline, so no line of JSON starts with a fence, and
+ *  a value carrying one (a code sample) never ends the block early. `[^\S\n]`
+ *  is a space, a tab, or the `\r` of a CRLF line. */
+const FENCED_BLOCK = /^[^\S\n]*```[^\S\n]*([^\s`]*)[^\n]*\n([\s\S]*?)^[^\S\n]*```/gm;
+
+function fencedJson(text: string): string | undefined {
+  for (const [, info = "", body = ""] of text.matchAll(FENCED_BLOCK)) {
+    const language = info.toLowerCase();
+    if (language === "" || language === "json") return body;
+  }
+  return undefined;
+}
+
+/** From the first `{` or `[` to the bracket that closes it, skipping brackets
+ *  inside strings. An answer cut off before it closes keeps its tail, and
+ *  JSON.parse says what is wrong with it.
+ *
+ *  ponytail: the FIRST opener wins, so prose with a bracket before the JSON
+ *  ("see [1]: {…}") picks the prose's. The upgrade is to try the next opener
+ *  when one fails to parse, once a model that writes that turns up. */
+function bracketed(text: string): string {
+  const start = text.search(/[[{]/);
+  if (start === -1) return text;
+  let depth = 0;
+  let inString = false;
+  for (let i = start; i < text.length; i++) {
+    const char = text[i];
+    if (inString) {
+      if (char === "\\") i++;
+      else if (char === '"') inString = false;
+    } else if (char === '"') inString = true;
+    else if (char === "{" || char === "[") depth++;
+    else if (char === "}" || char === "]") {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return text.slice(start);
+}
+
 /**
  * How the schema rides on a call that ALSO carries tools.
  *