@providerkit/core 0.21.0 → 0.22.0

package/src/providers/openai.ts

@@ -31,7 +31,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    *  /chat/completions when the base already includes the API version, such as
    *  a gateway using /v4 rather than /v1. */
   path?: string;
-  /** Names the provider in errors and logs — "openrouter", "deepseek", … It
+  /** Names the provider in errors and logs ("openrouter", "deepseek", …). It
    *  also picks the effort dialect below, unless `effortDialect` overrides. */
   id?: string;
   effort?: Effort;
@@ -50,7 +50,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
   /**
    * How a json request rides when the SAME call also carries tools.
    *
-   * `response_format` — the default — sends both, which is what the shape
+   * `response_format` (the default) sends both, which is what the shape
    * documents and what most models honour. `prompt` drops the response format
    * from those calls only and sends the schema as prompt instead: the shape the
    * Anthropic adapter has always used, and the reason this failure cannot
@@ -58,7 +58,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    *
    * It needs a knob because a model that cannot serve both does not say so. Its
    * decoder is pinned to the schema, the tool call has nowhere to go, and the
-   * model writes the announcement instead — "let me look that up for you" — and
+   * model writes the announcement instead ("let me look that up for you") and
    * the turn ends looking like a model with no initiative rather than a request
    * that made the call impossible. Nothing is logged, because nothing failed.
    *
@@ -70,7 +70,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    * No default is right for everyone, which is why this stays a setting rather
    * than becoming a rule: the same run put `qwen3.8-flash` at 1/6 with the
    * schema in the prompt against 6/6 with the response format. Don't guess it
-   * from the model card — `probeJsonWithTools` asks the model itself, in one
+   * from the model card. `probeJsonWithTools` asks the model itself, in one
    * call. `StreamOptions.jsonWithTools` overrides this per call.
    */
   jsonWithTools?: JsonWithTools;
@@ -78,7 +78,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
   fetchImpl?: typeof fetch;
   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.
@@ -91,7 +91,7 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
   /**
    * Pin OpenRouter to preferred upstream hosts so the PROMPT CACHE stays warm
    * across rounds. The cache lives on the upstream host's account and default
-   * routing hops between them, and every hop is a cold cache — worse latency
+   * routing hops between them. Every hop is a cold cache, with worse latency
    * and higher effective input cost. Fallbacks stay on: this is a preference,
    * not a lock.
    */
@@ -109,6 +109,9 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
    *  `agent`. GitHub Copilot bills a premium request per `user` turn and lets
    *  the agent's own follow-ups (tool results) ride free. */
   initiatorHeader?: boolean;
+  /** Never send `temperature` or `top_p`. For an endpoint that fixes its own
+   *  sampling and rejects the fields (Gemini's OpenAI-compatible route). */
+  noSampling?: boolean;
   /** Default `service_tier` for every call; `StreamOptions.serviceTier` wins. */
   serviceTier?: ServiceTier;
 }
@@ -215,14 +218,14 @@ const OPENROUTER_NONE: ReadonlyMap<string, "low" | "minimal" | "none"> = new Map
  *   MiMo v2.6 Flash takes one, and DeepSeek V4 Flash thinks at `low` and not
  *   with the field omitted. So `none` is said per model, from
  *   `OPENROUTER_NONE`, which also says why an unlisted model gets nothing.
- *   Naming a level raises it — the accepted values are `low`, `high` and
+ *   Naming a level raises it. The accepted values are `low`, `high` and
  *   `max` (`medium` and `xhigh` are accepted too, but our vocabulary has no
  *   use for them).
  * - **DeepSeek V4 defaults thinking ON** on its own API, so `none` has to be an
  *   explicit refusal there. The same word is a different request on each
  *   dialect, and on OpenRouter on each model: the spelling belongs to the
  *   endpoint, never to the caller.
- * - **OpenAI** takes `reasoning_effort`, and `none` is one of its values — not
+ * - **OpenAI** takes `reasoning_effort`, and `none` is one of its values, not
  *   the absence of the field. GPT-5.1 both accepted `none` and made it the
  *   default; everything from GPT-5 back still defaults to `medium`. So sending
  *   nothing is NOT a way to say "do not think": on every model released before
