@plurnk/plurnk-providers 1.5.0 → 1.6.0

package/src/types.ts

@@ -9,15 +9,32 @@ import type {
     PluginAttributionContext,
     PluginAttributionSource,
 } from "@plurnk/plurnk-meta";
-import type { ProviderCost } from "@plurnk/plurnk-contracts";
+import type {
+    ProviderAccounting,
+    ProviderCost,
+    ProviderRequestAccounting,
+    ProviderUsage,
+} from "@plurnk/plurnk-contracts";
+
+export type {
+    ProviderAccounting,
+    ProviderCost,
+    ProviderRequestAccounting,
+    ProviderUsage,
+} from "@plurnk/plurnk-contracts";
 
 export interface ChatMessage {
     role: "system" | "user" | "assistant";
     content: string;
 }
 
+// {§provider-call-kind} The caller-owned semantic contract for one logical model call. Providers do
+// not infer this from messages or grammar presence: an emission expects PLURNK
+// output, while a bare call expects unconstrained response text.
+export type ProviderCallKind = "emission" | "bare";
+
 // Preflight evidence for the complete provider request. An empirical estimate
-// is useful telemetry but cannot authorize a hard physical-capacity decision.
+// is useful telemetry but cannot authorize hard context-envelope admission.
 export type PromptTokenMeasurement =
     | {
         readonly kind: "exact" | "upper_bound";
@@ -31,39 +48,44 @@ export type PromptTokenMeasurement =
         readonly detail: string;
     };
 
-// Normalized token accounting. Invariant (enforced by normalizeUsage at the
-// provider boundary): total = prompt + completion + reasoning; cached is a
-// subset of prompt. `completion` is visible output EXCLUDING reasoning; the
-// billable output is `completion + reasoning` (frontier providers bill reasoning
-// tokens at the output rate).
-export interface ProviderUsage {
-    readonly prompt: number;       // input tokens (cached ones included)
-    readonly completion: number;   // visible output tokens, excluding reasoning
-    readonly reasoning: number;    // reasoning tokens, billed as output
-    readonly cached: number;       // subset of prompt served from cache
-    readonly total: number;        // prompt + completion + reasoning
-}
-
-export type AuthoritativeCharge = Extract<ProviderCost, { kind: "authoritative" }>;
+export type ChargedCost = Extract<ProviderCost, { kind: "charged" }>;
 
 // Evidence exposed by the transport to the provider adapter that owns its
 // vendor protocol. Core and downstream consumers receive only the normalized
 // charge, never a requirement to understand provider metadata fields.
 export interface ProviderChargeEvidence {
     readonly providerMetadata?: unknown;
+    // A protocol-owned direct monetary field. It remains unknown until the
+    // selected adapter explicitly validates and normalizes it.
+    readonly charge?: unknown;
     // Provider-owned raw usage projection retained independently of optional
     // full-body capture. Accounting fields cannot disappear merely because
     // forensic raw-body capture is disabled.
     readonly usage?: unknown;
     readonly response: {
-        readonly id: string;
+        readonly id?: string;
         readonly headers?: Readonly<Record<string, string>>;
     };
 }
 
-export type AuthoritativeChargeNormalizer = (
+export type ProviderCostNormalizer = (
     evidence: ProviderChargeEvidence,
-) => AuthoritativeCharge | undefined;
+) => ProviderCost | undefined;
+
+export interface ProviderRequestIdentity {
+    readonly provider: string;
+    readonly model: string;
+}
+
+export type ProviderRequestSettlement = (
+    accounting: ProviderRequestAccounting,
+) => Promise<void>;
+
+// Core opens durable physical-request identity through this observer before
+// provider I/O. The returned settlement closes that exact identity.
+export type ProviderRequestObserver = (
+    identity: ProviderRequestIdentity,
+) => Promise<ProviderRequestSettlement>;
 
 // A successful exchange's closed finish set. ProviderAttemptFinishReason adds
 // the failed disposition that may occur only on ProviderError attempt evidence.
