@plurnk/plurnk-providers 1.4.0 → 1.6.0

package/src/Mock.test.ts

@@ -3,6 +3,7 @@ import { strict as assert } from "node:assert";
 import Mock from "./Mock.ts";
 import type { Provider } from "./types.ts";
 import type { MockResponse } from "./Mock.ts";
+import { ProviderError } from "./errors.ts";
 
 const build = (responses: MockResponse[] = [{ assistant: { content: "hi", reasoning: null } }]) =>
     new Mock({ contextWindow: 100000, responses });
@@ -34,19 +35,23 @@ test("Mock: prompt counting is exact for its declared mock vocabulary", async ()
     });
 });
 
-test("Mock: calculateCost returns its deliberate zero estimate", () => {
-    const m = build();
-    assert.equal(m.calculateCost({ prompt: 100, completion: 20, reasoning: 10, cached: 5, total: 130 }), 0);
-});
-
 // — Transport ({§provider-interface}) —
 
 test("Mock: generate resolves a valid ProviderResponse shape", async () => {
     const m = build([{ assistant: { content: "hello", reasoning: "cot" } }]);
-    const { assistant, assistantRaw } = await m.generate({ messages: [] });
+    const { assistant, assistantRaw, accounting } = await m.generate({ messages: [] });
     assert.equal(assistant.content, "hello");
     assert.equal(assistant.reasoning, "cot");
-    assert.deepEqual(assistant.usage, { prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 });
+    assert.deepEqual(accounting[0]?.usage, {
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+    });
+    assert.deepEqual(accounting[0]?.cost, {
+        kind: "estimated",
+        amount: { amount: "0", currency: "USD" },
+        source: "mock provider fixture",
+    });
     assert.equal(assistant.finishReason, "stop");
     assert.equal(assistant.model, "mock");
     assert.equal(assistantRaw, null); // present, defaulted
@@ -57,16 +62,20 @@ test("Mock: generate applies caller-supplied overrides", async () => {
         assistant: {
             content: "x",
             reasoning: null,
-            usage: { prompt: 1, completion: 2, reasoning: 0, cached: 0, total: 3 },
             finishReason: "length",
             model: "mock-xl",
         },
+        usage: { inputTokens: 1, outputTokens: 2, totalTokens: 3 },
         assistantRaw: { wire: true },
     }]);
-    const { assistant, assistantRaw } = await m.generate({ messages: [] });
+    const { assistant, assistantRaw, accounting } = await m.generate({ messages: [] });
     assert.equal(assistant.finishReason, "length");
     assert.equal(assistant.model, "mock-xl");
-    assert.deepEqual(assistant.usage, { prompt: 1, completion: 2, reasoning: 0, cached: 0, total: 3 });
+    assert.deepEqual(accounting[0]?.usage, {
+        inputTokens: 1,
+        outputTokens: 2,
+        totalTokens: 3,
+    });
     assert.deepEqual(assistantRaw, { wire: true });
 });
 
@@ -116,9 +125,25 @@ test("Mock: remaining decrements as responses are consumed", async () => {
     assert.equal(m.remaining, 1);
 });
 
