@plurnk/plurnk-providers 1.5.0 → 1.6.1

package/dist/AiSdkProvider.js

@@ -5,13 +5,29 @@
 // Composition, not inheritance: an official AI SDK language model supplies the
 // ordinary vendor protocol. The compatible URL path remains only for PLURNK
 // extensions and local endpoint probes the SDK cannot represent.
-import { executeAiSdkModel, executeOpenAICompatible } from "./aiSdkTransport.js";
-import { toProviderError, ProviderError } from "./errors.js";
-import { attributeUnitemizedReasoning } from "./usage.js";
+import { MAX_PROVIDER_TIMEOUT_MS } from "./env.js";
+import { executeAiSdkModel, executeOpenAICompatible, transportFailureEvidence, } from "./aiSdkTransport.js";
+import { prepareRetries } from "ai/internal";
+import { toProviderError, ProviderError, ProviderTimeoutError } from "./errors.js";
 import { validateGbnf } from "@plurnk/gbnf";
 import { assertPromptTokenMeasurement, estimatePromptTokens } from "./promptTokens.js";
 import { emitWarningOnce } from "./warnings.js";
-import { validateAuthoritativeCharge } from "./cost.js";
+import { resolveProviderCost } from "./cost.js";
+import { validateProviderRequestAccounting } from "./accounting.js";
+import { validateProviderUsage } from "./usage.js";
+import { assessRequestCapacity, effectiveInputCapacity, effectiveOutputBudget, effectiveReasoningBudget } from "./capacity.js";
+class ProviderRequestObserverError extends Error {
+    constructor(cause) {
+        super("provider request accounting could not be durably settled", { cause });
+        this.name = "ProviderRequestObserverError";
+    }
+}
+class ProviderRequestAccountingError extends Error {
+    constructor(cause) {
+        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
@@ -52,11 +68,20 @@ const projectLeadingReasoning = (content, structuredReasoning, opening, closing)
 const projectTaggedReasoning = (content, structuredReasoning, style) => style === "think-tags"
     ? 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) => 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) => {
+    for (const [opening, closing] of [
+        ["<|channel>thought\n", "<channel|>"],
+        ["<think>\n", "</think>"],
+    ]) {
+        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) => {
     if (budget <= 1000)
@@ -65,6 +90,11 @@ export const effortFromBudget = (budget) => {
         return "medium";
     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 output budget. An operator reasoning subset, when present, remains
+// the only input to the existing magnitude-to-tier projection.
+const effortFromReasoning = (reasoning) => 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,
@@ -73,7 +103,7 @@ export const effortFromBudget = (budget) => {
 //     response; n>1 = paid, dropped output), the tool-calling family (tools-in-
 //     body doctrine, §2: native tool_calls return null content = a broken turn),
 //     modalities/audio (text-only contract), prediction (decode semantics, not
-//     sampling), and the token caps (the envelope is the managed maxTokens —
+//     sampling), and the token caps (the envelope is the managed maxOutputTokens —
 //     sampling must not bypass the consumer's cap).
 // Sampling intent (temperature, top_p, penalties, stop, seed, logit_bias) and
 // platform knobs (user, service_tier, prompt_cache_*, safety_identifier,
@@ -91,6 +121,8 @@ export default class AiSdkProvider {
     #url;
     #languageModel;
     #fetchTimeoutMs;
+    #operationTimeoutMs;
+    #firstContentTimeoutMs;
     #streamIdleTimeoutMs;
     #headers;
     #fetch;
@@ -98,6 +130,11 @@ export default class AiSdkProvider {
     #apiKeyRejectedMessage;
     #eosText;
     #contextWindow;
+    #maxInputTokens;
+    #maxOutputTokens;
+    #outputBudget;
+    #reasoningBudget;
+    #additiveReasoningProvider;
     #reasoning;
     #temperature;
     #repeatPenalty;
@@ -110,12 +147,13 @@ export default class AiSdkProvider {
     #reasoningResponseStyle;
     #countPromptTokens;
     #promptTokensUrl;
-    #calculateCost;
-    #calculateCharge;
-    #normalizeCharge;
+    #estimateCost;
+    #normalizeCost;
     #source;
     #grammarStyle;
-    #promptCacheKey;
+    #cacheAffinity;
+    #systemCacheProviderOptions;
+    #reasoningResponseProviderOptions;
     #serviceTier;
     #gbnfDebug;
     #streaming;
@@ -125,12 +163,10 @@ export default class AiSdkProvider {
     #retryAttempts;
     #errorDetailLimit;
     #topLogprobs;
-    #reasoningReserve;
-    #completionReserve;
     #tuningFloors;
     #rawBody;
     #servedModel;
-    #requiresMaxTokens;
+    #requiresOutputBudget;
     attributions;
     // Optional capability ({§provider-local-capabilities}): exact tokenization served by the backend's
     // own vocab. Assigned in the constructor ONLY when the config carries a
@@ -145,11 +181,28 @@ export default class AiSdkProvider {
         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],
+        ]) {
+            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));
         this.#contextWindow = config.contextWindow ?? null;
+        this.#maxInputTokens = config.maxInputTokens ?? null;
+        this.#maxOutputTokens = config.maxOutputTokens ?? null;
+        this.#outputBudget = config.outputBudget ?? null;
+        this.#reasoningBudget = config.reasoningBudget ?? null;
+        this.#additiveReasoningProvider = config.additiveReasoningProvider;
         this.#reasoning = config.reasoning;
         // Loud guard: an out-of-date consumer (stale plugin dist) omitting the
         // required tuning fields must fail at construction, not silently send
@@ -173,12 +226,33 @@ export default class AiSdkProvider {
         }
         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;
@@ -189,18 +263,42 @@ export default class AiSdkProvider {
         this.#supportsSlotPinning = config.supportsSlotPinning ?? false;
         this.#slotCount = config.slotCount ?? null;
         this.#topLogprobs = config.topLogprobs ?? null;
-        this.#reasoningReserve = config.reasoningReserve;
-        this.#completionReserve = config.completionReserve;
         this.#tuningFloors = config.tuningFloors ?? true;
         this.#rawBody = config.rawBody ?? false;
         this.#servedModel = config.servedModel;
-        this.#requiresMaxTokens = config.requiresMaxTokens;
-        const reasoningReserve = this.reasoningReserve;
-        if (this.#reasoningStyle === "template"
+        this.#requiresOutputBudget = config.requiresOutputBudget;
+        for (const [name, value] of [
+            ["contextWindow", this.#contextWindow],
+            ["maxInputTokens", this.#maxInputTokens],
+            ["maxOutputTokens", this.#maxOutputTokens],
+            ["outputBudget", this.#outputBudget],
+            ["reasoningBudget", this.#reasoningBudget],
+        ]) {
+            if (value !== null && (!Number.isSafeInteger(value) || value <= 0)) {
+                throw new Error(`${this.#source}: ${name} must be a positive safe integer or null`);
+            }
+        }
+        if (this.#reasoningBudget !== null
+            && this.#outputBudget !== null
+            && this.#reasoningBudget >= this.#outputBudget) {
+            throw new Error(`${this.#source}: reasoningBudget must be smaller than the total outputBudget`);
+        }
+        if (this.#reasoning.budget !== this.#reasoningBudget) {
+            throw new Error(`${this.#source}: reasoning intent and generation envelope disagree on reasoningBudget`);
+        }
+        if (this.#reasoningStyle === "anthropic"
+            && this.#reasoning.mode === "on"
+            && this.#reasoning.budget === null
+            && this.#reasoningBudget === null) {
+            throw new Error(`${this.#source}: explicit Anthropic reasoning requires PLURNK_PROVIDERS_REASONING_BUDGET`);
+        }
+        if (this.#additiveReasoningProvider !== undefined
             && this.#reasoning.mode === "on"
-            && reasoningReserve !== null
-            && this.#reasoning.budget > reasoningReserve) {
-            throw new Error(`${this.#source}: PLURNK_PROVIDERS_REASONING_BUDGET (${this.#reasoning.budget}) exceeds the resolved PLURNK_PROVIDERS_REASONING_RESERVE (${reasoningReserve})`);
+            && this.#reasoningBudget === null) {
+            throw new Error(`${this.#source}: explicit ${this.#additiveReasoningProvider} reasoning requires PLURNK_PROVIDERS_REASONING_BUDGET so the total output budget remains bounded`);
+        }
+        if (this.#requiresOutputBudget === true && this.#outputBudget === null) {
+            throw new Error(`${this.#source}: this backend requires a resolved PLURNK_PROVIDERS_OUTPUT_BUDGET`);
         }
         const { tokenizeUrl } = config;
         if (tokenizeUrl !== undefined) {
@@ -209,7 +307,9 @@ export default class AiSdkProvider {
                     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}`);
@@ -222,22 +322,22 @@ export default class AiSdkProvider {
         }
     }
     get contextWindow() { return this.#contextWindow; }
-    // {§provider-generation-envelope} Envelope reserves — absolute pins stand alone; percentages need the
-    // detected window; null = underivable (no claim for core's no-cap path).
-    #resolveReserve(spec) {
-        if (spec === undefined)
-            return null;
-        if ("tokens" in spec)
-            return spec.tokens;
-        return this.#contextWindow === null ? null : Math.round(spec.percent * this.#contextWindow);
+    get maxInputTokens() { return this.#maxInputTokens; }
+    get maxOutputTokens() { return this.#maxOutputTokens; }
+    get outputBudget() { return this.#outputBudget; }
+    get reasoningBudget() { return this.#reasoningBudget; }
+    get inputCapacity() {
+        return effectiveInputCapacity({
+            contextWindow: this.#contextWindow,
+            maxInputTokens: this.#maxInputTokens,
+            outputBudget: this.#outputBudget,
+        });
     }
-    get reasoningReserve() { return this.#resolveReserve(this.#reasoningReserve); }
-    get completionReserve() { return this.#resolveReserve(this.#completionReserve); }
     get model() { return this.#model; }
     // Backend's self-reported served id; undefined when unprobed/unknown.
     get servedModel() { return this.#servedModel; }
     // Resolved "decodes unbounded without a cap" fact; undefined = no claim.
-    get requiresMaxTokens() { return this.#requiresMaxTokens; }
+    get requiresOutputBudget() { return this.#requiresOutputBudget; }
     // Resolved capability: will a transported grammar actually constrain
     // this backend's decode? Introspectable so a consumer can verify the rails
     // are LIVE without spending a generation on a forcing-grammar probe.
@@ -248,7 +348,14 @@ export default class AiSdkProvider {
         }
         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 },
@@ -257,7 +364,7 @@ export default class AiSdkProvider {
                     messages,
                     ...this.#reasoningBody(),
                 }),
-                signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
+                ...(requestSignal === undefined ? {} : { signal: requestSignal }),
             });
             if (!response.ok) {
                 return estimatePromptTokens(messages, `llama-server input-token endpoint returned HTTP ${response.status}`);
@@ -277,22 +384,38 @@ export default class AiSdkProvider {
             return estimatePromptTokens(messages, `llama-server input-token measurement failed: ${cause instanceof Error ? cause.message : String(cause)}`);
         }
     }
-    calculateCost(usage) { return this.#calculateCost(usage); }
-    calculateCharge(usage) {
-        return this.#calculateCharge?.(usage)
-            ?? { kind: "unknown", reason: "no provider rate or settled charge is available" };
+    async assessRequestCapacity(messages, maxOutputTokens, signal) {
+        const outputBudget = effectiveOutputBudget({
+            requested: maxOutputTokens,
+            configured: this.#outputBudget,
+            maxOutputTokens: this.#maxOutputTokens,
+            contextWindow: this.#contextWindow,
+        });
+        const reasoningBudget = effectiveReasoningBudget({
+            configured: this.#reasoningBudget,
+            outputBudget,
+        });
+        return assessRequestCapacity({
+            contextWindow: this.#contextWindow,
+            maxInputTokens: this.#maxInputTokens,
+            maxOutputTokens: this.#maxOutputTokens,
+            outputBudget,
+            reasoningBudget,
+            measurement: await this.countPromptTokens(messages, signal),
+        });
     }
     // 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}.
-    #reasoningBody(preserveGrammarSentence = false) {
-        const { mode, budget } = this.#reasoning;
+    #reasoningBody(preserveGrammarSentence = false, reasoningBudget = this.#reasoningBudget) {
+        const { mode } = this.#reasoning;
+        const budget = reasoningBudget;
         const on = mode !== "off";
         switch (this.#reasoningStyle) {
             case "template": {
                 const allowance = mode === "off"
                     ? 0
-                    : mode === "on" ? budget : this.reasoningReserve;
+                    : mode === "on" && budget !== null ? budget : this.#reasoningBudget;
                 return {
                     chat_template_kwargs: { enable_thinking: on },
                     reasoning_format: preserveGrammarSentence ? "none" : "auto",
@@ -301,9 +424,9 @@ export default class AiSdkProvider {
             }
             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({ mode, budget }) } : {};
             // 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
@@ -313,19 +436,25 @@ export default class AiSdkProvider {
             // efforts 400.
             case "effort_explicit": return mode === "off"
                 ? { reasoning_effort: "none" }
-                : mode === "on" ? { reasoning_effort: effortFromBudget(budget) } : {};
+                : mode === "on" ? { reasoning_effort: effortFromReasoning({ mode, budget }) } : {};
             // {§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 reasoning subset; 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,
+                    },
+                } : {};
             case "none": return {};
         }
     }
@@ -390,7 +519,7 @@ export default class AiSdkProvider {
             case "none": return this.#frequencyPenalty > 0 ? { frequency_penalty: this.#frequencyPenalty } : {};
         }
     }
-    // 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
@@ -398,7 +527,7 @@ export default class AiSdkProvider {
     // 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, client, strikes, workerId, primaryWorkerId, workspaceId, loop, turn) {
+    #metadataHeaders(attributions, client, strikes, workerId, primaryWorkerId, workspaceId, loop, turn, callKind) {
         if (!this.#firstPartyMetadata)
             return {};
         const h = {};
@@ -431,6 +560,8 @@ export default class AiSdkProvider {
             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;
     }
     // PLURNK_PROVIDERS_GBNF_DEBUG ({§gbnf-response-observation}): validate the supplied GBNF locally and fail
@@ -470,10 +601,57 @@ export default class AiSdkProvider {
                 out[k] = v;
         return out;
     }
-    async generate({ messages, workerId, primaryWorkerId, signal, grammar, maxTokens, attributions, client, strikes, workspaceId, loop, turn, sampling }) {
+    #requestProviderOptions(workerId, reasoningBudget) {
+        const responseOptions = this.#reasoning.mode === "off"
+            ? undefined
+            : this.#reasoningResponseProviderOptions;
+        const nativeReasoning = this.#reasoning.mode === "on" && reasoningBudget !== null
+            ? this.#additiveReasoningProvider === "anthropic"
+                ? { anthropic: { thinking: { type: "enabled", budgetTokens: reasoningBudget } } }
+                : this.#additiveReasoningProvider === "bedrock"
+                    ? { bedrock: { reasoningConfig: { type: "enabled", budgetTokens: reasoningBudget } } }
+                    : undefined
+            : undefined;
+        const options = {};
+        for (const part of [responseOptions, nativeReasoning]) {
+            for (const [provider, values] of Object.entries(part ?? {})) {
+                options[provider] = { ...options[provider], ...values };
+            }
+        }
+        if (this.#cacheAffinity?.target === "provider-option") {
+            const { provider, name } = this.#cacheAffinity;
+            options[provider] = { ...options[provider], [name]: workerId };
+        }
+        return Object.keys(options).length === 0 ? undefined : options;
+    }
+    #nativeMaxOutputTokens(outputBudget, reasoningBudget) {
+        if (outputBudget === null)
+            return undefined;
+        return this.#additiveReasoningProvider !== undefined
+            && this.#reasoning.mode === "on"
+            && reasoningBudget !== null
+            ? outputBudget - reasoningBudget
+            : outputBudget;
+    }
+    #accounting(outcome, usage, evidence, status) {
+        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, maxOutputTokens, attributions, client, strikes, workspaceId, loop, turn, sampling, observeRequest, callKind }) {
         // {§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();
@@ -485,6 +663,14 @@ export default class AiSdkProvider {
         const sendGrammar = wantGrammar && !this.#gbnfDebug ? grammar : undefined;
         const preserveGrammarSentence = wantGrammar
             && this.#reasoningStyle === "template";
+        const capacity = await this.assessRequestCapacity(messages, maxOutputTokens, signal);
+        if (capacity.decision === "reject") {
+            if (capacity.prompt.kind !== "exact") {
+                throw new TypeError(`${this.#source}: only an exact prompt measurement may reject capacity`);
+            }
+            throw new ProviderError(this.#source, "capacity_exceeded", `The exact provider request uses ${capacity.prompt.tokens} input tokens, exceeding its ${capacity.inputCapacity} token input capacity.`, { capacity, extensions: { capacityStage: "preflight", capacity } });
+        }
+        const effectiveMaxOutputTokens = capacity.outputBudget ?? undefined;
         // Assembly order = precedence: the family's sampling DEFAULTS
         // (PLURNK_PROVIDERS_TEMPERATURE — universal, measured on grammar
         // paths and the name promises every request) < the caller's `sampling`
@@ -497,80 +683,188 @@ export default class AiSdkProvider {
             ...(this.#serviceTier !== undefined ? { service_tier: this.#serviceTier } : {}),
             model: this.#model,
             messages,
-            ...this.#reasoningBody(preserveGrammarSentence),
+            ...this.#reasoningBody(preserveGrammarSentence, capacity.reasoningBudget),
             ...this.#grammarBody(sendGrammar),
-            ...(maxTokens !== undefined ? { max_tokens: maxTokens } : {}),
+            ...(effectiveMaxOutputTokens !== undefined ? { max_tokens: effectiveMaxOutputTokens } : {}),
             // Request per-token logprobs only when enabled (managed field —
             // 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 = [];
+        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;
+            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, usage, evidence, status) => {
+                let requestAccounting;
+                let normalizationFailure;
+                try {
+                    requestAccounting = this.#accounting(outcome, usage, evidence, status);
+                }
+                catch (cause) {
+                    normalizationFailure = { cause };
+                    let knownUsage;
+                    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, capacity.reasoningBudget),
+                        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: this.#nativeMaxOutputTokens(capacity.outputBudget, capacity.reasoningBudget),
+                        reasoning: this.#reasoning.mode === "off"
+                            ? "none"
+                            : this.#reasoning.mode === "adaptive"
+                                ? "provider-default"
+                                : this.#additiveReasoningProvider !== undefined && capacity.reasoningBudget !== null
+                                    ? "provider-default"
+                                    : effortFromReasoning({
+                                        mode: this.#reasoning.mode,
+                                        budget: capacity.reasoningBudget,
+                                    }),
+                    });
+            }
+            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;
-            const pe = toProviderError(err, this.#source, this.#errorDetailLimit);
+            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,
+                    capacity,
+                });
+            }
+            const pe = toProviderError(err, this.#source, this.#errorDetailLimit, capacity);
             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,
+                    capacity,
+                });
             }
+            pe.prependAccounting(accounting);
             throw pe;
         }
         // llama-server --special renders EOG tokens as text, so a turn ending
@@ -585,10 +879,10 @@ export default class AiSdkProvider {
         const projectedReasoning = preserveGrammarSentence && !raw.reasoningProjected
             ? projectTemplateReasoning(raw.content)
             : projectTaggedReasoning(raw.content, raw.reasoning, 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;
         if (wantGrammar) {
             if (preserveGrammarSentence) {
@@ -618,11 +912,12 @@ export default class AiSdkProvider {
         if (projectedReasoning.projected) {
             raw.content = projectedReasoning.content;
             raw.reasoning = projectedReasoning.reasoning;
-            raw.usage = attributeUnitemizedReasoning(raw.usage, raw.reasoning, raw.content);
         }
         let notices;
         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
@@ -633,12 +928,12 @@ export default class AiSdkProvider {
                     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,
                     });
                 }
@@ -658,22 +953,35 @@ export default class AiSdkProvider {
             ...(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,
+            capacity,
             ...(grammarEvidence !== undefined ? { grammarEvidence } : {}),
             ...(raw.rawBody !== undefined ? { rawBody: raw.rawBody } : {}),
             ...(meta !== undefined ? { meta } : {}),
             ...(notices !== undefined ? { notices } : {}),
         };
+        if (capacity.outputBudget !== null
+            && usage?.outputTokens !== undefined
+            && usage.outputTokens > capacity.outputBudget) {
+            const attempt = {
+                assistant: { ...assistant, finishReason: raw.finishReason },
+                ...evidence,
+            };
+            throw new ProviderError(this.#source, "invalid_response", `The provider reported ${usage.outputTokens} output tokens after receiving a total output budget of ${capacity.outputBudget}.`, {
+                attempt,
+                accounting,
+                extensions: {
+                    stage: "provider-response",
+                    outputBudget: capacity.outputBudget,
+                    reportedOutputTokens: usage.outputTokens,
+                },
+            });
+        }
         if (raw.finishReason === "resource_interrupted") {
             const attempt = {
                 assistant: { ...assistant, finishReason: raw.finishReason },
@@ -681,6 +989,7 @@ export default class AiSdkProvider {
             };
             throw new ProviderError(this.#source, "resource_interrupted", "The provider interrupted generation because inference resources were unavailable.", {
                 attempt,
+                accounting,
                 extensions: {
                     stage: "provider-response",
                     finishReason: "resource_interrupted",