@providerkit/core 0.21.1 → 0.22.0

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}`;
 }

package/src/usage.ts

@@ -15,14 +15,14 @@
 import type { TokenUsage } from "./types.ts";
 import { EMPTY_USAGE } from "./types.ts";
 
-/** USD per MILLION tokens — how every vendor prints its price sheet, so a row
+/** USD per million tokens, as every vendor prints its price sheet, so a row
  *  can be checked against one without arithmetic. */
 export interface ModelRate {
   /** Cache-MISS input: fresh tokens the provider had to read. */
   input: number;
   output: number;
   /** Cache-HIT input. Providers auto-cache repeated prefixes and bill the hit
-   *  portion far cheaper — 0.1× on Anthropic, ~0.1× on Gemini, 0.5× on some
+   *  portion far cheaper: 0.1× on Anthropic, ~0.1× on Gemini, 0.5× on some
    *  OpenAI models. In an agent loop the re-sent context is overwhelmingly
    *  hits, so billing it at the miss rate overcounts by up to 10×. */
   cacheRead: number;
@@ -95,14 +95,14 @@ export function costUsd(usage: TokenUsage, rate: ModelRate): number {
 }
 
 /** What one call adds to a run: its reported cost, else its rate, else
- *  nothing — an unpriced call still counts its tokens. */
+ *  nothing. An unpriced call still counts its tokens. */
 function callCost(usage: TokenUsage, rate: ModelRate | undefined): number {
   return rate ? costUsd(usage, rate) : (usage.reportedCostUsd ?? 0);
 }
 
 /**
  * Accumulates usage and cost across the calls of one run, pricing each with
- * the rate in effect for the model that served it — so a run that switches to
+ * the rate in effect for the model that served it, so a run that switches to
  * a backup model, or spans a time-of-day price boundary, still bills correctly.
  * A call that carries a reported cost is billed that, with or without a rate.
  */
@@ -110,7 +110,7 @@ export class UsageTracker {
   private usage: TokenUsage = { ...EMPTY_USAGE, cacheWriteTokens: 0 };
   private cost = 0;
   /** USD the cache hits saved, versus billing them all as misses.
-   *  Observability only — never billed. */
+   *  Observability only. Never billed. */
   private saved = 0;
 
   add(usage: TokenUsage, rate?: ModelRate): void {

package/src/watchdog.ts

@@ -42,7 +42,7 @@ import type {
  *  stream is dead. */
 export const STREAM_IDLE_MS = 60_000;
 
-/** No chunk for this long — the wait for the response to start included —
+/** No chunk for this long, including the wait for the response to start,
  *  and the stream is going nowhere, keep-alives or not. */
 export const STREAM_PROGRESS_MS = 300_000;
 
@@ -51,17 +51,17 @@ export interface StreamWatch {
   readonly signal: AbortSignal;
   /** A chunk arrived: re-arm both deadlines, and mark TTFT if it was the first. */
   sawByte(): void;
-  /** The response showed life without a chunk — its headers, a keep-alive, a
+  /** The response showed life without a chunk: its headers, a keep-alive, a
    *  partial frame. Starts or re-arms the idle deadline only. */
   sawActivity(): void;
   /**
-   * Milliseconds from the call opening to its first chunk of any kind — the
+   * Milliseconds from the call opening to its first chunk of any kind. The
    * wait a person actually experiences, and the number a prompt-cache pin
    * exists to shrink. Null until something arrives.
    */
   firstChunkMs(): number | null;
   /**
-   * Re-issue a provider failure as the timeout when — and only when — it was
+   * Re-issue a provider failure as the timeout only when it was
    * one of our deadlines that aborted. A caller's Stop passes through untouched.
    */
   classify(err: unknown): unknown;
@@ -148,7 +148,7 @@ export function streamWatch(opts: StreamWatchOptions = {}): StreamWatch {
 
 /**
  * Wrap a stream so every chunk re-arms `watch`, and a failure is re-classified
- * through it. Disposes on any exit — completion, throw, or the consumer
+ * through it. Disposes on any exit: completion, throw, or the consumer
  * breaking out of the loop.
  */
 export async function* watchChunks<T>(
@@ -173,7 +173,7 @@ export async function* watchChunks<T>(
  * A stream that ends with no text and no tool call is a failure wearing a
  * success's clothes: `stop_reason: end_turn` with zero content blocks, which
  * the vendors emit under load, or a thinking block that ate the whole
- * `max_tokens`. Nothing throws, so nothing retries — the caller simply shows a
+ * `max_tokens`. Nothing throws, so nothing retries. The caller simply shows a
  * person an empty answer, and the only trace is a bill.
  *
  * Reasoning is not an answer. It still streams the moment it arrives, so a
@@ -185,12 +185,12 @@ export async function* watchChunks<T>(
  *
  * Classified by what fixes it. A `length` finish is the caller's own cap:
  * `invalid`, so nothing retries it into the same cap and no backup model is
- * cooled down for it — the fix is a larger `maxTokens` or a lower effort. Any
+ * cooled down for it. The fix is a larger `maxTokens` or a lower effort. Any
  * other empty turn is `overload`, because that is both true and useful: it is
  * theirs and temporary, so it is transient (the same model, retried, usually
  * answers) and backup-eligible (a model that keeps doing it should be walked
  * away from). Until something streams, the empty frames are held back, so the
- * retry rule that matters — retry only while nothing was emitted — still holds.
+ * retry rule still holds: retry only while nothing was emitted.
  */
 export async function* requireContent<T extends ProviderChunk>(
   provider: string,
@@ -240,7 +240,7 @@ export async function* requireContent<T extends ProviderChunk>(
     throw new ProviderError(
       provider,
       "invalid",
-      `${provider}: the output cap ran out before any answer${spent} — raise maxTokens or lower effort`,
+      `${provider}: the output cap ran out before any answer${spent}. Raise maxTokens or lower effort.`,
     );
   }
   throw new ProviderError(provider, "overload", `${provider}: completed with no content`);
@@ -267,8 +267,8 @@ export interface WatchdogOptions {
  * A provider with both silent failures already handled.
  *
  * Every consumer of this package wrote the same three lines around every
- * `createStream` — build a watch, hand the provider the WATCH's signal, wrap
- * the chunks — and the middle one is the trap. Pass the caller's signal
+ * `createStream`: build a watch, hand the provider the watch's signal, wrap
+ * the chunks. The middle one is the trap. Pass the caller's signal
  * instead and everything still compiles, still streams, still passes the
  * tests: the watchdog simply never aborts anything, because the request it was
  * meant to cancel was never told about it. The failure has no symptom until
@@ -276,8 +276,8 @@ export interface WatchdogOptions {
  *
  * So the composition belongs here rather than in a docs snippet each app
  * copies. The result is still a `Provider`, so it composes unchanged with
- * `withStreamRetry` and `streamWithBackupModels` — and both of the failures it
- * catches are transient, which is what makes wrapping it in a retry correct.
+ * `withStreamRetry` and `streamWithBackupModels`. Timeouts and empty turns
+ * without a `length` finish are transient, so wrapping it in a retry is safe.
  */
 export function withWatchdog(provider: Provider, opts: WatchdogOptions = {}): Provider {
   return {