-test("Mock: exhausted queue throws a specific error", async () => {
+test("Mock: exhausted queue throws a ProviderError carrying its settled accounting", async () => {
     const m = build([]);
-    await assert.rejects(() => m.generate({ messages: [] }), /exhausted/);
+    await assert.rejects(
+        () => m.generate({ messages: [] }),
+        (error: unknown) => {
+            assert.ok(error instanceof ProviderError);
+            assert.match(error.message, /exhausted/);
+            assert.deepEqual(error.accounting, [{
+                provider: "provider:mock",
+                model: "mock",
+                outcome: "error",
+                cost: {
+                    kind: "unknown",
+                    reason: "mock provider exhausted before producing a response",
+                },
+            }]);
+            return true;
+        },
+    );
 });
 
 // -- {§provider-generation-envelope} --

package/src/Mock.ts

@@ -5,15 +5,14 @@
 // Provider contract. Production providers don't expose the `ops` escape
 // hatch — that's an intg-only convenience.
 
-import type { ChatMessage, FinishReason, GrammarEvidence, PromptTokenMeasurement, Provider, ProviderAssistant, ProviderEncryptedReasoningItem, ProviderResponse, ProviderUsage } from "./types.ts";
-import type { ProviderCost } from "@plurnk/plurnk-contracts";
+import type { ChatMessage, FinishReason, GrammarEvidence, PromptTokenMeasurement, Provider, ProviderAssistant, ProviderCost, ProviderEncryptedReasoningItem, ProviderRequestAccounting, ProviderResponse, ProviderUsage } from "./types.ts";
 import { resolveEnvelopeFromEnv } from "./env.ts";
+import { validateProviderRequestAccounting } from "./accounting.ts";
+import { ProviderError } from "./errors.ts";
 
 export type MockAssistant = {
     content: string;
     reasoning: string | null;
-    // Partial — omitted fields fall back to DEFAULT_USAGE (e.g. reasoning: 0).
-    usage?: Partial<ProviderUsage>;
     finishReason?: FinishReason;
     model?: string;
     // Provider-normalized encrypted reasoning fixture.
@@ -28,6 +27,9 @@ export type MockAssistant = {
 export type MockResponse = {
     assistant: MockAssistant;
     assistantRaw?: unknown;
+    // Partial — omitted fields fall back to the deliberate zero fixture.
+    usage?: Partial<ProviderUsage>;
+    cost?: ProviderCost;
     grammarEvidence?: GrammarEvidence;
 };
 
@@ -35,7 +37,12 @@ export type MockResponse = {
 export type MockReturnedAssistant = ProviderAssistant & { ops?: unknown[] };
 export type MockReturnedResponse = ProviderResponse & { assistant: MockReturnedAssistant };
 
-const DEFAULT_USAGE: ProviderUsage = { prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 };
+const DEFAULT_USAGE: ProviderUsage = {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+};
+type MockGenerateArgs = Omit<Parameters<Provider["generate"]>[0], "workerId"> & { workerId?: string };
 
 export default class Mock implements Provider {
     #contextWindow: number | null;
@@ -75,22 +82,48 @@ export default class Mock implements Provider {
         };
     }
 
-    // Mock is free.
-    calculateCost(_usage: ProviderUsage): number { return 0; }
-    calculateCharge(_usage: ProviderUsage): Exclude<ProviderCost, { kind: "authoritative" }> { return { kind: "free", source: "mock provider" }; }
-
-    async generate({ signal, grammar }: { messages: ChatMessage[]; workerId?: string; signal?: AbortSignal; grammar?: string }): Promise<MockReturnedResponse> {
+    async generate({ signal, grammar, observeRequest }: MockGenerateArgs): Promise<MockReturnedResponse> {
         // Honor abort before consuming the queue — an aborted call makes no
         // "wire call" and must not exhaust a queued response
         // ({§provider-failure-normalization}).
         signal?.throwIfAborted();
+        const settle = await observeRequest?.({ provider: "provider:mock", model: this.model });
         const next = this.#queue.shift();
-        if (next === undefined) throw new Error("Mock provider exhausted: no more queued responses");
+        if (next === undefined) {
+            const accounting = validateProviderRequestAccounting({
+                provider: "provider:mock",
+                model: this.model,
+                outcome: "error",
+                cost: { kind: "unknown", reason: "mock provider exhausted before producing a response" },
+            });
+            await settle?.(accounting);
+            throw new ProviderError(
+                "mock",
+                "invalid_response",
+                "Mock provider exhausted: no more queued responses",
+                { accounting: [accounting] },
+            );
+        }
         const a = next.assistant;
+        const usage: ProviderUsage = {
+            ...DEFAULT_USAGE,
+            ...next.usage,
+        };
+        const requestAccounting: ProviderRequestAccounting = validateProviderRequestAccounting({
+            provider: "provider:mock",
+            model: a.model ?? this.model,
+            outcome: "response",
+            usage,
+            cost: next.cost ?? {
+                kind: "estimated",
+                amount: { amount: "0", currency: "USD" },
+                source: "mock provider fixture",
+            },
+        });
+        await settle?.(requestAccounting);
         const assistant: MockReturnedAssistant = {
             content: a.content,
             reasoning: a.reasoning,
-            usage: { ...DEFAULT_USAGE, ...a.usage },
             ...(a.reasoningEncrypted !== undefined ? { reasoningEncrypted: a.reasoningEncrypted } : {}),
             finishReason: a.finishReason ?? "stop",
             model: a.model ?? "mock",
@@ -103,6 +136,7 @@ export default class Mock implements Provider {
         return {
             assistant,
             assistantRaw: next.assistantRaw ?? null,
+            accounting: [requestAccounting],
             ...(grammarEvidence !== undefined ? { grammarEvidence } : {}),
         };
     }

package/src/Pool.test.ts

@@ -7,13 +7,28 @@ import { resetEmittedWarnings } from "./warnings.ts";
 
 test.afterEach(() => { resetEmittedWarnings(); });
 
-const RESP = { assistant: { usage: { prompt: 1, completion: 1, reasoning: 0, cached: 0, total: 2 } }, assistantRaw: null } as unknown as ProviderResponse;
+const RESP: ProviderResponse = {
+    assistant: {
+        content: "ok",
+        reasoning: null,
+        finishReason: "stop",
+        model: "gemma",
+    },
+    assistantRaw: null,
+    accounting: [{
+        provider: "provider:test",
+        model: "gemma",
+        outcome: "response",
+        usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
+        cost: { kind: "unknown", reason: "test fixture has no cost" },
+    }],
+};
 
 type FakeOpts = {
     model?: string; window?: number | null; servedModel?: string;
     constrainsOutput?: boolean; requiresMaxTokens?: boolean;
     reasoningReserve?: number | null; completionReserve?: number | null;
-    tokenize?: boolean; cost?: number; throws?: Error;
+    tokenize?: boolean; throws?: Error;
     promptMeasurement?: PromptTokenMeasurement;
 };
 // A fake backend that records which workers it served, and optionally throws.
@@ -33,7 +48,6 @@ const backend = (opts: FakeOpts = {}) => {
             tokens: messages.reduce((sum, { content }) => sum + content.length, 0),
             source: "test:exact",
         }),
-        calculateCost: () => opts.cost ?? 0,
         generate: async (args: Parameters<Provider["generate"]>[0]): Promise<ProviderResponse> => {
             served.push(args.workerId);
             if (opts.throws !== undefined) throw opts.throws;
@@ -94,12 +108,11 @@ test("Pool: tokenize is exposed iff every backend has it", () => {
     assert.equal(new Pool([backend({ tokenize: true }).b, backend({ tokenize: false }).b]).tokenize, undefined);
 });
 
-test("Pool: prompt counting + calculateCost delegate to a backend", async () => {
-    const p = new Pool([backend({ cost: 42 }).b]);
+test("Pool: prompt counting delegates conservatively to its backends", async () => {
+    const p = new Pool([backend().b]);
     assert.deepEqual(await p.countPromptTokens([{ role: "user", content: "abcd" }]), {
         kind: "exact", tokens: 4, source: "pool:test:exact",
     });
-    assert.equal(p.calculateCost({ prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 }), 42);
 });
 
 test("Pool: prompt evidence is conservative across every routable backend", async () => {

package/src/Pool.ts

@@ -1,6 +1,4 @@
-import type { Provider, ProviderResponse, ProviderUsage, ChatMessage, PromptTokenMeasurement } from "./types.ts";
-import type { ProviderCost } from "@plurnk/plurnk-contracts";
-import { resolveProviderCost } from "./cost.ts";
+import type { Provider, ProviderRequestAccounting, ProviderResponse, ChatMessage, PromptTokenMeasurement } from "./types.ts";
 import { ProviderError, type ProviderErrorKind } from "./errors.ts";
 import { emitWarningOnce } from "./warnings.ts";
 import { assertPromptTokenMeasurement } from "./promptTokens.ts";
@@ -125,32 +123,38 @@ export default class Pool implements Provider {
             source: `pool:${sources}`,
         };
     }
-    calculateCost(usage: ProviderUsage): number { return this.#backends[0].calculateCost(usage); }
-    calculateCharge(usage: ProviderUsage): Exclude<ProviderCost, { kind: "authoritative" }> {
-        const backend = this.#backends[0];
-        return resolveProviderCost(undefined, backend.calculateCharge?.(usage), () => backend.calculateCost(usage)) as Exclude<ProviderCost, { kind: "authoritative" }>;
-    }
-
     // --- dispatch ---
 
-    async generate(args: { 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> {
+    async generate(args: Parameters<Provider["generate"]>[0]): Promise<ProviderResponse> {
         const { workerId, signal } = args;
         if (workerId === undefined || workerId.length === 0) throw new Error("Pool.generate: workerId is required - affinity keys on it");
         const tried = new Set<number>();
+        const priorAccounting: ProviderRequestAccounting[] = [];
         let idx = this.#route(workerId);
-        let lastErr: unknown;
         for (;;) {
             tried.add(idx);
             try {
-                return await this.#backends[idx].generate(args);
+                const response = await this.#backends[idx].generate(args);
+                return priorAccounting.length === 0
+                    ? response
+                    : { ...response, accounting: [...priorAccounting, ...response.accounting] };
             } catch (err) {
-                lastErr = err;
-                if (signal?.aborted) throw err; // caller cancellation is never a failover
+                if (signal?.aborted) {
+                    if (err instanceof ProviderError) err.prependAccounting(priorAccounting);
+                    throw err;
+                }
                 // Only a backend-AVAILABILITY failure overflows; auth/quota/content/
                 // malformed fail the same on a peer, so they propagate.
-                if (!(err instanceof ProviderError) || !OVERFLOW_KINDS.has(err.kind)) throw err;
+                if (!(err instanceof ProviderError) || !OVERFLOW_KINDS.has(err.kind)) {
+                    if (err instanceof ProviderError) err.prependAccounting(priorAccounting);
+                    throw err;
+                }
                 const next = this.#nextUntried(tried);
-                if (next === null) throw lastErr; // the whole fleet is unavailable
+                if (next === null) {
+                    err.prependAccounting(priorAccounting);
+                    throw err;
+                }
+                priorAccounting.push(...err.accounting);
                 this.#affinity.set(workerId, next); // re-stick: the worker's cache moves with it
                 idx = next;
             }

package/src/ProviderRegistry.test.ts

@@ -14,8 +14,10 @@ const mapOf = (entries: Record<string, string>, skipped: Record<string, string>
 
 const fullEnv = Object.freeze({
     PLURNK_PROVIDERS_FETCH_TIMEOUT: "600000",
+    PLURNK_PROVIDERS_OPERATION_TIMEOUT: "2700000",
+    PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT: "600000",
     PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT: "0",
-    PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_TEMPERATURE: "0.2", PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15", PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0.4", PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%", PLURNK_PROVIDERS_PROBE_ATTEMPTS: "3", PLURNK_PROVIDERS_PROBE_DELAY: "1", PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0", PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT: "512", PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "1",
+    PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_TEMPERATURE: "0.2", PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15", PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0.4", PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%", PLURNK_PROVIDERS_PROBE_ATTEMPTS: "3", PLURNK_PROVIDERS_PROBE_DELAY: "1", PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0", PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT: "512", PLURNK_PROVIDERS_CACHE_AFFINITY: "1", PLURNK_PROVIDERS_CACHE_WRITE_POLICY: "stable-system",
     OPENAI_BASE_URL: "http://x",
 });
 
@@ -271,30 +273,33 @@ test("{§deepseek-reasoning-request} #157: direct DeepSeek composes catalog fact
     assert.deepEqual(request.thinking, { type: "disabled" });
     assert.equal(provider.contextWindow, 1_000_000);
     assert.equal(response.assistant.content, "ok");
-    assert.deepEqual(response.assistant.usage, {
-        prompt: 10,
-        completion: 2,
-        reasoning: 0,
-        cached: 8,
-        total: 12,
+    assert.deepEqual(response.accounting[0]?.usage, {
+        inputTokens: 10,
+        outputTokens: 2,
+        totalTokens: 12,
+        inputTokenDetails: { noCacheTokens: 2, cacheReadTokens: 8 },
+    });
+    assert.deepEqual(response.accounting[0]?.cost, {
+        kind: "estimated",
+        amount: { amount: "0.0000008624", currency: "USD" },
+        source: "Models.dev catalog rates",
     });
-    assert.ok(Math.abs(provider.calculateCost(response.assistant.usage) - 0.0000008624) < 1e-15);
     mock.restoreAll();
 });
 
-test("an explicit malformed operator override still fails at its owning contract", async () => {
+test("an explicit malformed cache-affinity override still fails at its owning contract", async () => {
     await assert.rejects(
         () => instantiateProvider(
             "fireworks",
             {
                 FIREWORKS_API_KEY: "fw",
-                PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "malformed",
+                PLURNK_PROVIDERS_CACHE_AFFINITY: "malformed",
             },
             "deepseek-v4-pro",
             async () => ({}),
             mapOf({}),
         ),
-        /fireworks provider: PLURNK_PROVIDERS_PROMPT_CACHE_KEY must be "0" or "1"/,
+        /fireworks provider: PLURNK_PROVIDERS_CACHE_AFFINITY must be "0" or "1"/,
     );
 });
 

package/src/accounting.test.ts

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+    aggregateProviderAccounting,
+    plurnkCostNormalizer,
+    providerCostNormalizer,
+} from "./accounting.ts";
+
+const evidence = ({ providerMetadata, usage, charge }: {
+    providerMetadata?: unknown;
+    usage?: unknown;
+    charge?: unknown;
+}) => ({
+    ...(providerMetadata === undefined ? {} : { providerMetadata }),
+    ...(usage === undefined ? {} : { usage }),
+    ...(charge === undefined ? {} : { charge }),
+    response: { id: "response-1" },
+});
+
+test("xAI response ticks normalize to a directly charged request", () => {
+    const normalize = providerCostNormalizer("@ai-sdk/xai");
+    assert.notEqual(normalize, undefined);
+    assert.deepEqual(normalize!(evidence({ usage: { cost_in_usd_ticks: 15_493_500 } })), {
+        kind: "charged",
+        amount: { amount: "15493500", currency: "USDTICK" },
+        usdEquivalent: "0.00154935",
+        source: "xAI response usage.cost_in_usd_ticks",
+    });
+});
+
+test("OpenRouter response cost normalizes without rate reconstruction", () => {
+    const normalize = providerCostNormalizer("@openrouter/ai-sdk-provider");
+    assert.notEqual(normalize, undefined);
+    assert.deepEqual(normalize!(evidence({ providerMetadata: { openrouter: { usage: { cost: 3.2e-7 } } } })), {
+        kind: "charged",
+        amount: { amount: "0.00000032", currency: "USD" },
+        source: "OpenRouter response usage.cost",
+    });
+});
+
+test("DeepInfra's documented response estimate remains estimated", () => {
+    const normalize = providerCostNormalizer("@ai-sdk/deepinfra");
+    assert.notEqual(normalize, undefined);
+    assert.deepEqual(normalize!(evidence({ usage: { estimated_cost: 5.04e-5 } })), {
+        kind: "estimated",
+        amount: { amount: "0.0000504", currency: "USD" },
+        source: "DeepInfra response usage.estimated_cost",
+    });
+});
+
+test("first-party charged evidence is validated at its adapter boundary", () => {
+    const charged = {
+        kind: "charged",
+        amount: { amount: "0.01", currency: "USD" },
+        source: "plurnk endpoint",
+    } as const;
+    assert.deepEqual(plurnkCostNormalizer(evidence({ charge: charged })), charged);
+    assert.equal(plurnkCostNormalizer(evidence({})), undefined);
+});
+
+test("response cost normalization is an explicit adapter capability", () => {
+    assert.equal(providerCostNormalizer("@ai-sdk/anthropic"), undefined);
+    assert.equal(providerCostNormalizer("@ai-sdk/xai")!(evidence({ usage: {} })), undefined);
+    assert.throws(
+        () => providerCostNormalizer("@ai-sdk/xai")!(evidence({ usage: { cost_in_usd_ticks: "1" } })),
+        /cost_in_usd_ticks must be numeric/,
+    );
+});
+
+test("aggregateProviderAccounting preserves request order and only sums known fields", () => {
+    const accounting = aggregateProviderAccounting([
+        {
+            provider: "provider:a",
+            model: "m",
+            outcome: "error",
+            status: 429,
+            cost: { kind: "unknown", reason: "no response accounting" },
+        },
+        {
+            provider: "provider:b",
+            model: "m",
+            outcome: "response",
+            usage: { inputTokens: 2, outputTokens: 3, totalTokens: 5 },
+            cost: {
+                kind: "charged",
+                amount: { amount: "0.25", currency: "USD" },
+                source: "provider b",
+            },
+        },
+    ]);
+    assert.deepEqual(accounting.requests.map(({ provider }) => provider), ["provider:a", "provider:b"]);
+    assert.equal(accounting.usage, null, "an unknown failed request prevents fabricated totals");
+    assert.equal(accounting.costUsd, null);
+});

package/src/accounting.ts

@@ -0,0 +1,190 @@
+import type {
+    ChargedCost,
+    ProviderAccounting,
+    ProviderCost,
+    ProviderCostNormalizer,
+    ProviderRequestAccounting,
+    ProviderUsage,
+} from "./types.ts";
+import {
+    sumProviderCostsUsd,
+    validateChargedCost,
+    validateProviderCost,
+} from "./cost.ts";
+import { validateProviderUsage } from "./usage.ts";
+
+const recordOf = (value: unknown): Record<string, unknown> | null =>
+    typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value as Record<string, unknown>
+        : null;
+
+const decimalFromNumber = (value: number, subject: string): string => {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new TypeError(`${subject} must be a finite non-negative number`);
+    }
+    const source = String(value);
+    if (!/[eE]/.test(source)) return source;
+    const [coefficient, exponentSource] = source.toLowerCase().split("e");
+    const exponent = Number(exponentSource);
+    const [integer, fraction = ""] = coefficient!.split(".");
+    const digits = `${integer}${fraction}`;
+    const point = integer!.length + exponent;
+    if (point <= 0) return `0.${"0".repeat(-point)}${digits}`;
+    if (point >= digits.length) return `${digits}${"0".repeat(point - digits.length)}`;
+    return `${digits.slice(0, point)}.${digits.slice(point)}`;
+};
+
+const usdFromTicks = (ticks: number): string => {
+    if (!Number.isSafeInteger(ticks) || ticks < 0) {
+        throw new TypeError("xAI costInUsdTicks must be a non-negative safe integer");
+    }
+    const digits = String(ticks).padStart(11, "0");
+    const integer = digits.slice(0, -10).replace(/^0+(?=\d)/, "");
+    const fraction = digits.slice(-10).replace(/0+$/, "");
+    return fraction === "" ? integer : `${integer}.${fraction}`;
+};
+
+const xaiCost: ProviderCostNormalizer = ({ usage }) => {
+    const wireUsage = recordOf(usage);
+    if (wireUsage === null || !("cost_in_usd_ticks" in wireUsage)) return undefined;
+    const ticks = wireUsage.cost_in_usd_ticks;
+    if (typeof ticks !== "number") {
+        throw new TypeError("xAI usage.cost_in_usd_ticks must be numeric");
+    }
+    return {
+        kind: "charged",
+        amount: { amount: String(ticks), currency: "USDTICK" },
+        usdEquivalent: usdFromTicks(ticks),
+        source: "xAI response usage.cost_in_usd_ticks",
+    };
+};
+
+const openRouterCost: ProviderCostNormalizer = ({ providerMetadata }) => {
+    const usage = recordOf(recordOf(recordOf(providerMetadata)?.openrouter)?.usage);
+    if (usage === null || !("cost" in usage)) return undefined;
+    const cost = usage.cost;
+    if (typeof cost !== "number") throw new TypeError("OpenRouter usage.cost must be numeric");
+    return {
+        kind: "charged",
+        amount: { amount: decimalFromNumber(cost, "OpenRouter usage.cost"), currency: "USD" },
+        source: "OpenRouter response usage.cost",
+    };
+};
+
+const deepInfraCost: ProviderCostNormalizer = ({ usage }) => {
+    const wireUsage = recordOf(usage);
+    if (wireUsage === null || !("estimated_cost" in wireUsage)) return undefined;
+    const cost = wireUsage.estimated_cost;
+    if (typeof cost !== "number") throw new TypeError("DeepInfra usage.estimated_cost must be numeric");
+    return {
+        kind: "estimated",
+        amount: { amount: decimalFromNumber(cost, "DeepInfra usage.estimated_cost"), currency: "USD" },
+        source: "DeepInfra response usage.estimated_cost",
+    };
+};
+
+// The first-party endpoint owns the direct charged-cost wire field.
+export const plurnkCostNormalizer: ProviderCostNormalizer = ({ charge }) => {
+    if (charge === undefined) return undefined;
+    return validateChargedCost(charge) as ChargedCost;
+};
+
+export const providerCostNormalizer = (
+    sdkPackage: string,
+): ProviderCostNormalizer | undefined => {
+    switch (sdkPackage) {
+        case "@ai-sdk/xai": return xaiCost;
+        case "@ai-sdk/deepinfra": return deepInfraCost;
+        case "@openrouter/ai-sdk-provider": return openRouterCost;
+        default: return undefined;
+    }
+};
+
+export const validateProviderRequestAccounting = (
+    value: unknown,
+): ProviderRequestAccounting => {
+    const request = recordOf(value);
+    if (request === null) throw new TypeError("provider request accounting must be an object");
+    if (typeof request.provider !== "string" || request.provider.length === 0) {
+        throw new TypeError("provider request accounting.provider must be non-empty");
+    }
+    if (typeof request.model !== "string" || request.model.length === 0) {
+        throw new TypeError("provider request accounting.model must be non-empty");
+    }
+    if (request.outcome !== "response" && request.outcome !== "error") {
+        throw new TypeError("provider request accounting.outcome must be response or error");
+    }
+    if (request.status !== undefined
+        && (!Number.isInteger(request.status) || (request.status as number) < 100 || (request.status as number) > 599)) {
+        throw new TypeError("provider request accounting.status must be an HTTP status");
+    }
+    if (request.usage !== undefined) validateProviderUsage(request.usage as ProviderUsage);
+    validateProviderCost(request.cost);
+    return value as ProviderRequestAccounting;
+};
+
+const sumKnown = (
+    requests: readonly ProviderRequestAccounting[],
+    read: (usage: ProviderUsage) => number | undefined,
+): number | undefined => {
+    const values = requests.map((request) => request.usage === undefined
+        ? undefined
+        : read(request.usage));
+    return values.some((value) => value === undefined)
+        ? undefined
+        : (values as number[]).reduce((sum, value) => sum + value, 0);
+};
+
+export const aggregateProviderAccounting = (
+    values: readonly ProviderRequestAccounting[],
+): ProviderAccounting => {
+    const requests = values.map(validateProviderRequestAccounting);
+    if (requests.length === 0) {
+        return {
+            requests: [],
+            usage: {
+                inputTokens: 0,
+                outputTokens: 0,
+                totalTokens: 0,
+                inputTokenDetails: {
+                    noCacheTokens: 0,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                },
+                outputTokenDetails: { textTokens: 0, reasoningTokens: 0 },
+            },
+            costUsd: "0",
+        };
+    }
+
+    const inputTokens = sumKnown(requests, (usage) => usage.inputTokens);
+    const outputTokens = sumKnown(requests, (usage) => usage.outputTokens);
+    const totalTokens = sumKnown(requests, (usage) => usage.totalTokens);
+    const noCacheTokens = sumKnown(requests, (usage) => usage.inputTokenDetails?.noCacheTokens);
+    const cacheReadTokens = sumKnown(requests, (usage) => usage.inputTokenDetails?.cacheReadTokens);
+    const cacheWriteTokens = sumKnown(requests, (usage) => usage.inputTokenDetails?.cacheWriteTokens);
+    const textTokens = sumKnown(requests, (usage) => usage.outputTokenDetails?.textTokens);
+    const reasoningTokens = sumKnown(requests, (usage) => usage.outputTokenDetails?.reasoningTokens);
+    const inputTokenDetails = noCacheTokens === undefined
+        && cacheReadTokens === undefined && cacheWriteTokens === undefined
+        ? undefined
+        : { noCacheTokens, cacheReadTokens, cacheWriteTokens };
+    const outputTokenDetails = textTokens === undefined && reasoningTokens === undefined
+        ? undefined
+        : { textTokens, reasoningTokens };
+    const usage = inputTokens === undefined && outputTokens === undefined && totalTokens === undefined
+        && inputTokenDetails === undefined && outputTokenDetails === undefined
+        ? null
+        : validateProviderUsage({
+            ...(inputTokens === undefined ? {} : { inputTokens }),
+            ...(outputTokens === undefined ? {} : { outputTokens }),
+            ...(totalTokens === undefined ? {} : { totalTokens }),
+            ...(inputTokenDetails === undefined ? {} : { inputTokenDetails }),
+            ...(outputTokenDetails === undefined ? {} : { outputTokenDetails }),
+        });
+    return {
+        requests: [...requests],
+        usage,
+        costUsd: sumProviderCostsUsd(requests.map(({ cost }) => cost)),
+    };
+};