@plurnk/plurnk-providers 1.2.0 → 1.3.1

package/src/telemetry.test.ts

@@ -0,0 +1,62 @@
+import test from "node:test";
+import { strict as assert } from "node:assert";
+import { ProviderError, classifyProviderError, toProviderError, providerSource } from "./telemetry.ts";
+import { OpenAiHttpError } from "./openaiStream.ts";
+
+// Schema pattern for TelemetryEvent.source (from grammar's TelemetryEvent.json).
+const SOURCE_PATTERN = /^[a-z]+(:[a-z][a-z0-9-]*)?$/;
+
+test("providerSource produces a schema-valid colon-namespaced source", () => {
+    assert.equal(providerSource("openai"), "provider:openai");
+    assert.match(providerSource("openrouter"), SOURCE_PATTERN);
+    assert.match(providerSource("xai"), SOURCE_PATTERN); // contains no underscore — fine
+});
+
+test("classifyProviderError maps HTTP status to kind", () => {
+    const k = (status: number) => classifyProviderError(new OpenAiHttpError(status, "body", null)).kind;
+    assert.equal(k(401), "unauthorized");
+    assert.equal(k(403), "unauthorized");
+    assert.equal(k(402), "quota_exceeded");
+    assert.equal(k(429), "rate_limit");
+    assert.equal(k(500), "network_failure");
+    assert.equal(k(503), "network_failure");
+    assert.equal(k(400), "invalid_response");
+    assert.equal(k(404), "invalid_response");
+});
+
+test("classifyProviderError: a 422 flagged grammar_invalid is transient (#548); other 422s terminal", () => {
+    const rejected = new OpenAiHttpError(422, JSON.stringify({ error: { type: "grammar_invalid", message: "non-conforming emission rejected: ..." } }), null);
+    assert.equal(classifyProviderError(rejected).kind, "grammar_invalid");
+    // a 422 carrying any other error.type is a malformed request — terminal
+    assert.equal(classifyProviderError(new OpenAiHttpError(422, JSON.stringify({ error: { type: "invalid_request_error" } }), null)).kind, "invalid_response");
+    // a non-JSON 422 body (edge/proxy HTML) is terminal, and the sniff does not throw
+    assert.equal(classifyProviderError(new OpenAiHttpError(422, "<html>Bad</html>", null)).kind, "invalid_response");
+});
+
+test("classifyProviderError treats non-HTTP errors as network_failure", () => {
+    assert.equal(classifyProviderError(new TypeError("fetch failed")).kind, "network_failure");
+    const timeout = Object.assign(new Error("timed out"), { name: "TimeoutError" });
+    assert.equal(classifyProviderError(timeout).kind, "network_failure");
+});
+
+test("ProviderError.toTelemetryEvent emits the canonical envelope", () => {
+    const e = new ProviderError("provider:openai", "rate_limit", "OpenAI 429 - slow down", { status: 429 });
+    const ev = e.toTelemetryEvent();
+    assert.deepEqual(ev, { source: "provider:openai", kind: "rate_limit", message: "OpenAI 429 - slow down", position: null });
+    assert.match(ev.source, SOURCE_PATTERN);
+    assert.ok(e instanceof Error);   // still catchable as a plain Error
+    assert.equal(e.status, 429);
+});
+
+test("toProviderError classifies and tags an HTTP error with the source + status", () => {
+    const pe = toProviderError(new OpenAiHttpError(401, "no key", null), "provider:groq");
+    assert.equal(pe.kind, "unauthorized");
+    assert.equal(pe.source, "provider:groq");
+    assert.equal(pe.status, 401);
+    assert.equal(pe.cause instanceof OpenAiHttpError, true); // original preserved
+});
+
+test("toProviderError passes an existing ProviderError through unchanged", () => {
+    const original = new ProviderError("provider:xai", "rate_limit", "429");
+    assert.equal(toProviderError(original, "provider:other"), original);
+});

package/src/telemetry.ts

