@ultimat3/ai 27.8.1 → 27.10.0

package/src/prompt-cache.ts

@@ -0,0 +1,189 @@
+// Single responsibility: PROVIDER prompt caching — the neutral request shapes (a system prompt in
+// a stable and a per-run part, the hint that asks for the prefix to be cached) and the table that
+// says how each wire and host is told. Not the gateway's response cache, not `llm()`'s semantic one.
+//
+// THE RULE, and where it comes from (both pages read 2026-10-11):
+//
+//   Anthropic — https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching
+//     "Place `cache_control` directly on individual content blocks"; the shape is
+//     `"cache_control": { "type": "ephemeral" }` (5-minute TTL, the default).
+//     "Prompt caching references the entire prompt: `tools`, `system`, and `messages` (in that
+//     order), up to and including the block designated with `cache_control`."
+//     "You can define up to 4 cache breakpoints" — a fifth is a 400.
+//     "The system checks at most 20 positions per breakpoint, counting the breakpoint itself."
+//     "Shorter prompts cannot be cached, even if marked with `cache_control`. Any requests to cache
+//     fewer than this number of tokens will be processed without caching, and no error is
+//     returned." Minimums are per model (512 to 4,096 tokens) — `ModelSpec.cacheMinimumTokens`.
+//     "5-minute cache write tokens are 1.25 times the base input tokens price … Cache read tokens
+//     are 0.1 times the base input tokens price" (0.05x and 0.025x on named models).
+//
+//   OpenRouter — https://openrouter.ai/docs/features/prompt-caching
+//     Anthropic models: `cache_control` on a `text` part inside a message's `content` array;
+//     "There is a limit of four explicit breakpoints."
+//     Gemini: "Gemini 2.5 series models and newer support implicit caching" with no write cost; an
+//     explicit breakpoint is billed as a write (input price plus storage). So: never mark.
+//     OpenAI: automatic, no configuration. So: never mark.
+//     Stickiness: `session_id` in the body or the `x-session-id` header, at most 256 characters;
+//     "Sticky routing is skipped when you set `provider.order`" — this package sends no `provider`
+//     object at all, and must not start to.
+//     Usage: `prompt_tokens_details.cached_tokens` and `.cache_write_tokens`.
+//     https://openrouter.ai/docs/use-cases/usage-accounting: "The `usage: { include: true }` …
+//     parameters are deprecated and have no effect" — so it is not sent.
+//
+//   OpenAI — automatic above 1,024 tokens (the OpenRouter page's summary of it); the body field
+//     `prompt_cache_key` groups requests that share a prefix. OpenRouter reads it as a session id
+//     when neither `session_id` nor the header is given.
+//
+//   Checked against the live service, 2026-10-11, `anthropic/claude-sonnet-5.5` on OpenRouter, a
+//   three-turn `agent()` run: a mark on a `role: 'tool'` message's text part IS honoured (turn 2
+//   read turn 1's 19,914-token prefix and wrote 72), and `prompt_tokens` INCLUDES both the read and
+//   the written tokens — which is why ./openai-wire subtracts both.
+//
+// Two limits of the rows below, stated rather than hidden:
+//   - the `anthropic` row matches ANY host an `anthropicProvider({ baseUrl })` is pointed at — a
+//     proxy speaking that wire is assumed to speak its `cache_control` too;
+//   - the `parts` row marks the tail only, so the next turn finds this turn's entry through the
+//     20-position lookback alone. A turn that appends more blocks than that — more than about 9
+//     tool calls in ONE turn, each a `tool_use` and a `tool_result` — misses it and is billed as a
+//     fresh write of the whole transcript. The stable system block still reads.
+//
+// The table is DATA: a new host or model family is a row. Unknown endpoints get NOTHING — a field
+// a self-hosted server has never heard of is a 400 on some of them, and a mark is never worth that.
+
+/**
+ * A system prompt in two parts. `stable` is byte-identical across runs — rules, a knowledge-base
+ * index — and is what a cache shares BETWEEN runs; `run` is whatever differs per run and comes
+ * after it, so it never invalidates the stable half. A cache is a prefix match: one changed byte in
+ * `stable` (a timestamp, an unsorted list) is a full-price write on every call.
+ */
+export interface SystemParts {
+  readonly stable: string;
+  readonly run?: string;
+}
+
+/** A plain string is the whole prompt as one stable part. */
+export type SystemPrompt = string | SystemParts;
+
+/**
+ * "Cache this request's prefix": present on a `GenerateRequest`, each provider marks the stable
+ * system part and the transcript's tail the way its wire wants — or not at all, where the host
+ * caches implicitly. Absent, nothing is marked and nothing is sent.
+ */
+export interface PromptCacheHint {
+  /**
+   * A key naming the runs that share a prefix, for hosts that route or shard by one (an
+   * `x-session-id` header on OpenRouter, `prompt_cache_key` on OpenAI). Never a secret, never
+   * personal data: it leaves the process in a header.
+   */
+  readonly session?: string;
+}
+
+/** OpenRouter's documented ceiling on a session id ("Maximum length is 256 characters"). */
+export const SESSION_KEY_MAX = 256;
+
+/**
+ * The longest `prompt_cache_key` sent to OpenAI verbatim. OpenAI's prompt-caching guide and its
+ * SDK types (read 2026-10-11) state NO maximum, and its API reference could not be read from
+ * here; 64 is the conservative figure a reviewer recalled. A longer key is not refused — it is a
+ * grouping key, so it is replaced by a deterministic hash of itself: same key, same group.
+ */
+export const OPENAI_CACHE_KEY_MAX = 64;
+
+/** The one mark this package sends: the 5-minute TTL, which is the rate `costOf` prices. */
+export const CACHE_MARK = { type: 'ephemeral' } as const;
+
+/** Both parts as one text, stable first — for an estimate, and for a wire with one system string. */
+export function systemText(system: SystemPrompt | undefined): string {
+  if (system === undefined) return '';
+  if (typeof system === 'string') return system;
+  return [system.stable, system.run ?? ''].filter((part) => part !== '').join('\n\n');
+}
+
+/** The parts, normalised: `''` for an absent half, so a wire never sends an empty block. */
+export function systemParts(system: SystemPrompt | undefined): Required<SystemParts> {
+  if (system === undefined) return { stable: '', run: '' };
+  if (typeof system === 'string') return { stable: system, run: '' };
+  return { stable: system.stable, run: system.run ?? '' };
+}
+
+export type CacheWire = 'anthropic' | 'openai';
+
+export interface PromptCacheRule {
+  readonly wire: CacheWire;
+  /** A hostname and every subdomain of it; `'*'` is any endpoint on this wire. */
+  readonly host: string;
+  /** A model-id prefix; `''` is every model. */
+  readonly model: string;
+  /**
+   * `blocks`: `cache_control` on Anthropic content blocks — the stable system block and the last
+   * block of the last two messages (three of the four breakpoints; the fourth is left free).
+   * `parts`: the same mark on chat-completions content PARTS — the stable system part and the tail
+   * message's last part (two breakpoints).
+   * `none`: the host caches by itself, or is unknown.
+   */
+  readonly marks: 'blocks' | 'parts' | 'none';
+  /** Where a `PromptCacheHint.session` goes. */
+  readonly session: 'x-session-id' | 'prompt_cache_key' | 'none';
+}
+
+/** First match wins. */
+export const PROMPT_CACHE_RULES: readonly PromptCacheRule[] = [
+  { wire: 'anthropic', host: '*', model: '', marks: 'blocks', session: 'none' },
+  {
+    wire: 'openai',
+    host: 'openrouter.ai',
+    model: 'anthropic/',
+    marks: 'parts',
+    session: 'x-session-id',
+  },
+  // Gemini, OpenAI, and everything else OpenRouter fronts: implicit or automatic. An explicit mark
+  // on Gemini turns a free implicit cache into a paid write.
+  { wire: 'openai', host: 'openrouter.ai', model: '', marks: 'none', session: 'x-session-id' },
+  { wire: 'openai', host: 'api.openai.com', model: '', marks: 'none', session: 'prompt_cache_key' },
+];
+
+const NO_RULE: Pick<PromptCacheRule, 'marks' | 'session'> = { marks: 'none', session: 'none' };
+
+/** OpenAI's own endpoint, which is what an `openAiProvider()` with no `baseUrl` talks to. */
+const DEFAULT_OPENAI_HOST = 'api.openai.com';
+
+/** The rule for one request. Total: a base URL that does not parse matches no host. */
+export function promptCacheRule(
+  wire: CacheWire,
+  baseUrl: string | undefined,
+  model: string,
+): Pick<PromptCacheRule, 'marks' | 'session'> {
+  const host = baseUrl === undefined ? DEFAULT_OPENAI_HOST : hostOf(baseUrl);
+  const found = PROMPT_CACHE_RULES.find(
+    (rule) =>
+      rule.wire === wire &&
+      (rule.host === '*' || host === rule.host || host.endsWith(`.${rule.host}`)) &&
+      model.startsWith(rule.model),
+  );
+  return found ?? NO_RULE;
+}
+
+function hostOf(baseUrl: string): string {
+  return URL.canParse(baseUrl) ? new URL(baseUrl).hostname.toLowerCase() : '';
+}
+
+/**
+ * What a declaration writes: `'auto'` marks every request of the call, `'off'` marks none, and the
+ * object form is `'auto'` plus a session key — a constant, or derived per call (per org, say).
+ */
+export type PromptCacheOption<A> =
+  | 'auto'
+  | 'off'
+  | { readonly session: string | ((args: A) => string) };
+
+/** The hint one call sends on every request, or `undefined` for none. */
+export function promptCacheHint<A>(
+  option: PromptCacheOption<A> | undefined,
+  fallback: 'auto' | 'off',
+  args: A,
+): PromptCacheHint | undefined {
+  const chosen = option ?? fallback;
+  if (chosen === 'off') return undefined;
+  if (chosen === 'auto') return {};
+  return { session: typeof chosen.session === 'string' ? chosen.session : chosen.session(args) };
+}

