@plurnk/plurnk-providers 1.5.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 { AuthoritativeCharge, 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,7 +27,9 @@ export type MockAssistant = {
 export type MockResponse = {
     assistant: MockAssistant;
     assistantRaw?: unknown;
-    charge?: AuthoritativeCharge;
+    // Partial — omitted fields fall back to the deliberate zero fixture.
+    usage?: Partial<ProviderUsage>;
+    cost?: ProviderCost;
     grammarEvidence?: GrammarEvidence;
 };
 
@@ -36,7 +37,11 @@ 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 {
@@ -77,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 }: MockGenerateArgs): 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",
@@ -105,7 +136,7 @@ export default class Mock implements Provider {
         return {
             assistant,
             assistantRaw: next.assistantRaw ?? null,
-            ...(next.charge === undefined ? {} : { charge: next.charge }),
+            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)) 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

@@ -1,18 +1,27 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { authoritativeChargeNormalizer } from "./accounting.ts";
+import {
+    aggregateProviderAccounting,
+    plurnkCostNormalizer,
+    providerCostNormalizer,
+} from "./accounting.ts";
 
-const evidence = ({ providerMetadata, usage }: { providerMetadata?: unknown; usage?: unknown }) => ({
+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 an exact provider-authoritative charge", () => {
-    const normalize = authoritativeChargeNormalizer("@ai-sdk/xai");
+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: "authoritative",
+        kind: "charged",
         amount: { amount: "15493500", currency: "USDTICK" },
         usdEquivalent: "0.00154935",
         source: "xAI response usage.cost_in_usd_ticks",
@@ -20,39 +29,66 @@ test("xAI response ticks normalize to an exact provider-authoritative charge", (
 });
 
 test("OpenRouter response cost normalizes without rate reconstruction", () => {
-    const normalize = authoritativeChargeNormalizer("@openrouter/ai-sdk-provider");
+    const normalize = providerCostNormalizer("@openrouter/ai-sdk-provider");
     assert.notEqual(normalize, undefined);
     assert.deepEqual(normalize!(evidence({ providerMetadata: { openrouter: { usage: { cost: 3.2e-7 } } } })), {
-        kind: "authoritative",
+        kind: "charged",
         amount: { amount: "0.00000032", currency: "USD" },
-        usdEquivalent: "0.00000032",
         source: "OpenRouter response usage.cost",
     });
 });
 
-test("DeepInfra's documented response estimate wins over local rate reconstruction", () => {
-    const normalize = authoritativeChargeNormalizer("@ai-sdk/deepinfra");
+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: "authoritative",
+        kind: "estimated",
         amount: { amount: "0.0000504", currency: "USD" },
-        usdEquivalent: "0.0000504",
         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(authoritativeChargeNormalizer("@ai-sdk/anthropic"), undefined);
-    assert.equal(
-        authoritativeChargeNormalizer("@ai-sdk/xai")!(evidence({ usage: {} })),
-        undefined,
-    );
+    assert.equal(providerCostNormalizer("@ai-sdk/anthropic"), undefined);
+    assert.equal(providerCostNormalizer("@ai-sdk/xai")!(evidence({ usage: {} })), undefined);
     assert.throws(
-        () => authoritativeChargeNormalizer("@ai-sdk/xai")!(evidence({ usage: { cost_in_usd_ticks: "1" } })),
+        () => providerCostNormalizer("@ai-sdk/xai")!(evidence({ usage: { cost_in_usd_ticks: "1" } })),
         /cost_in_usd_ticks must be numeric/,
     );
-    assert.throws(
-        () => authoritativeChargeNormalizer("@ai-sdk/deepinfra")!(evidence({ usage: { estimated_cost: "1" } })),
-        /estimated_cost 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);
 });