@@ -0,0 +1,108 @@
+// Provider telemetry — the TelemetryEvent envelope for transport failures.
+//
+// TelemetryEvent is plurnk's cross-ecosystem error envelope (canonical schema:
+// @plurnk/plurnk-grammar's schemas.plurnk.dev/v0/TelemetryEvent.json). It is
+// mirrored here STRUCTURALLY rather than imported, so the framework keeps zero
+// dependency on grammar (see SPEC §11). Consumers route provider events through
+// the same `source` + `kind` discriminator as parse/rail events.
+
+import { OpenAiHttpError } from "./openaiStream.ts";
+
+// Required by the schema: source (producer id) + kind (discriminator). message
+// and position are optional. A transport failure isn't localizable, so it carries
+// a null position; a `grammar_unenforced` event (#24) carries the divergence
+// code-point offset into the model's emission, so the consumer can render a
+// snippet around it — same recovery affordance the consumer already gives DSL
+// parse errors.
+export type TelemetryEvent = {
+    source: string;            // e.g. "provider:openai" — schema pattern ^[a-z]+(:[a-z][a-z0-9-]*)?$
+    kind: string;              // open vocabulary; providers mint from ProviderTelemetryKind
+    message?: string | null;
+    position?: number | null;
+};
+
+// The kinds plurnk-service routes provider failures on.
+export type ProviderTelemetryKind =
+    | "rate_limit"
+    | "network_failure"
+    | "model_refused"
+    | "invalid_response"
+    | "unauthorized"
+    | "quota_exceeded"
+    // A 422 whose error.type is "grammar_invalid" (#548): the backend served ONE
+    // generation and rejected it as non-conforming. Transient, not terminal — a
+    // fresh sample may conform — so it rides the retry budget. Distinct from
+    // grammar_unenforced below: that observes a SUCCEEDED exchange; this is a
+    // thrown transport failure the daemon retries, then fails as a leaf.
+    | "grammar_invalid"
+    // Output did not conform to the GBNF. ALWAYS an observation, never a throw:
+    // a completed exchange returns its bytes with this event on
+    // response.telemetry (message + divergence position), whether the grammar
+    // was transported or withheld (filter mode). Discard/retry/escalate is
+    // consumer policy (#24, SPEC §13).
+    | "grammar_unenforced";
+
+// Build a provider source label (`provider:<vendor>`), schema-pattern-valid.
+export const providerSource = (vendor: string): string => `provider:${vendor}`;
+
+// A transport failure carrying its TelemetryEvent classification. IS-an Error
+// (existing catchers keep working); telemetry-aware consumers call
+// toTelemetryEvent() and route on source+kind.
+export class ProviderError extends Error {
+    readonly source: string;
+    readonly kind: ProviderTelemetryKind;
+    readonly status: number | null;
+
+    constructor(source: string, kind: ProviderTelemetryKind, message: string, options: { status?: number | null; cause?: unknown } = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "ProviderError";
+        this.source = source;
+        this.kind = kind;
+        this.status = options.status ?? null;
+    }
+
+    toTelemetryEvent(): TelemetryEvent {
+        return { source: this.source, kind: this.kind, message: this.message, position: null };
+    }
+}
+
+// An OpenAI-shaped error body carries error.type. null when the body is absent,
+// non-JSON (a proxy/CDN HTML page), or unshaped — none of which is a match.
+const wireErrorType = (body: string): string | null => {
+    try {
+        const { error } = JSON.parse(body) as { error?: { type?: unknown } };
+        return typeof error?.type === "string" ? error.type : null;
+    } catch {
+        return null;
+    }
+};
+
+// Map a thrown transport error to a (kind, message). Conservative; the message
+// is factual, no guidance prose (consumer SPEC §15.1 policy).
+export const classifyProviderError = (err: unknown): { kind: ProviderTelemetryKind; message: string } => {
+    if (err instanceof OpenAiHttpError) {
+        const { status, message } = err;
+        if (status === 401 || status === 403) return { kind: "unauthorized", message };
+        if (status === 402) return { kind: "quota_exceeded", message };
+        if (status === 429) return { kind: "rate_limit", message };
+        if (status >= 500) return { kind: "network_failure", message };
+        // A 422 flagged grammar_invalid is a stochastic output reject (#548) — one
+        // generation served then rejected, so a fresh sample may conform: transient.
+        // Any other 422 is a malformed request: terminal (invalid_response).
+        if (status === 422 && wireErrorType(err.body) === "grammar_invalid") return { kind: "grammar_invalid", message };
+        return { kind: "invalid_response", message };
+    }
+    const e = err as { name?: string; message?: string };
+    const message = (e?.message ?? String(err)) || "request failed";
+    // Timeouts / fetch-level failures are transport, not a usable response.
+    return { kind: "network_failure", message };
+};
+
+// Wrap any thrown error as a ProviderError tagged with this provider's source.
+// Already-classified errors pass through unchanged.
+export const toProviderError = (err: unknown, source: string): ProviderError => {
+    if (err instanceof ProviderError) return err;
+    const { kind, message } = classifyProviderError(err);
+    const status = err instanceof OpenAiHttpError ? err.status : null;
+    return new ProviderError(source, kind, message, { status, cause: err });
+};

package/src/types.ts

