@providerkit/core 0.22.0 → 0.24.0

package/src/gate.ts

@@ -0,0 +1,152 @@
+// How many calls run at once on one connection.
+//
+// A flat-rate plan caps concurrent requests, and says so only by failing: six
+// calls at once on one Z.ai Coding Plan key came back with some 429s (measured
+// 2026-09-25, `capability.ts`). Behind a fallback chain the overflow is
+// answered by the NEXT model, so the cap shows up as a quietly different
+// answer, not as an error. The capability probe runs one call at a time for
+// that reason, and one adopter runs its batches one item at a time on purpose.
+// A gate holds the overflow in a queue instead, and lets each call in as a
+// slot frees.
+//
+// The hard part is giving the slot back. A slot leaked by an abandoned stream
+// is gone for the life of the process, with no error anywhere: the connection
+// just serves one call fewer, until it serves none. So the slot is taken on the
+// first read (a stream nobody reads holds nothing) and released exactly once,
+// on whichever comes first: the stream ends, throws or is returned, or its
+// signal aborts. That last one matters when the consumer holds a stream and
+// stops reading it. Nothing else would ever free that slot.
+//
+// ponytail: three known ceilings.
+// - It counts one process only. Two replicas each let `max` calls through. The
+//   upgrade path is a shared counter (one adopter already keeps one in Redis).
+// - A full gate makes callers wait instead of moving on to the next candidate
+//   in a fallback chain. The upgrade is a bounded wait that fails as transient,
+//   so the pool tries the next one.
+// - A fallback probe stuck waiting here has no first chunk, so once it goes
+//   stale (`probeStaleMs`) the pool can let one extra probe in beside it.
+import type {
+  ChatMessage,
+  Provider,
+  ProviderChunk,
+  StreamOptions,
+  ToolDefinition,
+} from "./types.ts";
+
+export interface Gate {
+  /** How many calls may hold a slot at once. */
+  readonly max: number;
+  /** How many slots are held right now. */
+  readonly held: number;
+  /** How many calls are queued for a slot. */
+  readonly waiting: number;
+  /**
+   * Wait for a slot, first in, first out. Resolves to its release, which is
+   * safe to call more than once. The signal covers the whole life of the slot:
+   * an abort while waiting leaves the queue and rejects with `signal.reason`,
+   * and an abort while held releases it.
+   */
+  acquire(signal?: AbortSignal): Promise<() => void>;
+}
+
+/** A gate with `max` slots. Keep one alive per connection, so every call on
+ *  it shares the count. */
+export function createGate(max: number): Gate {
+  if (!Number.isInteger(max) || max < 1) {
+    throw new Error(`[providerkit] A gate needs a whole number of slots, 1 or more. Got ${max}.`);
+  }
+
+  let held = 0;
+  const queue: Array<() => void> = [];
+
+  function acquire(signal?: AbortSignal): Promise<() => void> {
+    // Rejected before it queues: a caller already gone must not take a place
+    // in line, or a slot, even for a moment.
+    if (signal?.aborted) return Promise.reject(signal.reason);
+
+    return new Promise((resolve, reject) => {
+      let state: "waiting" | "held" | "released" = "waiting";
+
+      const release = () => {
+        if (state !== "held") return;
+        state = "released";
+        signal?.removeEventListener("abort", onAbort);
+        // Handed straight to the next waiter, so `held` never dips and a
+        // newcomer arriving now finds the gate full and queues behind them.
+        const next = queue.shift();
+        if (next) next();
+        else held--;
+      };
+
+      const grant = () => {
+        state = "held";
+        resolve(release);
+      };
+
+      function onAbort() {
+        if (state === "held") {
+          release();
+        } else if (state === "waiting") {
+          state = "released";
+          queue.splice(queue.indexOf(grant), 1);
+          reject(signal?.reason);
+        }
+      }
+
+      if (held < max) {
+        held++;
+        grant();
+      } else {
+        queue.push(grant);
+      }
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+
+  return {
+    max,
+    get held() {
+      return held;
+    },
+    get waiting() {
+      return queue.length;
+    },
+    acquire,
+  };
+}
+
+/**
+ * Let a provider run at most `gate.max` calls at once.
+ *
+ * Put it outside the watchdog. The watchdog arms on its first read, and this
+ * reads it only once a slot is held, so a call queued here never spends its
+ * deadlines waiting. Inside it, a call that stood in line for five minutes
+ * would time out as a silent provider before it ever sent a byte.
+ */
+export function withGate(provider: Provider, gate: Gate): Provider {
+  return {
+    ...provider,
+    createStream(
+      messages: ChatMessage[],
+      tools: ToolDefinition[],
+      opts: StreamOptions = {},
+    ): AsyncIterable<ProviderChunk> {
+      // A generator, so nothing runs (the wait included) until the first read.
+      async function* gated(): AsyncGenerator<ProviderChunk> {
+        const release = await gate.acquire(opts.signal);
+        try {
+          // The slot can be granted and released by the same abort before this
+          // line runs (two calls sharing one signal). Such a call is over, and
+          // must not reach the wire without a slot.
+          opts.signal?.throwIfAborted();
+          yield* provider.createStream(messages, tools, opts);
+        } finally {
+          // Covers the end, a throw and a consumer's `break`. An abort may
+          // have released it already, and a second call is a no-op.
+          release();
+        }
+      }
+      return gated();
+    },
+  };
+}

package/src/index.ts

@@ -1,9 +1,11 @@
 export * from "./types.ts";
+export * from "./turn.ts";
 export * from "./errors.ts";
 export * from "./retry.ts";
 export * from "./fallback.ts";
 export * from "./key-pool.ts";
 export * from "./watchdog.ts";
+export * from "./gate.ts";
 export * from "./usage.ts";
 export * from "./transport.ts";
 export * from "./rate-limit.ts";
@@ -21,3 +23,4 @@ export * from "./providers/responses.ts";
 export * from "./providers/gemini.ts";
 export * from "./providers/zai.ts";
 export * from "./providers/factory.ts";
+export * from "./registry.ts";

package/src/key-pool.ts

@@ -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;
   }
@@ -93,6 +101,17 @@ export class KeyPool {
     return this.free.length + (this.paid ? 1 : 0);
   }
 
+  /** Each key's tier and when it is back (0 = serving now): free keys in
+   *  config order, then the paid one. Never the key itself, so a status page
+   *  can show it as is. */
+  status(): Array<{ tier: KeyTier; evictedUntil: number }> {
+    const now = this.now();
+    return [...this.free, ...(this.paid ? [this.paid] : [])].map(({ tier, evictedUntil }) => ({
+      tier,
+      evictedUntil: evictedUntil > now ? evictedUntil : 0,
+    }));
+  }
+
   /**
    * Run `fn` with the next available key, rotating on key-specific and
    * transient failures. Everything else (a bad request, a content block) throws
@@ -101,7 +120,7 @@ export class KeyPool {
    */
   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 +131,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 +139,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,9 +156,10 @@ 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());
   }
 }
 