package/src/provider.ts

@@ -1,18 +1,25 @@
-// The `Provider` interface, `AnthropicProvider` (the real Messages API, streaming and not) and
-// the money arithmetic over a call's reported usage — `EchoProvider`, the double, is
-// ./echo-provider's. The REQUEST half only: ./models owns the catalogue and the per-model rules,
+// The `Provider` interface and `AnthropicProvider` (the real Messages API, streaming and not) —
+// `EchoProvider`, the double, is ./echo-provider's, and the money arithmetic is ./cost's
+// (`costOf` is re-exported here, where every caller has always imported it from). The REQUEST half only: ./models owns the catalogue and the per-model rules,
 // ./wire owns the response half.
 
 import type { Money } from '@ultimat3/money';
 import type { AiMediaBlock } from './content-blocks';
 import { assertMediaContent, blockText, mediaTokenEstimate } from './content-blocks';
+import { costOf, exactCostOf } from './cost';
 import { detailOf, withoutKey } from './error-body';
 import { AiKeyMissingError, AiRequestInvalidError, AiTransportError } from './errors';
 import type { AiFetch } from './fetch-seam';
 import { resolveModel } from './model-resolve';
 import type { Effort, ModelId, ThinkingMode } from './models';
 import { modelSpec, reasoningBody } from './models';
