@providerkit/core 0.21.1 → 0.22.0

package/dist/usage.d.ts

@@ -1,12 +1,12 @@
 import type { TokenUsage } 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;
@@ -40,7 +40,7 @@ export declare function subtractUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
 export declare function costUsd(usage: TokenUsage, rate: ModelRate): number;
 /**
  * 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.
  */
@@ -48,7 +48,7 @@ export declare class UsageTracker {
     private usage;
     private cost;
     /** USD the cache hits saved, versus billing them all as misses.
-     *  Observability only — never billed. */
+     *  Observability only. Never billed. */
     private saved;
     add(usage: TokenUsage, rate?: ModelRate): void;
     subtract(usage: TokenUsage, rate?: ModelRate): void;

package/dist/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;qDACqD;AACrD,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;wEAGoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;0EAEsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;8DAG8D;AAC9D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAUjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAUtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAgBlE;AAQD;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAuD;IACpE,OAAO,CAAC,IAAI,CAAK;IACjB;6CACyC;IACzC,OAAO,CAAC,KAAK,CAAK;IAElB,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAQ9C,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAQnD,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;yDAEqD;IACrD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIrC,KAAK,IAAI,IAAI;CAKd"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;qDACqD;AACrD,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;wEAGoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;0EAEsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;8DAG8D;AAC9D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAUjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAUtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAgBlE;AAQD;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAuD;IACpE,OAAO,CAAC,IAAI,CAAK;IACjB;4CACwC;IACxC,OAAO,CAAC,KAAK,CAAK;IAElB,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAQ9C,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAQnD,IAAI,MAAM,IAAI,UAAU,CAEvB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;yDAEqD;IACrD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIrC,KAAK,IAAI,IAAI;CAKd"}

package/dist/usage.js

@@ -58,13 +58,13 @@ export function costUsd(usage, rate) {
         1_000_000);
 }
 /** 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, rate) {
     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.
  */