@@ -0,0 +1,219 @@
+// Provider transport contract. Providers return raw wire-level output —
+// content unparsed (consumer parses via @plurnk/plurnk-grammar), reasoning
+// is the wire-reported CoT only.
+
+import type { TelemetryEvent } from "./telemetry.ts";
+
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: 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
+}
+
+// Closed set per SPEC §2. Relay/aggregator providers MUST normalize wire
+// values back to one of these at the provider boundary.
+export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | null;
+
+// A per-token logprob (#36, SPEC §14). `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
+// model belief and the correct distillation target). `top` carries the top-N
+// alternatives when top_logprobs was requested. The verbatim per-token record
+// (sampling_logprob, token_id, bytes, mask fields) survives on
+// ProviderResponse.rawBody — this structured view is the canonical signal only.
+export interface TokenAlternative {
+    readonly token: string;
+    readonly logprob: number;
+}
+export interface TokenLogprob {
+    readonly token: string;
+    readonly logprob: number;
+    readonly top?: readonly TokenAlternative[];
+}
+
+export interface ProviderAssistant {
+    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 }> }>;
+    readonly usage: ProviderUsage;
+    readonly finishReason: FinishReason;
+    readonly model: string;
+    // Per-token logprobs (#36), 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[];
+    // Convenience: mean of logprobs[].logprob (natural log). Absent when logprobs is.
+    readonly meanLogprob?: number;
+}
+
+export interface ProviderResponse {
+    readonly assistant: ProviderAssistant;
+    readonly assistantRaw: unknown;
+    // Per-turn provider→client metadata bag: the backend's non-standard top-level
+    // response fields, passed through verbatim, PLUS validated known keys we hold a
+    // contract for (e.g. `balancePico` — a finite pico-USD number, from the plurnk
+    // endpoint). 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).
+    readonly meta?: Record<string, unknown>;
+    // The VERBATIM backend response body (#36, SPEC §14) — 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[];
+}
+
+export interface Provider {
+    // `grammar` is an optional GBNF string (canonically @plurnk/plurnk-grammar's
+    // 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).
+    //
+    // `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),
+    // so a constrained consumer is expected to pass it. Policy stays the
+    // consumer's; the provider only transports.
+    //
+    // `workerId` is the REQUIRED, opaque, stable identity of the consumer's work
+    // 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).
+    //
+    // `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.
+    //
+    // `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
+    // 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
+    // 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
+    // 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).
+    readonly contextWindow: number | null;
+    readonly model: string;
+    // OPTIONAL (#37): 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
+    // 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
+    // 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
+    // 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
+    // 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
+    // - completionReserve - <its own packing-safety margin>`; the generation cap
+    // is the two pooled. `null` = underivable (window unknown, no absolute pin) →
+    // the consumer's no-cap path. Absent = a bare sibling makes NO claim (treated
+    // 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;
+    // 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 cost calculation. Returns pico-USD (1e-12 USD).
+    // Returns 0 for siblings/models with no known rates.
+    costFor(usage: ProviderUsage): number;
+}
+
+// ProviderAlias moved to @plurnk/plurnk-aliases (the zero-dep parser, #27);
+// index.ts re-exports it so the "." surface is unchanged.
+
+// Per-alias instantiation overrides, threaded from the alias cascade into the
+// factory. `baseUrl` lets two aliases on the SAME provider name (openai, ollama)
+// target DIFFERENT endpoints — the only way to run N self-hosted boxes, since the
+// provider's own base-URL env var binds one URL per name. Absent → the provider
+// resolves its base from its env var as before.
+export interface ProviderOptions {
+    readonly baseUrl?: string;
+}
+
+// Each provider package's default export MUST be a factory:
+//   static fromEnv(env, model, options?) → Provider | Promise<Provider>
+// `model` is the second positional arg because PLURNK_MODEL_<alias>=<provider>/<model>
+// is parsed by the registry; the resolved model id flows through. `options` is an
+// optional third arg (per-alias overrides, e.g. baseUrl); a factory that ignores
+// it keeps working unchanged.
+export interface ProviderFactory {
+    fromEnv(env: NodeJS.ProcessEnv, model: string, options?: ProviderOptions): Provider | Promise<Provider>;
+}

package/src/usage.test.ts