+import type { PromptCacheHint, SystemPrompt } from './prompt-cache';
+import { promptCacheRule, systemText } from './prompt-cache';
+import { anthropicPrompt } from './prompt-cache-blocks';
+import type { SamplingWire } from './sampling';
+import { samplingBody } from './sampling';
 import { readSse } from './sse';
+import { assertToolArguments } from './tool-arguments';
 import type { LlmTool, LlmToolCall } from './tools';
 import {
   asToolInput,
@@ -65,7 +72,14 @@ export function messageText(message: AiMessage): string {
 
 export interface GenerateRequest {
   readonly model?: ModelId;
-  readonly system?: string;
+  /** One string, or a stable part and a per-run part (`./prompt-cache`) — two blocks on the wire. */
+  readonly system?: SystemPrompt;
+  /**
+   * Ask the provider to cache this request's prefix: the stable system part and the transcript's
+   * tail, marked per wire and host by `PROMPT_CACHE_RULES`. Absent sends no mark. Not part of
+   * `promptCacheKey` — it changes what a call costs, never what it answers.
+   */
+  readonly promptCache?: PromptCacheHint;
   readonly messages: readonly AiMessage[];
   /** Enforced output ceiling. The model never sees it, so it can be cut off mid-answer. */
   readonly maxTokens: number;
@@ -73,6 +87,10 @@ export interface GenerateRequest {
   readonly thinking?: ThinkingMode;
   readonly tools?: readonly LlmTool[];
   readonly stopSequences?: readonly string[];
+  /** Sent only to a model whose row takes it (`ModelSpec.sampling`, `./sampling`). 0 to 2. */
+  readonly temperature?: number;
+  /** As `temperature`; chat-completions only — the Messages API has no seed. */
+  readonly seed?: number;
   /**
    * The caller's abort signal, forwarded to the socket by every provider in this package.
    *
@@ -137,8 +155,14 @@ export interface GenerateResult {
   /** Required, not optional: a provider that forgets it turns a refusal into a silent empty answer. */
   readonly stopDetails: StopDetails | undefined;
   readonly usage: TokenUsage;
-  /** Cost of this call, computed from `usage` and the model's prices. */
+  /** Cost of this call in the currency's minor units, rounded up once (`costOf`). */
   readonly cost: Money;
+  /**
+   * The same cost EXACTLY, as `Money` at a finer `scale` (`exactCostOf`) — what a ledger sums, so
+   * a run of cheap calls is rounded once at the end and not once per call. Optional: a `Provider`
+   * an app wrote may not state it, and its `cost` is summed in its place.
+   */
+  readonly costExact?: Money;
 }
 
 /** One streamed increment. `done` carries the assembled result. */
@@ -148,39 +172,22 @@ export type StreamChunk =
   | { readonly type: 'tool-call'; readonly call: LlmToolCall }
   | { readonly type: 'done'; readonly result: GenerateResult };
 
+export { costOf } from './cost';
+
 export interface Provider {
   readonly name: string;
   /** Models this provider can serve. The gateway routes by membership. */
   readonly models: readonly ModelId[];
   generate(request: GenerateRequest): Promise<GenerateResult>;
   stream(request: GenerateRequest): AsyncIterable<StreamChunk>;
-}
-
-/**
- * Cost of one call, in integer minor units. Rounded UP: a fraction of a cent that we round
- * away is money the framework silently absorbs, and under-reporting spend defeats a budget.
- */
-export function costOf(model: ModelId, usage: TokenUsage): Money {
-  // The one price lookup: a model the app never `registerModel`-ed is `X_AI_MODEL_UNKNOWN` here,
-  // so no call is priced — and no budget reserved — against a number nobody chose.
-  const spec = modelSpec(model);
-  const input = spec.inputPerMillion.minor;
-  // In TWENTIETHS of a minor unit, so the standard multipliers stay integral on any whole price:
-  // a cache read is 0.1x input (2/20) and a 5-minute write 1.25x (25/20) unless the row states
-  // its own — Opus 5.5 reads at 0.05x and Fable 5.1 at 0.025x, which a fixed 0.1x overstated.
-  const read =
-    spec.cacheReadPerMillion === undefined ? input * 2 : spec.cacheReadPerMillion.minor * 20;
-  const write =
-    spec.cacheWritePerMillion === undefined ? input * 25 : spec.cacheWritePerMillion.minor * 20;
-  const inputUnits =
-    usage.inputTokens * input * 20 + usage.cacheReadTokens * read + usage.cacheWriteTokens * write;
-  const inputMinor = divideCeil(inputUnits, 20_000_000);
-  const outputMinor = divideCeil(usage.outputTokens * spec.outputPerMillion.minor, 1_000_000);
-  return { minor: inputMinor + outputMinor, currency: spec.inputPerMillion.currency };
-}
-
-function divideCeil(numerator: number, denominator: number): number {
-  return Math.ceil(numerator / denominator);
+  /**
+   * Whether a request carrying `promptCache` for this model would be sent with an explicit cache
+   * mark — billed as a cache WRITE. Absent is no: the gateway prices the write only where one
+   * can happen.
+   */
+  marksPromptCache?(model: ModelId): boolean;
+  /** Which wire format this provider speaks, when it is one of the two built in (`./sampling`). */
+  readonly wire?: SamplingWire;
 }
 
 /** Total tokens a usage record accounts for — what a budget is debited by. */
@@ -228,12 +235,14 @@ export function anthropicProvider(input: AnthropicProviderInput): AnthropicProvi
 /**
  * The real Messages API shape. The request-surface rules are encoded rather than documented,
  * because getting them wrong is a 400:
- *   - `temperature`/`top_p`/`top_k` are REJECTED on every current model. Steer with the prompt.
+ *   - `top_p`/`top_k` are never sent, and `temperature` only to a model whose row takes it
+ *     (`ModelSpec.sampling`): a reasoning model rejects all three.
  *   - `thinking.budget_tokens` is REJECTED. Use `output_config.effort`.
  *   - `effort` and adaptive thinking are per-model, and ./models owns which model takes which.
  */
 export class AnthropicProvider implements Provider {
   readonly name = 'anthropic';
+  readonly wire = 'anthropic' as const;
   /** The app's list, never the registry's: a model served elsewhere must not be routed here. */
   readonly models: readonly ModelId[];
   private readonly config: AnthropicProviderInput;
@@ -316,25 +325,37 @@ export class AnthropicProvider implements Provider {
           'the stream ended before message_stop, or with a tool call still open — the answer is truncated',
       });
     }
-    const state = message.state();
+    const { malformed, ...state } = message.state();
+    const cost = costOf(model, state.usage);
+    // After usage is known, so a finished turn with unreadable arguments fails WITH its bill.
+    assertToolArguments({ provider: this.name, model, ...state, malformed, cost });
     yield {
       type: 'done',
-      result: { model, ...state, cost: costOf(model, state.usage) },
+      result: { model, ...state, cost, costExact: exactCostOf(model, state.usage) },
     };
   }
 
+  marksPromptCache(model: ModelId): boolean {
+    return promptCacheRule('anthropic', this.config.baseUrl, model).marks === 'blocks';
+  }
+
   /** The request body. Pure and side-effect free so a test can assert it directly. */
   body(request: GenerateRequest): Record<string, unknown> {
     const model = this.modelOf(request);
     // The blocks pass through untouched below — they ARE this wire's shapes — so this is the screen.
     assertMediaContent(request.messages, { provider: this.name, model });
+    const prompt = anthropicPrompt(
+      request,
+      request.promptCache !== undefined && this.marksPromptCache(model),
+    );
     const body: Record<string, unknown> = {
       model,
       max_tokens: Math.min(request.maxTokens, modelSpec(model).maxOutput),
-      messages: request.messages.map((m) => ({ role: m.role, content: m.content })),
+      messages: prompt.messages,
       ...reasoningBody(model, request.effort, request.thinking),
+      ...samplingBody('anthropic', model, request),
     };
-    if (request.system !== undefined) body['system'] = request.system;
+    if (prompt.system !== undefined) body['system'] = prompt.system;
     if (request.tools !== undefined && request.tools.length > 0) body['tools'] = request.tools;
     if (request.stopSequences !== undefined) body['stop_sequences'] = request.stopSequences;
     return body;
@@ -421,6 +442,7 @@ export function parseMessage(model: ModelId, raw: Record<string, unknown>): Gene
     stopDetails,
     usage,
     cost: costOf(model, usage),
+    costExact: exactCostOf(model, usage),
   };
 }
 
