@providerkit/core 0.15.0 → 0.16.0

package/src/providers/anthropic.ts

@@ -1,5 +1,5 @@
 // Anthropic-shape adapter — SSE from POST /v1/messages.
-import { fileRefused, streamError } from "../errors.ts";
+import { fileRefused, streamCut, streamError } from "../errors.ts";
 import { schemaPrompt, toAnthropicToolSchema } from "../schema.ts";
 import { parseToolArgs } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
@@ -14,6 +14,7 @@ import type {
   Provider,
   ProviderChunk,
   StreamOptions,
+  ToolChoice,
   ToolDefinition,
 } from "../types.ts";
 
@@ -82,14 +83,19 @@ const THINKING_BUDGET: Record<Exclude<Effort, "none">, number> = {
 
 /** 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";
+  /** How `effort: "none"` is said: nothing, an explicit off, an off for
+   *  up-front thinking only, or the lowest effort where there is no off. */
+  none: "omit" | "disabled" | "between_tools" | "low";
   /** Whether a non-default temperature or top_p survives while thinking is off. */
   sampling: boolean;
+  /** Whether a tool choice that forces a tool (`any`, or one named tool) is
+   *  accepted. Where it is not, it is a 400 on every request. */
+  forcedTool: boolean;
 }
 
-const ALWAYS_ON: ClaudeThinking = { none: "low", sampling: false };
+const ALWAYS_ON: ClaudeThinking = { none: "low", sampling: false, forcedTool: true };
+/** Always on, and a forced tool choice is a 400: the 5.1 and 5.5 models. */
+const LATEST: ClaudeThinking = { ...ALWAYS_ON, forcedTool: false };
 
 /**
  * Claude models that take adaptive thinking, keyed by id. A graded effort is
@@ -103,6 +109,10 @@ const ALWAYS_ON: ClaudeThinking = { none: "low", sampling: false };
  * `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").
+ *
+ * `forcedTool: false` marks the models that "reject forced tool use on every
+ * request with a 400 error" (same page, "Response prefill and forced tool use",
+ * read 2026-10-01). Every other model here takes it with adaptive thinking.
  */
 const CLAUDE_THINKING: ReadonlyMap<string, ClaudeThinking> = new Map([
   // Always on: `enabled` and `disabled` are both 400s (Mythos Preview still
@@ -110,12 +120,17 @@ const CLAUDE_THINKING: ReadonlyMap<string, ClaudeThinking> = new Map([
   // 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-1", LATEST],
+  ["claude-mythos-5-1", LATEST],
+  ["claude-opus-5-5", LATEST],
   ["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 a 400. `between_tools` is its lowest
+  // setting: no thinking up front, at effort high or below — and high is this
+  // model's default, so it needs no effort beside it (effort page, read
+  // 2026-10-01). It is also the one field it takes.
+  ["claude-sonnet-5-5", { ...LATEST, none: "between_tools" }],
   // 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
@@ -126,16 +141,16 @@ const CLAUDE_THINKING: ReadonlyMap<string, ClaudeThinking> = new Map([
   // 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 }],
+  ["claude-sonnet-5", { none: "disabled", sampling: false, forcedTool: true }],
   // 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 }],
+  ["claude-opus-4-8", { none: "omit", sampling: false, forcedTool: true }],
+  ["claude-opus-4-7", { none: "omit", sampling: false, forcedTool: true }],
   // 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-opus-4-6", { none: "omit", sampling: true, forcedTool: true }],
+  ["claude-sonnet-4-6", { none: "omit", sampling: true, forcedTool: true }],
 ]);
 
 /** Claude 4.5 and everything before it: extended thinking only (`adaptive` is
@@ -152,14 +167,15 @@ const CLAUDE_EXTENDED_ONLY = /^claude-(3-|(opus|sonnet|haiku)-4(-[0-5])?$)/;
  * 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.
+ * Claude since Opus 4.7 answers a non-default one with a 400. Nor a forced tool
+ * choice, which the newest refuse and an unforced request never trips. 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;
+  return CLAUDE_THINKING.get(family) ?? LATEST;
 }
 
 /** Whether a request continues a tool loop: its last assistant message made
@@ -188,6 +204,18 @@ function mapStopReason(reason: string | undefined): FinishReason | undefined {
   }
 }
 
+interface AnthropicToolChoice {
+  type: "auto" | "any" | "none" | "tool";
+  name?: string;
+  disable_parallel_tool_use?: boolean;
+}
+
+function toAnthropicToolChoice(choice: Exclude<ToolChoice, "auto">): AnthropicToolChoice {
+  if (choice === "none") return { type: "none" };
+  if (choice === "required") return { type: "any" };
+  return { type: "tool", name: choice.name };
+}
+
 function partsToAnthropic(content: string | ContentPart[], provider: string): unknown[] {
   if (typeof content === "string") return [{ type: "text", text: content }];
   return content.map((part) => {
@@ -354,22 +382,36 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
       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) => ({
+      const claude = claudeThinking(model);
+      const forcesTool = opts.toolChoice === "required" || typeof opts.toolChoice === "object";
+      // A model that refuses a forced tool choice gets `auto` instead, which is
+      // the docs' own advice, and a named tool becomes the only tool it is
+      // offered. Sending the choice anyway is a 400 on every request.
+      // ponytail: the model may still answer in text. The upgrade is strict
+      // tool use or structured outputs, which the docs pair with `auto`.
+      const unforced = forcesTool && claude?.forcedTool === false;
+      const named = typeof opts.toolChoice === "object" ? opts.toolChoice.name : undefined;
+      const offered =
+        unforced && named !== undefined ? tools.filter((tool) => tool.name === named) : tools;
+      if (offered.length > 0) {
+        request.tools = offered.map((tool) => ({
           name: tool.name,
           description: tool.description,
           input_schema: toAnthropicToolSchema(tool.inputSchema),
         }));
       }
-      if (opts.toolChoice && opts.toolChoice !== "auto") {
-        request.tool_choice =
-          opts.toolChoice === "none"
-            ? { type: "none" }
-            : opts.toolChoice === "required"
-              ? { type: "any" }
-              : { type: "tool", name: opts.toolChoice.name };
+      const choice =
+        opts.toolChoice && opts.toolChoice !== "auto" && !unforced
+          ? toAnthropicToolChoice(opts.toolChoice)
+          : undefined;
+      // This wire says "one call at a time" inside the tool choice, so asking
+      // for it needs a choice to ride on — `auto` when the caller named none.
+      // `none` calls nothing, so there is nothing to serialize.
+      if (opts.parallelToolCalls === false && offered.length > 0 && choice?.type !== "none") {
+        request.tool_choice = { ...(choice ?? { type: "auto" }), disable_parallel_tool_use: true };
+      } else if (choice) {
+        request.tool_choice = choice;
       }
-      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):
@@ -382,7 +424,6 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
       //   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) {
@@ -390,6 +431,7 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
         // default, which on most of these is thinking ON.
         if (effort === "none") {
           if (claude.none === "disabled") request.thinking = { type: "disabled" };
+          if (claude.none === "between_tools") request.thinking = { type: "between_tools" };
           if (claude.none === "low") request.output_config = { effort: "low" };
         } else if (effort) {
           request.thinking = { type: "adaptive" };
@@ -423,6 +465,19 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
       let outputTokens = 0;
       let toolCall: { index: number; id: string; name: string } | null = null;
       let blockIndex = -1;
+      // What proves the turn ended rather than the socket: a stated stop
+      // reason, or `message_stop`. See the check after the loop.
+      let stopped = false;
+      let closed = false;
+      const usageChunk = (): ProviderChunk => ({
+        type: "usage",
+        usage: {
+          inputTokens: freshInputTokens + cachedInputTokens + cacheWriteTokens,
+          cachedInputTokens,
+          cacheWriteTokens,
+          outputTokens,
+        },
+      });
 
       for await (const data of streamSse({
         url: apiUrl(baseUrl, "/v1/messages"),
@@ -438,6 +493,7 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
         provider: id,
         ...(opts.signal ? { signal: opts.signal } : {}),
         ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
+        ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
       })) {
         let event: AnthropicEvent;
         try {
@@ -505,24 +561,26 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
             cachedInputTokens = event.usage?.cache_read_input_tokens ?? cachedInputTokens;
             cacheWriteTokens = event.usage?.cache_creation_input_tokens ?? cacheWriteTokens;
             outputTokens = event.usage?.output_tokens ?? outputTokens;
+            if (event.delta?.stop_reason) stopped = true;
             const finishReason = mapStopReason(event.delta?.stop_reason);
             if (finishReason) yield { type: "finish", finishReason };
             break;
           }
 
           case "message_stop":
-            yield {
-              type: "usage",
-              usage: {
-                inputTokens: freshInputTokens + cachedInputTokens + cacheWriteTokens,
-                cachedInputTokens,
-                cacheWriteTokens,
-                outputTokens,
-              },
-            };
+            closed = true;
+            yield usageChunk();
             break;
         }
       }
+      if (closed) return;
+      // A gateway that states its stop reason and then skips `message_stop`
+      // still finished the turn — and still billed it.
+      if (stopped) {
+        yield usageChunk();
+        return;
+      }
+      throw streamCut(id);
     },
   };
   return withConfiguredFallbacks(provider, config);

package/src/providers/gemini.ts

@@ -5,7 +5,7 @@
 // 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 { ProviderError, streamCut, streamError } from "../errors.ts";
 import { schemaPrompt, toGeminiToolSchema } from "../schema.ts";
 import { parseToolArgs } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
@@ -257,6 +257,8 @@ interface GeminiResponse {
   };
   /** Present only on the in-band failure below — never on a real candidate. */
   error?: GeminiStatus;
+  /** A prompt Gemini refused outright: no candidate at all, just the reason. */
+  promptFeedback?: { blockReason?: string };
 }
 
 export function createGeminiProvider(config: GeminiConfig): Provider {
@@ -329,6 +331,16 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
       ];
       if (systemParts.length > 0) request.systemInstruction = { parts: systemParts };
       if (tools.length > 0) {
+        // Gemini has no switch for one call per turn. Sending the request
+        // anyway would hand back the parallel calls the caller ruled out.
+        if (opts.parallelToolCalls === false) {
+          throw new ProviderError(
+            id,
+            "invalid",
+            `${id}: Gemini can't limit a turn to one tool call. Leave parallelToolCalls unset ` +
+              "for Gemini models, or run the calls it returns one at a time.",
+          );
+        }
         request.tools = [
           {
             functionDeclarations: tools.map((tool) => ({
@@ -351,6 +363,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
       // remembered rather than read off the final chunk.
       let sawFunctionCalls = false;
       let callIndex = 0;
+      let finished = false;
 
       for await (const data of streamSse({
         // Without `?alt=sse` the response is one long JSON array that only
@@ -361,6 +374,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
         provider: id,
         ...(opts.signal ? { signal: opts.signal } : {}),
         ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
+        ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
       })) {
         let chunk: GeminiResponse;
         try {
@@ -373,6 +387,14 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
         // 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);
+        // A blocked PROMPT has no candidate to finish, so it reads as a cut
+        // stream — retried, into the same block. It is a content failure.
+        const blocked = chunk.promptFeedback?.blockReason;
+        if (blocked) {
+          throw new ProviderError(id, "content", `${id}: the prompt was blocked (${blocked})`, {
+            code: blocked,
+          });
+        }
 
         if (chunk.usageMetadata) {
           const usage = chunk.usageMetadata;
@@ -385,6 +407,9 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
               // turn by most of what it cost.
               outputTokens: (usage.candidatesTokenCount ?? 0) + (usage.thoughtsTokenCount ?? 0),
               cachedInputTokens: usage.cachedContentTokenCount ?? 0,
+              ...(usage.thoughtsTokenCount !== undefined
+                ? { reasoningTokens: usage.thoughtsTokenCount }
+                : {}),
             },
           };
         }
@@ -428,6 +453,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
         }
 
         if (candidate.finishReason) {
+          finished = true;
           yield {
             type: "finish",
             // A turn that called tools finishes as tool_calls whatever the
@@ -437,6 +463,9 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
           };
         }
       }
+      // Gemini states a finish reason on the last candidate of every turn it
+      // completes; a stream that closes without one was cut.
+      if (!finished) throw streamCut(id);
     },
   };
 

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 { fileRefused, streamError } from "../errors.ts";
+import { fileRefused, streamCut, streamError } from "../errors.ts";
 import { streamSse, apiUrl } from "../transport.ts";
 import { attributionHeaders } from "../attribution.ts";
 import type {
@@ -315,7 +315,14 @@ function partsToOpenAI(content: string | ContentPart[], provider: string): unkno
  */
 export function toOpenAIMessages(messages: readonly ChatMessage[], provider = "openai"): unknown[] {
   const out: unknown[] = [];
+  // Images from a run of tool results, held until the run ends. See "tool".
+  let toolImages: unknown[] = [];
+  const flushToolImages = () => {
+    if (toolImages.length > 0) out.push({ role: "user", content: toolImages });
+    toolImages = [];
+  };
   for (const message of messages) {
+    if (message.role !== "tool") flushToolImages();
     switch (message.role) {
       case "system":
         out.push({ role: "system", content: message.content });
@@ -329,17 +336,16 @@ export function toOpenAIMessages(messages: readonly ChatMessage[], provider = "o
         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) },
-            })),
-          });
+        // follows as a 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.
+        //
+        // It follows the whole RUN of tool results, not this one: an assistant
+        // turn that made parallel calls needs every answer before any user
+        // message, and an image wedged between two of them is a 400 that
+        // classifies as "invalid" — never retried, never walked to a backup.
+        for (const image of message.images ?? []) {
+          toolImages.push({ type: "image_url", image_url: { url: toDataUri(image) } });
         }
         break;
 
@@ -369,6 +375,7 @@ export function toOpenAIMessages(messages: readonly ChatMessage[], provider = "o
       }
     }
   }
+  flushToolImages();
   return out;
 }
 
@@ -392,9 +399,12 @@ interface OpenAIChunk {
     prompt_tokens?: number;
     completion_tokens?: number;
     prompt_tokens_details?: { cached_tokens?: number };
+    completion_tokens_details?: { reasoning_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;
+    /** Kimi (Moonshot) puts it at the top level of `usage`. */
+    cached_tokens?: number;
     /** OpenRouter only, from here down: what the call cost, in its credits,
      *  which are US dollars. */
     cost?: unknown;
@@ -487,6 +497,8 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
             parameters: tool.inputSchema,
           },
         }));
