@providerkit/core 0.21.1 → 0.23.0

package/src/tool-args.ts

@@ -12,6 +12,8 @@
 //     `\uXXXX`, which JSON.parse decodes correctly. Some escape it twice and
 //     emit `\\u00e7`, so even a clean parse leaves six literal characters
 //     standing and a Portuguese answer reaches the user as `atenção`.
+import { ProviderError } from "./errors.ts";
+import type { ToolCallDelta } from "./types.ts";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -58,7 +60,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.
@@ -129,6 +131,48 @@ export function normalizeToolId(id: string | undefined | null, prefix = "call_pk
   return clean;
 }
 
+/** A tool call's identity as a stream stated it: the last id and name it gave. */
+export interface ToolCallIdentity {
+  index: number;
+  id: string;
+  name: string;
+}
+
+/**
+ * Make a turn's tool calls runnable before its finish goes out, or fail the turn.
+ *
+ * A call with no name can't run: nothing says which tool to dispatch. It used to
+ * pass through (the Messages reader wrote `""` for both fields), and the loop
+ * failed one step later with nothing to say why. It throws `overload` now, a
+ * broken turn the same request usually does not repeat; cc-proxy answers it
+ * with a 502.
+ *
+ * A call with no id still can run. It gets one from `normalizeToolId`, written
+ * back into `calls` and returned as the deltas to send, so the result has an id
+ * to quote. An id the vendor did send is never rewritten: the four wires must
+ * agree on it (invariant 10), and repeated ids are history repair's job.
+ */
+export function settleToolCalls(
+  provider: string,
+  calls: Iterable<ToolCallIdentity>,
+): ToolCallDelta[] {
+  const minted: ToolCallDelta[] = [];
+  for (const call of calls) {
+    if (!call.name.trim()) {
+      throw new ProviderError(
+        provider,
+        "overload",
+        `${provider}: tool call ${call.index} came with no name, so no tool can run it`,
+      );
+    }
+    if (!call.id.trim()) {
+      call.id = normalizeToolId(call.id);
+      minted.push({ index: call.index, id: call.id });
+    }
+  }
+  return minted;
+}
+
 /**
  * Parse a tool call's raw argument string into an object, salvaging what a
  * truncated stream left behind, resolving concatenated JSON, and healing
@@ -151,7 +195,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

@@ -4,8 +4,12 @@
 //
 // Adapters keep only their per-event mapping; everything about being an HTTP
 // client lives here once.
-import { classifyHttp, isTransportFailure, parseRetryAfterMs, ProviderError } from "./errors.ts";
-import { parseRateLimitReset, parseRateLimitResponse } from "./rate-limit.ts";
+import { classifyHttp, parseRetryAfterMs, ProviderError } from "./errors.ts";
+import {
+  parseRateLimitReset,
+  parseRateLimitResponse,
+  type RateLimitReading,
+} from "./rate-limit.ts";
 
 export interface RequestInit_ {
   url: string;
@@ -16,11 +20,16 @@ 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`. */
   onDone?: () => void;