@@ -286,11 +289,12 @@ export function effortParams(
 /**
  * OpenCode Go's chat models each take a different set of `reasoning_effort`
  * values (cc-proxy's table, measured on live traffic). A level a model can't
- * take is refused here, rather than sent as a 400 or quietly changed into a
- * level the caller didn't ask for.
+ * take is raised to the least it offers (GLM, DeepSeek) or refused (MiMo
+ * `max`), rather than sent as a 400. A refusal is `invalid`, which stops the
+ * whole fallback chain, so refuse only where there is nothing sensible to send.
  *
  * - GLM 5.2 and 5.3 take only `high` and `max`, with no way to turn thinking
- *   off. `none` gets `high`, the least they offer.
+ *   off. `none`, `low` and `medium` get `high`, the least they offer.
  * - DeepSeek V4 takes `low` to `max`. `none` gets `low`, its least.
  * - MiMo takes `low`, `medium` and `high`, and `none` (measured 2026-09-27 on
  *   `mimo-v2.6-flash`; cc-proxy maps it to `low` instead).
@@ -307,8 +311,7 @@ function goEffortParams(effort: Effort, model = ""): Record<string, unknown> {
   };
   const level = (value: string) => ({ reasoning_effort: value });
   if (/glm-5[-.p]?[23]/.test(id)) {
-    if (effort === "none" || effort === "high") return level("high");
-    return effort === "max" ? level("max") : refuse("high or max");
+    return level(effort === "max" ? "max" : "high");
   }
   if (id.includes("deepseek-v4")) return level(effort === "none" ? "low" : effort);
   if (id.includes("mimo"))
@@ -351,7 +354,7 @@ function partsToOpenAI(content: string | ContentPart[], provider: string): unkno
 }
 
 /**
- * Assistant turns carry `reasoning_content` when the history has it — thinking
+ * Assistant turns carry `reasoning_content` when the history has it. Thinking
  * providers require the prior turn's chain-of-thought replayed on a turn that
  * made a tool call. A caller running a turn with thinking OFF must strip it
  * first (`stripReasoning`); the two cannot be mixed.
@@ -454,7 +457,7 @@ interface OpenAIChunk {
     is_byok?: boolean;
     cost_details?: { upstream_inference_cost?: unknown } | null;
   } | null;
-  /** Present only on the in-band failure below — never beside a choice.
+  /** Present only on the in-band failure below. Never beside a choice.
    *  `code` is the numeric HTTP status on the gateways, a slug on OpenAI. */
   error?: { message?: string; code?: string | number; type?: string };
 }
@@ -527,8 +530,10 @@ export function createOpenAIProvider(config: OpenAIConfig): Provider {
       };
       const maxTokens = opts.maxTokens ?? config.maxTokens;
       if (maxTokens !== undefined) request.max_tokens = maxTokens;
-      if (opts.temperature !== undefined) request.temperature = opts.temperature;
-      if (opts.topP !== undefined) request.top_p = opts.topP;
+      if (!config.noSampling) {
+        if (opts.temperature !== undefined) request.temperature = opts.temperature;
+        if (opts.topP !== undefined) request.top_p = opts.topP;
+      }
       if (opts.stopSequences?.length) request.stop = opts.stopSequences;
       const serviceTier = opts.serviceTier ?? config.serviceTier;
       if (serviceTier) request.service_tier = serviceTier;

package/src/providers/responses.ts

@@ -39,7 +39,7 @@ export interface ResponsesConfig extends ProviderFallbackConfig {
   effort?: Effort;
   maxTokens?: number;
   fetchImpl?: typeof fetch;
-  /** Extra request headers — where a subscription backend's account id goes
+  /** Extra request headers, where a subscription backend's account id goes
    *  (`ChatGPT-Account-Id`), which those backends reject the request without. */
   headers?: Record<string, string>;
   /** Header that carries `StreamOptions.sessionId`. When set and a call has no
@@ -50,7 +50,7 @@ export interface ResponsesConfig extends ProviderFallbackConfig {
    * The ChatGPT subscription surface serves it at `/backend-api/codex/responses`
    * with no version segment, so that backend needs
    * `{ baseUrl: "https://chatgpt.com/backend-api/codex", path: "/responses" }`.
-   * Without the override the POST 404s, and a 404 classifies as "model" — the
+   * Without the override the POST 404s, and a 404 classifies as "model". The
    * user is told the model id does not exist when the path was the problem.
    */
   path?: string;
@@ -141,8 +141,8 @@ function partsToResponses(
   });
 }
 