+        // Only beside tools: OpenAI refuses the field on a request without any.
+        if (opts.parallelToolCalls === false) request.parallel_tool_calls = false;
       }
       if (opts.toolChoice && opts.toolChoice !== "auto") {
         request.tool_choice =
@@ -561,6 +573,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
         ? "/chat/completions"
         : "/v1/chat/completions";
 
+      let ended = false;
       for await (const data of streamSse({
         url: apiUrl(baseUrl, config.path ?? defaultPath),
         headers: {
@@ -575,6 +588,10 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
         provider: id,
         ...(opts.signal ? { signal: opts.signal } : {}),
         ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
+        ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+        onDone: () => {
+          ended = true;
+        },
       })) {
         let chunk: OpenAIChunk;
         try {
@@ -594,13 +611,15 @@ 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;
-          // 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×.
+          // Three spellings for the same subset. DeepSeek's native endpoint and
+          // Kimi each use their 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 ??
+            chunk.usage.cached_tokens ??
             0;
           const reportedCostUsd = reportsCost ? openRouterCostUsd(chunk.usage) : undefined;
           yield {
@@ -611,6 +630,9 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
               // Anthropic's, which excludes them. No reconciling to do.
               cachedInputTokens: cached,
               outputTokens: chunk.usage.completion_tokens ?? 0,
+              ...(chunk.usage.completion_tokens_details?.reasoning_tokens !== undefined
+                ? { reasoningTokens: chunk.usage.completion_tokens_details.reasoning_tokens }
+                : {}),
               ...(reportedCostUsd !== undefined ? { reportedCostUsd } : {}),
             },
           };
@@ -653,9 +675,13 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
           if (has) yield out;
         }
 
+        if (choice.finish_reason) ended = true;
         const finishReason = mapFinishReason(choice.finish_reason);
         if (finishReason) 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);
     },
   };