@plurnk/plurnk-providers 1.5.0 → 1.6.0

package/src/AiSdkProvider.ts

@@ -6,19 +6,40 @@
 // ordinary vendor protocol. The compatible URL path remains only for PLURNK
 // extensions and local endpoint probes the SDK cannot represent.
 
-import type { AuthoritativeChargeNormalizer, ChatMessage, GrammarEvidence, PromptTokenMeasurement, Provider, ProviderResponse, ProviderUsage } from "./types.ts";
+import type {
+    ChatMessage,
+    GrammarEvidence,
+    PromptTokenMeasurement,
+    Provider,
+    ProviderCostNormalizer,
+    ProviderCallKind,
+    ProviderGenerateArgs,
+    ProviderRequestAccounting,
+    ProviderRequestObserver,
+    ProviderRequestSettlement,
+    ProviderResponse,
+    ProviderUsage,
+} from "./types.ts";
 import type { ProviderCost } from "@plurnk/plurnk-contracts";
+import type { JSONValue } from "ai";
+import { MAX_PROVIDER_TIMEOUT_MS } from "./env.ts";
 import type { Reasoning, ReasoningResponseStyle, ReserveSpec } from "./env.ts";
-import { executeAiSdkModel, executeOpenAICompatible } from "./aiSdkTransport.ts";
+import {
+    executeAiSdkModel,
+    executeOpenAICompatible,
+    transportFailureEvidence,
+} from "./aiSdkTransport.ts";
 import type { LanguageModel } from "ai";
-import { toProviderError, ProviderError } from "./errors.ts";
-import { attributeUnitemizedReasoning } from "./usage.ts";
+import { prepareRetries } from "ai/internal";
+import { toProviderError, ProviderError, ProviderTimeoutError } from "./errors.ts";
 import type { ProviderNotice } from "./notices.ts";
 import { validateGbnf } from "@plurnk/gbnf";
 import { assertPromptTokenMeasurement, estimatePromptTokens } from "./promptTokens.ts";
 import { emitWarningOnce } from "./warnings.ts";
 import type { PluginAttribution, PluginAttributionContext } from "@plurnk/plurnk-meta";
-import { validateAuthoritativeCharge } from "./cost.ts";
+import { resolveProviderCost } from "./cost.ts";
+import { validateProviderRequestAccounting } from "./accounting.ts";
+import { validateProviderUsage } from "./usage.ts";
 
 export type ProviderFetch = typeof globalThis.fetch;
 
@@ -30,30 +51,40 @@ export type ReasoningStyle = "none" | "think" | "include_reasoning" | "effort" |
 // service-managed constrained sampling; endpoint-owned settings are not inferred.
 export type GrammarStyle = "none" | "llamacpp";
 