@@ -72,7 +72,7 @@ export class UsageTracker {
     usage = { ...EMPTY_USAGE, cacheWriteTokens: 0 };
     cost = 0;
     /** USD the cache hits saved, versus billing them all as misses.
-     *  Observability only — never billed. */
+     *  Observability only. Never billed. */
     saved = 0;
     add(usage, rate) {
         this.usage = addUsage(this.usage, usage);

package/dist/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"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"}

package/dist/watchdog.d.ts

@@ -2,7 +2,7 @@ import type { Provider, ProviderChunk } from "./types.ts";
 /** No byte at all for this long, once the response has started, and the
  *  stream is dead. */
 export declare const STREAM_IDLE_MS = 60000;
-/** 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 declare const STREAM_PROGRESS_MS = 300000;
 export interface StreamWatch {
@@ -10,17 +10,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;
@@ -36,7 +36,7 @@ export interface StreamWatchOptions {
 export declare 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 declare function watchChunks<T>(watch: StreamWatch, chunks: AsyncIterable<T>): AsyncGenerator<T>;
@@ -46,7 +46,7 @@ export declare function watchChunks<T>(watch: StreamWatch, chunks: AsyncIterable
  * 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
@@ -58,12 +58,12 @@ export declare function watchChunks<T>(watch: StreamWatch, chunks: AsyncIterable
  *
  * 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 declare function requireContent<T extends ProviderChunk>(provider: string, chunks: AsyncIterable<T>, opts?: {
     afterToolResult?: boolean;
@@ -88,8 +88,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
@@ -97,8 +97,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 declare function withWatchdog(provider: Provider, opts?: WatchdogOptions): Provider;
 //# sourceMappingURL=watchdog.d.ts.map

package/dist/watchdog.js

@@ -32,7 +32,7 @@ import { ProviderError } from "./errors.js";
 /** No byte at all for this long, once the response has started, and the
  *  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;
 export function streamWatch(opts = {}) {
@@ -102,7 +102,7 @@ export function streamWatch(opts = {}) {
 }
 /**
  * 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(watch, chunks) {
@@ -125,7 +125,7 @@ export async function* watchChunks(watch, chunks) {
  * 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
@@ -137,12 +137,12 @@ export async function* watchChunks(watch, chunks) {
  *
  * 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(provider, chunks, opts = {}) {
     const held = [];
@@ -186,7 +186,7 @@ export async function* requireContent(provider, chunks, opts = {}) {
         const spent = usage?.reasoningTokens
             ? ` (${usage.reasoningTokens} of ${usage.outputTokens} output tokens went to reasoning)`
             : "";
-        throw new ProviderError(provider, "invalid", `${provider}: the output cap ran out before any answer${spent} — raise maxTokens or lower effort`);
+        throw new ProviderError(provider, "invalid", `${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`);
 }
@@ -194,8 +194,8 @@ export async function* requireContent(provider, chunks, opts = {}) {
  * 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
@@ -203,8 +203,8 @@ export async function* requireContent(provider, chunks, opts = {}) {
  *
  * 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, opts = {}) {
     return {

package/dist/zod.d.ts

@@ -5,8 +5,8 @@ import type { JsonObjectSchema } from "./types.ts";
  * A zod schema as the JSON Schema every provider's tool contract wants.
  *
  * `$schema` is dropped. zod emits the dialect URI at the root, and a provider
- * validating a tool's `parameters` against its own supported subset — OpenAI
- * under `strict: true`, Gemini's `parametersJsonSchema` — rejects the whole
+ * validating a tool's `parameters` against its own supported subset (OpenAI
+ * under `strict: true`, Gemini's `parametersJsonSchema`) rejects the whole
  * tool over that one key, with a message that names neither zod nor the field.
  */
 export declare function toJsonObjectSchema(schema: z.ZodType, label?: string): JsonObjectSchema;
@@ -26,13 +26,13 @@ export interface ZodToolSpec<I, O> {
      * rejecting the call. Worth it for a TERMINAL tool, which gets no second
      * chance: a forced-submit salvage turn runs exactly once, and discarding an
      * otherwise-valid answer over a few extra characters loses the whole run.
-     * Off by default — an ordinary tool can simply be called again.
+     * Off by default: an ordinary tool can simply be called again.
      */
     clampOverflow?: boolean;
 }
 /**
  * A tool whose arguments are validated by zod, with the failure reported to
- * the MODEL in words it can act on — `topic: expected string, received number`
+ * the model in words it can act on. `topic: expected string, received number`
  * beats a stack trace it cannot read.
  */
 export declare function zodTool<I, O>(spec: ZodToolSpec<I, O>): Tool<I, O>;

package/dist/zod.js

@@ -10,8 +10,8 @@ import { clampToSchema } from "./schema.js";
  * A zod schema as the JSON Schema every provider's tool contract wants.
  *
  * `$schema` is dropped. zod emits the dialect URI at the root, and a provider
- * validating a tool's `parameters` against its own supported subset — OpenAI
- * under `strict: true`, Gemini's `parametersJsonSchema` — rejects the whole
+ * validating a tool's `parameters` against its own supported subset (OpenAI
+ * under `strict: true`, Gemini's `parametersJsonSchema`) rejects the whole
  * tool over that one key, with a message that names neither zod nor the field.
  */
 export function toJsonObjectSchema(schema, label = "schema") {
@@ -26,7 +26,7 @@ export function toJsonObjectSchema(schema, label = "schema") {
 }
 /**
  * A tool whose arguments are validated by zod, with the failure reported to
- * the MODEL in words it can act on — `topic: expected string, received number`
+ * the model in words it can act on. `topic: expected string, received number`
  * beats a stack trace it cannot read.
  */
 export function zodTool(spec) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@providerkit/core",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "The layer under your agent loop: one seam for every LLM provider, plus the failure handling you only learn in production.",
   "type": "module",
   "license": "MIT",

package/src/attribution.ts

@@ -9,9 +9,9 @@
 // HTTP header names are case-insensitive but this seam carries them as a
 // plain record, so `http-referer` and `HTTP-Referer` must mean the same opt-out.
 export interface Attribution {
-  /** Site URL, sent as `HTTP-Referer` — e.g. "https://your.app". */
+  /** Site URL, sent as `HTTP-Referer` (e.g. "https://your.app"). */
   siteUrl?: string;
-  /** App name, sent as `X-Title` — e.g. "Your App". */
+  /** App name, sent as `X-Title` (e.g. "Your App"). */
   siteName?: string;
 }
 

package/src/capability.ts

@@ -18,12 +18,12 @@
 
 import type { JsonWithTools, Provider } from "./types.ts";
 
-/** Nothing a model can answer from memory — so a tool call is the only correct
- *  turn, and NOT making one is a real signal rather than a judgement call. */
+/** A question the model cannot answer from memory, so a tool call is the only
+ *  correct turn. Not making one is a real signal rather than a judgement call. */
 const PROBE_TOOL = {
   name: "get_current_time",
   description:
-    "The only source of the current time. You cannot know the time without calling this — never answer a time question from memory or guess.",
+    "The only source of the current time. You cannot know the time without calling this. Never answer a time question from memory or guess.",
   inputSchema: {
     type: "object" as const,
     properties: { timezone: { type: "string", description: "IANA timezone, e.g. Asia/Tokyo" } },
@@ -46,7 +46,7 @@ const SHAPES: JsonWithTools[] = ["response_format", "prompt"];
 export interface JsonWithToolsProbe {
   /**
    * The shape to configure, or `null` when neither called the tool on every
-   * sample — that model cannot be trusted with tools and a schema together,
+   * sample. That model cannot be trusted with tools and a schema together,
    * whichever way the schema rides, and the honest fix is a different model.
    */
   use: JsonWithTools | null;
@@ -58,8 +58,8 @@ export interface JsonWithToolsProbe {
 
 export interface ProbeOptions {
   /**
-   * Samples per shape. Above one because the interesting failures are partial —
-   * `gemini-3.8-flash` called its tool 3/10 — and a single sample reports a
+   * Samples per shape. Above one because the interesting failures are partial:
+   * `gemini-3.8-flash` called its tool 3/10. A single sample reports a
    * coin flip as a capability. A shape passes only when EVERY sample calls.
    */
   samples?: number;
@@ -95,12 +95,12 @@ async function callsTool(
 
 /**
  * Ask a model, on the wire, which {@link JsonWithTools} shape it actually
- * serves — then configure the provider with `probe.use`.
+ * serves. Then configure the provider with `probe.use`.
  *
  * Both shapes are always tried, because a result you can read beats a result
  * you have to trust: `calls` is the table to log, and "0/3 and 3/3" is what
  * makes a later regression obvious. It costs `samples × 2` short calls, made
- * one after another, once, at whatever moment the app decides to ask — boot is
+ * one after another, once, at whatever moment the app decides to ask. Boot is
  * the usual one.
  *
  * Probe each provider on its own, never a fallback chain: the shape is a fact
@@ -117,8 +117,8 @@ async function callsTool(
  * report "this model cannot call tools", which is a much worse thing to
  * believe than "the call failed".
  *
- * What it catches is the structural failure — the model that CANNOT emit the
- * call, every time, on the easiest question there is. A model that is merely
+ * It catches a structural failure: a model that cannot emit the call, every
+ * time, on the easiest question there is. A model that is merely
  * unreliable will pass: `gemini-3.8-flash` answers this probe 3/3 and a real
  * sales turn 3/10. That is the right line to draw. A harder probe would start
  * failing good models for being terse, and "sometimes forgets its tools" is a
@@ -226,8 +226,8 @@ function normalizeId(id: string): string {
  * - `deepseek/deepseek-v4.1-flash` matches `deepseek-v4.1-flash`
  * - `accounts/fireworks/models/glm-5p3-flash` matches `glm-5.3-flash`
  *
- * Never throws — if the catalog cannot be retrieved or the model is unknown,
- * returns `undefined` so capability lookups never break caller execution.
+ * Never throws. If the catalog cannot be retrieved or the model is unknown,
+ * it returns `undefined` so capability lookups never break caller execution.
  */
 export async function resolveModelCapabilities(
   modelId: string,

package/src/context.ts

@@ -9,13 +9,13 @@ import type { ChatMessage } from "./types.ts";
  * What the answer needs after the prompt: an output budget, plus the tools'
  * own schemas, plus the slack no provider documents.
  *
- * Absolute rather than a percentage on purpose — a 1M window does not need a
+ * Absolute rather than a percentage on purpose: a 1M window does not need a
  * 100k cushion, and a 128k window needs more than 12k.
  */
 export const CONTEXT_RESERVE_TOKENS = 32_000;
 
 /**
- * Four characters per token — the rule of thumb every provider's own
+ * Four characters per token is the rule of thumb every provider's own
  * calculator agrees with to within a fifth, which is all the precision this
  * needs. It decides WHEN to fold: folding one turn early costs a cheap model
  * call, folding one turn late costs the whole turn.
@@ -64,7 +64,7 @@ export function conversationTokens(messages: readonly ChatMessage[]): number {
 }
 
 /**
- * The provider's own input count says the wall is close — fold before the next
+ * The provider's own input count says the limit is close. Fold before the next
  * step rather than after the 400.
  *
  * Takes the REPORTED count, not an estimate, because it is the only figure
@@ -99,7 +99,7 @@ export function historyBudgetTokens(contextWindow: number): number {
  *
  *  1. Never split a tool call from its result. Every provider rejects a tool
  *     result whose call is missing, so a cut landing between them produces a
- *     400 on the very next turn — the failure compaction was called to avoid.
+ *     400 on the very next turn, the failure compaction was called to avoid.
  *  2. Never cut into the system prompt. It is not history.
  *
  * Returns the index the kept tail starts at, or 0 when everything already fits.

package/src/errors.ts

@@ -15,7 +15,7 @@ import type { FilePart } from "./types.ts";
 
 /** What kind of failure this is, named by what actually fixes it. */
 export type ErrorKind =
-  /** Our own cancel — the caller pressed Stop. Never retried. */
+  /** Our own cancel: the caller pressed Stop. Never retried. */
   | "aborted"
   /** Our own deadline, or the provider's 408. Retry. */
   | "timeout"
@@ -24,13 +24,13 @@ export type ErrorKind =
   /** Theirs, and temporary: 5xx, Anthropic's 529, "overloaded". Retry, and
    *  worth trying a different model. */
   | "overload"
-  /** 429 per-minute throttle. Wait — or rotate to another key or model. */
+  /** 429 per-minute throttle. Wait, or rotate to another key or model. */
   | "rate"
   /** Balance or usage window exhausted. Waiting minutes will not fix it. */
   | "quota"
   /** The plan never included this API. Neither a new key nor a top-up fixes it. */
   | "entitlement"
-  /** 401/403 — the key is wrong, not the request. */
+  /** 401/403: the key is wrong, not the request. */
   | "auth"
   /** The model id does not exist or is not served here. */
   | "model"
@@ -38,7 +38,7 @@ export type ErrorKind =
   | "context"
   /** Safety filter or refusal. */
   | "content"
-  /** Any other 4xx — a bug in what we sent. */
+  /** Any other 4xx: a bug in what we sent. */
   | "invalid"
   | "unknown";
 
@@ -81,7 +81,7 @@ export function isBackupEligible(kind: ErrorKind): boolean {
  * 1. Caller aborts are never retryable.
  * 2. An explicit `shouldRetry` directive on ProviderError (e.g. from server `x-should-retry`)
  * 3. Non-retryable kinds (quota, context, model, entitlement, content, invalid) return false.
- * 4. Excessive retry-after waits (exceeding `maxWaitMs`) return false — long waits belong to fallbacks.
+ * 4. Excessive retry-after waits (exceeding `maxWaitMs`) return false. Long waits belong to fallbacks.
  * 5. Transient kinds (rate, overload, network, timeout) return true.
  * 6. Transport-level network faults (fetch failed, connection lost, SSL blips) return true.
  */
@@ -115,7 +115,7 @@ export class ProviderError extends Error {
   readonly window?: RateLimitWindow;
   /** Explicit server directive (`x-should-retry`), overriding default classification. */
   readonly shouldRetry?: boolean;
-  /** The provider's own response body, truncated — the actual reason, which is
+  /** The provider's own response body, truncated. It carries the actual reason,
    *  otherwise lost behind "400 status code (no body)". */
   readonly body?: string;
 
@@ -213,7 +213,7 @@ export function messageOf(err: unknown): string {
  * Everything readable about the failure as one searchable string: the message
  * plus the parsed provider body. SDKs park the parsed body on `.error`, and
  * that is where the real reason lives ("max_tokens too large", the quotaId,
- * `"type": "billing_error"`). Scanned as TEXT — the error-type strings
+ * `"type": "billing_error"`). Scanned as text: the error-type strings
  * serialize into it, so no JSON walking is needed.
  */
 function bodyTextOf(err: unknown): string {
@@ -293,7 +293,7 @@ function isAbort(err: unknown): boolean {
  * A transport fault: the socket died before or during the response, so there
  * is NO status and no body for the patterns below to read.
  *
- * The chain is walked because the useful code is rarely on the thrown error —
+ * The chain is walked because the useful code is rarely on the thrown error:
  * it sits on `cause`, sometimes several wrappers deep. Without this walk every
  * network blip classifies as permanent, and a long run dies on its first
  * hiccup, which is the single likeliest way to lose a minutes-long job.
@@ -455,7 +455,7 @@ const CONTENT_PATTERNS: readonly RegExp[] = [
  * A throttle said in words rather than in a 429.
  *
  * Every other kind has body evidence; rate had only the status, which is
- * exactly the evidence an in-band failure lacks — an SSE response is already
+ * exactly the evidence an in-band failure lacks. An SSE response is already
  * 200 when the throttle lands, so the reason arrives as a payload with no
  * status line at all. Checked below the status branches, so it only ever
  * catches what would otherwise fall through to "unknown".
@@ -501,18 +501,18 @@ const matches = (patterns: readonly RegExp[], text: string): boolean =>
  * The kind of failure, from whatever was thrown.
  *
  * Body patterns outrank status for the 4xx family; within them, context beats
- * entitlement beats quota beats auth — each earlier category's fix is useless
+ * entitlement beats quota beats auth. Each earlier category's fix is useless
  * for the later ones.
  */
 /**
- * The kind of a failure that arrived as an HTTP response — a status and a body,
+ * The kind of a failure that arrived as an HTTP response: a status and a body,
  * with nothing thrown.
  *
  * `classify` below is for a caught error, and it reads `status` and the body
  * text off that error when they are not passed separately. A response has no
  * error object, so callers were inventing one to fill the slot: a bare body
  * string, the same text twice, a `{ status, error }` literal. All three are
- * inert — nothing on them can satisfy `isAbort` or `isTransportFailure` — so
+ * inert (nothing on them can satisfy `isAbort` or `isTransportFailure`), so
  * they were three spellings of `undefined`.
  */
 export function classifyHttp(status: number | undefined, body: string): ErrorKind {
@@ -568,7 +568,7 @@ export function classify(err: unknown, status?: number, body?: string): ErrorKin
 /**
  * How long the provider asked us to wait, in ms. Two dialects: Gemini's
  * RetryInfo (`"retryDelay": "52s"`, inside the body) and the `Retry-After`
- * header, which SDKs keep on the error. Honouring it beats guessing — a
+ * header, which SDKs keep on the error. Honouring it beats guessing: a
  * backoff shorter than the window just burns an attempt.
  */
 export function parseRetryAfterMs(err: unknown, body?: string): number | undefined {
@@ -664,14 +664,14 @@ export function parseContextOverflow(err: unknown, body?: string): ContextOverfl
  * completion: retry sees nothing to retry, and a key pool never rotates off an
  * exhausted key.
  *
- * `error` is the vendor's own payload, whatever shape it came in — the numeric
+ * `error` is the vendor's own payload, whatever shape it came in: the numeric
  * HTTP `code` Gemini and OpenRouter use, the slug OpenAI and Anthropic put in
  * `code`/`type`, the canonical `status` name. The whole thing serializes into
  * the searchable body, so RetryInfo's `retryDelay` is honoured wherever it sits.
  *
  * `unknown` is floored to "overload" rather than kept: a stream that dies after
  * its headers is by construction a transient upstream fault, and "unknown" is
- * never retried. Everything the body DOES name keeps its own kind — which is
+ * never retried. Everything the body does name keeps its own kind, which is
  * what tells the caller to wait, rotate a key, or compact instead of retrying
  * a failure that will repeat.
  */
@@ -697,7 +697,7 @@ export function streamError(provider: string, error: unknown): ProviderError {
 }
 
 /** The reset a stream error carries: the body's clock, plus the rate-limit
- *  headers the ChatGPT backend mirrors INTO its error frame — the only place a
+ *  headers the ChatGPT backend mirrors into its error frame, the only place a
  *  failure after the 200 can say which window ran out. */
 function readReset(error: unknown, body: string) {
   const raw =
@@ -720,7 +720,7 @@ function readReset(error: unknown, body: string) {
  * read it: a caller that never checks the finish keeps half an answer as if it
  * were the whole one, the ledger records a billed turn as free, and no pool
  * learns the endpoint is dropping streams. cc-proxy shipped the same fix
- * (0.1.39) for the same reason — "instead of marking affected streamed
+ * (0.1.39) for the same reason: "instead of marking affected streamed
  * responses as successful".
  *
  * `network`, because that is what it is: the same failure as a socket that
@@ -736,7 +736,7 @@ export function streamCut(provider: string): ProviderError {
   );
 }
 
-/** The loggable surface of a failure — so a dead run never reads
+/** The failure details you can log, so a dead run never reads
  *  "400 status code (no body)". */
 export function describeProviderError(err: unknown): Record<string, unknown> {
   if (err instanceof ProviderError) {

package/src/image.ts

@@ -16,7 +16,7 @@ export interface ImageLimits {
   minSide: number;
   /** Smallest area, in square pixels. */
   minArea: number;
-  /** Largest decoded size — width × height × bytes per pixel — in bytes. */
+  /** Largest decoded size in bytes (width × height × bytes per pixel). */
   maxDecodedBytes: number;
   /** Most images in one request. The newest win; older ones become notes. */
   maxImages: number;