@providerkit/core 0.23.0 → 0.25.0

package/src/providers/gemini.ts

@@ -7,7 +7,7 @@
 // and the SDK is a Node-shaped one.
 import { repairHistory } from "../context.ts";
 import { ProviderError, streamCut, streamError, type ErrorKind } from "../errors.ts";
-import { schemaPrompt, toGeminiToolSchema } from "../schema.ts";
+import { schemaPrompt, toAntigravityToolSchema, toGeminiToolSchema } from "../schema.ts";
 import { parseToolArgs, settleToolCalls } from "../tool-args.ts";
 import { streamSse, apiUrl } from "../transport.ts";
 import { withConfiguredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
@@ -28,12 +28,20 @@ export interface GeminiConfig extends ProviderFallbackConfig {
   apiKey: string;
   model: string;
   /** Any endpoint speaking the Generative Language REST dialect, including a proxy or
-   *  gateway. Defaults to the Generative Language API.
-   *
-   *  Not Vertex: it serves `/v1/projects/…/locations/…/publishers/google/models`
-   *  and authenticates with a Bearer token, and both the path and the
-   *  `x-goog-api-key` header are fixed below. Vertex would be its own adapter. */
+   *  gateway. Defaults to the Generative Language API. */
   baseUrl?: string;
+  /** Explicit path override when a backend has custom routing (Antigravity:
+   *  `/v1internal:streamGenerateContent?alt=sse`). */
+  path?: string;
+  /** Send the credential as `Authorization: Bearer` instead of `x-goog-api-key`
+   *  (Antigravity OAuth). */
+  bearer?: boolean;
+  /** Google Antigravity (Cloud Code Assist) project id for the request envelope. */
+  projectId?: string;
+  /** Header that carries `StreamOptions.sessionId`. */
+  sessionHeader?: string;
+  /** The id `sessionHeader` carries when a call has no `sessionId`. */
+  instanceSessionId?: string;
   /** Names the provider in errors and logs. */
   id?: string;
   /** Bound default; a per-call `effort` overrides it. */
@@ -53,23 +61,77 @@ export interface GeminiConfig extends ProviderFallbackConfig {
 }
 
 const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com";
+const ANTIGRAVITY_DAILY_API = "https://daily-cloudcode-pa.googleapis.com";
+const ANTIGRAVITY_PROD_API = "https://cloudcode-pa.googleapis.com";
+const ANTIGRAVITY_IDE_USER_AGENT =
+  "antigravity/ide/2.5.5 (os_type=windows; arch=amd64; aidev_client; auth_method=oauth)";
+const ANTIGRAVITY_CLI_USER_AGENT =
+  "antigravity/cli/1.3.4 (os_type=darwin; arch=arm64; aidev_client; auth_method=oauth)";
+const REJECTED_CLAUDE_SDK_PARAGRAPH =
+  "You are a Claude agent, built on Anthropic's Claude Agent SDK.";
+
+const ANTIGRAVITY_WIRE_MODELS: Record<string, string> = {
+  "gemini-4-argon": "gemini-4-argon-high",
+  "gemini-3.8-flash": "gemini-3.8-flash-medium",
+  "gemini-3.7-flash": "gemini-3.7-flash-tiered",
+  "gemini-3.1-pro": "gemini-pro-agent",
+  "claude-opus-5-5": "claude-opus-5-5-high",
+  "claude-sonnet-5-5": "claude-sonnet-5-5-high",
+};
+
+/** Resolve an Antigravity model id to its Cloud Code Assist wire model id. */
+export function resolveAntigravityWireModel(model: string): string {
+  const stripped = model.replace(/^antigravity\//, "");
+  return ANTIGRAVITY_WIRE_MODELS[stripped] ?? stripped;
+}
+
+/** Deterministic Antigravity session id (`-<uint64>`), matching cc-proxy. */
+export async function antigravitySessionId(sessionId?: string): Promise<string> {
+  const seed = sessionId && sessionId.length > 0 ? sessionId : crypto.randomUUID();
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(seed)),
+  );
+  const view = new DataView(digest.buffer, digest.byteOffset, 8);
+  const masked = view.getBigUint64(0, false) & 0x7fffffffffffffffn;
+  return `-${masked.toString()}`;
+}
+
+function cleanAntigravitySystemText(text: string): string {
+  return text
+    .replace(/^x-anthropic-billing-header:[^\n]*\n*/, "")
+    .split("\n\n")
+    .filter((p) => p !== REJECTED_CLAUDE_SDK_PARAGRAPH)
+    .join("\n\n");
+}
 
 /**
- * Gemini 3's thinking dial. `none` is MINIMAL rather than a 0 budget: the Pro
- * models reject a hard 0, so the only way to say "think as little as possible"
- * without a 400 is the lowest level.
+ * Gemini 3+ thinking dial.
+ *
+ * Measured across all 17 text models on 2026-10-21:
+ * - Only `gemini-3-flash*`, `gemini-3.5-flash*`, `gemini-3.6-flash`, and the
+ *   `flash-lite` models accept `MINIMAL` (which spends 0 thought tokens).
+ * - `gemini-3.7-flash`, `gemini-3.8-flash`, `gemini-4-*`, `gemini-flash-latest`,
+ *   and every Pro model answer `MINIMAL` with `400 Thinking level MINIMAL is not
+ *   supported for this model`, and take `LOW` as their lowest level.
  *
  * Sent as the REST enum NAMES. The SDK's `ThinkingLevel` members serialize to
  * exactly these strings, so nothing is lost by writing them out.
  */
-const THINKING_LEVEL: Record<Effort, string> = {
-  none: "MINIMAL",
+const THINKING_LEVEL: Record<Exclude<Effort, "none">, string> = {
   low: "LOW",
   medium: "MEDIUM",
   high: "HIGH",
   max: "HIGH",
 };
 
+const TAKES_MINIMAL_THINKING =
+  /^gemini-(?:3(?:\.[056])?-flash(?:-preview|-lite(?:-preview)?)?|3\.1-flash-lite(?:-preview)?|flash-lite-latest)$/i;
+
+function geminiThinkingLevel(model: string, effort: Effort): string {
+  if (effort !== "none") return THINKING_LEVEL[effort];
+  return TAKES_MINIMAL_THINKING.test(model) ? "MINIMAL" : "LOW";
+}
+
 /**
  * Gemini 2.x thinking budget dial (tokens). Gemini 2.5 takes `thinkingBudget`
  * (0 disables thinking) and has no level. Every newer model takes
@@ -327,6 +389,9 @@ interface GeminiResponse {
 export function createGeminiProvider(config: GeminiConfig): Provider {
   const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
   const id = config.id ?? "gemini";
+  const isAntigravity = id === "antigravity";
+  const instanceSessionId =
+    config.sessionHeader || isAntigravity ? (config.instanceSessionId ?? crypto.randomUUID()) : "";
 
   const provider: Provider = {
     id,
@@ -347,6 +412,7 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
       // the doubled segment 404s as "model not found" — a confusing way to
       // learn about a prefix.
       const model = (opts.model ?? config.model).replace(/^models\//, "");
+      const wireModel = isAntigravity ? resolveAntigravityWireModel(model) : model;
       const isGemini3 = /gemini-3/i.test(model);
       // Not `!isGemini3`: `gemini-flash-latest` and models newer than 3 are not
       // Gemini 3 either, and they must get a level.
@@ -361,10 +427,10 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
       // No effort means the model's own dynamic thinking. Sending MINIMAL / 0 here
       // would switch that off for a caller who never asked, which is the whole
       // reason the seam treats an absent effort as "never sent".
-      if (effort) {
+      if (effort && !isAntigravity) {
         generationConfig.thinkingConfig = isGemini2
           ? { thinkingBudget: GEMINI_2_THINKING_BUDGET[effort] }
-          : { thinkingLevel: THINKING_LEVEL[effort] };
+          : { thinkingLevel: geminiThinkingLevel(model, effort) };
       }
       // A schema that shares its call with tools pins the decoder, and a pinned
       // decoder cannot emit a functionCall — the model narrates the call it
@@ -399,8 +465,9 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
       // The prompt-carried schema rides as a second part, after the caller's
       // own text: this shape's cache is a prefix too, so a per-call schema in
       // front of the conversation would cold-start it on every change.
+      const cleanedSystem = system && isAntigravity ? cleanAntigravitySystemText(system) : system;
       const systemParts = [
-        ...(system ? [{ text: system }] : []),
+        ...(cleanedSystem ? [{ text: cleanedSystem }] : []),
         ...(opts.json && promptCarried ? [{ text: schemaPrompt(opts.json.schema) }] : []),
       ];
       if (systemParts.length > 0) request.systemInstruction = { parts: systemParts };
@@ -420,9 +487,12 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
             functionDeclarations: tools.map((tool) => ({
               name: tool.name,
               description: tool.description,
-              // Same rule as the response schema: `parameters` is the trimmed
-              // dialect, `parametersJsonSchema` is the schema we actually wrote.
-              parametersJsonSchema: toGeminiToolSchema(tool.inputSchema),
+              // Antigravity (Cloud Code Assist) still expects the OpenAPI-subset
+              // `parameters` field; the Gemini API and OpenCode Zen take standard
+              // JSON Schema in `parametersJsonSchema` (cc-proxy 0.2.8).
+              ...(isAntigravity
+                ? { parameters: toAntigravityToolSchema(tool.inputSchema) }
+                : { parametersJsonSchema: toGeminiToolSchema(tool.inputSchema) }),
             })),
           },
         ];
@@ -432,119 +502,198 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
         if (toolConfig) request.toolConfig = toolConfig;
       }
 
-      // Gemini reports the finish reason on a candidate that can arrive AFTER
-      // the chunk carrying the function calls, so a turn's tool use has to be
-      // remembered rather than read off the final chunk.
-      let sawFunctionCalls = false;
-      let callIndex = 0;
-      let finished = false;
+      const rawHeaders = { ...config.headers };
+      const headerProjectId = rawHeaders["x-antigravity-project"];
+      delete rawHeaders["x-antigravity-project"];
 
-      for await (const data of streamSse({
-        // Without `?alt=sse` the response is one long JSON array that only
-        // parses once complete, which is not a stream.
-        url: apiUrl(baseUrl, `/v1beta/models/${model}:streamGenerateContent?alt=sse`),
-        headers: { "x-goog-api-key": config.apiKey, ...config.headers },
-        body: request,
-        provider: id,
-        ...(opts.signal ? { signal: opts.signal } : {}),
-        ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
-        ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
-        ...(opts.onRateLimit ? { onRateLimit: opts.onRateLimit } : {}),
-        // This wire has no terminal event to stop at, so the finish reason is
-        // the end: a read that dies after it can cost a late usage record, never
-        // the answer.
-        finished: () => finished,
-      })) {
-        let chunk: GeminiResponse;
-        try {
-          chunk = JSON.parse(data) as GeminiResponse;
-        } catch {
-          continue;
-        }
-
-        // `?alt=sse` commits to 200 the moment the headers go out, so a
-        // 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;
-          yield {
-            type: "usage",
-            usage: {
-              inputTokens: usage.promptTokenCount ?? 0,
-              // Thoughts bill as OUTPUT, and Gemini reports them OUTSIDE
-              // candidatesTokenCount — leaving them out undercounts a thinking
-              // turn by most of what it cost.
-              outputTokens: (usage.candidatesTokenCount ?? 0) + (usage.thoughtsTokenCount ?? 0),
-              cachedInputTokens: usage.cachedContentTokenCount ?? 0,
-              ...(usage.thoughtsTokenCount !== undefined
-                ? { reasoningTokens: usage.thoughtsTokenCount }
-                : {}),
-            },
-          };
+      let wireBody: Record<string, unknown> = request;
+      if (isAntigravity) {
+        request.sessionId = await antigravitySessionId(opts.sessionId ?? instanceSessionId);
+        if (wireModel.includes("claude") && !request.toolConfig) {
+          request.toolConfig = { functionCallingConfig: { mode: "VALIDATED" } };
         }
+        wireBody = {
+          model: wireModel,
+          userAgent: "antigravity",
+          requestType: "agent",
+          project: config.projectId ?? headerProjectId ?? "",
+          requestId: `agent-${crypto.randomUUID()}`,
+          request,
+        };
+      }
 
-        const candidate = chunk.candidates?.[0];
-        if (!candidate) continue;
-
-        // One chunk can carry several parts of each kind. They are coalesced
-        // per kind so the seam sees one reasoning delta and one content delta
-        // per chunk, in that order, rather than interleaved fragments.
-        let reasoning = "";
-        let content = "";
-        const toolCalls: ToolCallDelta[] = [];
-        for (const part of candidate.content?.parts ?? []) {
-          if (part.text) {
-            if (part.thought) reasoning += part.text;
-            else content += part.text;
-            continue;
+      const versionedBase = /\/v\d+[^/]*$/i.test(baseUrl.replace(/\/+$/, ""));
+      const defaultPath = `${versionedBase ? "" : "/v1beta"}/models/${model}:streamGenerateContent?alt=sse`;
+      const path = config.path ?? defaultPath;
+      const useBearer = config.bearer || isAntigravity;
+      const authHeader: Record<string, string> = config.apiKey
+        ? useBearer
+          ? { authorization: `Bearer ${config.apiKey}` }
+          : { "x-goog-api-key": config.apiKey }
+        : {};
+      const antigravityUa: Record<string, string> = isAntigravity
+        ? {
+            "user-agent": wireModel.startsWith("gemini-4-argon")
+              ? ANTIGRAVITY_CLI_USER_AGENT
+              : ANTIGRAVITY_IDE_USER_AGENT,
           }
-          const call = part.functionCall;
-          if (!call) continue;
-          const index = callIndex++;
-          const identity = { index, id: call.id ?? "", name: call.name ?? "" };
-          // The part is the whole call, so it is settled here: one with no
-          // name can't run, and one with no id gets one the way the other
-          // three wires mint it. Gemini omits the id on a single-call turn, and
-          // the seam's consumers pair a result back to its call by id.
-          settleToolCalls(id, [identity]);
-          toolCalls.push({
-            ...identity,
-            // Whole and already assembled — unlike the OpenAI shape, Gemini
-            // never fragments an argument object across chunks.
-            arguments: JSON.stringify(call.args ?? {}),
-            ...(part.thoughtSignature ? { thoughtSignature: part.thoughtSignature } : {}),
-          });
-        }
+        : {};
+      const headers: Record<string, string> = {
+        ...antigravityUa,
+        ...authHeader,
+        ...rawHeaders,
+        ...(config.sessionHeader
+          ? { [config.sessionHeader]: opts.sessionId ?? instanceSessionId }
+          : {}),
+      };
+
+      const bases =
+        isAntigravity && baseUrl.replace(/\/+$/, "") === ANTIGRAVITY_DAILY_API
+          ? [ANTIGRAVITY_DAILY_API, ANTIGRAVITY_PROD_API]
+          : [baseUrl];
 
-        if (reasoning) yield { type: "delta", reasoning };
-        if (content) yield { type: "delta", content };
-        if (toolCalls.length > 0) {
-          sawFunctionCalls = true;
-          yield { type: "delta", toolCalls };
-        }
+      let sawFunctionCalls = false;
+      let callIndex = 0;
+      let finished = false;
+      let emitted = false;
 
-        if (candidate.finishReason) {
-          // Mapped first: a reason that throws must not be dressed as tool_calls.
-          const finishReason = mapFinishReason(id, candidate.finishReason);
-          finished = true;
-          yield {
-            type: "finish",
-            // Gemini routinely reports STOP on a turn that called tools, and a
-            // caller reading that as "done" drops the tool round entirely.
-            // Only STOP is promoted, as on the other three wires: a length cut
-            // or a filter may be what broke the call (invariant 10).
-            finishReason: sawFunctionCalls && finishReason === "stop" ? "tool_calls" : finishReason,
-          };
+      for (let baseIdx = 0; baseIdx < bases.length; baseIdx++) {
+        const currentBase = bases[baseIdx]!;
+        try {
+          for await (const data of streamSse({
+            // Without `?alt=sse` the response is one long JSON array that only
+            // parses once complete, which is not a stream.
+            url: apiUrl(currentBase, path),
+            headers,
+            body: wireBody,
+            provider: id,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
+            ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+            ...(opts.onRateLimit ? { onRateLimit: opts.onRateLimit } : {}),
+            // This wire has no terminal event to stop at, so the finish reason is
+            // the end: a read that dies after it can cost a late usage record, never
+            // the answer.
+            finished: () => finished,
+          })) {
+            let parsed: GeminiResponse & { response?: GeminiResponse };
+            try {
+              parsed = JSON.parse(data) as GeminiResponse & { response?: GeminiResponse };
+            } catch {
+              continue;
+            }
+            const chunk = parsed.response ?? parsed;
+
+            // `?alt=sse` commits to 200 the moment the headers go out, so a
+            // 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;
+              emitted = true;
+              yield {
+                type: "usage",
+                usage: {
+                  inputTokens: usage.promptTokenCount ?? 0,
+                  // Thoughts bill as OUTPUT, and Gemini reports them OUTSIDE
+                  // candidatesTokenCount — leaving them out undercounts a thinking
+                  // turn by most of what it cost.
+                  outputTokens: (usage.candidatesTokenCount ?? 0) + (usage.thoughtsTokenCount ?? 0),
+                  cachedInputTokens: usage.cachedContentTokenCount ?? 0,
+                  ...(usage.thoughtsTokenCount !== undefined
+                    ? { reasoningTokens: usage.thoughtsTokenCount }
+                    : {}),
+                },
+              };
+            }
+
+            const candidate = chunk.candidates?.[0];
+            if (!candidate) continue;
+
+            // One chunk can carry several parts of each kind. They are coalesced
+            // per kind so the seam sees one reasoning delta and one content delta
+            // per chunk, in that order, rather than interleaved fragments.
+            let reasoning = "";
+            let content = "";
+            const toolCalls: ToolCallDelta[] = [];
+            for (const part of candidate.content?.parts ?? []) {
+              if (part.text) {
+                if (part.thought) reasoning += part.text;
+                else content += part.text;
+                continue;
+              }
+              const call = part.functionCall;
+              if (!call) continue;
+              const index = callIndex++;
+              const identity = { index, id: call.id ?? "", name: call.name ?? "" };
+              // The part is the whole call, so it is settled here: one with no
+              // name can't run, and one with no id gets one the way the other
+              // three wires mint it. Gemini omits the id on a single-call turn, and
+              // the seam's consumers pair a result back to its call by id.
+              settleToolCalls(id, [identity]);
+              toolCalls.push({
+                ...identity,
+                // Whole and already assembled — unlike the OpenAI shape, Gemini
+                // never fragments an argument object across chunks.
+                arguments: JSON.stringify(call.args ?? {}),
+                ...(part.thoughtSignature ? { thoughtSignature: part.thoughtSignature } : {}),
+              });
+            }
+
+            if (reasoning) {
+              emitted = true;
+              yield { type: "delta", reasoning };
+            }
+            if (content) {
+              emitted = true;
+              yield { type: "delta", content };
+            }
+            if (toolCalls.length > 0) {
+              sawFunctionCalls = true;
+              emitted = true;
+              yield { type: "delta", toolCalls };
+            }
+
+            if (candidate.finishReason) {
+              // Mapped first: a reason that throws must not be dressed as tool_calls.
+              const finishReason = mapFinishReason(id, candidate.finishReason);
+              finished = true;
+              emitted = true;
+              yield {
+                type: "finish",
+                // Gemini routinely reports STOP on a turn that called tools, and a
+                // caller reading that as "done" drops the tool round entirely.
+                // Only STOP is promoted, as on the other three wires: a length cut
+                // or a filter may be what broke the call (invariant 10).
+                finishReason:
+                  sawFunctionCalls && finishReason === "stop" ? "tool_calls" : finishReason,
+              };
+            }
+          }
+          break;
+        } catch (err) {
+          const canFallback =
+            !emitted &&
+            baseIdx === 0 &&
+            bases.length > 1 &&
+            err instanceof ProviderError &&
+            (err.status === 403 ||
+              err.status === 404 ||
+              err.status === 500 ||
+              err.status === 502 ||
+              err.status === 503 ||
+              err.status === 504);
+          if (canFallback) continue;
+          throw err;
         }
       }
       // Gemini states a finish reason on the last candidate of every turn it

package/src/providers/openai.ts

@@ -107,6 +107,13 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    *  no sessionId, the provider's own per-instance id rides instead, so the
    *  gateway never sees a call without one. */
   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;
   /** Send `X-Initiator`: `user` when the last message is the user's, else
    *  `agent`. GitHub Copilot bills a premium request per `user` turn and lets
    *  the agent's own follow-ups (tool results) ride free. */
@@ -315,7 +322,9 @@ function goEffortParams(effort: Effort, model = ""): Record<string, unknown> {
   if (/glm-5[-.p]?[23]/.test(id)) {
     return level(effort === "max" ? "max" : "high");
   }
-  if (id.includes("deepseek-v4")) return level(effort === "none" ? "low" : effort);
+  if (id.includes("deepseek-v4") || id.includes("minimax")) {
+    return level(effort === "none" ? "low" : effort);
+  }
   if (id.includes("mimo"))
     return effort === "max" ? refuse("none, low, medium or high") : level(effort);
   return level(effort === "max" ? "high" : effort);
@@ -326,7 +335,7 @@ function goEffortParams(effort: Effort, model = ""): Record<string, unknown> {
 function dialectFor(id: string): EffortDialect {
   if (id === "openrouter") return "openrouter";
   if (id === "deepseek") return "deepseek";
-  if (id === "opencode-go") return "opencode-go";
+  if (id === "opencode-go" || id === "opencode-zen") return "opencode-go";
   return "openai";
 }
 
@@ -531,7 +540,9 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
   // `usage.cost` is its field in its unit. Another gateway that sends a
   // `cost` has not said what it means.
   const reportsCost = isOpenRouter(baseUrl);
-  const instanceSessionId = config.sessionHeader ? crypto.randomUUID() : undefined;
+  const instanceSessionId = config.sessionHeader
+    ? (config.instanceSessionId ?? crypto.randomUUID())
+    : undefined;
 
   const provider: Provider = {
     id,
@@ -658,7 +669,7 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
       for await (const data of streamSse({
         url: apiUrl(baseUrl, config.path ?? defaultPath),
         headers: {
-          authorization: `Bearer ${config.apiKey}`,
+          ...(config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}),
           ...attributionHeaders(config, config.headers),
           ...(config.sessionHeader
             ? { [config.sessionHeader]: opts.sessionId ?? instanceSessionId }

package/src/providers/responses.ts

@@ -48,6 +48,17 @@ export interface ResponsesConfig 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`.
+   *
+   *  It is not sent as `prompt_cache_key`, which stays the per-call
+   *  `sessionId`'s: this id names the adapter, so it is shared by every
+   *  conversation the adapter serves, and a minted one never was a cache key. */
+  instanceSessionId?: string;
   /**
    * Where this backend serves the endpoint, when it is not `/v1/responses`.
    * The ChatGPT subscription surface serves it at `/backend-api/codex/responses`
@@ -395,7 +406,9 @@ function unsentTail(snapshot: string, streamed: string): string {
 export function createResponsesProvider(config: ResponsesConfig): Provider {
   const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
   const id = config.id ?? "openai-responses";
-  const instanceSessionId = config.sessionHeader ? crypto.randomUUID() : undefined;
+  const instanceSessionId = config.sessionHeader
+    ? (config.instanceSessionId ?? crypto.randomUUID())
+    : undefined;
 
   const provider: Provider = {
     id,