-/** A tool result is a bare string unless it carried images — then the content-
- *  array form, the only way to hand this shape a screenshot back. */
+/** A tool result is a bare string unless it carried images. Then it uses the
+ *  content-array form, the only way to hand this shape a screenshot back. */
 function toolOutput(
   content: string,
   images: readonly ImagePart[],
@@ -157,7 +157,7 @@ function toolOutput(
 /**
  * Flatten a history into `instructions` plus the input item list.
  *
- * This shape has no system ROLE — the system prompt is a top-level
+ * This shape has no system role. The system prompt is a top-level
  * `instructions` string, and everything else is items. One assistant turn can
  * become several items (its text, then one `function_call` per tool it asked
  * for), which is why a message maps to a list rather than to one item.
@@ -244,7 +244,7 @@ interface ResponsesUsage {
 
 interface ResponsesItem {
   type?: string;
-  /** The output item's own id (`fc_…`) — what the argument deltas reference. */
+  /** The output item's own id (`fc_…`), which the argument deltas reference. */
   id?: string;
   /** The id a `function_call_output` must quote on the next turn. */
   call_id?: string;
@@ -263,7 +263,7 @@ interface ResponsesEvent {
   arguments?: string;
   item?: ResponsesItem;
   response?: {
-    /** `completed`, `incomplete` or `failed` — stated on the terminal event,
+    /** `completed`, `incomplete` or `failed`, stated on the terminal event,
      *  and not always the one its `type` implies. */
     status?: string;
     usage?: ResponsesUsage;
@@ -297,8 +297,8 @@ interface CodexRateLimits {
 /**
  * The quota wall a `codex.rate_limits` snapshot reports, if it is one.
  *
- * The snapshot rides ahead of the first output on every turn and is telemetry
- * — a full window the account's credits cover, or that the backend still
+ * The snapshot rides ahead of the first output on every turn and is telemetry.
+ * A full window the account's credits cover, or that the backend still
  * `allowed`, lets the turn proceed. It is only the reason when the stream then
  * closes without a response: that close is a spent window, not a dropped
  * socket, and retrying it walks every backup into the same wall. The fuller
@@ -336,8 +336,8 @@ function usageChunk(usage: ResponsesUsage): ProviderChunk {
   };
 }
 
-/** What has already gone out for one in-flight function call — identity and
- *  arguments both — so the authoritative snapshot on `.done` can be diffed
+/** What has already gone out for one in-flight function call (identity and
+ *  arguments), so the authoritative snapshot on `.done` can be diffed
  *  against it instead of duplicated. */
 interface PendingCall {
   index: number;

package/src/providers/zai.ts

@@ -13,8 +13,8 @@ export type ZaiCodingConfig = Omit<AnthropicConfig, "baseUrl" | "id" | "bearer">
  *  adapter.
  *
  *  Dialect notes, measured 2026-09-13 against the live endpoint on
- *  `glm-5.3-flash`: an absent thinking field means the MODEL's default —
- *  thinking ON — so `effort: "none"` is sent as an explicit
+ *  `glm-5.3-flash`: an absent thinking field means the model's default
+ *  (thinking on), so `effort: "none"` is sent as an explicit
  *  `thinking: { type: "disabled" }`; `low`–`max` ride the standard thinking
  *  budgets, which the endpoint accepts. Images force a thinking block even
  *  under `disabled` (the model's choice, billed as output). */

package/src/rate-limit.ts

@@ -32,7 +32,7 @@ export type RateLimitWindow = "5h" | "weekly" | "monthly";
 export interface RateLimitReset {
   /** Absolute time the binding window resets, when any header disclosed it. */
   resetAtMs?: number;
-  /** Server-requested wait (`retry-after`) — what a retry policy honours. */
+  /** Server-requested wait (`retry-after`), which a retry policy honours. */
   retryAfterMs?: number;
   /** Which subscription window bound, when it could be named at all. */
   window?: RateLimitWindow;
@@ -58,7 +58,7 @@ const RESET_HEADERS = [
 ];
 
 /**
- * The ChatGPT backend's two windows. Both ride every response — the slots are
+ * The ChatGPT backend's two windows. Both ride every response. The slots are
  * "primary" and "secondary", NOT "5h" and "weekly", so the window is named by
  * its own `-window-minutes` (300 and 10080 in every capture), and its
  * `-used-percent` says which one is full. Recorded by cc-proxy off a live turn
@@ -154,7 +154,7 @@ function parseRetryAfter(value: string | null, now: number): number | undefined
  * Anthropic's `anthropic-ratelimit-unified-*` pair rides on every OAuth
  * response, so both windows are always reported and only one of them is the
  * reason for this 429. API-key accounts get the `anthropic-ratelimit-*-reset`
- * RFC 3339 timestamps instead. Everything is optional — an unrecognized shape
+ * RFC 3339 timestamps instead. Everything is optional: an unrecognized shape
  * yields an empty result, and the caller falls back to its generic message.
  */
 export function parseRateLimitReset(headers: Headers, now = Date.now()): RateLimitReset {
@@ -270,7 +270,7 @@ function parseProseRetryMs(text: string): number | undefined {
  * Other providers and gateways (LiteLLM, Cloudflare, Ollama) report countdowns in prose:
  * `Rate limit exceeded. Try again in 20s.`
  * The window name is inferred from the wait itself, and only past the floor
- * above — a sub-minute retry is a throttle, not a subscription window.
+ * above. A sub-minute retry is a throttle, not a subscription window.
  */
 export function parseUsageLimitBody(bodyText: string, now = Date.now()): RateLimitReset {
   let body: unknown;

package/src/retry.ts

@@ -93,8 +93,8 @@ function delayFor(err: unknown, attempt: number, opts: RetryOptions): number | n
 const defaultShouldRetry = (err: unknown, _attempt: number): boolean => isRetryable(err);
 
 /**
- * Run `fn`, retrying transient failures with backoff. For one-shot calls —
- * a title, a summary, a compaction pass.
+ * Run `fn`, retrying transient failures with backoff. For one-shot calls such
+ * as a title, a summary or a compaction pass.
  */
 export async function withRetry<T>(
   fn: (attempt: number) => Promise<T>,
@@ -124,7 +124,7 @@ export async function withRetry<T>(
 }
 
 /**
- * The streaming twin — with the rule that makes it safe: a retry happens only
+ * The streaming twin of `withRetry`. A retry happens only
  * while NOTHING has been yielded yet.
  *
  * `factory` is re-invoked per attempt and gets a fresh signal, so an abandoned
@@ -182,7 +182,7 @@ export interface BackupModelOptions {
   models: string[];
   /**
    * Whether a failure may fall through to the remaining models. Default:
-   * overload and rate limits only — those are per-model-endpoint, and nothing
+   * overload and rate limits only. Those are per-model-endpoint, and nothing
    * else on the list is. An auth failure or an invalid request would land
    * identically on every backup.
    */
@@ -226,7 +226,7 @@ export async function withBackupModels<T>(
 }
 
 /**
- * The streaming twin — carrying the same commitment rule as `withStreamRetry`.
+ * The streaming twin of `withBackupModels`, with the same commitment rule as `withStreamRetry`.
  *
  * This is the correction worth naming: walking to a backup model AFTER chunks
  * have already reached the consumer replays the answer from the top, in a

package/src/schema.ts

@@ -70,19 +70,19 @@ export function clampToSchema(value: unknown, node: unknown): unknown {
  * Whether OpenAI's `strict` schema mode will accept this schema.
  *
  * Strict is the only JSON mode that actually guarantees the shape, so it is
- * worth having — but it demands more than JSON Schema does: every property an
+ * worth having, but it demands more than JSON Schema does: every property an
  * object lists must ALSO be required, and every object must close itself with
  * `additionalProperties: false`, all the way down. A schema with one optional
  * field is not "mostly strict"; it is a flat 400 naming a nested path rather
  * than the rule it broke.
  *
  * That trap is the reason this exists. An agent's response schema grows
- * optional fields naturally — a `data` block only some flows fill, the fields
- * one step collects — and a caller who adds one wants their answer, not a
+ * optional fields naturally (a `data` block only some flows fill, the fields
+ * one step collects). A caller who adds one wants their answer, not a
  * lecture about a mode they never asked for. So the OpenAI-shape adapters ask
  * this and drop to plain (unenforced) schema mode instead of failing the turn.
  *
- * Anything it cannot verify — a `$ref`, a composed `allOf` — answers false:
+ * Anything it cannot verify (a `$ref`, a composed `allOf`) answers false:
  * the cost of guessing wrong that way is unenforced output, and the cost of
  * guessing wrong the other way is a request that cannot succeed at all.
  */
@@ -97,7 +97,7 @@ export function clampToSchema(value: unknown, node: unknown): unknown {
  *
  * Two shapes need it, which is why the wording lives here rather than in one of
  * them. Anthropic has never had a schema mode. The OpenAI dialect falls back to
- * plain JSON mode on every gateway — `json_object` asks for valid JSON and says
+ * plain JSON mode on every gateway: `json_object` asks for valid JSON and says
  * nothing whatsoever about its shape.
  */
 export function schemaPrompt(schema: unknown): string {
@@ -134,8 +134,8 @@ export function isStrictSchema(node: unknown): boolean {
   );
 }
 
-/** Keywords whose value is a schema, a list of schemas, or a map of them —
- *  the only places a `pattern` can mean a regex. Everything else (`default`,
+/** Keywords whose value is a schema, a list of schemas, or a map of them.
+ *  These are the only places a `pattern` can mean a regex. Everything else (`default`,
  *  `examples`, `enum`, property NAMES) is data and is left alone. */
 const SCHEMA_SLOTS = [
   "items",
@@ -156,7 +156,7 @@ const SCHEMA_MAPS = ["properties", "patternProperties", "$defs", "definitions",
  * A tool schema with every `pattern` constraint removed.
  *
  * The ChatGPT backend compiles tool schemas with OpenAI's own regex dialect and
- * answers a pattern it cannot read with a 400 for the WHOLE request — strict
+ * answers a pattern it cannot read with a 400 for the whole request, strict
  * or not. Claude Code's Artifact tool carries one, and every request that
  * offered it failed (cc-proxy #141/#142). Losing the constraint costs a
  * validation the caller's tool runner repeats anyway; the 400 costs the turn.

package/src/tool-args.ts

@@ -58,7 +58,7 @@ function unescapeJson(text: string): string {
 /**
  * Best-effort recovery of `"key": "value"` string fields from truncated JSON.
  *
- * Only strings: they are what a summary field — the one worth rescuing — is
+ * Only strings: they are what a summary field (the one worth rescuing) is
  * made of, and a closing quote is the single reliable boundary in a partial
  * stream. Numbers, booleans and objects are dropped, because a salvaged
  * half-value is worse than none.
@@ -151,7 +151,7 @@ export function parseToolArgs(raw: string): Record<string, unknown> {
   return healArgs(isRecord(parsed) ? parsed : {});
 }
 
-/** Whether `raw` parses at all — how a caller tells a truncated tool call from
+/** Whether `raw` parses at all. Lets a caller tell a truncated tool call from
  *  an intact one, since `parseToolArgs` deliberately never throws. */
 export function isCompleteJson(raw: string): boolean {
   if (!raw.trim()) return false;

package/src/tools.ts

@@ -13,7 +13,7 @@ import type { JsonObjectSchema, ToolDefinition } from "./types.ts";
 import { messageOf } from "./errors.ts";
 
 export interface ToolContext {
-  /** The model's own call id when there is one — the event, any approval row
+  /** The model's own call id when there is one. The event, any approval row
    *  and the tool message must all key on what the provider expects back. */
   callId?: string;
   signal?: AbortSignal;
@@ -29,7 +29,7 @@ export type ToolOutcome<O> =
       ok: false;
       callId: string;
       kind: ToolFailure;
-      /** Fed back to the model verbatim — so it must read as an instruction to
+      /** Fed back to the model verbatim, so it must read as an instruction to
        *  a reader who cannot see our stack trace. */
       error: string;
       durationMs: number;
@@ -83,7 +83,7 @@ export class ToolTimeoutError extends Error {
   }
 }
 
-/** Rejects when `signal` aborts — races a `run` that ignores its own signal. */
+/** Rejects when `signal` aborts. Races a `run` that ignores its own signal. */
 function abortion(signal: AbortSignal): Promise<never> {
   return new Promise((_resolve, reject) => {
     if (signal.aborted) reject(signal.reason);
@@ -220,7 +220,7 @@ export class ToolRegistry {
   }
 
   /**
-   * Definitions for an allow-list, in the order given — which is the order the
+   * Definitions for an allow-list, in the order given. This is the order the
    * model reads them in, and it is part of the cached prompt prefix. Reordering
    * or appending mid-conversation invalidates that prefix, so a caller that
    * cares should freeze the list when the session opens.

package/src/transport.ts

@@ -16,7 +16,7 @@ export interface RequestInit_ {
   signal?: AbortSignal;
   /** Swapped in tests, or to route through a proxy. Defaults to global fetch. */
   fetchImpl?: typeof fetch;
-  /** Called when the response headers arrive and on every body read after —
+  /** Called when the response headers arrive and on every body read after,
    *  keep-alives included. What the watchdog's idle clock runs on. */
   onActivity?: () => void;
   /** Called when the body states `[DONE]`. See `SseHooks.onDone`. */
@@ -41,8 +41,8 @@ export interface SseHooks {
 
 /**
  * One frame larger than this is not a frame. Without a cap a malformed or
- * runaway upstream grows the buffer until the runtime dies — an MV3 worker
- * first. cc-proxy caps the ChatGPT backend at the same 8 MiB.
+ * runaway upstream grows the buffer until the runtime dies, starting with an
+ * MV3 worker. cc-proxy caps the ChatGPT backend at the same 8 MiB.
  */
 export const MAX_SSE_FRAME_CHARS = 8 * 1024 * 1024;
 
@@ -53,7 +53,7 @@ export function apiUrl(baseUrl: string, path: string): string {
 
 /**
  * How long the provider says to wait, read from the RESPONSE rather than from
- * a thrown error. Headers are authoritative — `Retry-After` first, then the
+ * a thrown error. Headers are authoritative: `Retry-After` first, then the
  * vendor reset headers that name a subscription window rather than a
  * per-minute throttle, because "try again in a moment" is a lie for those.
  */
@@ -168,21 +168,21 @@ function payloadOf(frame: string): string | null {
 }
 
 /**
- * Yield each `data:` payload of an SSE body, trimmed — plus the bare JSON
+ * Yield each `data:` payload of an SSE body, trimmed, plus the bare JSON
  * object a vendor appends outside the framing, which is only ever an error
  * (see `payloadOf`).
  *
  * Frames are split on the blank line the spec requires, so a payload containing
  * a bare newline survives; `[DONE]` is swallowed here rather than in every
  * adapter, and reported through `hooks.onDone`. CRLF and bare CR are
- * normalized — some gateways send them, and a `\r` left on the end of a JSON
+ * normalized: some gateways send them, and a `\r` left on the end of a JSON
  * payload is a parse error nobody enjoys debugging.
  *
  * Exported apart from `streamSse` because the envelope above it is the half an
  * adopting app most often cannot take: an app with its own translated error
  * copy, its own log levels, or its own auth refresh has to keep building the
  * request and reading the failure itself. Framing is the half nobody should
- * write twice — hand it a `res.body` and keep your own envelope.
+ * write twice. Hand it a `res.body` and keep your own envelope.
  */
 export async function* parseSseStream(
   body: ReadableStream<Uint8Array>,

package/src/types.ts

@@ -14,7 +14,7 @@
  * `output_config.effort` for current Claude models, where `none` is the lowest
  * effort on a model that cannot stop thinking; and to thinking budgets for
  * Claude 4.5 and older and for every other vendor on that wire.
- * Support varies per model — an unsupported level comes back as a clean 400.
+ * Support varies per model. An unsupported level comes back as a clean 400.
  *
  * Ordered least → most; the type derives from the array so the runtime guard
  * and the union can never drift apart.
@@ -34,7 +34,7 @@ export interface TextPart {
   text: string;
 }
 
-/** An image the model looks at (vision) — bytes as base64, never a URL the
+/** An image the model looks at (vision), with bytes as base64, never a URL the
  *  provider would have to fetch on our behalf. */
 export interface ImagePart {
   type: "image";
@@ -48,7 +48,7 @@ export type FileMimeType =
   `application/${string}` | `audio/${string}` | `video/${string}` | `text/${string}`;
 
 /**
- * A file the model reads — a PDF, a recording, a video — as base64 bytes,
+ * A file the model reads (a PDF, a recording, a video) as base64 bytes,
  * never a URL. Only the Gemini adapter sends one, as `inlineData`, the way it
  * sends an image. Every other adapter refuses it with an `invalid`
  * ProviderError before any request goes out, rather than drop it: a dropped
@@ -94,7 +94,7 @@ export type ChatMessage =
        * OpenAI-shape serializes it as `reasoning_content`; Anthropic-shape
        * drops it, since its thinking blocks carry signatures we never capture.
        *
-       * A turn that DISABLES thinking must not carry it — mixing the two is
+       * A turn that disables thinking must not carry it. Mixing the two is
        * unsupported. `stripReasoning` below is that rule, once.
        */
       reasoning?: string;
@@ -102,7 +102,7 @@ export type ChatMessage =
        * OpenRouter's normalized reasoning payload, arriving on the stream and
        * riding back UNMODIFIED on the next turn's assistant message.
        *
-       * Opaque on purpose — the same contract as Gemini's `thoughtSignature`,
+       * Opaque on purpose, with the same contract as Gemini's `thoughtSignature`,
        * and for the same reason: it is the provider's own record of how it got
        * here, and reading, reshaping or dropping it costs the model its
        * continuity across a tool round. Absent on every other dialect.
@@ -133,7 +133,7 @@ export interface ReasoningItems {
   items: unknown[];
 }
 
-/** JSON Schema for an object — what every provider's tool contract wants. */
+/** JSON Schema for an object, as every provider's tool contract requires. */
 export interface JsonObjectSchema {
   type: "object";
   properties?: Record<string, unknown>;
@@ -161,19 +161,19 @@ export interface ToolCallDelta {
 
 export interface TokenUsage {
   inputTokens: number;
-  /** Cache-HIT subset of `inputTokens` — providers auto-cache repeated
+  /** Cache-hit subset of `inputTokens`. Providers auto-cache repeated
    *  prefixes and bill the hit portion far cheaper, so it must be tracked
    *  separately to cost a turn correctly. 0 when the provider reports none. */
   cachedInputTokens: number;
-  /** Tokens WRITTEN to cache — also a subset of `inputTokens`, so the total
+  /** Tokens written to cache, also a subset of `inputTokens`, so the total
    *  stays the whole prompt the window has to hold. Anthropic bills these
    *  above the input rate; the OpenAI-shape auto-cachers bill them at it.
    *  0 when not reported. */
   cacheWriteTokens?: number;
   outputTokens: number;
   /**
-   * The part of `outputTokens` spent thinking, when the provider reports it —
-   * already INSIDE `outputTokens`, so never add it again. It is the number
+   * The part of `outputTokens` spent thinking, when the provider reports it.
+   * Already inside `outputTokens`, so never add it again. It is the number
    * that explains a turn that came back empty with a length finish: the
    * reasoning ate the budget. Anthropic does not report it; absent there.
    */
@@ -195,7 +195,7 @@ export const EMPTY_USAGE: TokenUsage = {
   outputTokens: 0,
 };
 
-/** Normalized streaming chunk — every provider's shape collapses into this. */
+/** Normalized streaming chunk. Every provider's shape maps to this. */
 export interface ProviderChunk {
   type: "delta" | "usage" | "finish";
   /** The selected endpoint and model when a fallback provider emits this chunk.
@@ -203,7 +203,7 @@ export interface ProviderChunk {
   source?: { provider: string; model: string };
   content?: string;
   reasoning?: string;
-  /** OpenRouter's normalized reasoning payload — hand it back on the next
+  /** OpenRouter's normalized reasoning payload. Hand it back on the next
    *  turn's assistant message verbatim. See ChatMessage.reasoningDetails. */
   reasoningDetails?: unknown[];
   /** Once per turn, where a provider replays its reasoning. See ChatMessage.reasoningItems. */
@@ -213,22 +213,22 @@ export interface ProviderChunk {
   finishReason?: FinishReason;
 }
 
-/** Pin or deny tool use. `{ name }` forces one specific tool — how a run is
+/** Pin or deny tool use. `{ name }` forces one specific tool, so a run is
  *  made to commit an answer at its step budget's edge. */
 export type ToolChoice = "auto" | "none" | "required" | { name: string };
 
 /**
  * Ask for a JSON object matching `schema`. Providers that enforce schemas get
  * it verbatim; the rest get JSON mode plus the schema in the prompt. Either
- * way the CALLER validates — a provider's "guaranteed" JSON is not one.
+ * way the caller validates: a provider's "guaranteed" JSON is not one.
  */
 export interface JsonOutput {
   name: string;
   schema: JsonObjectSchema;
   /**
    * Force OpenAI's strict schema mode on or off. Left unset, the adapters ask
-   * `isStrictSchema` and enforce whenever the schema actually qualifies —
-   * which is what keeps an optional field from turning a working call into a
+   * `isStrictSchema` and enforce whenever the schema actually qualifies.
+   * This keeps an optional field from turning a working call into a
    * 400. Set it only to overrule that reading.
    */
   strict?: boolean;
@@ -339,13 +339,13 @@ function bracketed(text: string): string {
 /**
  * How the schema rides on a call that ALSO carries tools.
  *
- * `"response_format"` sends both — what the shapes document, what most models
+ * `"response_format"` sends both, as the shapes document and most models
  * honour. `"prompt"` leaves the format off that call and sends the schema as
  * prompt instead, which is what the Anthropic shape has always done.
  *
  * It is a setting because a model that cannot serve both never says so: its
  * decoder is pinned to the schema, the tool call has nowhere to go, and it
- * writes the announcement instead — "let me look that up" — and stops. Nothing
+ * writes the announcement instead ("let me look that up") and stops. Nothing
  * is logged, because nothing failed. `probeJsonWithTools` answers it in one
  * call; there is no default that is right for every model.
  */
@@ -359,9 +359,10 @@ export interface StreamOptions {
    *  task emitting a large artifact must raise it or the tool-call JSON is
    *  silently truncated mid-argument. */
   maxTokens?: number;
+  /** Not sent to Gemini, which fixes its own sampling. Same for `topP`. */
   temperature?: number;
   /**
-   * Nucleus sampling. Set this OR `temperature`, not both — the vendors all
+   * Nucleus sampling. Set this or `temperature`, not both. The vendors all
    * document them as alternatives and some reject the pair outright.
    */
   topP?: number;
@@ -378,7 +379,7 @@ export interface StreamOptions {
   toolChoice?: ToolChoice;
   json?: JsonOutput;
   /**
-   * Overrides the provider's own setting for this call — how `probeJsonWithTools`
+   * Overrides the provider's own setting for this call, so `probeJsonWithTools`
    * asks the same model both ways. See {@link JsonWithTools}.
    */
   jsonWithTools?: JsonWithTools;
@@ -397,7 +398,7 @@ export interface StreamOptions {
    */
   onActivity?: () => void;
   /**
-   * `false` asks for at most one tool call per turn — for tools that must run
+   * `false` asks for at most one tool call per turn, for tools that must run
    * in order, or a backend lane that refuses parallel calls. Absent or `true`
    * is every vendor's default and sends nothing. Gemini has no such switch,
    * so it refuses `false` rather than silently ignore it.
@@ -488,7 +489,7 @@ export async function drainStream(
  *
  * The chain-of-thought belongs only to thinking turns. A provider that
  * requires it replayed while thinking is ON (DeepSeek) rejects it when
- * thinking is OFF — which is exactly the shape of a forced-submit salvage
+ * thinking is off. This is exactly the shape of a forced-submit salvage
  * turn, where a run reasons through its whole investigation and then drops
  * thinking to serialize what it already found.
  *
@@ -518,7 +519,7 @@ export function stripReasoning(messages: readonly ChatMessage[]): ChatMessage[]
   });
 }
 
-/** `data:` URI for an image part — what the OpenAI dialect wants inline. */
+/** `data:` URI for an image part, as the OpenAI dialect requires inline. */
 export function toDataUri(part: ImagePart): string {
   return `data:${part.mimeType};base64,${part.data}`;
 }