@@ -149,15 +168,24 @@ export class KeyPool {
  * 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.
@@ -189,6 +217,10 @@ function cooldownFor(err: unknown): { kind: ErrorKind; forMs: number } | null {
  * committed to one key, exactly as a retry is committed past its first chunk
  * (retry.ts, rule 2): a mid-stream 429 evicts nothing and rotates nothing,
  * because there is no way to resume a half-rendered answer on another key.
+ *
+ * The factory runs once per attempt. An adapter with a session header mints
+ * its id when it is built, so give the factory an `instanceSessionId`, or each
+ * attempt opens a new session on a gateway that pins sessions to one host.
  */
 export function withKeyPool(pool: KeyPool, factory: (apiKey: string) => Provider): Provider {
   // The identity every key shares. Building an adapter performs no I/O — it

package/src/presets.ts

@@ -373,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
@@ -408,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",

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 {
@@ -54,6 +55,13 @@ export interface AnthropicConfig extends ProviderFallbackConfig {
   /** Header that carries `StreamOptions.sessionId`. When set and a call has no
    *  sessionId, one stable id for this provider instance rides instead. */
   sessionHeader?: string;
+  /** The id `sessionHeader` carries when a call has no `sessionId`. Absent, the
+   *  adapter mints one when it is built. Pass one when something rebuilds the
+   *  adapter (`withKeyPool` and `withToken` build one per attempt): each build
+   *  mints a new id, and a gateway that pins a session to one upstream host
+   *  then treats every call as a new session, re-routes it and misses its
+   *  prompt cache. Ignored without `sessionHeader`. */
+  instanceSessionId?: 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
@@ -191,19 +199,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,
+      });
   }
 }
 
@@ -270,6 +291,34 @@ 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 +326,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 +349,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 +369,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),
       });
