@providerkit/core 0.21.0 → 0.22.0

package/src/jev.ts

@@ -34,7 +34,7 @@ export type JevInstructions = string | Record<string, unknown> | readonly unknow
 export interface ChoiceQuestion<Option extends string = string> {
   type: "choice";
   instructions?: JevInstructions;
-  /** Each option, mapped to what it means — `null` when its name says it all.
+  /** Each option, mapped to what it means. Use `null` when its name says it all.
    *  TypeSafe takes up to 255. */
   criteria: Record<Option, unknown>;
 }
@@ -64,7 +64,7 @@ export interface ChoiceAnswer<Option extends string = string> {
    *  because a caller acting on it needs more than the pick: the runner-up,
    *  P(yes) when the pick was no, a joint probability across two questions. */
   probabilities: Record<Option, number>;
-  /** How peaked `probabilities` is, 0 to 1 — NOT the probability of the pick.
+  /** How peaked `probabilities` is, from 0 to 1. Not the probability of the pick.
    *  TypeSafe's own example spreads 0.57 / 0.43 and reports 0.35, so reading
    *  it as P(pick) would put the pick below the option it beat. Null when the
    *  host sent none. */
@@ -90,7 +90,7 @@ export interface ScoreAnswer {
 
 export type JevAnswer = ChoiceAnswer | NoulAnswer | ScoreAnswer;
 
-/** The answer type a question gets back — a choice's options carry through. */
+/** The answer type a question gets back. A choice's options carry through. */
 export type AnswerTo<Q> =
   Q extends ChoiceQuestion<infer Option extends string>
     ? ChoiceAnswer<Option>
@@ -101,12 +101,12 @@ export type AnswerTo<Q> =
         : never;
 
 export interface JevReply<Q extends Record<string, JevQuestion>> {
-  /** One per question — `null` when that answer did not pass the checks in
+  /** One per question. `null` when that answer did not pass the checks in
    *  `readAnswer`. Each fails alone: in a fan-out, a malformed answer to a
    *  question the caller never acts on must not cost the one it does. */
   answers: { [Id in keyof Q]: AnswerTo<Q[Id]> | null };
   usage: TokenUsage;
-  /** The model that answered, as the host names it — `jev-1.13.0` on
+  /** The model that answered, as the host names it: `jev-1.13.0` on
    *  TypeSafe, `typesafe/jev-1.13-20260917` on OpenRouter. */
   model: string;
 }
@@ -139,8 +139,8 @@ export interface JevClient {
   ): Promise<JevReply<Q>>;
   /** Proves the key, the account and the model work, with one real question:
    *  about 40 input tokens, a few millionths of a dollar. A free read (a
-   *  model list, a balance) proves only the key — not that this account can
-   *  run this model — and Vercel has none. Throws the classified failure. */
+   *  model list, a balance) proves only the key, not that this account can
+   *  run this model. Vercel has no such free read. Throws the classified failure. */
   checkKey(opts?: { signal?: AbortSignal }): Promise<void>;
 }
 
@@ -158,7 +158,7 @@ interface HostRow {
   url(config: JevConfig): string;
   headers(config: JevConfig, model: string): Record<string, string>;
   body(model: string, state: unknown, questions: Record<string, JevQuestion>): unknown;
-  /** The reply in TypeSafe's own shape — `{ model, answers, usage }` —
+  /** The reply in TypeSafe's own shape (`{ model, answers, usage }`),
    *  whatever the host wrapped it in. */
   unwrap(json: unknown): Record<string, unknown> | undefined;
 }