@@ -0,0 +1,136 @@
+import test from "node:test";
+import { strict as assert } from "node:assert";
+import { normalizeUsage, computeCost } 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: OpenAI-style — reasoning split out of completion_tokens", () => {
+    // completion_tokens includes reasoning; total = prompt + completion.
+    const u = 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
+});
+
+test("normalizeUsage: xAI/Grok-style — reasoning is ADDITIVE, not subtracted from completion (#28)", () => {
+    // Real grok-4.3 shape: completion_tokens is visible-only; reasoning_tokens is
+    // detailed but ADDITIVE — total = prompt + completion + reasoning.
+    const u = 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);
+});
+
+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: 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 (#425) --
+
+test("normalizeUsage: fireworks folds reasoning into completion -- re-split by text proportion, sum preserved (#425)", () => {
+    // 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 (#425)", () => {
+    // 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 });
+});
+
+// — computeCost —
+
+test("computeCost: bills reasoning at the output rate", () => {
+    // 100 input, 0 cached, 50 completion + 200 reasoning = 250 output.
+    const usage = { prompt: 100, completion: 50, reasoning: 200, cached: 0, total: 350 };
+    // input 1 pico/tok, output 10 pico/tok → 100*1 + 250*10 = 2600
+    assert.equal(computeCost(usage, { input: 1, output: 10, cached: 0 }), 2600);
+});
+
+test("computeCost: cached prompt billed at the cache rate, remainder at input", () => {
+    const usage = { prompt: 1000, completion: 0, reasoning: 0, cached: 400, total: 1000 };
+    // 600 non-cached @5 + 400 cached @1 = 3000 + 400 = 3400
+    assert.equal(computeCost(usage, { input: 5, output: 99, cached: 1 }), 3400);
+});
+
+test("computeCost: zero rates → 0", () => {
+    const usage = { prompt: 9, completion: 9, reasoning: 9, cached: 9, total: 27 };
+    assert.equal(computeCost(usage, { input: 0, output: 0, cached: 0 }), 0);
+});

package/src/usage.ts

@@ -0,0 +1,82 @@
+// Usage normalization + cost — the shared token-accounting model.
+//
+// Providers report token usage in two incompatible ways:
+//   - OpenAI-style: reasoning is a SUBSET of completion_tokens, surfaced via
+//     completion_tokens_details.reasoning_tokens; total = prompt + completion.
+//   - Gemini-style: reasoning is OMITTED from completion_tokens and only
+//     recoverable as total - prompt - completion (no details field at all).
+//   - Fireworks-style: reasoning ships as TEXT (reasoning_content) but is folded
+//     into completion_tokens with NO reasoning_tokens itemization -- unrecoverable
+//     from the numbers alone, so it is re-split from the emitted text lengths.
+// normalizeUsage collapses all three into one invariant (see ProviderUsage):
+//   total = prompt + completion + reasoning;  cached ⊆ prompt;
+//   completion EXCLUDES reasoning;  billable output = completion + reasoning.
+
+import type { ProviderUsage } from "./types.ts";
+
+// Raw OpenAI-compatible usage block — the superset of fields providers emit.
+export type RawUsage = {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    cached_tokens?: number;
+    prompt_tokens_details?: { cached_tokens?: number };
+    completion_tokens_details?: { reasoning_tokens?: number };
+};
+
+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 reasoningDetail = raw?.completion_tokens_details?.reasoning_tokens;
+
+    let completion: number;
+    let reasoning: number;
+    if (reasoningDetail !== undefined) {
+        reasoning = reasoningDetail;
+        // reasoning_tokens is reported two incompatible ways when detailed. OpenAI
+        // 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
+        // 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.
+        const additive = reportedTotal > 0
+            ? reportedTotal === prompt + completionRaw + reasoningDetail
+            : completionRaw < reasoningDetail;
+        completion = additive ? completionRaw : Math.max(0, completionRaw - reasoningDetail);
+    } else {
+        // Gemini-style (or no reasoning): tokens beyond prompt+completion are
+        // 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 };
+};
+
+// Per-token rates in pico-USD (1e-12 USD).
+export type TokenRates = { input: number; output: number; cached: number };
+
+// 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 computeCost = (usage: ProviderUsage, rates: TokenRates): number => {
+    const nonCachedPrompt = Math.max(0, usage.prompt - usage.cached);
+    const output = usage.completion + usage.reasoning;
+    return Math.round(nonCachedPrompt * rates.input + usage.cached * rates.cached + output * rates.output);
+};

package/src/warnings.test.ts

@@ -0,0 +1,31 @@
+import test, { mock } from "node:test";
+import { strict as assert } from "node:assert";
+import { emitWarningOnce, resetEmittedWarnings } from "./warnings.ts";
+
+test.afterEach(() => { mock.restoreAll(); resetEmittedWarnings(); });
+
+test("#40: 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"]);
+});
+
+test("#40: 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"]);
+});
+
+test("#40: resetEmittedWarnings clears the set (test-order independence)", () => {
+    const seen: string[] = [];
+    mock.method(process, "emitWarning", (msg: string | Error) => { seen.push(String(msg)); });
+    emitWarningOnce("m", "C");
+    resetEmittedWarnings();
+    emitWarningOnce("m", "C");
+    assert.equal(seen.length, 2);
+});