@@ -359,7 +409,9 @@ interface AnthropicEvent {
 export function createAnthropicProvider(config: AnthropicConfig): Provider {
   const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
   const id = config.id ?? "anthropic";
-  const instanceSessionId = config.sessionHeader ? crypto.randomUUID() : undefined;
+  const instanceSessionId = config.sessionHeader
+    ? (config.instanceSessionId ?? crypto.randomUUID())
+    : undefined;
 
   const provider: Provider = {
     id,
@@ -373,7 +425,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 +493,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 +531,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 +565,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 +596,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 +635,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;

package/src/providers/factory.ts

@@ -46,6 +46,17 @@ export interface PresetProviderConfig extends ProviderFallbackConfig {
   /** Per-request headers (request ids, `ChatGPT-Account-Id`) on top of the
    *  preset's static protocol headers. */
   headers?: Record<string, string>;
+  /**
+   * The session id for a call without `StreamOptions.sessionId`, on a preset
+   * that sends one (`opencode-go`, `chatgpt`). Absent, the provider mints its
+   * own when it is built. Pass one when you build the provider per attempt
+   * (`withKeyPool`, `withToken`): each build would mint a new id, and a gateway
+   * that pins a session to one upstream host then treats every call as a new
+   * session, re-routes it and misses its prompt cache. Every model in a chain
+   * sends the same one. A preset without a session header has nowhere to put
+   * it and ignores it.
+   */
+  instanceSessionId?: string;
   /**
    * App attribution for OpenRouter's rankings. The site URL rides as
    * `HTTP-Referer`, the app name as `X-Title`. Public, not secret. Sent on
@@ -69,15 +80,15 @@ export interface PresetProviderConfig extends ProviderFallbackConfig {
   fetchImpl?: typeof fetch;
 }
 
+/** What one adapter for one model takes: a `PresetProviderConfig` without the
+ *  chain (`models`) and without the layers that go around an adapter. */
+export type PresetAdapterConfig = Omit<
+  PresetProviderConfig,
+  "models" | keyof ProviderFallbackConfig
+>;
+
 export function createPresetProvider(id: ProviderPresetId, config: PresetProviderConfig): Provider {
-  // The table is closed (`satisfies`), but a caller may hold an id as a plain
-  // string — validate rather than index into undefined.
-  if (!(id in PROVIDER_PRESETS)) {
-    throw new Error(
-      `[providerkit] Unknown provider preset "${id}". Valid ids: ${PRESET_IDS.join(", ")}`,
-    );
-  }
-  const preset: ProviderPreset = PROVIDER_PRESETS[id];
+  const preset = presetFor(id);
   const chain = config.models?.length ? config.models : config.model ? undefined : preset.rotation;
   if (chain && chain.length > 1) {
     const { models: _models, fallbacks = [], ...single } = config;
@@ -90,7 +101,27 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
       ],
     });
   }
-  const model = chain?.[0] ?? config.model ?? preset.defaultModel;
+  const { models: _models, ...single } = config;
+  return withConfiguredFallbacks(
+    presetAdapter(id, { ...single, model: chain?.[0] ?? config.model }),
+    config,
+  );
+}
+
+/**
+ * The bare adapter for one preset and one model: the wire that serves the
+ * model, its auth style and the preset's quirks, and nothing around them. No
+ * fallbacks, no watchdog, no `models` chain. A registry builds one per
+ * (connection, model) and puts those layers around all of them once; calling
+ * `createPresetProvider` per model would nest a second pool and a second
+ * watchdog inside its own.
+ *
+ * The adapter's `id` is the preset id, because the OpenAI shape reads its
+ * effort dialect from it (`opencode-go`, `openrouter`, `deepseek`).
+ */
+export function presetAdapter(id: ProviderPresetId, config: PresetAdapterConfig): Provider {
+  const preset = presetFor(id);
+  const model = config.model ?? preset.defaultModel;
   if (!model) {
     throw new Error(`[providerkit] Preset "${id}" has no defaultModel. Pass a model.`);
   }
@@ -104,14 +135,16 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
   const headers = { ...preset.headers, ...config.headers };
   const baseUrl = config.baseUrl ?? wire.baseUrl;
   const maxTokens = config.maxTokens ?? preset.maxTokens;
-
-  const {
-    fallbacks: _fallbacks,
-    fallbackOptions: _fallbackOptions,
-    watchdog: _watchdog,
-    models: _models,
-    ...baseConfig
-  } = config;
+  // Every adapter builds its own pool and watchdog from these. The type leaves
+  // them out, but a wider object (a whole `PresetProviderConfig` in a variable)
+  // can still carry them, and the adapter would nest a second pool and a
+  // second watchdog inside the caller's. Cleared, it stays bare.
+  const baseConfig = {
+    ...config,
+    fallbacks: undefined,
+    fallbackOptions: undefined,
+    watchdog: undefined,
+  };
 
   let provider: Provider;
   switch (wire.shape) {
@@ -184,10 +217,22 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
       break;
   }
 
-  return withConfiguredFallbacks(
-    preset.routes ? refuseOtherWires(provider, preset, wire) : provider,
-    config,
-  );
+  // Here rather than in `createPresetProvider`: the wire is resolved here, and
+  // the bare adapter is exported, so it must refuse on its own a per-call model
+  // it would post to the wrong endpoint. That 404 reads as an unknown model,
+  // and a pool benches the model for an hour.
+  return preset.routes ? refuseOtherWires(provider, preset, wire) : provider;
+}
+
+/** The table is closed (`satisfies`), but a caller may hold an id as a plain
+ *  string. Validate rather than index into undefined. */
+function presetFor(id: ProviderPresetId): ProviderPreset {
+  if (!(id in PROVIDER_PRESETS)) {
+    throw new Error(
+      `[providerkit] Unknown provider preset "${id}". Valid ids: ${PRESET_IDS.join(", ")}`,
+    );
+  }
+  return PROVIDER_PRESETS[id];
 }
 
 /** The endpoint a model is served from: its route when the preset has one for