@@ -439,7 +461,7 @@ const completionCeiling = (request: GenerateRequest): number =>
 /** The prompt half alone — what the provider bills at the input rate. */
 export function estimateInputTokens(request: GenerateRequest): number {
   const body = request.messages.map(messageText).join(' ');
-  const text = estimateTextTokens(body) + estimateTextTokens(request.system ?? '');
+  const text = estimateTextTokens(body) + estimateTextTokens(systemText(request.system));
   return text + mediaTokenEstimate(request.messages);
 }
 
@@ -448,13 +470,17 @@ export function estimateInputTokens(request: GenerateRequest): number {
  * `maxTokens` at the output rate. Deliberately pessimistic — a ceiling checked against an
  * optimistic estimate is a ceiling one long completion walks through.
  */
-export function estimateCost(request: GenerateRequest): Money {
-  return costOf(resolveModel('provider', request.model), {
-    inputTokens: estimateInputTokens(request),
-    outputTokens: completionCeiling(request),
-    cacheReadTokens: 0,
-    cacheWriteTokens: 0,
-  });
+export function estimateCost(request: GenerateRequest, marked = false): Money {
+  const model = resolveModel('provider', request.model);
+  const prompt = estimateInputTokens(request);
+  const usage = { outputTokens: completionCeiling(request), cacheReadTokens: 0 };
+  const asInput = costOf(model, { ...usage, inputTokens: prompt, cacheWriteTokens: 0 });
+  // A request a provider WILL mark (`marked`: the gateway asks the providers serving the model) can
+  // be billed as a cache write end to end. The DEARER of the two: a row whose write is cheaper
+  // than input must not lower the ceiling's estimate below what an unmarked call costs.
+  if (!marked || request.promptCache === undefined) return asInput;
+  const asWrite = costOf(model, { ...usage, inputTokens: 0, cacheWriteTokens: prompt });
+  return asWrite.minor > asInput.minor ? asWrite : asInput;
 }
 
 export function estimateTextTokens(text: string): number {

package/src/run-meter.ts

@@ -0,0 +1,147 @@
+// Single responsibility: one run's meter — every provider call an `llm()` or an `agent()` makes
+// goes through it, so the run always knows what it was billed, and a failure can say so.
+//
+// The ledger is not the place to read this from: a ledger is shared (a job's scope, an org's
+// window), and the question a failed job asks is about THIS run.
+
+import { asyncContext, isUltimateError } from '@ultimat3/core';
+import type { AgentRunUsage } from './agent-usage';
+import { addUsage } from './agent-usage';
+import type { Billed } from './billed';
+import { BILLED_META, billedCall, billedOf } from './billed';
+import { addMoney } from './cost';
+import type { GenerateResult } from './provider';
+import { ZERO_USAGE } from './wire';
+
+export interface RunMeter {
+  /**
+   * Await one provider call. Until it reports usage it is UNSETTLED: an abort, a deadline or a
+   * transport failure leaves it that way, and its bill cannot be known from here.
+   */
+  call(work: Promise<GenerateResult>): Promise<GenerateResult>;
+  /** The run so far, re-priced from the summed usage — `undefined` before the first answer. */
+  total(): AgentRunUsage | undefined;
+  /** The run's bill, or `undefined` when no provider call was ever started. */
+  billed(): Billed | undefined;
+  /**
+   * What runs UNDERNEATH this one were billed — a tool that itself calls `llm()` or an `agent()`.
+   * Their failures are read by the model as tool results and never thrown here, so this is the
+   * only way that spend reaches the run that caused it.
+   */
+  below(): Billed | undefined;
+  /** Run `fn` with this meter as the one nested runs report to. */
+  within<T>(fn: () => T): T;
+  /**
+   * `error`, carrying the run's bill on `meta.billed`. Returned for a `throw`, never thrown here.
+   * Only an `UltimateError` has a `meta` to carry it; anything else is returned untouched (the
+   * ledger still holds the bill).
+   */
+  fail(error: unknown): unknown;
+}
+
+// The meter of the run in flight, so a run started underneath it can report upward.
+const meters = asyncContext<{ report(bill: Billed): void }>('an AI run meter');
+
+/** Errors a nested meter already reported upward: their `meta.billed` must not be added again. */
+const reported = new WeakSet<object>();
+
+export function runMeter(): RunMeter {
+  const parent = meters.get();
+  let nested: Billed | undefined;
+  const report = (bill: Billed): void => {
+    nested = nested === undefined ? bill : sum(nested, bill);
+    parent?.report(bill);
+  };
+  let own: AgentRunUsage | undefined;
+  let calls = 0;
+  let unsettled = 0;
+  // Bills that arrived ON an error and were not priced by this meter: a provider's
+  // `X_LLM_TOOL_ARGUMENTS_INVALID`, or a nested run's failure passing through.
+  let carried: Billed | undefined;
+  const counted = new WeakSet<object>();
+
+  const absorb = (error: unknown): void => {
+    const billed = billedOf(error);
+    if (billed === undefined || typeof error !== 'object' || error === null) return;
+    if (counted.has(error) || reported.has(error)) return;
+    counted.add(error);
+    carried = carried === undefined ? billed : sum(carried, billed);
+  };
+
+  const billed = (): Billed | undefined => {
+    const direct = directBill();
+    if (direct === undefined) return nested;
+    return nested === undefined ? direct : sum(direct, nested);
+  };
+  const directBill = (): Billed | undefined => {
+    if (calls === 0 && unsettled === 0 && carried === undefined) return undefined;
+    const mine: Billed = {
+      usage: own?.usage ?? ZERO_USAGE,
+      cost: own?.cost ?? carried?.cost ?? { minor: 0, currency: 'USD' },
+      calls,
+      unsettled,
+    };
+    if (carried === undefined) return mine;
+    return own === undefined
+      ? { ...carried, unsettled: carried.unsettled + unsettled }
+      : sum(mine, carried);
+  };
+
+  return {
+    async call(work) {
+      unsettled += 1;
+      try {
+        const result = await work;
+        unsettled -= 1;
+        calls += 1;
+        own = addUsage(own, result);
+        parent?.report(billedCall(result.usage, result.costExact ?? result.cost));
+        return result;
+      } catch (error) {
+        // The provider answered and billed, then the answer could not be used: settled after all.
+        const bill = billedOf(error);
+        if (bill !== undefined) {
+          unsettled -= 1;
+          absorb(error);
+          parent?.report(bill);
+        }
+        throw error;
+      }
+    },
+    total: () => own,
+    billed,
+    below: () => nested,
+    within: (fn) => meters.run({ report }, fn),
+    fail(error) {
+      absorb(error);
+      // Everything this run was billed already reached the parent call by call.
+      if (parent !== undefined && typeof error === 'object' && error !== null) reported.add(error);
+      const bill = billed();
+      if (bill === undefined || !isUltimateError(error)) return error;
+      // An error is thrown once, by the run it failed, and `meta` is a plain own property the
+      // constructor assigned. Written in place rather than wrapped: a wrapper would be a second
+      // error with a different stack, and every reader upstream matches on the ORIGINAL's code.
+      try {
+        Reflect.set(error, 'meta', { ...error.meta, [BILLED_META]: bill });
+      } catch {
+        // A frozen error keeps the meta it was thrown with.
+      }
+      return error;
+    },
+  };
+}
+
+/** Two bills as one. A cost in another currency cannot be added and is left out of the sum. */
+function sum(a: Billed, b: Billed): Billed {
+  return {
+    usage: {
+      inputTokens: a.usage.inputTokens + b.usage.inputTokens,
+      outputTokens: a.usage.outputTokens + b.usage.outputTokens,
+      cacheReadTokens: a.usage.cacheReadTokens + b.usage.cacheReadTokens,
+      cacheWriteTokens: a.usage.cacheWriteTokens + b.usage.cacheWriteTokens,
+    },
+    cost: a.cost.currency === b.cost.currency ? addMoney(a.cost, b.cost) : a.cost,
+    calls: a.calls + b.calls,
+    unsettled: a.unsettled + b.unsettled,
+  };
+}

package/src/sampling.ts

@@ -0,0 +1,86 @@
+// Single responsibility: the two determinism knobs a request may carry — `temperature` and `seed`
+// — screened once where they are declared, and written onto a wire body only for a model whose
+// row says it takes them.
+//
+// A row decides, never an `if` in a body builder (the rule `reasoningBody` follows): a reasoning
+// model in either family answers a sampling parameter with a 400, and which models those are is
+// the app's catalogue. So `ModelSpec.sampling` is the switch, absent means NOT SENT — every row
+// that predates it keeps sending exactly what it sent — and an asked-for knob the row does not
+// take is left out, not refused: a verifier that asks for `temperature: 0` still runs on a model
+// that has no such control, and `ignoredSampling` is what a span says about it.
+
+import { AiRequestInvalidError } from './errors';
+import type { ModelId } from './models';
+import { modelSpec } from './models';
+
+export interface Sampling {
+  /** 0 to 2. `0` is the most repeatable a model offers; it is not a guarantee of determinism. */
+  readonly temperature?: number;
+  /** A whole number. Honoured by chat-completions endpoints that support it; best effort there. */
+  readonly seed?: number;
+}
+
+/** Which knobs each wire HAS. The Messages API has no `seed` at all. */
+const WIRE_KNOBS = {
+  openai: ['temperature', 'seed'],
+  anthropic: ['temperature'],
+} as const;
+
+export type SamplingWire = keyof typeof WIRE_KNOBS;
+
+/** A declaration's knobs, screened: a `NaN` temperature or a fractional seed is a 400 mid-run. */
+export function screenSampling(subject: string, sampling: Sampling): Sampling {
+  const { temperature, seed } = sampling;
+  if (
+    temperature !== undefined &&
+    !(Number.isFinite(temperature) && temperature >= 0 && temperature <= 2)
+  ) {
+    throw new AiRequestInvalidError({
+      detail: `${subject} temperature is ${String(temperature)}; it must be a number from 0 to 2`,
+      fix: `temperature: 0   # on the ${subject}() declaration — 0 to 2, or drop the key`,
+    });
+  }
+  if (seed !== undefined && !Number.isSafeInteger(seed)) {
+    throw new AiRequestInvalidError({
+      detail: `${subject} seed is ${String(seed)}; it must be a whole number`,
+      fix: `seed: 7   # on the ${subject}() declaration — a whole number, or drop the key`,
+    });
+  }
+  return {
+    ...(temperature === undefined ? {} : { temperature }),
+    ...(seed === undefined ? {} : { seed }),
+  };
+}
+
+/** The body fields for the knobs this request asks for AND this model, on this wire, takes. */
+export function samplingBody(
+  wire: SamplingWire,
+  model: ModelId,
+  request: Sampling,
+): Record<string, number> {
+  const accepts = modelSpec(model).sampling;
+  const body: Record<string, number> = {};
+  for (const knob of WIRE_KNOBS[wire]) {
+    const value = request[knob];
+    if (value !== undefined && accepts?.[knob] === true) body[knob] = value;
+  }
+  return body;
+}
+
+/** The knobs a request asked for that no wire will send to `model` — what a span reports. */
+export function ignoredSampling(
+  model: ModelId,
+  request: Sampling,
+  /** The wire formats of the providers serving `model`, when the gateway can say. */
+  wires?: readonly SamplingWire[],
+): readonly string[] {
+  const accepts = modelSpec(model).sampling;
+  // A knob no serving wire has a word for is dropped too — `seed` on the Messages API.
+  const sendable = (knob: 'temperature' | 'seed'): boolean =>
+    wires === undefined ||
+    wires.length === 0 ||
+    wires.some((wire) => (WIRE_KNOBS[wire] as readonly string[]).includes(knob));
+  return (['temperature', 'seed'] as const).filter(
+    (knob) => request[knob] !== undefined && (accepts?.[knob] !== true || !sendable(knob)),
+  );
+}