@providerkit/core 0.21.1 → 0.23.0

package/src/key-pool.ts

@@ -25,10 +25,10 @@ import type {
 
 /** A per-minute throttle: the window it names is the next one. */
 const RATE_COOLDOWN_MS = 60_000;
-/** A balance or a daily window — minutes will not bring it back. */
+/** A balance or a daily window. Minutes will not bring it back. */
 const QUOTA_COOLDOWN_MS = 60 * 60_000;
 const AUTH_COOLDOWN_MS = 12 * 60 * 60_000;
-/** The vendor's bad time, not the key's — benched only long enough for the
+/** The vendor's bad time, not the key's. Benched only long enough for the
  *  next call to land somewhere else. */
 const TRANSIENT_COOLDOWN_MS = 60_000;
 const MIN_EVICTION_MS = 1_000;
@@ -47,7 +47,7 @@ export interface KeyPoolOptions {
   /** Free-tier keys, walked round-robin before the paid one. */
   keys: readonly string[];
   paidKey?: string | null;
-  /** Fires whenever a key is benched — the pool's only report, in place of a
+  /** Fires whenever a key is benched. The pool's only report, in place of a
    *  logger a zero-dependency package has no business owning. */
   onEvict?: (info: { tier: KeyTier; kind: ErrorKind; forMs: number }) => void;
   /** Injected in tests, so an expiry can be exercised without waiting out a
@@ -55,12 +55,20 @@ export interface KeyPoolOptions {
   now?: () => number;
 }
 
-/** No key can serve right now. `retryAtMs` = when the soonest one is back. */
-export class NoAvailableKeyError extends Error {
+/** No key can serve right now. `retryAtMs` = when the soonest one is back.
+ *
+ *  A `ProviderError` of kind `rate` that carries that moment as `resetAtMs` and
+ *  `retryAfterMs`. As a plain `Error` it classified as `rate` only by its
+ *  wording and carried no deadline anyone read, so a FallbackPool around the
+ *  key pool benched it for its default minute, whatever the keys had said. */
+export class NoAvailableKeyError extends ProviderError {
   readonly retryAtMs: number;
 
-  constructor(label: string, retryAtMs: number) {
-    super(`No ${label} API key available (all rate-limited or denied)`);
+  constructor(label: string, retryAtMs: number, now: number) {
+    super(label, "rate", `No ${label} API key available (all rate-limited or denied)`, {
+      resetAtMs: retryAtMs,
+      retryAfterMs: Math.max(0, retryAtMs - now),
+    });
     this.name = "NoAvailableKeyError";
     this.retryAtMs = retryAtMs;
   }
@@ -96,12 +104,12 @@ export class KeyPool {
   /**
    * Run `fn` with the next available key, rotating on key-specific and
    * transient failures. Everything else (a bad request, a content block) throws
-   * straight through — it would fail identically on every key, and spending the
+   * straight through: it would fail identically on every key, and spending the
    * pool on it only turns one bad request into an outage.
    */
   async with<T>(fn: (apiKey: string, tier: KeyTier) => Promise<T>): Promise<T> {
     const candidates = this.candidates(this.now());
-    if (candidates.length === 0) throw new NoAvailableKeyError(this.label, this.nextAvailableAt());
+    if (candidates.length === 0) throw this.noneAvailable();
 
     let last: unknown;
     for (const key of candidates) {
@@ -112,7 +120,7 @@ export class KeyPool {
         // The single-key rule: with nothing to rotate to, benching the only key
         // answers NoAvailableKeyError to every call for the next minute — for a
         // failure the caller's own retry would have absorbed.
-        const cooldown = this.size > 1 ? cooldownFor(err) : null;
+        const cooldown = this.size > 1 ? cooldownFor(err, this.now()) : null;
         if (cooldown === null) throw err;
         key.evictedUntil = this.now() + cooldown.forMs;
         this.onEvict?.({ tier: key.tier, kind: cooldown.kind, forMs: cooldown.forMs });
@@ -120,8 +128,7 @@ export class KeyPool {
     }
 
     // Every candidate was evicted during this call.
-    if (this.candidates(this.now()).length === 0)
-      throw new NoAvailableKeyError(this.label, this.nextAvailableAt());
+    if (this.candidates(this.now()).length === 0) throw this.noneAvailable();
     throw last;
   }
 
@@ -138,26 +145,36 @@ export class KeyPool {
     return out;
   }
 
-  private nextAvailableAt(): number {
+  private noneAvailable(): NoAvailableKeyError {
     const all = this.paid ? [...this.free, this.paid] : this.free;
-    return Math.min(...all.map((key) => key.evictedUntil));
+    const retryAtMs = Math.min(...all.map((key) => key.evictedUntil));
+    return new NoAvailableKeyError(this.label, retryAtMs, this.now());
   }
 }
 
 /**
  * How long to bench a key for this failure, or null when the failure is not the
- * key's fault — nothing is gained by rotating, and benching would spend the
+ * key's fault. Nothing is gained by rotating, and benching would spend the
  * pool on a request that fails the same way everywhere.
  */
-function cooldownFor(err: unknown): { kind: ErrorKind; forMs: number } | null {
+function cooldownFor(err: unknown, now: number): { kind: ErrorKind; forMs: number } | null {
   if (!(err instanceof ProviderError)) return null;
   const clamp = (ms: number) => Math.min(Math.max(ms, MIN_EVICTION_MS), MAX_EVICTION_MS);
   switch (err.kind) {
     // The three kinds that are about THIS key.
     case "rate":
       return { kind: err.kind, forMs: clamp(err.retryAfterMs ?? RATE_COOLDOWN_MS) };
-    case "quota":
-      return { kind: err.kind, forMs: clamp(err.retryAfterMs ?? QUOTA_COOLDOWN_MS) };
+    case "quota": {
+      // A spent window names its reset, and that outranks Retry-After: Anthropic
+      // sends `retry-after: 60` beside a weekly window, and a key benched for
+      // the minute is dialled again into the same wall.
+      const reset = err.resetAtMs;
+      const forMs =
+        reset !== undefined && Number.isFinite(reset)
+          ? reset - now
+          : (err.retryAfterMs ?? QUOTA_COOLDOWN_MS);
+      return { kind: err.kind, forMs: clamp(forMs) };
+    }
     case "auth":
       // 12 h, not forever: a key is also refused while a billing account is
       // reinstated, and a pool that drops keys permanently ends up empty.
@@ -179,8 +196,8 @@ function cooldownFor(err: unknown): { kind: ErrorKind; forMs: number } | null {
  * Give any provider a rotating pool of keys.
  *
  * The subtlety is the seam's shape. `createStream` is an async generator, so
- * CALLING it performs no I/O: the POST — and the 429 that should rotate the key
- * — happens on the first `next()`, long after a `pool.with` wrapped around the
+ * calling it performs no I/O. The POST and the 429 that should rotate the key
+ * happen on the first `next()`, long after a `pool.with` wrapped around the
  * call itself would have returned, with nothing left to rotate. So the first
  * chunk is pulled INSIDE the pool and only the rest of the stream is consumed
  * outside it.

package/src/presets.ts

@@ -1,9 +1,9 @@
 /**
- * Provider presets — hand-curated, wire-level facts only.
+ * Provider presets: hand-curated, wire-level facts only.
  *
  * A preset is everything `createPresetProvider` needs to speak to one
  * endpoint: which adapter shape it speaks, its API root, how the credential
- * rides, and what it is called. Deliberately absent: prices (invariant 9 —
+ * rides, and what it is called. Deliberately absent: prices (invariant 9;
  * they drift on a vendor's schedule and a wrong number in a library is a
  * wrong number in everyone's ledger), icons, colors, marketing names, and
  * sign-in flows (an `oauth` preset expects the CALLER to hand over an access
@@ -11,12 +11,12 @@
  *
  * Sources: the coding-plan endpoints and auth quirks are measured
  * (tabrunner's extension + this repo's adopters, 2026-09); the model lists
- * are representative, not exhaustive — every adapter takes a per-call model,
+ * are representative, not exhaustive. Every adapter takes a per-call model,
  * so a missing id costs nothing.
  *
  * Azure is deliberately ABSENT: its base URL is per-deployment
- * (`https://<resource>.openai.azure.com`), so no static preset can carry it —
- * point createOpenAIProvider's baseUrl at your resource instead.
+ * (`https://<resource>.openai.azure.com`), so no static preset can carry it.
+ * Point createOpenAIProvider's baseUrl at your resource instead.
  */
 import type { ImageLimits } from "./image.ts";
 
@@ -27,7 +27,7 @@ export type PresetShape = "anthropic" | "openai" | "responses" | "gemini";
  * - `key`: the vendor's native key header (Anthropic reads `x-api-key`,
  *   Gemini `x-goog-api-key`); the OpenAI shapes have only Bearer, so they
  *   never use this.
- * - `bearer`: `Authorization: Bearer` — the OpenAI shapes' only mode, and the
+ * - `bearer`: `Authorization: Bearer`, the OpenAI shapes' only mode, and the
  *   coding-plan gateways' mode on the Anthropic wire (measured: Z.ai's coding
  *   endpoint ignores `x-api-key` and reads Bearer).
  * - `oauth`: same wire as `bearer`, but the token is a short-lived access
@@ -54,7 +54,7 @@ export interface PresetRoute {
 export interface ProviderPreset {
   /** Adapter wire format. */
   shape: PresetShape;
-  /** API root — if it ends with /v1, /v4 or another version segment, the
+  /** API root. If it ends with /v1, /v4 or another version segment, the
    *  adapter automatically routes to /chat/completions instead of /v1/chat/completions. */
   baseUrl: string;
   /** Explicit path override when a gateway has custom routing. */
@@ -71,8 +71,8 @@ export interface ProviderPreset {
   textOnly?: boolean;
   /** Anthropic-shape dialect: say "no thinking" with an explicit
    *  `thinking: { type: "disabled" }` marker when effort is none. For
-   *  endpoints where an ABSENT field means the model's default — thinking ON
-   *  for reasoning-mandatory models (measured on Z.ai's coding endpoint:
+   *  endpoints where an absent field means the model's default, with thinking
+   *  on for reasoning-mandatory models (measured on Z.ai's coding endpoint:
    *  omit → thinking block; disabled → none). Leave it unset for native
    *  Anthropic: the adapter spells none per Claude model, and ignores this
    *  flag for every Claude from 4.6 on. */
@@ -82,7 +82,7 @@ export interface ProviderPreset {
    *  neither text nor a tool call. */
   maxTokens?: number;
   /** Header that carries `StreamOptions.sessionId`, for gateways that route
-   *  and cache per conversation — and refuse a call without it (OpenCode Go:
+   *  and cache per conversation and refuse a call without it (OpenCode Go:
    *  `MissingSessionID`, measured 2026-09-27). */
   sessionHeader?: string;
   /** Wires for model ids that don't use the preset's own `shape`. The first
@@ -103,6 +103,9 @@ export interface ProviderPreset {
   /** OpenAI shape: send `X-Initiator` (`user` or `agent`) on every call. GitHub
    *  Copilot bills a premium request per `user` turn. */
   initiatorHeader?: boolean;
+  /** OpenAI shape: never send `temperature` or `top_p`, for an endpoint that
+   *  fixes its own sampling and answers the fields with an error. */
+  noSampling?: boolean;
 }
 
 export const PROVIDER_PRESETS = {
@@ -130,12 +133,13 @@ export const PROVIDER_PRESETS = {
     defaultModel: "gemini-3.1-pro-preview",
     models: ["gemini-3.1-pro-preview", "gemini-3.8-flash", "gemini-flash-latest"],
   },
-  /** Gemini behind its OpenAI-compatible route — the drop-in for codebases
+  /** Gemini behind its OpenAI-compatible route, for codebases
    *  that only speak the openai shape. */
   "google-openai": {
     shape: "openai",
     baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
     auth: "key",
+    noSampling: true,
     defaultModel: "gemini-3.1-pro-preview",
     models: ["gemini-3.1-pro-preview", "gemini-3.8-flash", "gemini-flash-latest"],
   },
@@ -357,7 +361,7 @@ export const PROVIDER_PRESETS = {
     models: ["glm-5.3-flash", "glm-5.3", "glm-5.2"],
   },
   /**
-   * OpenCode Go — one $10/month key across many open models, each with its own
+   * OpenCode Go: one $10/month key across many open models, each with its own
    * monthly dollar limit (5h = 20%, week = 50%). Chain several models as
    * `fallbacks` so a spent one hands over to the next.
    *
@@ -369,8 +373,9 @@ export const PROVIDER_PRESETS = {
    * Go serves three wires, and `routes` picks one from the model id (cc-proxy's
    * table, from Go's own docs): `minimax-` and `qwen` on Anthropic /messages
    * (key in `x-api-key`), `gpt-`, `grok-` and `muse-spark-` on /responses, and
-   * everything else on chat completions. Each model in a chain resolves its
-   * own route, so one preset serves a chain that crosses wires.
+   * everything else on chat completions, `grok-4.5` included. Each model in a
+   * chain resolves its own route, so one preset serves a chain that crosses
+   * wires.
    *
    * Muse Contributor, measured 2026-09-28 on /responses: text, images, strict
    * JSON Schema, parallel tools and tool-result round trips all passed. It
@@ -404,6 +409,15 @@ export const PROVIDER_PRESETS = {
         baseUrl: "https://opencode.ai/zen/go",
         auth: "key",
       },
+      {
+        // The one Grok Go serves on chat completions, while 4.6 and 4.7 are on
+        // /responses: cc-proxy's catalog pins it there as an override of the
+        // family rule. It sits above the `grok-` route because the first match
+        // wins.
+        prefixes: ["grok-4.5"],
+        shape: "openai",
+        baseUrl: "https://opencode.ai/zen/go/v1",
+      },
       {
         prefixes: ["gpt-", "grok-", "muse-spark-"],
         shape: "responses",
@@ -431,7 +445,7 @@ export const PROVIDER_PRESETS = {
     defaultModel: "kimi-k2.7-code",
     models: ["kimi-k2.7-code", "kimi-k2.7-code-highspeed", "kimi-k3"],
   },
-  /** Alibaba's dashscope coding plan — OpenAI-compatible per its registry. */
+  /** Alibaba's DashScope coding plan, OpenAI-compatible per its registry. */
   "alibaba-coding-plan": {
     shape: "openai",
     baseUrl: "https://coding-intl.dashscope.aliyuncs.com/v1",
@@ -439,7 +453,7 @@ export const PROVIDER_PRESETS = {
     defaultModel: "qwen3.5-plus",
     models: ["qwen3.5-plus", "qwen3-coder-next", "glm-5"],
   },
-  /** QwenCloud's token plan — Anthropic wire (measured by tabrunner). */
+  /** QwenCloud's token plan on the Anthropic wire (measured by tabrunner). */
   qwen: {
     shape: "anthropic",
     baseUrl: "https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
@@ -447,7 +461,7 @@ export const PROVIDER_PRESETS = {
     defaultModel: "qwen3.8-max",
     models: ["qwen3.8-max", "qwen3.8-flash", "qwen3.6-flash"],
   },
-  /** QwenCloud's token plan — OpenAI-compatible endpoint. */
+  /** QwenCloud's token plan on an OpenAI-compatible endpoint. */
   "qwen-token-plan-openai": {
     shape: "openai",
     baseUrl: "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
@@ -455,7 +469,7 @@ export const PROVIDER_PRESETS = {
     defaultModel: "qwen3.8-max",
     models: ["qwen3.8-max", "qwen3.8-flash", "qwen3.6-flash"],
   },
-  /** Alibaba DashScope Platform API — standard pay-as-you-go API key. */
+  /** Alibaba DashScope Platform API, with a standard pay-as-you-go API key. */
   alibaba: {
     shape: "openai",
     baseUrl: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
@@ -501,8 +515,8 @@ export const PROVIDER_PRESETS = {
     headers: { "anthropic-beta": "claude-code-20250219,oauth-2025-04-20" },
   },
   /**
-   * The Codex backend behind a ChatGPT sign-in — Responses wire, no public
-   * model list, so these ids are the list.
+   * The Codex backend behind a ChatGPT sign-in, on the Responses wire. It has no
+   * public model list, so these ids are the list.
    *
    * The endpoint is `/backend-api/codex/responses`, with no version segment.
    * Without the `path` the adapter appends `/v1/responses`, the POST 404s, and
@@ -540,8 +554,8 @@ export const PROVIDER_PRESETS = {
     replayReasoning: true,
   },
   /**
-   * A Grok subscription (SuperGrok, X Premium) — the backend the Grok CLI
-   * talks to, Responses wire. Distinct from `xai`, which is the keyed API and
+   * A Grok subscription (SuperGrok, X Premium), on the backend the Grok CLI
+   * talks to, using the Responses wire. Distinct from `xai`, which is the keyed API and
    * bills per token.
    *
    * The two `x-…` headers are what switch the backend into CLI-token mode;
@@ -568,7 +582,7 @@ export const PROVIDER_PRESETS = {
     imageLimits: { minSide: 8, minArea: 512, maxDecodedBytes: 5 * 1024 * 1024, maxImages: 4 },
   },
   /** Kimi's coding endpoint reached with a subscription token instead of a
-   *  key — Kimi bills the two separately. */
+   *  key. Kimi bills the two separately. */
   "kimi-plan": {
     shape: "anthropic",
     baseUrl: "https://api.kimi.ai/coding",
@@ -607,5 +621,5 @@ export const PROVIDER_PRESETS = {
 
 export type ProviderPresetId = keyof typeof PROVIDER_PRESETS;
 
-/** Every valid preset id — the factory's unknown-id error lists these. */
+/** Every valid preset id. The factory's unknown-id error lists these. */
 export const PRESET_IDS = Object.keys(PROVIDER_PRESETS) as ProviderPresetId[];

package/src/providers/anthropic.ts

@@ -1,8 +1,9 @@
 // Anthropic-shape adapter — SSE from POST /v1/messages.
+import { repairHistory } from "../context.ts";
 import { fileRefused, ProviderError, streamCut, streamError } from "../errors.ts";
 import { schemaPrompt, toAnthropicToolSchema } from "../schema.ts";
-import { parseToolArgs } from "../tool-args.ts";
-import { streamSse, apiUrl } from "../transport.ts";
+import { parseToolArgs, settleToolCalls, type ToolCallIdentity } from "../tool-args.ts";
+import { streamSse, apiUrl, parseFrame } from "../transport.ts";
 import { attributionHeaders } from "../attribution.ts";
 import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
 import type {
@@ -21,7 +22,7 @@ import type {
 export interface AnthropicConfig extends ProviderFallbackConfig {
   apiKey: string;
   model: string;
-  /** Any endpoint speaking the Anthropic Messages dialect — a proxy or gateway.
+  /** Any endpoint speaking the Anthropic Messages dialect, including a proxy or gateway.
    *  Defaults to Anthropic itself. */
   baseUrl?: string;
   /** Names the provider in errors and logs. The subscription backend is the
@@ -38,7 +39,7 @@ export interface AnthropicConfig extends ProviderFallbackConfig {
    *  headers, and a gateway in front usually wants one of its own. */
   headers?: Record<string, string>;
   /**
-   * App attribution for OpenRouter's rankings — the site URL rides as
+   * App attribution for OpenRouter's rankings. The site URL rides as
    * `HTTP-Referer`, the app name as `X-Title`. Public, not secret. Sent
    * whenever set (other vendors ignore unknown headers); an explicit entry
    * in `headers` always wins. Covers OpenRouter's Anthropic-dialect endpoint.
@@ -48,15 +49,15 @@ export interface AnthropicConfig extends ProviderFallbackConfig {
    * App name for OpenRouter's rankings, sent as `X-Title`. See `siteUrl`.
    */
   siteName?: string;
-  /** Send the key as a Bearer instead of `x-api-key` — what a subscription
-   *  access token needs. */
+  /** Send the key as a Bearer instead of `x-api-key`, as a subscription
+   *  access token requires. */
   bearer?: boolean;
   /** Header that carries `StreamOptions.sessionId`. When set and a call has no
    *  sessionId, one stable id for this provider instance rides instead. */
   sessionHeader?: string;
   /** Say "no thinking" with an explicit `thinking: { type: "disabled" }` when
    *  effort resolves to none, instead of omitting the field. For endpoints
-   *  where an absent field means the MODEL's default, not off — Z.ai's coding
+   *  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. Ignored for a Claude id that
@@ -72,9 +73,9 @@ const DEFAULT_VERSION = "2023-06-01";
 const DEFAULT_MAX_TOKENS = 8_192;
 
 /**
- * Thinking budgets, in output tokens, for extended thinking — Claude 4.5 and
+ * Thinking budgets, in output tokens, for extended thinking on 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
+ * 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> = {
@@ -102,8 +103,8 @@ const LATEST: ClaudeThinking = { ...ALWAYS_ON, forcedTool: 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
+ * 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);
@@ -191,19 +192,32 @@ function continuesToolLoop(messages: readonly ChatMessage[]): boolean {
   return false;
 }
 
-function mapStopReason(reason: string | undefined): FinishReason | undefined {
+/**
+ * A stated stop, or a throw for one this adapter does not know. An unknown
+ * reason used to end the stream as a clean success with no finish at all.
+ * Nothing says the answer ended on purpose, so it is `overload`: theirs, and
+ * worth a retry (cc-proxy answers it the same way). `pause_turn` lands there
+ * too: it is a server-tool turn waiting to be sent back, which this adapter
+ * never asks for, and a half answer is not a finished one.
+ */
+function mapStopReason(provider: string, reason: string): FinishReason {
   switch (reason) {
     case "end_turn":
     case "stop_sequence":
       return "stop";
     case "tool_use":
       return "tool_calls";
+    // `model_context_window_exceeded`: the context window filled before the
+    // answer did. Cut short, and a retry fills it the same way.
     case "max_tokens":
+    case "model_context_window_exceeded":
       return "length";
     case "refusal":
       return "content_filter";
     default:
-      return undefined;
+      throw new ProviderError(provider, "overload", `${provider} stopped the turn on "${reason}"`, {
+        code: reason,
+      });
   }
 }
 
@@ -233,13 +247,13 @@ function partsToAnthropic(content: string | ContentPart[], provider: string): un
 
 /**
  * Anthropic takes `system` at the top level and expects tool RESULTS as user
- * turns carrying `tool_result` blocks — not as a role of their own. Consecutive
+ * 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
+ * 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
@@ -247,14 +261,14 @@ function partsToAnthropic(content: string | ContentPart[], provider: string): un
  *
  * 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.
+ * by the second turn, which always comes in the loop this package sits under.
  */
 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,
+ * 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,
@@ -263,13 +277,41 @@ function systemBlocks(text: string): unknown[] | undefined {
  * 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
+ * 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: schemaPrompt(json.schema) };
 }
 
+/**
+ * Tool ids as this wire accepts them: `[A-Za-z0-9_-]` only. Kimi's
+ * `functions.search:0` is a 400 here, and an opencode-go rotation hands a
+ * history from chat completions to Messages mid-conversation, so a Kimi id
+ * does arrive. Each other character becomes `_`, and a result follows its call
+ * because both go through the same map.
+ *
+ * Collision-safe in one forward pass: an id whose cleaned form is already
+ * taken gets `_2`, `_3`…, judged only against ids seen before it, so an earlier
+ * id never changes because of a later one and the prompt cache keeps its
+ * prefix. A history whose ids are already clean comes out byte for byte.
+ */
+function anthropicIds(): (id: string) => string {
+  const sent = new Map<string, string>();
+  const taken = new Set<string>();
+  return (id) => {
+    let wire = sent.get(id);
+    if (wire === undefined) {
+      const clean = id.replace(/[^A-Za-z0-9_-]/g, "_");
+      wire = clean;
+      for (let k = 2; taken.has(wire); k++) wire = `${clean}_${k}`;
+      sent.set(id, wire);
+      taken.add(wire);
+    }
+    return wire;
+  };
+}
+
 export function toAnthropicMessages(
   messages: readonly ChatMessage[],
   provider = "anthropic",
@@ -277,6 +319,7 @@ export function toAnthropicMessages(
   system?: unknown[];
   messages: unknown[];
 } {
+  const wireId = anthropicIds();
   const system = messages
     .filter((m) => m.role === "system")
     .map((m) => m.content)
@@ -299,7 +342,7 @@ export function toAnthropicMessages(
       pushBlocks("user", [
         {
           type: "tool_result",
-          tool_use_id: message.toolCallId,
+          tool_use_id: wireId(message.toolCallId),
           content: [
             { type: "text", text: message.content },
             ...(message.images ?? []).map((image) => ({
@@ -319,7 +362,7 @@ export function toAnthropicMessages(
     for (const call of message.toolCalls ?? []) {
       blocks.push({
         type: "tool_use",
-        id: call.id,
+        id: wireId(call.id),
         name: call.name,
         input: parseToolArgs(call.arguments),
       });
@@ -373,7 +416,10 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
       const model = opts.model ?? config.model;
       const maxTokens = opts.maxTokens ?? config.maxTokens ?? DEFAULT_MAX_TOKENS;
       const effort = opts.effort ?? config.effort;
-      const { system, messages: body } = toAnthropicMessages(messages, id);
+      // Repaired first: a result with no call, a call with no result, or an id
+      // used twice is a 400 that loses the turn. See repairHistory.
+      const sent = repairHistory(messages).messages;
+      const { system, messages: body } = toAnthropicMessages(sent, id);
 
       // Anthropic's own `service_tier` means auto or standard_only, not this.
       if (opts.serviceTier) {
@@ -438,7 +484,7 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
       // ponytail: every loop step after the first goes unthought on these
       // models. The upgrade is replaying the signed thinking blocks.
       const unthought =
-        !claude && model.startsWith("claude-") && (forcesTool || continuesToolLoop(messages));
+        !claude && model.startsWith("claude-") && (forcesTool || continuesToolLoop(sent));
       if (claude) {
         // An effort the caller never set sends nothing: the model keeps its own
         // default, which on most of these is thinking ON.
@@ -476,12 +522,12 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
       let cachedInputTokens = 0;
       let cacheWriteTokens = 0;
       let outputTokens = 0;
-      let toolCall: { index: number; id: string; name: string } | null = null;
+      let toolCall: ToolCallIdentity | null = null;
+      let sawToolCall = false;
       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: {
@@ -510,13 +556,12 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
         ...(opts.signal ? { signal: opts.signal } : {}),
         ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
         ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+        ...(opts.onRateLimit ? { onRateLimit: opts.onRateLimit } : {}),
+        // The stop reason rides in `message_delta` with the final usage, so a
+        // read that dies after it loses nothing but `message_stop`.
+        finished: () => stopped,
       })) {
-        let event: AnthropicEvent;
-        try {
-          event = JSON.parse(data) as AnthropicEvent;
-        } catch {
-          continue; // a keep-alive or a frame we do not model
-        }
+        const event = parseFrame<AnthropicEvent>(data, id);
 
         switch (event.type) {
           // A failure the backend reports after its headers went out. Classified
@@ -542,6 +587,10 @@ export function createAnthropicProvider(config: AnthropicConfig): Provider {
                 id: event.content_block.id ?? "",
                 name: event.content_block.name ?? "",
               };
+              // Checked here, because this block is the only place this shape
+              // states a call's id and name.
+              settleToolCalls(id, [toolCall]);
+              sawToolCall = true;
               yield {
                 type: "delta",
                 toolCalls: [{ index: toolCall.index, id: toolCall.id, name: toolCall.name }],
@@ -577,21 +626,31 @@ 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 };
+            if (event.delta?.stop_reason) {
+              const stated = mapStopReason(id, event.delta.stop_reason);
+              stopped = true;
+              // Anthropic-compatible gateways can end a tool turn on
+              // `end_turn`, and a caller reading that as done never runs the
+              // tool. Only `stop` is promoted: a length cut may be what broke
+              // the call.
+              const finishReason = stated === "stop" && sawToolCall ? "tool_calls" : stated;
+              yield { type: "finish", finishReason };
+            }
             break;
           }
 
+          // The turn's last event, so the reader stops here. Some gateways
+          // append a `[DONE]` or other bytes after it, and a read that died on
+          // those failed an answer that was already whole (Kimi, GLM and
+          // OpenCode Go, measured by cc-proxy).
           case "message_stop":
-            closed = true;
             yield usageChunk();
-            break;
+            return;
         }
       }
-      if (closed) return;
-      // A gateway that states its stop reason and then skips `message_stop`
-      // still finished the turn — and still billed it.
+      // A gateway that states its stop reason and then skips `message_stop`, or
+      // whose socket dies after the reason, still finished the turn, and still
+      // billed it.
       if (stopped) {
         yield usageChunk();
         return;