@plurnk/plurnk-providers 1.3.12 → 1.5.0

package/src/sdkModels.ts

@@ -6,13 +6,15 @@ import { createGroq } from "@ai-sdk/groq";
 import { createMistral } from "@ai-sdk/mistral";
 import { createOpenAI } from "@ai-sdk/openai";
 import { createTogetherAI } from "@ai-sdk/togetherai";
-import { createXai } from "@ai-sdk/xai";
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 import { lookupProvider, type ProviderInfo } from "@plurnk/plurnk-models";
 import type { LanguageModel } from "ai";
+import { authoritativeChargeNormalizer } from "./accounting.ts";
+import type { AuthoritativeChargeNormalizer } from "./types.ts";
 
 export type SdkModel = {
     readonly languageModel?: LanguageModel;
+    readonly normalizeCharge?: AuthoritativeChargeNormalizer;
     readonly compatible?: {
         readonly url: string;
         readonly headers: Readonly<Record<string, string>>;
@@ -85,12 +87,6 @@ const baseUrl = (
     return value === undefined ? undefined : expandEnv(value, env, provider).replace(/\/+$/, "");
 };
 
-const apiKey = (
-    provider: string,
-    env: NodeJS.ProcessEnv,
-    catalog: ProviderInfo,
-): string | undefined => firstSet(env, configuredKeyNames(provider, env, catalog));
-
 const requireApiKey = (
     provider: string,
     env: NodeJS.ProcessEnv,
@@ -111,6 +107,7 @@ export const createSdkModel = (
     const catalog = lookupProvider(provider) ?? configuredProviderInfo(provider, env);
     if (catalog === null) return null;
     const url = baseUrl(provider, env, catalog, baseUrlOverride);
+    const normalizeCharge = authoritativeChargeNormalizer(catalog.npm);
 
     switch (catalog.npm) {
         case "@ai-sdk/openai":
@@ -136,6 +133,7 @@ export const createSdkModel = (
         case "@ai-sdk/deepinfra":
             return {
                 languageModel: createDeepInfra({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                ...(normalizeCharge === undefined ? {} : { normalizeCharge }),
                 catalog,
             };
         case "@ai-sdk/google":
@@ -143,11 +141,18 @@ export const createSdkModel = (
                 languageModel: createGoogle({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
                 catalog,
             };
-        case "@ai-sdk/xai":
+        case "@ai-sdk/xai": {
+            const key = requireApiKey(provider, env, catalog);
+            const compatibleBase = url ?? "https://api.x.ai/v1";
             return {
-                languageModel: createXai({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
+                compatible: {
+                    url: `${compatibleBase}/chat/completions`,
+                    headers: { Authorization: `Bearer ${key}` },
+                },
+                ...(normalizeCharge === undefined ? {} : { normalizeCharge }),
                 catalog,
             };
+        }
         case "@ai-sdk/anthropic":
             return {
                 languageModel: createAnthropic({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).languageModel(model),
@@ -175,16 +180,19 @@ export const createSdkModel = (
                         ...(env.OPENROUTER_X_TITLE === undefined ? {} : { "X-Title": env.OPENROUTER_X_TITLE }),
                     },
                 }).languageModel(model),
+                ...(normalizeCharge === undefined ? {} : { normalizeCharge }),
                 catalog,
             };
         case "@ai-sdk/openai-compatible":
             if (url === undefined) throw new Error(`${provider} provider: Models.dev supplies no API URL and no base URL was configured`);
+            const keyNames = configuredKeyNames(provider, env, catalog);
+            const key = keyNames.length === 0 ? undefined : requireApiKey(provider, env, catalog);
             return {
                 compatible: {
                     url: `${url}/chat/completions`,
-                    headers: apiKey(provider, env, catalog) === undefined
+                    headers: key === undefined
                         ? {}
-                        : { Authorization: `Bearer ${apiKey(provider, env, catalog)}` },
+                        : { Authorization: `Bearer ${key}` },
                 },
                 catalog,
             };

package/src/types.ts

@@ -1,15 +1,36 @@
 // Provider transport contract. Providers return raw wire-level output —
-// content unparsed (consumer parses via @plurnk/plurnk-grammar), reasoning
+// content unparsed (consumer parses via @plurnk/plurnk-contracts), reasoning
 // is the wire-reported CoT only.
 
-import type { TelemetryEvent } from "./telemetry.ts";
+import type { ProviderNotice } from "./notices.ts";
 import type { LanguageModel } from "ai";
+import type {
+    PluginAttribution,
+    PluginAttributionContext,
+    PluginAttributionSource,
+} from "@plurnk/plurnk-meta";
+import type { ProviderCost } from "@plurnk/plurnk-contracts";
 
 export interface ChatMessage {
     role: "system" | "user" | "assistant";
     content: string;
 }
 
+// Preflight evidence for the complete provider request. An empirical estimate
+// is useful telemetry but cannot authorize a hard physical-capacity decision.
+export type PromptTokenMeasurement =
+    | {
+        readonly kind: "exact" | "upper_bound";
+        readonly tokens: number;
+        readonly source: string;
+    }
+    | {
+        readonly kind: "estimate";
+        readonly tokens: number;
+        readonly source: string;
+        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
@@ -23,11 +44,33 @@ export interface ProviderUsage {
     readonly total: number;        // prompt + completion + reasoning
 }
 
-// Closed set per SPEC §2. Relay/aggregator providers MUST normalize wire
-// values back to one of these at the provider boundary.
+export type AuthoritativeCharge = Extract<ProviderCost, { kind: "authoritative" }>;
+
+// 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;
+    // 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 headers?: Readonly<Record<string, string>>;
+    };
+}
+
+export type AuthoritativeChargeNormalizer = (
+    evidence: ProviderChargeEvidence,
+) => AuthoritativeCharge | undefined;
+
+// A successful exchange's closed finish set. ProviderAttemptFinishReason adds
+// the failed disposition that may occur only on ProviderError attempt evidence.
 export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | null;
+export type ProviderAttemptFinishReason = FinishReason | "resource_interrupted";
 
-// A per-token logprob (#36, SPEC §14). `logprob` is the backend's RAW model
+// {§provider-evidence} A per-token logprob. `logprob` is the backend's raw model
 // log-probability of the emitted token — the sampling-transform-invariant
 // confidence, chosen over Fireworks' post-mask `sampling_logprob` (measured
 // IDENTICAL under grammar, incl. an adversarial mask; the raw value is the honest
@@ -45,20 +88,24 @@ export interface TokenLogprob {
     readonly top?: readonly TokenAlternative[];
 }
 
-export interface ProviderAssistant {
+// {§provider-encrypted-reasoning} `id` is provider detail identity; `subtype`
+// is the provider's evidence-backed classification. Neither is a client entity
+// correlation, so consumers must not substitute `id` for a message/tool-call ID.
+export interface ProviderEncryptedReasoningItem {
+    readonly id: string | null;
+    readonly subtype: string;
+    readonly encrypted: ReadonlyArray<{ data: string; format: string | null }>;
+}
+
+export interface ProviderAssistant<TFinish extends ProviderAttemptFinishReason = FinishReason> {
     readonly content: string;
     readonly reasoning: string | null;
-    // Sealed reasoning (#482): a relay backend (OpenRouter fronting OpenAI
-    // o-series) returns the chain-of-thought ENCRYPTED — surfaced verbatim as
-    // items { id, subtype, encrypted: [{data, format}] } (id from the wire,
-    // subtype from wire position), never decoded, never synthesized. Readable text
-    // stays on `reasoning`. Absent when the turn produced none; consumers (agui)
-    // project it as REASONING_ENCRYPTED_VALUE.
-    readonly reasoningEncrypted?: ReadonlyArray<{ id: string | null; subtype: string; encrypted: ReadonlyArray<{ data: string; format: string | null }> }>;
+    // Encrypted reasoning remains distinct from readable `reasoning`.
+    readonly reasoningEncrypted?: ReadonlyArray<ProviderEncryptedReasoningItem>;
     readonly usage: ProviderUsage;
-    readonly finishReason: FinishReason;
+    readonly finishReason: TFinish;
     readonly model: string;
-    // Per-token logprobs (#36), present ONLY when PLURNK_PROVIDERS_TOP_LOGPROBS is set
+    // Per-token logprobs, present only when PLURNK_PROVIDERS_TOP_LOGPROBS is set
     // AND the backend returned them. Absent otherwise — NEVER synthesized. Opt-in,
     // per-alias: a scraping alias enables it; serving turns carry nothing.
     readonly logprobs?: readonly TokenLogprob[];
@@ -66,42 +113,59 @@ export interface ProviderAssistant {
     readonly meanLogprob?: number;
 }
 
-export interface ProviderResponse {
-    readonly assistant: ProviderAssistant;
+export interface GrammarEvidence {
+    // Exact sentence observed at the grammar boundary before any reasoning/content
+    // projection. Offsets are Unicode code points, matching @plurnk/gbnf verdicts.
+    readonly input: string;
+    readonly contentStart: number;
+    readonly transported: boolean;
+}
+
+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;
+    // {§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
     // response fields passed through verbatim. Monetary values carry their own
     // amount and currency; the provider does not reinterpret them. The consumer
     // (service) merges this into its Turn metadata and
     // filters what reaches the client; it reads `meta`, never mines `assistantRaw`.
-    // Absent when the backend reported no extra fields (#23, generalized).
+    // Absent when the backend reported no extra fields.
     readonly meta?: Record<string, unknown>;
-    // The VERBATIM backend response body (#36, SPEC §14) — the full wire JSON for
+    // The verbatim backend response body ({§provider-evidence}) — the full wire JSON for
     // a non-streamed turn, or the reassembled equivalent for a streamed one.
     // `assistantRaw` is a normalized DIGEST (it drops choices[]); this is the
     // capture-everything record for the endpoint's fine-tune corpus. Present ONLY
     // when PLURNK_PROVIDERS_RAWBODY is on — off by default so serving turns never
     // carry it. Absent otherwise.
     readonly rawBody?: unknown;
-    // Observations attached to a COMPLETED exchange (#24, SPEC §13). The model's
-    // bytes always flow through `assistant`; these events annotate them. Today: a
-    // `grammar_unenforced` event whenever the output diverges from the grammar —
-    // transported OR withheld (filter mode) — carrying the divergence `position`.
-    // The provider never adjudicates conformance; discard/retry/escalate/
-    // self-correct is consumer policy. Absent when the turn produced no telemetry.
-    readonly telemetry?: readonly TelemetryEvent[];
+    // Notices attached to the represented attempt. Successful
+    // returns may relay them; interrupted attempt notices remain forensic.
+    // Grammar conformance itself is consumer-owned.
+    readonly notices?: readonly ProviderNotice[];
 }
 
+export type ProviderAttempt = ProviderResponse<ProviderAttemptFinishReason>;
+
 export interface Provider {
-    // `grammar` is an optional GBNF string (canonically @plurnk/plurnk-grammar's
+    // 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
     // 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 (SPEC §13).
+    // to constrain and which root variant to send is consumer policy
+    // ({§gbnf-response-observation}).
     //
     // `maxTokens` is the consumer's per-call output ceiling (wire `max_tokens`).
     // Without it, most servers generate UNBOUNDED (llama-server n_predict -1) —
-    // under a multi-op grammar that degenerates to the context wall (SPEC §13),
+    // under a multi-op grammar that degenerates to the context wall,
     // so a constrained consumer is expected to pass it. Policy stays the
     // consumer's; the provider only transports.
     //
@@ -109,70 +173,64 @@ export interface Provider {
     // stream (loop/run). Providers MAY key backend affinity on it — e.g.
     // llama-server slot pinning for KV-cache reuse — and MUST NOT interpret
     // its content. The consumer never sees or chooses backend resources
-    // (slot integers, connections); the *mechanism* is the provider's (#11).
+    // (slot integers, connections); the mechanism is the provider's.
     //
-    // `attributions` (per-turn, runtime-observed) and `client` (workspace-stable,
-    // self-identified) are first-party telemetry the consumer hands down: which
-    // installed plugin packages dispatched this turn, and which frontend
-    // originated the worker. They are forwarded ONLY by a provider whose spec opts
-    // in (the first-party `plurnk` endpoint, via `Plurnk-Attribution` /
-    // `Plurnk-Client` headers); every other provider DROPS them — the gate is
-    // structural so first-party metadata can never leak to a third-party backend.
+    // `attributions` is opaque consumer-supplied creator telemetry; the consumer
+    // owns what contribution that set claims ({§attribution}). `client` is the
+    // consumer's workspace-stable, self-identified frontend. They are forwarded ONLY by a
+    // provider whose spec opts in (the first-party `plurnk` endpoint, via
+    // `Plurnk-Attribution` / `Plurnk-Client` headers); every other provider DROPS
+    // them — the gate is structural so first-party metadata can never leak to a
+    // third-party backend.
     //
     // `sampling` is an optional bag of standard OpenAI-compat sampling params
     // (temperature, top_p, top_k, min_p, penalties, stop, seed, …) forwarded into
     // the request body UNDER the provider's managed fields — model/messages/grammar/
     // reasoning/max_tokens/slot always win, and transport/protocol keys (stream,
     // response_format, grammar, id_slot) are stripped, so it carries sampling intent
-    // only and can't bypass grammar transport (SPEC §8 holds). A PROXY consumer (the
+    // only and can't bypass grammar transport ({§provider-request-authority}). A
+    // proxy consumer (the
     // plurnk endpoint fronting its own backends) uses it to pass its caller's sampling
     // knobs through; a direct consumer typically leaves it unset.
     //
     // `strikes` is the worker's CURRENT rail-strike streak at time-of-generate
-    // (0 = clean; a clean turn zeroes it; every loop starts at 0 — contract:
-    // plurnk-service#313). Forwarded as a `Plurnk-Strikes` header ONLY under the
+    // (0 = clean; a clean turn zeroes it; every loop starts at 0 — contract
+    // {§strikes-first-party-metadata}). Forwarded as a `Plurnk-Strikes` header ONLY under the
     // same firstPartyMetadata gate as attributions/client; dropped everywhere
     // else. Headers only — the packet NEVER carries strike state (the model must
     // not see engine accounting; it would become a metric to game).
     //
-    // `workspaceId`/`loop`/`turn` (#404, per #391) are the turn COORDINATE — the
+    // `workspaceId`/`loop`/`turn` are the turn coordinate ({§lifecycle-terms}) — the
     // daemon-side sequence of the turn being generated, which the endpoint can
     // never scrape from the wire. Forwarded as `Plurnk-Workspace-Id`/`Plurnk-Loop`/
     // `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>;
-    // The model's context window in tokens. The provider RESOLVES it (operator pin
-    // -> live probe -> @plurnk/plurnk-models catalog). A CLOUD provider (no probe)
-    // FAILS AT CONSTRUCTION when it can't (#419/#417: never budget against a wrong
-    // number). A PROBING provider (openai/llama-server) instead DEGRADES to null on a
-    // probe miss - a blip must not crash it (#34) - and surfaces it once
-    // (PLURNK_CONTEXT_UNKNOWN). So null still means "window unknown -> no cap"; the
-    // consumer must NOT improvise a stand-in from it (#421). NOTE: under llama-server
-    // --parallel N, the window is PER SLOT (the server splits --ctx-size across slots
-    // and reports the divided value).
+    // {§model-fact-resolution} — effective physical context in tokens. `null`
+    // means unknown; under llama-server parallelism the probed value is per slot.
     readonly contextWindow: number | null;
     readonly model: string;
-    // OPTIONAL (#37): the backend's SELF-REPORTED served model id, from a
+    // Optional: the backend's self-reported served model id, from a
     // /v1/models-shaped probe (llama-server today; any such backend). For a local
     // alias, `model` is the alias but this is the real served name (the .gguf) the
     // tokenizer seam maps exactly. Read-only, best-effort, no extra probing —
     // absent when no probe ran. Consumers resolve `servedModel ?? model`.
     readonly servedModel?: string;
-    // OPTIONAL resolved capability (#34): true when a transported grammar will
+    // Optional resolved capability: true when a transported grammar will
     // actually constrain the decode (rails LIVE), false/undefined otherwise —
     // introspectable so the consumer can fail hard on a dark-rails boot instead
     // of discovering it from unconstrained emissions.
     readonly constrainsOutput?: boolean;
-    // OPTIONAL resolved capability (#43): true when this backend decodes
+    // Optional resolved capability: true when this backend decodes
     // UNBOUNDED absent a caller cap — llama-server honors n_predict to the
-    // context wall (the 30,736-junk-token wall-run, providers#10), so a consumer
-    // MUST bring an output envelope (SPEC §13). Cloud backends that silently
+    // context wall (observed in a 30,736-junk-token wall run), so a consumer
+    // MUST bring an output envelope ({§provider-generation-envelope}). Cloud backends that silently
     // clamp an over-ask (fireworks/xai, verified live) never set this; undefined
     // = no claim. Introspectable so a consumer can refuse AT BOOT a local alias
     // with no declared envelope, instead of dying mid-turn in partition math.
     readonly requiresMaxTokens?: boolean;
-    // OPTIONAL generation-envelope reserves (#507, owner-ruled) — the amounts OF
+    // Optional generation-envelope reserves ({§provider-generation-envelope}) — the amounts of
     // the DETECTED 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
@@ -182,22 +240,25 @@ export interface Provider {
     // as null). All first-party providers claim, so null means genuinely-unknown.
     readonly reasoningReserve?: number | null;
     readonly completionReserve?: number | null;
-    // Provider-owned tokenizer. Synchronous, non-negative integer. Without an
-    // exact family configured this is the chars/2 UPPER BOUND (surfaced at
-    // construction, never silent) — safe for refusal math, not an exact count.
-    countTokens(text: string): number;
+    // 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.
+    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.
     // Present ONLY when the backend exposes such an endpoint (probe-gated);
     // `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[]>;
-    // Provider-owned estimated cost calculation. Returns USD.
-    // Returns 0 for siblings/models with no known rates.
+    // {§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 moved to @plurnk/plurnk-aliases (the zero-dep parser, #27);
+// ProviderAlias lives in @plurnk/plurnk-aliases (the zero-dependency parser);
 // index.ts re-exports it so the "." surface is unchanged.
 
 // Per-alias instantiation overrides, threaded from the alias cascade into the
@@ -211,6 +272,6 @@ export interface ProviderOptions {
 
 // A discovered provider plugin default-exports an AI SDK provider. PLURNK owns
 // the adapter into Provider; the plugin owns only its protocol binding.
-export interface AiSdkProviderPlugin {
+export interface AiSdkProviderPlugin extends PluginAttributionSource {
     languageModel(model: string): LanguageModel;
 }

package/src/usage.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { normalizeUsage, calculateCostUsd } from "./usage.ts";
+import { normalizeUsage, calculateCostUsd, calculateCostUsdDecimal } from "./usage.ts";
 
 // — normalizeUsage —
 
@@ -23,7 +23,7 @@ test("normalizeUsage: OpenAI-style — reasoning split out of completion_tokens"
     assert.equal(u.completion + u.reasoning, 100); // billable output unchanged
 });
 
-test("normalizeUsage: xAI/Grok-style — reasoning is ADDITIVE, not subtracted from completion (#28)", () => {
+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({
@@ -48,6 +48,17 @@ test("normalizeUsage: top-level cached_tokens still honored", () => {
     assert.equal(u.cached, 12);
 });
 
+test("#157: normalizeUsage maps DeepSeek's prompt cache hit count", () => {
+    const u = normalizeUsage({
+        prompt_tokens: 50,
+        prompt_cache_hit_tokens: 30,
+        prompt_cache_miss_tokens: 20,
+        completion_tokens: 10,
+        total_tokens: 60,
+    });
+    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 });
@@ -63,9 +74,9 @@ test("normalizeUsage: absent usage → all zeros", () => {
     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 (#425) --
+// -- 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 (#425)", () => {
+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(
@@ -78,7 +89,7 @@ test("normalizeUsage: fireworks folds reasoning into completion -- re-split by t
     assert.equal(u.prompt + u.completion + u.reasoning, u.total); // invariant
 });
 
-test("normalizeUsage: pure-reasoning turn (empty content) attributes all completion to reasoning (#425)", () => {
+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 },
@@ -132,3 +143,11 @@ 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("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",
+    );
+});

package/src/usage.ts

@@ -20,16 +20,39 @@ export type RawUsage = {
     completion_tokens?: number;
     total_tokens?: number;
     cached_tokens?: number;
+    prompt_cache_hit_tokens?: number;
+    prompt_cache_miss_tokens?: number;
     prompt_tokens_details?: { cached_tokens?: number };
     completion_tokens_details?: { reasoning_tokens?: number };
 };
 
+// Some providers return distinct reasoning text while reporting one combined
+// output count. Attribute that count without disturbing an upstream split.
+export const attributeUnitemizedReasoning = (
+    usage: ProviderUsage,
+    reasoningText: string,
+    contentText: string,
+): ProviderUsage => {
+    if (usage.reasoning !== 0 || usage.completion === 0 || reasoningText.length === 0) return usage;
+    const reasoning = contentText.length === 0
+        ? usage.completion
+        : Math.round(usage.completion * reasoningText.length / (reasoningText.length + contentText.length));
+    return {
+        ...usage,
+        completion: usage.completion - reasoning,
+        reasoning,
+    };
+};
+
 export const normalizeUsage = (raw: RawUsage | null | undefined, reasoningText = "", contentText = ""): ProviderUsage => {
     const prompt = raw?.prompt_tokens ?? 0;
     const completionRaw = raw?.completion_tokens ?? 0;
     const reportedTotal = raw?.total_tokens ?? 0;
     // OpenAI nests cached under prompt_tokens_details; others put it top-level.
-    const cached = raw?.prompt_tokens_details?.cached_tokens ?? raw?.cached_tokens ?? 0;
+    const cached = raw?.prompt_tokens_details?.cached_tokens
+        ?? raw?.prompt_cache_hit_tokens
+        ?? raw?.cached_tokens
+        ?? 0;
     const reasoningDetail = raw?.completion_tokens_details?.reasoning_tokens;
 
     let completion: number;
@@ -40,7 +63,7 @@ export const normalizeUsage = (raw: RawUsage | null | undefined, reasoningText =
         // o-series folds it INTO completion_tokens (subset: total = prompt + completion,
         // so completion must have reasoning subtracted out). xAI/Grok reports it
         // ADDITIVE to a visible-only completion_tokens (total = prompt + completion +
-        // reasoning), where subtracting wrongly zeroes the visible output (#28). Tell
+        // reasoning), where subtracting wrongly zeroes the visible output. Tell
         // them apart by the total identity; with no total reported, fall back on the
         // impossible-subset signal — reasoning can't exceed the completion it's a
         // subset of.
@@ -53,34 +76,62 @@ export const normalizeUsage = (raw: RawUsage | null | undefined, reasoningText =
         // reasoning. Only trust the gap when a total was actually reported.
         reasoning = reportedTotal > 0 ? Math.max(0, reportedTotal - prompt - completionRaw) : 0;
         completion = completionRaw;
-        // Fireworks folds reasoning INTO completion_tokens and itemizes no
-        // reasoning_tokens, so a turn that shipped only reasoning reads reasoning=0
-        // though 300k chars of it arrived (#425). When reasoning TEXT came back but
-        // the reported totals leave no gap, re-split the reported completion by the
-        // emitted text proportions. Sum-preserving: billable output
-        // (completion+reasoning) and cost are byte-identical; only the
-        // visible/reasoning gauge is corrected (pure-reasoning turn -> completion 0).
-        if (reasoning === 0 && reasoningText.length > 0 && reportedTotal > 0 && completionRaw > 0) {
-            reasoning = Math.round(completionRaw * reasoningText.length / (reasoningText.length + contentText.length));
-            completion = completionRaw - reasoning;
-        }
     }
     const total = reportedTotal > 0 ? reportedTotal : prompt + completion + reasoning;
-    return { prompt, completion, reasoning, cached, total };
+    const usage = { prompt, completion, reasoning, cached, total };
+    // Fireworks folds reasoning INTO completion_tokens and itemizes no
+    // reasoning_tokens. A reported total establishes that completion is an
+    // upstream quantity rather than a locally synthesized fallback.
+    return reasoningDetail === undefined && reportedTotal > 0
+        ? attributeUnitemizedReasoning(usage, reasoningText, contentText)
+        : usage;
 };
 
 // Conventional provider pricing: USD per million tokens, matching Models.dev.
 export type TokenRates = { input: number; output: number; cached: number };
 
+const decimalParts = (value: number): { coefficient: bigint; scale: number } => {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new TypeError("token rates must be finite non-negative numbers");
+    }
+    const match = /^(\d+)(?:\.(\d+))?(?:e([+-]?\d+))?$/i.exec(String(value));
+    if (match === null) throw new TypeError(`cannot represent token rate ${value} as a decimal`);
+    const fraction = match[2] ?? "";
+    const exponent = Number(match[3] ?? "0");
+    const scale = fraction.length - exponent;
+    const coefficient = BigInt(`${match[1]}${fraction}`);
+    return scale < 0
+        ? { coefficient: coefficient * 10n ** BigInt(-scale), scale: 0 }
+        : { coefficient, scale };
+};
+
+const decimalString = (coefficient: bigint, scale: number): string => {
+    const digits = String(coefficient).padStart(scale + 1, "0");
+    if (scale === 0) return digits;
+    const integer = digits.slice(0, -scale);
+    const fraction = digits.slice(-scale).replace(/0+$/, "");
+    return fraction.length === 0 ? integer : `${integer}.${fraction}`;
+};
+
+// Models.dev rates are decimal USD-per-million values. Calculate their
+// projection as decimal arithmetic so ProviderCost preserves the table and
+// exact response counts without binary floating-point artifacts.
+export const calculateCostUsdDecimal = (usage: ProviderUsage, rates: TokenRates): string => {
+    const parts = [rates.input, rates.cached, rates.output].map(decimalParts);
+    const rateScale = Math.max(...parts.map(({ scale }) => scale));
+    const [input, cached, output] = parts.map(({ coefficient, scale }) =>
+        coefficient * 10n ** BigInt(rateScale - scale));
+    const nonCachedPrompt = Math.max(0, usage.prompt - usage.cached);
+    const outputTokens = usage.completion + usage.reasoning;
+    const coefficient = BigInt(nonCachedPrompt) * input!
+        + BigInt(usage.cached) * cached!
+        + BigInt(outputTokens) * output!;
+    return decimalString(coefficient, rateScale + 6);
+};
+
 // The one cost formula every provider uses: non-cached prompt at the input
 // rate, cached prompt at the cache rate, and billable output (completion +
 // reasoning) at the output rate.
 export const calculateCostUsd = (usage: ProviderUsage, rates: TokenRates): number => {
-    const nonCachedPrompt = Math.max(0, usage.prompt - usage.cached);
-    const output = usage.completion + usage.reasoning;
-    return (
-        nonCachedPrompt * rates.input
-        + usage.cached * rates.cached
-        + output * rates.output
-    ) / 1_000_000;
+    return Number(calculateCostUsdDecimal(usage, rates));
 };

package/src/warnings.test.ts

@@ -4,24 +4,24 @@ import { emitWarningOnce, resetEmittedWarnings } from "./warnings.ts";
 
 test.afterEach(() => { mock.restoreAll(); resetEmittedWarnings(); });
 
-test("#40: same (code, message) fires once per process", () => {
+test("same (code, message) fires once per process", () => {
     const seen: string[] = [];
     mock.method(process, "emitWarning", (msg: string | Error) => { seen.push(String(msg)); });
-    emitWarningOnce("openai provider: heuristic", "PLURNK_TOKENIZER_HEURISTIC");
-    emitWarningOnce("openai provider: heuristic", "PLURNK_TOKENIZER_HEURISTIC");
-    emitWarningOnce("openai provider: heuristic", "PLURNK_TOKENIZER_HEURISTIC");
-    assert.deepEqual(seen, ["openai provider: heuristic"]);
+    emitWarningOnce("openai provider: estimate", "PLURNK_PROMPT_COUNT_ESTIMATE");
+    emitWarningOnce("openai provider: estimate", "PLURNK_PROMPT_COUNT_ESTIMATE");
+    emitWarningOnce("openai provider: estimate", "PLURNK_PROMPT_COUNT_ESTIMATE");
+    assert.deepEqual(seen, ["openai provider: estimate"]);
 });
 
-test("#40: dedup is by (code, MESSAGE), not code — a second provider's surfacing is never suppressed", () => {
+test("dedup is by (code, MESSAGE), not code — a second provider's surfacing is never suppressed", () => {
     const seen: string[] = [];
     mock.method(process, "emitWarning", (msg: string | Error) => { seen.push(String(msg)); });
-    emitWarningOnce("openai provider: heuristic", "PLURNK_TOKENIZER_HEURISTIC");
-    emitWarningOnce("groq provider: heuristic", "PLURNK_TOKENIZER_HEURISTIC"); // same code, different provider
-    assert.deepEqual(seen, ["openai provider: heuristic", "groq provider: heuristic"]);
+    emitWarningOnce("openai provider: estimate", "PLURNK_PROMPT_COUNT_ESTIMATE");
+    emitWarningOnce("groq provider: estimate", "PLURNK_PROMPT_COUNT_ESTIMATE"); // same code, different provider
+    assert.deepEqual(seen, ["openai provider: estimate", "groq provider: estimate"]);
 });
 
-test("#40: resetEmittedWarnings clears the set (test-order independence)", () => {
+test("resetEmittedWarnings clears the set (test-order independence)", () => {
     const seen: string[] = [];
     mock.method(process, "emitWarning", (msg: string | Error) => { seen.push(String(msg)); });
     emitWarningOnce("m", "C");