+export type CacheAffinity =
+    | { readonly target: "header" | "body"; readonly name: string }
+    | { readonly target: "provider-option"; readonly provider: string; readonly name: string };
+
+export type AiSdkProviderOptions = Record<string, Record<string, JSONValue | undefined>>;
+
 export type AiSdkProviderConfig = {
     model: string;
     url?: string;                             // OpenAI-compatible chat-completions URL
     languageModel?: LanguageModel;            // native AI SDK provider model
     attributions?: (context: PluginAttributionContext) => PluginAttribution;
-    fetchTimeoutMs: number;
-    streamIdleTimeoutMs?: number;             // streamed body inter-chunk deadline; zero/unset disables
+    fetchTimeoutMs: number;                    // one physical generation attempt; zero disables
+    operationTimeoutMs: number;                // complete logical call across retries/backoff; zero disables
+    firstContentTimeoutMs: number;             // first semantic streamed content; zero disables
+    streamIdleTimeoutMs?: number;             // semantic streamed-content idle deadline; zero/unset disables
     headers?: Record<string, string>;         // fully-resolved request headers (incl. auth); default {}
     fetch?: ProviderFetch;                    // per-instance request executor; default globalThis.fetch
     contextWindow?: number | null;              // default null; caller resolves-or-fails, narrows to required with the interface
     reasoningStyle?: ReasoningStyle;          // default "none"
     reasoningResponseStyle?: ReasoningResponseStyle; // {§provider-tagged-reasoning}; default "verbatim"
     countPromptTokens?: (messages: readonly ChatMessage[], signal?: AbortSignal) => PromptTokenMeasurement | Promise<PromptTokenMeasurement>;
-    calculateCost?: (usage: ProviderUsage) => number; // default () => 0
-    calculateCharge?: (usage: ProviderUsage) => Exclude<ProviderCost, { kind: "authoritative" }>;
-    normalizeCharge?: AuthoritativeChargeNormalizer;
+    estimateCost?: (usage: ProviderUsage | undefined) => ProviderCost;
+    normalizeCost?: ProviderCostNormalizer;
     source?: string;                           // notice/problem source, e.g. "provider:openai"; default "provider"
     grammarStyle?: GrammarStyle;               // how a GBNF grammar is carried; default "none" (not sent)
-    // Send the OpenAI-standard `prompt_cache_key` set to workerId, so a
-    // serverless backend with REPLICA-LOCAL prompt caching (fireworks, verified)
-    // pins a worker's turns to one replica and claims its stable prefix. Default
-    // false -- a backend that strict-validates unknown fields 400s, so enable only
-    // where the field is accepted. Same identity that already drives slot affinity.
-    promptCacheKey?: boolean;
+    // {§provider-cache-affinity} Provider routes own the exact documented
+    // projection; the common transport only applies it as managed request state.
+    cacheAffinity?: CacheAffinity;
+    // {§provider-cache-write-policy} Already policy-gated by provider construction.
+    // The transport attaches it to only the final leading system instruction.
+    systemCacheProviderOptions?: AiSdkProviderOptions;
+    // {§provider-readable-reasoning} Route-owned native option needed to expose
+    // readable reasoning. Applied only when the effective posture is not off.
+    reasoningResponseProviderOptions?: AiSdkProviderOptions;
     // Optional provider-configured service tier. Unlike caller sampling, this is
     // a fixed deployment choice and therefore wins on every request.
     serviceTier?: string;
@@ -83,9 +114,9 @@ export type AiSdkProviderConfig = {
     requiresMaxTokens?: boolean;
     // The side-channel reasoning intent — REQUIRED, no in-code default
     // (PLURNK_PROVIDERS_REASONING + _BUDGET, read via reasoningFromEnv):
-    // { mode: off|adaptive|on, budget: iff on }. The provider maps it to the
-    // backend's mechanism via reasoningStyle; budget is only ever a magnitude,
-    // never a hidden activation flag.
+    // { mode: off|adaptive|on, budget: optional when on }. The provider maps it
+    // to the backend's mechanism via reasoningStyle; budget is only ever an
+    // explicit magnitude, never a hidden activation flag.
     reasoning: Reasoning;
     // Decode tuning: no in-code defaults; the canonical measured values (0.2 /
     // 1.15) ship as the floor in .env.defaults (alias-scopable). `temperature` is the
@@ -140,6 +171,20 @@ export type AiSdkProviderConfig = {
     tuningFloors?: boolean;
 };
 
+class ProviderRequestObserverError extends Error {
+    constructor(cause: unknown) {
+        super("provider request accounting could not be durably settled", { cause });
+        this.name = "ProviderRequestObserverError";
+    }
+}
+
+class ProviderRequestAccountingError extends Error {
+    constructor(cause: unknown) {
+        super("provider request accounting could not be normalized", { cause });
+        this.name = "ProviderRequestAccountingError";
+    }
+}
+
 // Drop trailing occurrences of a server-rendered EOG marker. llama-server
 // under --special renders EOS as literal text, so a raw-EOS-ended turn carries a
 // trailing <eos> the grammar never sanctioned. Trailing-only + exact-match, so it
@@ -197,12 +242,19 @@ const projectTaggedReasoning = (
     ? projectLeadingReasoning(content, structuredReasoning, "<think>", "</think>")
     : { content, reasoning: structuredReasoning, projected: false, contentStart: 0 };
 
-// llama-server's template reasoning parser can project this leading channel out
-// of the OpenAI-compatible response. Grammar evidence needs the sentence before
-// that lossy projection, so constrained template turns request it verbatim and
-// split the observed enclosure here.
-const projectTemplateReasoning = (content: string): TaggedReasoningProjection =>
-    projectLeadingReasoning(content, "", "<|channel>thought\n", "<channel|>");
+// llama-server's template reasoning parser can project either supported leading
+// reasoning envelope out of the OpenAI-compatible response. Grammar evidence
+// needs the sentence before that lossy projection, so constrained template turns
+// request it verbatim and split the observed enclosure here.
+const projectTemplateReasoning = (content: string): TaggedReasoningProjection => {
+    for (const [opening, closing] of [
+        ["<|channel>thought\n", "<channel|>"],
+        ["<think>\n", "</think>"],
+    ] as const) {
+        if (content.startsWith(opening)) return projectLeadingReasoning(content, "", opening, closing);
+    }
+    return { content, reasoning: "", projected: false, contentStart: 0 };
+};
 
 // Shared budget→effort breakpoints (xai and google had identical copies).
 export const effortFromBudget = (budget: number): "low" | "medium" | "high" => {
@@ -211,6 +263,13 @@ export const effortFromBudget = (budget: number): "low" | "medium" | "high" => {
     return "high";
 };
 
+// AI SDK's portable reasoning control has no boolean-enabled value. `medium`
+// is the neutral activation projection for an explicit, unqualified `on`; it
+// changes no PLURNK token reserve. An operator budget, when present, remains
+// the only input to the existing magnitude-to-tier projection.
+const effortFromReasoning = (reasoning: Reasoning): "low" | "medium" | "high" =>
+    reasoning.budget === null ? "medium" : effortFromBudget(reasoning.budget);
+
 // Body keys the provider owns — a caller's `sampling` passthrough may not set
 // these. Two families:
 //   transport/managed — grammar transport, the stream/JSON choice, slot pinning,
@@ -238,6 +297,8 @@ export default class AiSdkProvider implements Provider {
     #url: string | undefined;
     #languageModel: LanguageModel | undefined;
     #fetchTimeoutMs: number;
+    #operationTimeoutMs: number;
+    #firstContentTimeoutMs: number;
     #streamIdleTimeoutMs: number | undefined;
     #headers: Record<string, string>;
     #fetch: ProviderFetch;
@@ -257,12 +318,13 @@ export default class AiSdkProvider implements Provider {
     #reasoningResponseStyle: ReasoningResponseStyle;
     #countPromptTokens: (messages: readonly ChatMessage[], signal?: AbortSignal) => PromptTokenMeasurement | Promise<PromptTokenMeasurement>;
     #promptTokensUrl: string | undefined;
-    #calculateCost: (usage: ProviderUsage) => number;
-    #calculateCharge?: (usage: ProviderUsage) => Exclude<ProviderCost, { kind: "authoritative" }>;
-    #normalizeCharge?: AuthoritativeChargeNormalizer;
+    #estimateCost: (usage: ProviderUsage | undefined) => ProviderCost;
+    #normalizeCost?: ProviderCostNormalizer;
     #source: string;
     #grammarStyle: GrammarStyle;
-    #promptCacheKey: boolean;
+    #cacheAffinity: CacheAffinity | undefined;
+    #systemCacheProviderOptions: AiSdkProviderOptions | undefined;
+    #reasoningResponseProviderOptions: AiSdkProviderOptions | undefined;
     #serviceTier: string | undefined;
     #gbnfDebug: boolean;
     #streaming: boolean;
@@ -293,7 +355,19 @@ export default class AiSdkProvider implements Provider {
         if ((this.#url === undefined) === (this.#languageModel === undefined)) {
             throw new Error(`${config.source ?? "provider"}: configure exactly one AI SDK model or OpenAI-compatible URL`);
         }
+        for (const [name, value] of [
+            ["fetchTimeoutMs", config.fetchTimeoutMs],
+            ["operationTimeoutMs", config.operationTimeoutMs],
+            ["firstContentTimeoutMs", config.firstContentTimeoutMs],
+            ["streamIdleTimeoutMs", config.streamIdleTimeoutMs],
+        ] as const) {
+            if (value !== undefined && (!Number.isInteger(value) || value < 0 || value > MAX_PROVIDER_TIMEOUT_MS)) {
+                throw new Error(`${config.source ?? "provider"}: ${name} must be an integer from 0 through ${MAX_PROVIDER_TIMEOUT_MS} milliseconds`);
+            }
+        }
         this.#fetchTimeoutMs = config.fetchTimeoutMs;
+        this.#operationTimeoutMs = config.operationTimeoutMs;
+        this.#firstContentTimeoutMs = config.firstContentTimeoutMs;
         this.#streamIdleTimeoutMs = config.streamIdleTimeoutMs;
         this.#headers = config.headers ?? {};
         this.#fetch = config.fetch ?? ((input, init) => globalThis.fetch(input, init));
@@ -321,12 +395,36 @@ export default class AiSdkProvider implements Provider {
         }
         this.#countPromptTokens = config.countPromptTokens ?? ((messages) => estimatePromptTokens(messages));
         this.#promptTokensUrl = config.promptTokensUrl;
-        this.#calculateCost = config.calculateCost ?? (() => 0);
-        this.#calculateCharge = config.calculateCharge;
-        this.#normalizeCharge = config.normalizeCharge;
+        this.#estimateCost = config.estimateCost
+            ?? (() => ({
+                kind: "unknown",
+                reason: "the request reported no direct cost and no model rate is configured",
+            }));
+        this.#normalizeCost = config.normalizeCost;
         this.#source = config.source ?? "provider";
         this.#grammarStyle = config.grammarStyle ?? "none";
-        this.#promptCacheKey = config.promptCacheKey ?? false;
+        this.#cacheAffinity = config.cacheAffinity;
+        this.#systemCacheProviderOptions = config.systemCacheProviderOptions;
+        this.#reasoningResponseProviderOptions = config.reasoningResponseProviderOptions;
+        if (this.#languageModel === undefined && this.#cacheAffinity?.target === "provider-option") {
+            throw new Error(`${this.#source}: native provider-option cache affinity requires an AI SDK model`);
+        }
+        if (this.#languageModel !== undefined && this.#cacheAffinity?.target === "body") {
+            throw new Error(`${this.#source}: body cache affinity requires an OpenAI-compatible URL`);
+        }
+        if (this.#languageModel === undefined && this.#systemCacheProviderOptions !== undefined) {
+            throw new Error(`${this.#source}: system cache provider options require an AI SDK model`);
+        }
+        if (this.#languageModel === undefined && this.#reasoningResponseProviderOptions !== undefined) {
+            throw new Error(`${this.#source}: reasoning response provider options require an AI SDK model`);
+        }
+        if (this.#cacheAffinity?.target === "provider-option"
+            && Object.hasOwn(
+                this.#reasoningResponseProviderOptions?.[this.#cacheAffinity.provider] ?? {},
+                this.#cacheAffinity.name,
+            )) {
+            throw new Error(`${this.#source}: reasoning response options conflict with cache-affinity option ${this.#cacheAffinity.provider}.${this.#cacheAffinity.name}`);
+        }
         this.#serviceTier = config.serviceTier;
         this.#gbnfDebug = config.gbnfDebug ?? false;
         this.#streaming = config.streaming ?? true;
@@ -346,10 +444,17 @@ export default class AiSdkProvider implements Provider {
         const reasoningReserve = this.reasoningReserve;
         if (this.#reasoningStyle === "template"
             && this.#reasoning.mode === "on"
+            && this.#reasoning.budget !== null
             && reasoningReserve !== null
-            && this.#reasoning.budget! > reasoningReserve) {
+            && this.#reasoning.budget > reasoningReserve) {
             throw new Error(`${this.#source}: PLURNK_PROVIDERS_REASONING_BUDGET (${this.#reasoning.budget}) exceeds the resolved PLURNK_PROVIDERS_REASONING_RESERVE (${reasoningReserve})`);
         }
+        if (this.#reasoningStyle === "anthropic"
+            && this.#reasoning.mode === "on"
+            && this.#reasoning.budget === null
+            && reasoningReserve === null) {
+            throw new Error(`${this.#source}: explicit Anthropic reasoning requires a resolved reasoning reserve or PLURNK_PROVIDERS_REASONING_BUDGET`);
+        }
         const { tokenizeUrl } = config;
         if (tokenizeUrl !== undefined) {
             this.tokenize = async (text: string): Promise<number[]> => {
@@ -357,7 +462,9 @@ export default class AiSdkProvider implements Provider {
                     method: "POST",
                     headers: { "Content-Type": "application/json", ...this.#headers },
                     body: JSON.stringify({ content: text }),
-                    signal: AbortSignal.timeout(this.#fetchTimeoutMs),
+                    ...(this.#fetchTimeoutMs > 0
+                        ? { signal: AbortSignal.timeout(this.#fetchTimeoutMs) }
+                        : {}),
                 });
                 if (!res.ok) throw new Error(`${this.#source}: tokenize endpoint returned ${res.status}`);
                 const { tokens } = (await res.json()) as { tokens?: unknown };
@@ -402,7 +509,14 @@ export default class AiSdkProvider implements Provider {
 
         signal?.throwIfAborted();
         try {
-            const timeout = AbortSignal.timeout(this.#fetchTimeoutMs);
+            const timeout = this.#fetchTimeoutMs > 0
+                ? AbortSignal.timeout(this.#fetchTimeoutMs)
+                : undefined;
+            const requestSignal = signal === undefined
+                ? timeout
+                : timeout === undefined
+                    ? signal
+                    : AbortSignal.any([signal, timeout]);
             const response = await this.#fetch(this.#promptTokensUrl, {
                 method: "POST",
                 headers: { "Content-Type": "application/json", ...this.#headers },
@@ -411,7 +525,7 @@ export default class AiSdkProvider implements Provider {
                     messages,
                     ...this.#reasoningBody(),
                 }),
-                signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
+                ...(requestSignal === undefined ? {} : { signal: requestSignal }),
             });
             if (!response.ok) {
                 return estimatePromptTokens(
@@ -439,12 +553,6 @@ export default class AiSdkProvider implements Provider {
             );
         }
     }
-    calculateCost(usage: ProviderUsage): number { return this.#calculateCost(usage); }
-    calculateCharge(usage: ProviderUsage): Exclude<ProviderCost, { kind: "authoritative" }> {
-        return this.#calculateCharge?.(usage)
-            ?? { kind: "unknown", reason: "no provider rate or settled charge is available" };
-    }
-
     // Reasoning activation and allowance are independent of grammar transport;
     // only the response representation becomes lossless when evidence is needed.
     // The llama-server template mapping is owned by {§llama-reasoning-request}.
@@ -455,7 +563,7 @@ export default class AiSdkProvider implements Provider {
             case "template": {
                 const allowance = mode === "off"
                     ? 0
-                    : mode === "on" ? budget : this.reasoningReserve;
+                    : mode === "on" && budget !== null ? budget : this.reasoningReserve;
                 return {
                     chat_template_kwargs: { enable_thinking: on },
                     reasoning_format: preserveGrammarSentence ? "none" : "auto",
@@ -464,9 +572,9 @@ export default class AiSdkProvider implements Provider {
             }
             case "think": return on ? { think: true } : {};
             case "include_reasoning": return on ? { include_reasoning: true } : {};
-            // effort tiers from the budget; off/adaptive omit the field (the
-            // API's default depth is its adaptive).
-            case "effort": return mode === "on" ? { reasoning_effort: effortFromBudget(budget!) } : {};
+            // Explicit on uses the portable enabled posture or a tier derived
+            // from an explicit budget; off/adaptive omit the field.
+            case "effort": return mode === "on" ? { reasoning_effort: effortFromReasoning(this.#reasoning) } : {};
             // Fireworks enum: OFF is sent EXPLICITLY ("none") — omission leaves a
             // reason-by-default model (DeepSeek V4: default 'high') reasoning.
             // ADAPTIVE omits the field: the backend's own default posture IS the
@@ -476,19 +584,25 @@ export default class AiSdkProvider implements Provider {
             // efforts 400.
             case "effort_explicit": return mode === "off"
                 ? { reasoning_effort: "none" }
-                : mode === "on" ? { reasoning_effort: effortFromBudget(budget!) } : {};
+                : mode === "on" ? { reasoning_effort: effortFromReasoning(this.#reasoning) } : {};
             // {§deepseek-reasoning-request}
             case "thinking_effort": return mode === "off"
                 ? { thinking: { type: "disabled" } }
                 : mode === "on" ? {
                     thinking: { type: "enabled" },
-                    reasoning_effort: effortFromBudget(budget!),
+                    ...(budget === null ? {} : { reasoning_effort: effortFromBudget(budget) }),
                 } : {};
             // Anthropic compat: explicit thinking object. off → disabled; on →
-            // enabled with budget_tokens; adaptive → omit (the API default).
+            // enabled with the explicit budget or resolved reserve; adaptive →
+            // omit (the API default).
             case "anthropic": return mode === "off"
                 ? { thinking: { type: "disabled" } }
-                : mode === "on" ? { thinking: { type: "enabled", budget_tokens: budget } } : {};
+                : mode === "on" ? {
+                    thinking: {
+                        type: "enabled",
+                        budget_tokens: budget ?? this.reasoningReserve!,
+                    },
+                } : {};
             case "none": return {};
         }
     }
@@ -555,7 +669,7 @@ export default class AiSdkProvider implements Provider {
         }
     }
 
-    // First-party telemetry headers ({§provider-request-authority}): forwarded only when the spec
+    // First-party telemetry headers ({§provider-request-authority} {§provider-call-kind}): forwarded only when the spec
     // opted in (the plurnk endpoint). The gate is here, not at the call site, so
     // attributions/client/strikes can never reach a third-party backend even if
     // the consumer passes them to the wrong provider. Empty values emit no header
@@ -563,7 +677,7 @@ export default class AiSdkProvider implements Provider {
     // absent (consumer didn't report); contract {§strikes-first-party-metadata}. Strikes
     // ride HTTP headers only — the packet never carries them (the model must
     // never see strike state; engine accounting is not a metric to game).
-    #metadataHeaders(attributions: string[] | undefined, client: string | undefined, strikes: number | undefined, workerId: string, primaryWorkerId: string | undefined, workspaceId: string | undefined, loop: number | undefined, turn: number | undefined): Record<string, string> {
+    #metadataHeaders(attributions: string[] | undefined, client: string | undefined, strikes: number | undefined, workerId: string, primaryWorkerId: string | undefined, workspaceId: string | undefined, loop: number | undefined, turn: number | undefined, callKind: ProviderCallKind | undefined): Record<string, string> {
         if (!this.#firstPartyMetadata) return {};
         const h: Record<string, string> = {};
         if (attributions !== undefined && attributions.length > 0) h["Plurnk-Attribution"] = JSON.stringify(attributions);
@@ -588,6 +702,7 @@ export default class AiSdkProvider implements Provider {
         if (workspaceId !== undefined && workspaceId.length > 0) h["Plurnk-Workspace-Id"] = workspaceId;
         if (loop !== undefined && Number.isInteger(loop) && loop >= 1) h["Plurnk-Loop"] = String(loop);
         if (turn !== undefined && Number.isInteger(turn) && turn >= 1) h["Plurnk-Turn"] = String(turn);
+        if (callKind !== undefined) h["Plurnk-Call-Kind"] = callKind;
         return h;
     }
 
@@ -627,9 +742,45 @@ export default class AiSdkProvider implements Provider {
         return out;
     }
 
-    async generate({ messages, workerId, primaryWorkerId, signal, grammar, maxTokens, attributions, client, strikes, workspaceId, loop, turn, sampling }: { messages: ChatMessage[]; workerId: string; primaryWorkerId?: string; signal?: AbortSignal; grammar?: string; maxTokens?: number; attributions?: string[]; client?: string; strikes?: number; workspaceId?: string; loop?: number; turn?: number; sampling?: Record<string, unknown> }): Promise<ProviderResponse> {
+    #requestProviderOptions(workerId: string): AiSdkProviderOptions | undefined {
+        const reasoningOptions = this.#reasoning.mode === "off"
+            ? undefined
+            : this.#reasoningResponseProviderOptions;
+        if (this.#cacheAffinity?.target !== "provider-option") return reasoningOptions;
+        const { provider, name } = this.#cacheAffinity;
+        return {
+            ...reasoningOptions,
+            [provider]: {
+                ...reasoningOptions?.[provider],
+                [name]: workerId,
+            },
+        };
+    }
+
+    #accounting(
+        outcome: ProviderRequestAccounting["outcome"],
+        usage: ProviderUsage | undefined,
+        evidence: Parameters<ProviderCostNormalizer>[0],
+        status?: number,
+    ): ProviderRequestAccounting {
+        const knownUsage = usage === undefined ? undefined : validateProviderUsage(usage);
+        const direct = this.#normalizeCost?.(evidence);
+        return validateProviderRequestAccounting({
+            provider: this.#source,
+            model: this.#model,
+            outcome,
+            ...(status === undefined ? {} : { status }),
+            ...(knownUsage === undefined ? {} : { usage: knownUsage }),
+            cost: resolveProviderCost(direct, this.#estimateCost(knownUsage)),
+        });
+    }
+
+    async generate({ messages, workerId, primaryWorkerId, signal, grammar, maxTokens, attributions, client, strikes, workspaceId, loop, turn, sampling, observeRequest, callKind }: ProviderGenerateArgs): Promise<ProviderResponse> {
         // {§provider-interface} The worker identity is required.
         if (workerId === undefined || workerId.length === 0) throw new Error("generate: workerId is required — the worker's stable, opaque identity");
+        if (callKind !== undefined && callKind !== "emission" && callKind !== "bare") {
+            throw new Error(`generate: unsupported callKind ${JSON.stringify(callKind)}`);
+        }
         // Reject before any wire call when already aborted
         // ({§provider-failure-normalization}).
         signal?.throwIfAborted();
@@ -661,72 +812,181 @@ export default class AiSdkProvider implements Provider {
             // reserved from caller sampling; the env flag is the single control).
             ...(this.#topLogprobs !== null ? { logprobs: true, top_logprobs: this.#topLogprobs } : {}),
             ...this.#slotBody(workerId),
-            // Prompt-cache affinity -- workerId as the OpenAI-standard
-            // prompt_cache_key routes a worker's turns to one serverless replica so
-            // its stable prefix caches (managed; reserved from caller sampling).
-            ...(this.#promptCacheKey ? { prompt_cache_key: workerId } : {}),
+            ...(this.#cacheAffinity?.target === "body"
+                ? { [this.#cacheAffinity.name]: workerId }
+                : {}),
         };
 
         // Per-request headers = static auth/routing + any first-party telemetry.
-        const metaHeaders = this.#metadataHeaders(attributions, client, strikes, workerId, primaryWorkerId, workspaceId, loop, turn);
-        const headers = Object.keys(metaHeaders).length === 0
-            ? this.#headers
-            : { ...this.#headers, ...metaHeaders };
-        let raw;
-        try {
-            raw = this.#languageModel === undefined
-                ? await executeOpenAICompatible({
-                    url: this.#url!,
+        const metaHeaders = this.#metadataHeaders(attributions, client, strikes, workerId, primaryWorkerId, workspaceId, loop, turn, callKind);
+        const headers = new Headers(this.#headers);
+        if (this.#cacheAffinity?.target === "header") {
+            headers.set(this.#cacheAffinity.name, workerId);
+        }
+        for (const [name, value] of Object.entries(metaHeaders)) headers.set(name, value);
+        const requestHeaders = Object.fromEntries(headers.entries());
+        const accounting: ProviderRequestAccounting[] = [];
+        const operationTimeout = this.#operationTimeoutMs > 0
+            ? AbortSignal.timeout(this.#operationTimeoutMs)
+            : undefined;
+        const operationSignal = signal === undefined
+            ? operationTimeout
+            : operationTimeout === undefined
+                ? signal
+                : AbortSignal.any([signal, operationTimeout]);
+        const executeRequest = async () => {
+            let settle: ProviderRequestSettlement | undefined;
+            try {
+                settle = await observeRequest?.({
+                    provider: this.#source,
                     model: this.#model,
-                    headers,
-                    body,
-                    messages,
-                    signal,
-                    fetch: this.#fetch,
-                    fetchTimeoutMs: this.#fetchTimeoutMs,
-                    streamIdleTimeoutMs: this.#streamIdleTimeoutMs,
-                    retryAttempts: this.#retryAttempts,
-                    streaming: this.#streaming,
-                    captureRawBody: this.#rawBody,
-                })
-                : await executeAiSdkModel({
-                    languageModel: this.#languageModel,
-                    headers,
-                    messages,
-                    signal,
-                    fetchTimeoutMs: this.#fetchTimeoutMs,
-                    streamIdleTimeoutMs: this.#streamIdleTimeoutMs,
-                    retryAttempts: this.#retryAttempts,
-                    streaming: this.#streaming,
-                    captureRawBody: this.#rawBody,
-                    temperature: this.#tuningFloors
-                        ? (typeof sampling?.temperature === "number" ? sampling.temperature : this.#temperature)
-                        : typeof sampling?.temperature === "number" ? sampling.temperature : undefined,
-                    topP: typeof sampling?.top_p === "number" ? sampling.top_p : undefined,
-                    topK: typeof sampling?.top_k === "number" ? sampling.top_k : undefined,
-                    presencePenalty: typeof sampling?.presence_penalty === "number" ? sampling.presence_penalty : undefined,
-                    frequencyPenalty: typeof sampling?.frequency_penalty === "number"
-                        ? sampling.frequency_penalty
-                        : this.#tuningFloors && this.#frequencyPenalty > 0 ? this.#frequencyPenalty : undefined,
-                    stopSequences: typeof sampling?.stop === "string"
-                        ? [sampling.stop]
-                        : Array.isArray(sampling?.stop) && sampling.stop.every((value) => typeof value === "string")
-                            ? sampling.stop
-                            : undefined,
-                    seed: typeof sampling?.seed === "number" ? sampling.seed : undefined,
-                    maxOutputTokens: maxTokens,
-                    reasoning: this.#reasoning.mode === "off"
-                        ? "none"
-                        : this.#reasoning.mode === "adaptive"
-                            ? "provider-default"
-                            : effortFromBudget(this.#reasoning.budget!),
                 });
+            } catch (cause) {
+                throw new ProviderRequestObserverError(cause);
+            }
+            const settleAccounting = async (
+                outcome: ProviderRequestAccounting["outcome"],
+                usage: ProviderUsage | undefined,
+                evidence: Parameters<ProviderCostNormalizer>[0],
+                status?: number,
+            ): Promise<ProviderRequestAccounting> => {
+                let requestAccounting: ProviderRequestAccounting;
+                let normalizationFailure: { cause: unknown } | undefined;
+                try {
+                    requestAccounting = this.#accounting(outcome, usage, evidence, status);
+                } catch (cause) {
+                    normalizationFailure = { cause };
+                    let knownUsage: ProviderUsage | undefined;
+                    try {
+                        knownUsage = usage === undefined ? undefined : validateProviderUsage(usage);
+                    } catch {
+                        knownUsage = undefined;
+                    }
+                    requestAccounting = validateProviderRequestAccounting({
+                        provider: this.#source,
+                        model: this.#model,
+                        outcome,
+                        ...(status === undefined ? {} : { status }),
+                        ...(knownUsage === undefined ? {} : { usage: knownUsage }),
+                        cost: {
+                            kind: "unknown",
+                            reason: "provider request accounting could not be normalized after physical I/O",
+                        },
+                    });
+                }
+                accounting.push(requestAccounting);
+                try {
+                    await settle?.(requestAccounting);
+                } catch (cause) {
+                    throw new ProviderRequestObserverError(cause);
+                }
+                if (normalizationFailure !== undefined) {
+                    throw new ProviderRequestAccountingError(normalizationFailure.cause);
+                }
+                return requestAccounting;
+            };
+            let response;
+            try {
+                response = this.#languageModel === undefined
+                    ? await executeOpenAICompatible({
+                        url: this.#url!,
+                        model: this.#model,
+                        headers: requestHeaders,
+                        body,
+                        messages,
+                        signal: operationSignal,
+                        fetch: this.#fetch,
+                        fetchTimeoutMs: this.#fetchTimeoutMs,
+                        firstContentTimeoutMs: this.#firstContentTimeoutMs,
+                        streamIdleTimeoutMs: this.#streamIdleTimeoutMs,
+                        streaming: this.#streaming,
+                        captureRawBody: this.#rawBody,
+                    })
+                    : await executeAiSdkModel({
+                        languageModel: this.#languageModel,
+                        headers: requestHeaders,
+                        providerOptions: this.#requestProviderOptions(workerId),
+                        systemProviderOptions: this.#systemCacheProviderOptions,
+                        messages,
+                        signal: operationSignal,
+                        fetchTimeoutMs: this.#fetchTimeoutMs,
+                        firstContentTimeoutMs: this.#firstContentTimeoutMs,
+                        streamIdleTimeoutMs: this.#streamIdleTimeoutMs,
+                        streaming: this.#streaming,
+                        captureRawBody: this.#rawBody,
+                        temperature: this.#tuningFloors
+                            ? (typeof sampling?.temperature === "number" ? sampling.temperature : this.#temperature)
+                            : typeof sampling?.temperature === "number" ? sampling.temperature : undefined,
+                        topP: typeof sampling?.top_p === "number" ? sampling.top_p : undefined,
+                        topK: typeof sampling?.top_k === "number" ? sampling.top_k : undefined,
+                        presencePenalty: typeof sampling?.presence_penalty === "number" ? sampling.presence_penalty : undefined,
+                        frequencyPenalty: typeof sampling?.frequency_penalty === "number"
+                            ? sampling.frequency_penalty
+                            : this.#tuningFloors && this.#frequencyPenalty > 0 ? this.#frequencyPenalty : undefined,
+                        stopSequences: typeof sampling?.stop === "string"
+                            ? [sampling.stop]
+                            : Array.isArray(sampling?.stop) && sampling.stop.every((value) => typeof value === "string")
+                                ? sampling.stop
+                                : undefined,
+                        seed: typeof sampling?.seed === "number" ? sampling.seed : undefined,
+                        maxOutputTokens: maxTokens,
+                        reasoning: this.#reasoning.mode === "off"
+                            ? "none"
+                            : this.#reasoning.mode === "adaptive"
+                                ? "provider-default"
+                                : effortFromReasoning(this.#reasoning),
+                    });
+            } catch (error) {
+                const failure = transportFailureEvidence(error);
+                await settleAccounting(
+                    "error",
+                    failure.usage,
+                    failure.chargeEvidence,
+                    failure.status,
+                );
+                throw error;
+            }
+            await settleAccounting(
+                "response",
+                response.usage,
+                response.chargeEvidence,
+            );
+            return response;
+        };
+
+        let raw;
+        try {
+            const { retry } = prepareRetries({
+                maxRetries: this.#retryAttempts,
+                abortSignal: operationSignal,
+            });
+            raw = await retry(executeRequest);
         } catch (err) {
+            if (err instanceof ProviderRequestObserverError
+                || err instanceof ProviderRequestAccountingError) throw err.cause;
             if (signal?.aborted) throw err;
+            if (operationTimeout?.aborted) {
+                const timeout = new ProviderTimeoutError("operation", this.#operationTimeoutMs, err);
+                throw new ProviderError(this.#source, "deadline_exceeded", timeout.message, {
+                    status: 504,
+                    cause: timeout,
+                    retryable: false,
+                    extensions: {
+                        timeoutPhase: timeout.phase,
+                        timeoutMs: timeout.timeoutMs,
+                    },
+                    accounting,
+                });
+            }
             const pe = toProviderError(err, this.#source, this.#errorDetailLimit);
             if ((pe.status === 401 || pe.status === 403) && this.#hasApiKey && this.#apiKeyRejectedMessage !== undefined) {
-                throw new ProviderError(this.#source, "unauthorized", this.#apiKeyRejectedMessage, { status: pe.status, cause: err });
+                throw new ProviderError(this.#source, "unauthorized", this.#apiKeyRejectedMessage, {
+                    status: pe.status,
+                    cause: err,
+                    accounting,
+                });
             }
+            pe.prependAccounting(accounting);
             throw pe;
         }
 
@@ -747,10 +1007,10 @@ export default class AiSdkProvider implements Provider {
                 this.#reasoningResponseStyle,
             );
 
-        // Preserve the exact sentence seen at the grammar boundary. Constrained
-        // template turns request `reasoning_format: "none"`, so even an empty
-        // channel remains observable. An unexpectedly projected response cannot
-        // supply independent pre-projection evidence.
+        // Preserve the exact pre-projection response. Constrained template turns
+        // request `reasoning_format: "none"`, so even an empty channel and any
+        // template-provided opener remain observable. An unexpectedly projected
+        // response cannot supply independent evidence.
         let grammarEvidence: GrammarEvidence | undefined;
         if (wantGrammar) {
             if (preserveGrammarSentence) {
@@ -779,12 +1039,13 @@ export default class AiSdkProvider implements Provider {
         if (projectedReasoning.projected) {
             raw.content = projectedReasoning.content;
             raw.reasoning = projectedReasoning.reasoning;
-            raw.usage = attributeUnitemizedReasoning(raw.usage, raw.reasoning, raw.content);
         }
 
         let notices: ProviderNotice[] | undefined;
         const usage = raw.usage;
-        if (sendGrammar !== undefined && this.tokenize !== undefined) {
+        if (sendGrammar !== undefined
+            && this.tokenize !== undefined
+            && usage?.outputTokens !== undefined) {
             // Channel-escape detector: completion tokens
             // billed far beyond every visible channel mean the decode ESCAPED into
             // a server-discarded reasoning block mid-emission. This diagnostic
@@ -795,12 +1056,12 @@ export default class AiSdkProvider implements Provider {
                     this.tokenize(raw.reasoning),
                 ]);
                 const visible = contentTokens.length + reasoningTokens.length;
-                if (usage.completion > visible + 64) {
+                if (usage.outputTokens > visible + 64) {
                     (notices ??= []).push({
                         source: this.#source,
                         kind: "grammar_unenforced",
                         level: "warn",
-                        message: `decode escaped the grammar: ${usage.completion} completion tokens billed but only ${visible} visible across content+reasoning — the balance ran unconstrained in a discarded reasoning channel`,
+                        message: `decode escaped the grammar: ${usage.outputTokens} output tokens billed but only ${visible} visible across content+reasoning — the balance ran unconstrained in a discarded reasoning channel`,
                         position: [...raw.content].length,
                     });
                 }
@@ -824,17 +1085,12 @@ export default class AiSdkProvider implements Provider {
             ...(raw.reasoningEncrypted.length > 0
                 ? { reasoningEncrypted: raw.reasoningEncrypted }
                 : {}),
-            usage,
             model: raw.model,
             ...(logprobs !== undefined ? { logprobs, meanLogprob } : {}),
         };
-        const normalizedCharge = this.#normalizeCharge?.(raw.chargeEvidence);
-        const charge = normalizedCharge === undefined
-            ? undefined
-            : validateAuthoritativeCharge(normalizedCharge);
         const evidence = {
             assistantRaw: raw,
-            ...(charge === undefined ? {} : { charge }),
+            accounting,
             ...(grammarEvidence !== undefined ? { grammarEvidence } : {}),
             ...(raw.rawBody !== undefined ? { rawBody: raw.rawBody } : {}),
             ...(meta !== undefined ? { meta } : {}),
@@ -851,6 +1107,7 @@ export default class AiSdkProvider implements Provider {
                 "The provider interrupted generation because inference resources were unavailable.",
                 {
                     attempt,
+                    accounting,
                     extensions: {
                         stage: "provider-response",
                         finishReason: "resource_interrupted",