@@ -228,7 +228,7 @@ const HOSTS: Record<JevHost, HostRow> = {
  * `providerMetadata.typesafe.confidence`, and usage is camelCase.
  *
  * ponytail: read from @jkudish/jev-agent-tools' adapter, not from a recorded
- * reply — no Vercel key has run it here. If a real reply disagrees, this
+ * reply. No Vercel key has run it here. If a real reply disagrees, this
  * function is the whole fix.
  */
 function fromVercel(json: unknown): Record<string, unknown> | undefined {
@@ -282,7 +282,7 @@ function distribution(value: unknown, keys: readonly string[]): Record<string, n
 }
 
 /**
- * One answer, checked against the question that asked it — or null.
+ * One answer, checked against the question that asked it, or null.
  *
  * A Jev answer usually becomes an action (a click, a label, a route), so it is
  * read fail-closed: the right type; for a choice, a pick among the offered
@@ -291,7 +291,7 @@ function distribution(value: unknown, keys: readonly string[]): Record<string, n
  * the pick.
  *
  * `ask` runs this on every answer. It is exported for the app that has to
- * keep its own request — its own error copy, its own auth refresh — and can
+ * keep its own request (its own error copy, its own auth refresh) and can
  * still take the checks.
  */
 export function readAnswer<Q extends JevQuestion>(question: Q, raw: unknown): AnswerTo<Q> | null;

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
@@ -96,7 +96,7 @@ 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> {
@@ -146,7 +146,7 @@ export class KeyPool {
 
 /**
  * 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 {
@@ -179,8 +179,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.
    *
@@ -431,7 +435,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 +443,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 +451,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 +459,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 +505,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 +544,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 +572,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 +611,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

@@ -21,7 +21,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 +38,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 +48,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 +72,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 +102,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);
@@ -233,13 +233,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 +247,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,7 +263,7 @@ 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 {

package/src/providers/factory.ts

@@ -47,7 +47,7 @@ export interface PresetProviderConfig extends ProviderFallbackConfig {
    *  preset's static protocol headers. */
   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 on
    * the OpenAI-compatible and Anthropic shapes (OpenRouter reads them for app
    * attribution); the Gemini and Responses shapes ignore them. An explicit
@@ -60,7 +60,7 @@ export interface PresetProviderConfig extends ProviderFallbackConfig {
   siteName?: string;
   /** OpenRouter-only: preferred upstream hosts, in order. OpenRouter's cache
    *  lives on the upstream host's account and default routing hops hosts
-   *  between rounds — pinning keeps a conversation's rounds (and their cache)
+   *  between rounds. Pinning keeps a conversation's rounds (and their cache)
    *  on one host. Empty/absent = default routing. */
   providerOrder?: string[];
   /** Default `service_tier` for every call on the OpenAI and Responses shapes;
@@ -92,7 +92,7 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
   }
   const model = chain?.[0] ?? config.model ?? preset.defaultModel;
   if (!model) {
-    throw new Error(`[providerkit] Preset "${id}" has no defaultModel — pass a model.`);
+    throw new Error(`[providerkit] Preset "${id}" has no defaultModel. Pass a model.`);
   }
   const wire = wireFor(preset, model);
   if (config.serviceTier && (wire.shape === "anthropic" || wire.shape === "gemini")) {
@@ -149,6 +149,7 @@ export function createPresetProvider(id: ProviderPresetId, config: PresetProvide
         ...(config.providerOrder ? { providerOrder: config.providerOrder } : {}),
         ...(preset.sessionHeader ? { sessionHeader: preset.sessionHeader } : {}),
         ...(preset.initiatorHeader ? { initiatorHeader: true } : {}),
+        ...(preset.noSampling ? { noSampling: true } : {}),
         fetchImpl: config.fetchImpl,
       });
       break;

package/src/providers/gemini.ts

@@ -26,7 +26,7 @@ import type {
 export interface GeminiConfig extends ProviderFallbackConfig {
   apiKey: string;
   model: string;
-  /** Any endpoint speaking the Generative Language REST dialect — a proxy or
+  /** 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`
@@ -39,7 +39,7 @@ export interface GeminiConfig extends ProviderFallbackConfig {
   effort?: Effort;
   /**
    * How the schema rides on a call that also carries tools. See
-   * {@link JsonWithTools} — and note that it is the MODEL's answer, not the
+   * {@link JsonWithTools}. Note that it is the model's answer, not the
    * endpoint's: measured 2026-09-07, `gemini-3.5-flash` and
    * `gemini-3.5-flash-lite` called their tool under `responseJsonSchema` every
    * time, while `gemini-3.8-flash` managed 3/10. `probeJsonWithTools` asks the
@@ -70,9 +70,10 @@ const THINKING_LEVEL: Record<Effort, string> = {
 };
 
 /**
- * Gemini 2.x thinking budget dial (tokens).
- * Gemini 2.5 uses `thinkingBudget` (0 disables thinking), while Gemini 3+ uses
- * `thinkingLevel` (MINIMAL, LOW, MEDIUM, HIGH).
+ * Gemini 2.x thinking budget dial (tokens). Gemini 2.5 takes `thinkingBudget`
+ * (0 disables thinking) and has no level. Every newer model takes
+ * `thinkingLevel`, and Google has said the next ones answer a budget with a
+ * 400 instead of remapping it.
  */
 const GEMINI_2_THINKING_BUDGET: Record<Effort, number> = {
   none: 0,
@@ -95,7 +96,7 @@ function isJsonObject(value: unknown): value is Record<string, unknown> {
 /**
  * Tool-call arguments as the OBJECT Gemini's `functionCall.args` requires.
  *
- * A bare JSON scalar or array is wrapped rather than rejected — the shared
+ * A bare JSON scalar or array is wrapped rather than rejected. The shared
  * `parseToolArgs` drops a non-object as a protocol violation, which is right
  * for reading a fresh tool call and wrong here, where replaying `{}` deletes an
  * argument the model did send. Everything else defers to it, so a truncated or
@@ -205,7 +206,7 @@ export function toGeminiContents(messages: readonly ChatMessage[]): {
 
 /**
  * `auto` and an absent choice are Gemini's own default, so the field is omitted
- * rather than sent as AUTO. `required` and a pinned tool are both mode ANY —
+ * rather than sent as AUTO. `required` and a pinned tool are both mode ANY:
  * the pin is the allow-list, not the mode.
  */
 function toToolConfig(choice: ToolChoice | undefined): unknown {
@@ -236,7 +237,7 @@ interface GeminiPart {
 }
 
 /** Google's `google.rpc.Status`: an HTTP `code`, the canonical `status` name,
- *  and `details` — which is where RetryInfo's `retryDelay` rides. */
+ *  and `details`, which is where RetryInfo's `retryDelay` rides. */
 interface GeminiStatus {
   code?: number;
   message?: string;
@@ -255,7 +256,7 @@ interface GeminiResponse {
     thoughtsTokenCount?: number;
     cachedContentTokenCount?: number;
   };
-  /** Present only on the in-band failure below — never on a real candidate. */
+  /** Present only on the in-band failure below. Never on a real candidate. */
   error?: GeminiStatus;
   /** A prompt Gemini refused outright: no candidate at all, just the reason. */
   promptFeedback?: { blockReason?: string };
@@ -283,21 +284,23 @@ export function createGeminiProvider(config: GeminiConfig): Provider {
       // learn about a prefix.
       const model = (opts.model ?? config.model).replace(/^models\//, "");
       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.
+      const isGemini2 = /gemini-2/i.test(model);
 
       const generationConfig: Record<string, unknown> = {};
       if (maxTokens !== undefined) generationConfig.maxOutputTokens = maxTokens;
-      if (opts.temperature !== undefined) generationConfig.temperature = opts.temperature;
-      if (opts.topP !== undefined) generationConfig.topP = opts.topP;
+      // `temperature` and `topP` are never sent: Gemini 3.6 Flash and later ignore
+      // them and the next models reject them. Dropping them, rather than refusing,
+      // keeps a fallback chain that shares one set of options working.
       if (opts.stopSequences?.length) generationConfig.stopSequences = opts.stopSequences;
       // 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".
-      // Gemini 3 uses thinkingLevel (MINIMAL..HIGH), while Gemini 2.5 uses
-      // thinkingBudget (0 tokens disables thinking, positive numbers set budget).
       if (effort) {
-        generationConfig.thinkingConfig = isGemini3
-          ? { thinkingLevel: THINKING_LEVEL[effort] }
-          : { thinkingBudget: GEMINI_2_THINKING_BUDGET[effort] };
+        generationConfig.thinkingConfig = isGemini2
+          ? { thinkingBudget: GEMINI_2_THINKING_BUDGET[effort] }
+          : { thinkingLevel: THINKING_LEVEL[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