+  /** Called when the response headers report how full a subscription window
+   *  is. See `StreamOptions.onRateLimit`. */
+  onRateLimit?: (reading: RateLimitReading) => void;
+  /** Whether the turn already stated its finish. See `SseHooks.finished`. */
+  finished?: () => boolean;
 }
 
 export interface SseHooks {
@@ -33,6 +42,18 @@ export interface SseHooks {
    * was not simply cut off.
    */
   onDone?: () => void;
+  /**
+   * Whether the turn already stated its finish, so only trailing frames (the
+   * usage record, `[DONE]`) are left. Once this says true, a read that fails
+   * ends the stream instead of throwing. Kimi, GLM and OpenCode Go drop the
+   * socket there, and the failure threw away an answer the reader had already
+   * been shown (cc-proxy, measured on live traffic). The usage may be lost;
+   * the answer is not.
+   */
+  finished?: () => boolean;
+  /** The request's signal. A caller's Stop is never swallowed, finished or not:
+   *  a loop that sees a clean end goes on to run the turn's tools. */
+  signal?: AbortSignal;
   /** Largest partial frame held before giving up. Defaults to 8 MiB. */
   maxFrameChars?: number;
   /** Names the provider on the oversized-frame error. */
@@ -41,8 +62,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 +74,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.
  */
@@ -120,18 +141,25 @@ async function errorFor(provider: string, res: Response): Promise<ProviderError>
 
 async function send(opts: RequestInit_): Promise<Response> {
   const doFetch = opts.fetchImpl ?? globalThis.fetch;
+  // Serialized outside the catch below: a body that cannot become JSON is a
+  // bug of ours, and must not be dressed as a network blip and retried.
+  const body = typeof opts.body === "string" ? opts.body : JSON.stringify(opts.body);
   try {
     return await doFetch(opts.url, {
       method: "POST",
       headers: { "content-type": "application/json", ...opts.headers },
-      body: typeof opts.body === "string" ? opts.body : JSON.stringify(opts.body),
+      body,
       signal: opts.signal,
     });
   } catch (err) {
-    // A stopped run rejects here too, and that is not a failure — let it pass
-    // through untouched. Anything that is not a recognizable transport
-    // rejection is a bug of ours and keeps its own loud shape.
-    if (opts.signal?.aborted || !isTransportFailure(err)) throw err;
+    // An aborted signal passes through untouched: the caller's Stop stays
+    // `aborted`, and the watchdog re-issues its own abort as `timeout`
+    // (invariant 2). Every other rejection means no response came back, so it
+    // is a transport failure whatever its wording. Matching known wordings
+    // missed each runtime's next one, and a missed one was never retried: a
+    // long run died on its first blip. cc-proxy reads every failed send the
+    // same way.
+    if (opts.signal?.aborted) throw err;
     throw new ProviderError(opts.provider, "network", `no response from ${opts.url}`, {
       cause: err,
     });
@@ -168,21 +196,22 @@ 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
- * payload is a parse error nobody enjoys debugging.
+ * a bare newline survives. `[DONE]` is swallowed here rather than in every
+ * adapter, reported through `hooks.onDone`, and ends the stream: it is the
+ * body's last word, and a read after it can only fail a finished turn. CRLF and
+ * bare CR are 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>,
@@ -195,17 +224,36 @@ export async function* parseSseStream(
   // A CR at the very end of a read may be the first half of a CRLF; it waits
   // for the next read before it is turned into a line break.
   let heldCR = false;
+  // Whether the body was read to its end. Any other exit (`[DONE]`, a failed
+  // read, a consumer that stopped at its own terminal event) cancels it, so the
+  // connection is let go now rather than whenever the body is collected.
+  let drained = false;
 
-  function* emit(frame: string): Generator<string> {
+  /** Yields the frame's payload, and returns true when the frame was `[DONE]`. */
+  function* emit(frame: string): Generator<string, boolean> {
     const payload = payloadOf(frame);
-    if (payload === "[DONE]") hooks.onDone?.();
-    else if (payload !== null) yield payload;
+    if (payload === "[DONE]") {
+      hooks.onDone?.();
+      return true;
+    }
+    if (payload !== null) yield payload;
+    return false;
   }
 
   try {
     for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
+      let read: ReadableStreamReadResult<Uint8Array>;
+      try {
+        read = await reader.read();
+      } catch (err) {
+        if (hooks.finished?.() && !hooks.signal?.aborted) return;
+        throw err;
+      }
+      const { done, value } = read;
+      if (done) {
+        drained = true;
+        break;
+      }
       hooks.onActivity?.();
       let text: string = (heldCR ? "\r" : "") + decoder.decode(value, { stream: true });
       heldCR = text.endsWith("\r");
@@ -222,7 +270,7 @@ export async function* parseSseStream(
 
       let boundary = buffer.indexOf("\n\n", from);
       while (boundary !== -1) {
-        yield* emit(buffer.slice(0, boundary));
+        if (yield* emit(buffer.slice(0, boundary))) return;
         buffer = buffer.slice(boundary + 2);
         from = 0;
         boundary = buffer.indexOf("\n\n");
@@ -240,10 +288,32 @@ export async function* parseSseStream(
     // hand — dropping it loses the last delta, or the usage record.
     yield* emit(buffer + decoder.decode() + (heldCR ? "\n" : ""));
   } finally {
+    if (!drained) reader.cancel().catch(() => {});
     reader.releaseLock();
   }
 }
 
+/**
+ * Parse one SSE payload as the JSON event it must be.
+ *
+ * A frame that is not JSON used to be skipped as "a keep-alive or a frame we do
+ * not model". But `parseSseStream` already drops comments and empty frames,
+ * which is every keep-alive the vendors send, so what reaches here unparsable
+ * is a broken stream: a delta, a tool call or the finish itself, gone, with the
+ * turn still reading as whole. It fails as `network`, the same as a socket that
+ * dies mid-read (cc-proxy fails these too).
+ */
+export function parseFrame<T>(data: string, provider: string): T {
+  try {
+    return JSON.parse(data) as T;
+  } catch (err) {
+    throw new ProviderError(provider, "network", `${provider}: a stream frame was not JSON`, {
+      body: data.slice(0, 2_000),
+      cause: err,
+    });
+  }
+}
+
 /**
  * POST an SSE request and stream its payloads: the envelope (auth, the
  * classified error, the retry hints) plus `parseSseStream`.
@@ -254,6 +324,16 @@ export async function* streamSse(opts: RequestInit_): AsyncGenerator<string> {
   // the POST: a backend that withholds them until its first output token (the
   // ChatGPT backend does, for minutes on a large high-effort turn) is working.
   opts.onActivity?.();
+  // The window's fill rides every response, the ones that go through too.
+  // Read only off a refusal, a caller learns the window was filling once it
+  // is already full.
+  if (opts.onRateLimit) {
+    const reading = parseRateLimitReset(res.headers);
+    const { utilization, resetAtMs } = reading;
+    if (utilization !== undefined && resetAtMs !== undefined) {
+      opts.onRateLimit({ ...reading, utilization, resetAtMs });
+    }
+  }
   if (!res.ok) throw await errorFor(opts.provider, res);
   // A 2xx with no body at all is an upstream anomaly, not a request we got
   // wrong — worth the same retry a 5xx gets.

package/src/types.ts

@@ -6,6 +6,7 @@
 // the lingua franca forces the other adapters to round-trip through a dialect
 // that isn't theirs, and every quirk of that dialect then leaks into callers
 // who never asked for it.
+import type { RateLimitReading } from "./rate-limit.ts";
 
 /**
  * How hard the model thinks before answering. Absent = the provider's own
@@ -14,7 +15,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 +35,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 +49,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 +95,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 +103,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 +134,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 +162,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 +196,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 +204,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 +214,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 +340,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 +360,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 +380,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 +399,19 @@ export interface StreamOptions {
    */
   onActivity?: () => void;
   /**
-   * `false` asks for at most one tool call per turn — for tools that must run
+   * Called once per response whose headers report how full a subscription
+   * window is, whatever its status: `utilization` (1 is full), `resetAtMs`,
+   * and `window` when the headers name it. A caller sees the window fill
+   * turn by turn, instead of learning about it from the 429 that ends a run.
+   *
+   * Every adapter forwards it. Two backends send the headers today: Claude
+   * subscriptions (Anthropic's unified 5h/7d headers) and the ChatGPT backend
+   * (`x-codex-*`). A response that reports no window never calls it, which
+   * covers API-key accounts on every vendor and all of Gemini.
+   */
+  onRateLimit?: (reading: RateLimitReading) => void;
+  /**
+   * `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 +502,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 +532,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 {