@@ -102,7 +124,6 @@ export interface ProviderAssistant<TFinish extends ProviderAttemptFinishReason =
     readonly reasoning: string | null;
     // Encrypted reasoning remains distinct from readable `reasoning`.
     readonly reasoningEncrypted?: ReadonlyArray<ProviderEncryptedReasoningItem>;
-    readonly usage: ProviderUsage;
     readonly finishReason: TFinish;
     readonly model: string;
     // Per-token logprobs, present only when PLURNK_PROVIDERS_TOP_LOGPROBS is set
@@ -114,8 +135,9 @@ export interface ProviderAssistant<TFinish extends ProviderAttemptFinishReason =
 }
 
 export interface GrammarEvidence {
-    // Exact sentence observed at the grammar boundary before any reasoning/content
-    // projection. Offsets are Unicode code points, matching @plurnk/gbnf verdicts.
+    // Exact pre-projection response represented by the provider. A generated
+    // rail's response root composes any template prefix before @plurnk/gbnf
+    // grades it. Offsets are Unicode code points, matching validator verdicts.
     readonly input: string;
     readonly contentStart: number;
     readonly transported: boolean;
@@ -124,10 +146,9 @@ export interface GrammarEvidence {
 export interface ProviderResponse<TFinish extends ProviderAttemptFinishReason = FinishReason> {
     readonly assistant: ProviderAssistant<TFinish>;
     readonly assistantRaw: unknown;
-    // A settled upstream charge is a validated public fact, not opaque metadata.
-    // Non-USD settlement carries an explicit provider-owned USD equivalent for
-    // the platform's existing USD aggregate. Core never supplies an FX rate.
-    readonly charge?: AuthoritativeCharge;
+    // Ordered physical request evidence, including automatic retries and pool
+    // failover that preceded this response. {§provider-request-accounting}
+    readonly accounting: readonly ProviderRequestAccounting[];
     // {§gbnf-response-observation} — evidence only; the consumer owns the verdict.
     readonly grammarEvidence?: GrammarEvidence;
     // Per-turn provider→client metadata bag: the backend's non-standard top-level
@@ -152,12 +173,30 @@ export interface ProviderResponse<TFinish extends ProviderAttemptFinishReason =
 
 export type ProviderAttempt = ProviderResponse<ProviderAttemptFinishReason>;
 
+export interface ProviderGenerateArgs {
+    readonly messages: ChatMessage[];
+    readonly workerId: string;
+    readonly primaryWorkerId?: string;
+    readonly signal?: AbortSignal;
+    readonly grammar?: string;
+    readonly maxTokens?: number;
+    readonly attributions?: string[];
+    readonly client?: string;
+    readonly strikes?: number;
+    readonly workspaceId?: string;
+    readonly loop?: number;
+    readonly turn?: number;
+    readonly sampling?: Record<string, unknown>;
+    readonly observeRequest?: ProviderRequestObserver;
+    readonly callKind?: ProviderCallKind;
+}
+
 export interface Provider {
     // Optional package-authored folksonomy evaluated by the consumer immediately
     // before a provider emission attempt ({§plugin-attribution}).
     attributions?(context: PluginAttributionContext): PluginAttribution;
     // `grammar` is an optional GBNF string (canonically @plurnk/plurnk-contracts'
-    // plurnk.gbnf, possibly root-substituted by the consumer). Backends that
+    // plurnk.gemma.gbnf or plurnk.qwen.gbnf, possibly root-substituted by the consumer). Backends that
     // support grammar-constrained sampling attach it verbatim; all others
     // ignore it. The provider never chooses or modifies the grammar — whether
     // to constrain and which root variant to send is consumer policy
@@ -206,9 +245,15 @@ export interface Provider {
     // `Plurnk-Turn` ONLY under the same firstPartyMetadata gate; dropped
     // everywhere else. Coordinates are 1-based: absent/0 emits no header (no
     // strikes-style zero exception). Headers only, never the packet.
-    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>;
-    // {§model-fact-resolution} — effective physical context in tokens. `null`
-    // means unknown; under llama-server parallelism the probed value is per slot.
+    //
+    // `callKind` is the caller's explicit output contract. It is transported as
+    // `Plurnk-Call-Kind` only under the first-party metadata gate and never
+    // inferred from the request shape. Generic callers may omit it; Core always
+    // supplies `emission` or `bare`.
+    generate(args: ProviderGenerateArgs): Promise<ProviderResponse>;
+    // {§model-fact-resolution} — effective total context envelope in tokens,
+    // including any stricter operator cap. `null` means unknown; under
+    // llama-server parallelism the probed natural value is per slot.
     readonly contextWindow: number | null;
     readonly model: string;
     // Optional: the backend's self-reported served model id, from a
@@ -231,7 +276,7 @@ export interface Provider {
     // with no declared envelope, instead of dying mid-turn in partition math.
     readonly requiresMaxTokens?: boolean;
     // Optional generation-envelope reserves ({§provider-generation-envelope}) — the amounts of
-    // the DETECTED window reserved for reasoning and completion: floor
+    // the effective window reserved for reasoning and completion: floor
     // percentages of `contextWindow`, or absolute per-alias pins that win
     // outright. The consumer's prompt budget is `contextWindow - reasoningReserve
     // - completionReserve - <its own packing-safety margin>`; the generation cap
@@ -242,7 +287,7 @@ export interface Provider {
     readonly completionReserve?: number | null;
     // Provider-owned preflight measurement of the complete chat request,
     // including provider/template framing when the adapter can know it.
-    // Estimates are explicit and MUST NOT authorize hard physical admission.
+    // Estimates are explicit and MUST NOT authorize hard context-envelope admission.
     countPromptTokens(messages: readonly ChatMessage[], signal?: AbortSignal): Promise<PromptTokenMeasurement>;
     // OPTIONAL capability: exact tokenization served by the backend's own vocab
     // (llama-server /tokenize) — token ids in the model's real vocabulary.
@@ -250,12 +295,6 @@ export interface Provider {
     // `tokenize === undefined` means the backend can't. Exact-counting
     // consumers (the tokenizer seam) prefer this over any client-side data.
     tokenize?(text: string): Promise<number[]>;
-    // {§model-fact-resolution} — frozen 1.x local USD estimate compatibility.
-    // This is not a monetary-reporting authority.
-    calculateCost(usage: ProviderUsage): number;
-    // Models.dev-derived monetary fallback. Direct response charges travel on
-    // ProviderResponse and take precedence at the consuming attempt boundary.
-    calculateCharge?(usage: ProviderUsage): Exclude<ProviderCost, AuthoritativeCharge>;
 }
 
 // ProviderAlias lives in @plurnk/plurnk-aliases (the zero-dependency parser);

package/src/usage.test.ts

@@ -1,153 +1,149 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { normalizeUsage, calculateCostUsd, calculateCostUsdDecimal } from "./usage.ts";
+import { calculateCostUsdDecimal, normalizeUsage } from "./usage.ts";
 
-// — normalizeUsage —
-
-test("normalizeUsage: Gemini-style — reasoning recovered from total gap", () => {
-    // Real Gemini OAI-compat shape: no details, reasoning hidden in total.
-    const u = normalizeUsage({ prompt_tokens: 19, completion_tokens: 285, total_tokens: 1165 });
-    assert.deepEqual(u, { prompt: 19, completion: 285, reasoning: 861, cached: 0, total: 1165 });
-    assert.equal(u.prompt + u.completion + u.reasoning, u.total); // invariant
+test("normalizeUsage recovers additive hidden reasoning from an exact total", () => {
+    const usage = normalizeUsage({
+        prompt_tokens: 19,
+        completion_tokens: 285,
+        total_tokens: 1165,
+    });
+    assert.deepEqual(usage, {
+        inputTokens: 19,
+        outputTokens: 1146,
+        totalTokens: 1165,
+        outputTokenDetails: { textTokens: 285, reasoningTokens: 861 },
+    });
 });
 
-test("normalizeUsage: OpenAI-style — reasoning split out of completion_tokens", () => {
-    // completion_tokens includes reasoning; total = prompt + completion.
-    const u = normalizeUsage({
+test("normalizeUsage preserves OpenAI output totals while itemizing reasoning", () => {
+    const usage = normalizeUsage({
         prompt_tokens: 10,
         completion_tokens: 100,
         total_tokens: 110,
         completion_tokens_details: { reasoning_tokens: 40 },
     });
-    assert.deepEqual(u, { prompt: 10, completion: 60, reasoning: 40, cached: 0, total: 110 });
-    assert.equal(u.completion + u.reasoning, 100); // billable output unchanged
+    assert.deepEqual(usage, {
+        inputTokens: 10,
+        outputTokens: 100,
+        totalTokens: 110,
+        outputTokenDetails: { textTokens: 60, reasoningTokens: 40 },
+    });
 });
 
-test("normalizeUsage: xAI/Grok-style — reasoning is ADDITIVE, not subtracted from completion", () => {
-    // Real grok-4.3 shape: completion_tokens is visible-only; reasoning_tokens is
-    // detailed but ADDITIVE — total = prompt + completion + reasoning.
-    const u = normalizeUsage({
+test("normalizeUsage recognizes xAI reasoning as additive from the total identity", () => {
+    const usage = normalizeUsage({
         prompt_tokens: 143,
         completion_tokens: 1,
         total_tokens: 441,
         prompt_tokens_details: { cached_tokens: 128 },
         completion_tokens_details: { reasoning_tokens: 297 },
     });
-    assert.deepEqual(u, { prompt: 143, completion: 1, reasoning: 297, cached: 128, total: 441 });
-    assert.equal(u.completion, 1); // visible output preserved, NOT zeroed by the subtraction
-    assert.equal(u.completion + u.reasoning, 298); // billable output = visible + reasoning
-});
-
-test("normalizeUsage: cached read from prompt_tokens_details (OpenAI nesting)", () => {
-    const u = normalizeUsage({ prompt_tokens: 50, completion_tokens: 10, total_tokens: 60, prompt_tokens_details: { cached_tokens: 30 } });
-    assert.equal(u.cached, 30);
+    assert.deepEqual(usage, {
+        inputTokens: 143,
+        outputTokens: 298,
+        totalTokens: 441,
+        inputTokenDetails: { cacheReadTokens: 128 },
+        outputTokenDetails: { textTokens: 1, reasoningTokens: 297 },
+    });
 });
 
-test("normalizeUsage: top-level cached_tokens still honored", () => {
-    const u = normalizeUsage({ prompt_tokens: 50, completion_tokens: 10, total_tokens: 60, cached_tokens: 12 });
-    assert.equal(u.cached, 12);
+test("normalizeUsage maps cache-read spellings without inventing uncached tokens", () => {
+    assert.deepEqual(normalizeUsage({
+        prompt_tokens: 50,
+        completion_tokens: 10,
+        total_tokens: 60,
+        prompt_tokens_details: { cached_tokens: 30 },
+    })?.inputTokenDetails, { cacheReadTokens: 30 });
+    assert.deepEqual(normalizeUsage({
+        prompt_tokens: 50,
+        completion_tokens: 10,
+        total_tokens: 60,
+        cached_tokens: 12,
+    })?.inputTokenDetails, { cacheReadTokens: 12 });
 });
 
-test("#157: normalizeUsage maps DeepSeek's prompt cache hit count", () => {
-    const u = normalizeUsage({
+test("#157: normalizeUsage maps DeepSeek cache hit and miss counts", () => {
+    assert.deepEqual(normalizeUsage({
         prompt_tokens: 50,
         prompt_cache_hit_tokens: 30,
         prompt_cache_miss_tokens: 20,
         completion_tokens: 10,
         total_tokens: 60,
+    }), {
+        inputTokens: 50,
+        outputTokens: 10,
+        totalTokens: 60,
+        inputTokenDetails: { noCacheTokens: 20, cacheReadTokens: 30 },
     });
-    assert.deepEqual(u, { prompt: 50, completion: 10, reasoning: 0, cached: 30, total: 60 });
-});
-
-test("normalizeUsage: no reasoning — plain prompt+completion", () => {
-    const u = normalizeUsage({ prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 });
-    assert.deepEqual(u, { prompt: 10, completion: 20, reasoning: 0, cached: 0, total: 30 });
-});
-
-test("normalizeUsage: missing total is reconstructed, never negative reasoning", () => {
-    const u = normalizeUsage({ prompt_tokens: 10, completion_tokens: 20 });
-    assert.deepEqual(u, { prompt: 10, completion: 20, reasoning: 0, cached: 0, total: 30 });
 });
 
-test("normalizeUsage: absent usage → all zeros", () => {
-    assert.deepEqual(normalizeUsage(null), { prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 });
-    assert.deepEqual(normalizeUsage(undefined), { prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 });
-});
-
-// -- Fireworks-style: reasoning shipped as TEXT, folded into completion, not itemized --
-
-test("normalizeUsage: fireworks folds reasoning into completion -- re-split by text proportion, sum preserved", () => {
-    // total = prompt + completion (no gap), reasoning_tokens absent, but 750 vs 250
-    // chars of reasoning vs content came back. Split completion 75/25; cost base held.
-    const u = normalizeUsage(
-        { prompt_tokens: 100, completion_tokens: 1000, total_tokens: 1100 },
-        "r".repeat(750),
-        "c".repeat(250),
-    );
-    assert.deepEqual(u, { prompt: 100, completion: 250, reasoning: 750, cached: 0, total: 1100 });
-    assert.equal(u.completion + u.reasoning, 1000); // billable output byte-identical
-    assert.equal(u.prompt + u.completion + u.reasoning, u.total); // invariant
-});
-
-test("normalizeUsage: pure-reasoning turn (empty content) attributes all completion to reasoning", () => {
-    // The run52 runaway shape: 0 visible content, the whole budget spent reasoning.
-    const u = normalizeUsage(
-        { prompt_tokens: 100, completion_tokens: 500, total_tokens: 600 },
-        "t".repeat(9000),
-        "",
-    );
-    assert.deepEqual(u, { prompt: 100, completion: 0, reasoning: 500, cached: 0, total: 600 });
-});
-
-test("normalizeUsage: text args never perturb the itemized (reasoning_tokens) path", () => {
-    // OpenAI o-series reports reasoning_tokens -> that split wins, text is ignored.
-    const u = normalizeUsage(
-        { prompt_tokens: 10, completion_tokens: 100, total_tokens: 110, completion_tokens_details: { reasoning_tokens: 40 } },
-        "r".repeat(999), "c".repeat(1),
-    );
-    assert.deepEqual(u, { prompt: 10, completion: 60, reasoning: 40, cached: 0, total: 110 });
-});
-
-test("normalizeUsage: text args never perturb the Gemini gap path (gap already yields reasoning)", () => {
-    // A real total gap means reasoning is itemized-by-subtraction; do not re-split.
-    const u = normalizeUsage(
-        { prompt_tokens: 19, completion_tokens: 285, total_tokens: 1165 },
-        "r".repeat(500), "c".repeat(500),
-    );
-    assert.equal(u.reasoning, 861); // from the gap, NOT a text re-split
-    assert.equal(u.completion, 285);
-});
-
-test("normalizeUsage: no total reported -> re-split skipped, reasoning stays 0 (cannot split an unknown base)", () => {
-    const u = normalizeUsage(
-        { prompt_tokens: 10, completion_tokens: 20 },
-        "r".repeat(500), "c".repeat(500),
-    );
-    assert.deepEqual(u, { prompt: 10, completion: 20, reasoning: 0, cached: 0, total: 30 });
-});
-
-// — calculateCostUsd —
-
-test("calculateCostUsd: bills reasoning at the USD-per-million output rate", () => {
-    // 100 input, 0 cached, 50 completion + 200 reasoning = 250 output.
-    const usage = { prompt: 100, completion: 50, reasoning: 200, cached: 0, total: 350 };
-    assert.equal(calculateCostUsd(usage, { input: 1, output: 10, cached: 0 }), 0.0026);
+test("normalizeUsage derives only exact totals", () => {
+    assert.deepEqual(normalizeUsage({ prompt_tokens: 10, completion_tokens: 20 }), {
+        inputTokens: 10,
+        outputTokens: 20,
+        totalTokens: 30,
+    });
+    assert.deepEqual(normalizeUsage({ prompt_tokens: 10, total_tokens: 30 }), {
+        inputTokens: 10,
+        outputTokens: 20,
+        totalTokens: 30,
+    });
 });
 
-test("calculateCostUsd: cached prompt billed at the cache rate, remainder at input", () => {
-    const usage = { prompt: 1000, completion: 0, reasoning: 0, cached: 400, total: 1000 };
-    assert.equal(calculateCostUsd(usage, { input: 5, output: 99, cached: 1 }), 0.0034);
+test("normalizeUsage preserves unknown usage as absence", () => {
+    assert.equal(normalizeUsage(null), undefined);
+    assert.equal(normalizeUsage(undefined), undefined);
 });
 
-test("calculateCostUsd: zero rates → 0", () => {
-    const usage = { prompt: 9, completion: 9, reasoning: 9, cached: 9, total: 27 };
-    assert.equal(calculateCostUsd(usage, { input: 0, output: 0, cached: 0 }), 0);
+test("normalizeUsage never apportions tokens from reasoning or content length", () => {
+    assert.deepEqual(normalizeUsage({
+        prompt_tokens: 100,
+        completion_tokens: 1000,
+        total_tokens: 1100,
+    }), {
+        inputTokens: 100,
+        outputTokens: 1000,
+        totalTokens: 1100,
+    });
 });
 
-test("calculateCostUsdDecimal preserves Models.dev rates without floating-point artifacts", () => {
-    const usage = { prompt: 1_000, completion: 100, reasoning: 50, cached: 400, total: 1_150 };
-    assert.equal(
-        calculateCostUsdDecimal(usage, { input: 0.14, output: 0.28, cached: 0.0028 }),
-        "0.00012712",
-    );
+test("calculateCostUsdDecimal bills all output, including reasoning, at the output rate", () => {
+    assert.equal(calculateCostUsdDecimal({
+        inputTokens: 100,
+        outputTokens: 250,
+        totalTokens: 350,
+        outputTokenDetails: { textTokens: 50, reasoningTokens: 200 },
+    }, { input: 1, output: 10 }), "0.0026");
+});
+
+test("calculateCostUsdDecimal applies distinct cache-read and cache-write rates", () => {
+    assert.equal(calculateCostUsdDecimal({
+        inputTokens: 1000,
+        outputTokens: 0,
+        totalTokens: 1000,
+        inputTokenDetails: {
+            noCacheTokens: 500,
+            cacheReadTokens: 400,
+            cacheWriteTokens: 100,
+        },
+    }, { input: 5, output: 99, cacheRead: 1, cacheWrite: 8 }), "0.0037");
+});
+
+test("calculateCostUsdDecimal returns unknown when a differently-priced category is absent", () => {
+    assert.equal(calculateCostUsdDecimal({
+        inputTokens: 1000,
+        outputTokens: 0,
+        totalTokens: 1000,
+    }, { input: 5, output: 99, cacheRead: 1 }), null);
+});
+
+test("calculateCostUsdDecimal preserves Models.dev decimals without floating-point artifacts", () => {
+    assert.equal(calculateCostUsdDecimal({
+        inputTokens: 1000,
+        outputTokens: 150,
+        totalTokens: 1150,
+        inputTokenDetails: { cacheReadTokens: 400 },
+        outputTokenDetails: { textTokens: 100, reasoningTokens: 50 },
+    }, { input: 0.14, output: 0.28, cacheRead: 0.0028 }), "0.00012712");
 });