@providerkit/core 0.23.0 → 0.25.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

@@ -101,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
@@ -206,6 +217,10 @@ function cooldownFor(err: unknown, now: number): { kind: ErrorKind; forMs: numbe
  * 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

@@ -431,6 +431,82 @@ export const PROVIDER_PRESETS = {
     // privacy setting, and answers 500 without it.
     rotation: ["mimo-v2.6-flash", "mimo-v2.5", "glm-5.3-flash", "qwen3.8-flash", "longcat-2.0"],
   },
+  /**
+   * OpenCode Zen: free and pay-as-you-go models on `https://opencode.ai/zen/v1`,
+   * matching cc-proxy's `opencode-zen` provider.
+   *
+   * Free models (`big-pickle` and every `-free` id) lead the list and the default
+   * rotation. Zen's free tier requires the OpenCode CLI headers, a `ses_` session
+   * id and a `read` tool on the request; the factory adds those automatically and
+   * retries a free model anonymously if a stale key answers 401.
+   *
+   * `routes` picks each model's wire from its id: `claude-` and Qwen (except
+   * `qwen3.8-max`) on Anthropic `/v1/messages`, `gpt-`, `grok-` and `muse-` on
+   * `/v1/responses`, `gemini-` on `/v1/models/<id>:streamGenerateContent?alt=sse`,
+   * and everything else on `/v1/chat/completions`.
+   */
+  "opencode-zen": {
+    shape: "openai",
+    baseUrl: "https://opencode.ai/zen/v1",
+    auth: "bearer",
+    defaultModel: "minimax-m3.1-flash-free",
+    models: [
+      "minimax-m3.1-flash-free",
+      "mimo-v2.6-flash-free",
+      "deepseek-v4.1-flash-free",
+      "glm-5.3-flash-free",
+      "big-pickle",
+      "mimo-v2.5-free",
+      "nemotron-3.5-super-vl-free",
+      "nemotron-3.5-lightning-free",
+      "longcat-2.5-preview-free",
+      "beam-free",
+      "ll-alpha-free",
+      "exo-free",
+      "nemotron-3-ultra-free",
+      "claude-sonnet-5-5",
+      "claude-opus-5-5",
+      "claude-fable-5-1",
+      "claude-haiku-5-5",
+      "gpt-6-sol",
+      "gpt-5.6-luna",
+      "gemini-4-argon",
+      "gemini-3.8-flash",
+      "grok-4.7",
+      "glm-5.3-flash",
+      "deepseek-v4.1-flash",
+      "kimi-k3",
+      "minimax-m3",
+      "qwen3.8-flash",
+    ],
+    sessionHeader: "x-opencode-session",
+    routes: [
+      {
+        prefixes: ["claude-", "qwen3.8-flash", "qwen3.7", "qwen3.6", "qwen3.5"],
+        shape: "anthropic",
+        baseUrl: "https://opencode.ai/zen",
+        auth: "key",
+      },
+      {
+        prefixes: ["gpt-", "grok-", "muse-"],
+        shape: "responses",
+        baseUrl: "https://opencode.ai/zen",
+      },
+      {
+        prefixes: ["gemini-"],
+        shape: "gemini",
+        baseUrl: "https://opencode.ai/zen/v1",
+        auth: "key",
+      },
+    ],
+    rotation: [
+      "minimax-m3.1-flash-free",
+      "mimo-v2.6-flash-free",
+      "deepseek-v4.1-flash-free",
+      "big-pickle",
+      "glm-5.3-flash-free",
+    ],
+  },
   kimi: {
     shape: "anthropic",
     baseUrl: "https://api.kimi.ai/coding",
@@ -617,6 +693,30 @@ export const PROVIDER_PRESETS = {
     },
     initiatorHeader: true,
   },
+  /**
+   * Google Antigravity (Cloud Code Assist) OAuth, matching cc-proxy's
+   * `antigravity` provider. Sign in with `createAuthFlow("antigravity", host)`
+   * from `@providerkit/core/auth`, which discovers the Cloud Code Assist
+   * `projectId` and stores it on the credential; `withToken` and `createRegistry`
+   * forward it automatically.
+   */
+  antigravity: {
+    shape: "gemini",
+    baseUrl: "https://daily-cloudcode-pa.googleapis.com",
+    path: "/v1internal:streamGenerateContent?alt=sse",
+    auth: "oauth",
+    defaultModel: "gemini-4-argon",
+    models: [
+      "gemini-4-argon",
+      "gemini-3.8-flash",
+      "gemini-3.7-flash",
+      "gemini-3.1-pro",
+      "claude-opus-5-5",
+      "claude-sonnet-5-5",
+      "claude-sonnet-4-6",
+      "claude-opus-4-6-thinking",
+    ],
+  },
 } as const satisfies Record<string, ProviderPreset>;
 
 export type ProviderPresetId = keyof typeof PROVIDER_PRESETS;

package/src/providers/anthropic.ts

@@ -55,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
@@ -402,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,