@plurnk/plurnk-providers 1.16.4 → 1.17.0

package/src/AiSdkProvider.test.ts

@@ -1061,6 +1061,45 @@ test("generate aggregates reasoning deltas under multiple field names", async ()
     assert.equal("reasoningEncrypted" in assistant, false); // open reasoning only -> field absent
 });
 
+for (const style of ["think-tags", "template-think", "template-channel"] as const) test(`{§provider-reasoning-observer} ${style} reasoning arrives while the response is still open`, async () => {
+    const template = style !== "think-tags";
+    const opening = style === "template-channel" ? "<|channel>thought\n" : template ? "<think>\n" : "<think>";
+    const closing = style === "template-channel" ? "<channel|>" : "</think>";
+    const observed: string[] = [];
+    const ready = Promise.withResolvers<void>();
+    let controller!: ReadableStreamDefaultController<Uint8Array>;
+    const send = (text: string, finish: string | null = null): void => controller.enqueue(new TextEncoder().encode(
+        `data: ${JSON.stringify({ id: "paced", object: "chat.completion.chunk", created: 1, model: "m", choices: [{ index: 0, delta: { content: text }, finish_reason: finish }] })}\n\n`,
+    ));
+    const fetch: typeof globalThis.fetch = async () => new Response(new ReadableStream<Uint8Array>({ start(stream) {
+        controller = stream;
+        send(opening.slice(0, 3));
+        send(`${opening.slice(3)}Thinking 🧠${closing.slice(0, 3)}`);
+    } }), { headers: { "Content-Type": "text/event-stream" } });
+    const provider = testProvider({ ...injectedBase, fetch, rawBody: true, ...(template
+        ? { reasoningStyle: "template" as const, grammarStyle: "llamacpp" as const, reasoning: { mode: "adaptive" as const, budget: null } }
+        : { reasoningResponseStyle: "think-tags" as const }) });
+    const result = provider.generate({ workerId: "paced", messages: [], ...(template ? { grammar: 'root ::= "x"' } : {}), observeReasoning(delta) {
+        observed.push(delta);
+        if (observed.join("") === "Thinking 🧠") ready.resolve();
+    } });
+    const timer = setTimeout(() => ready.reject(new Error("reasoning was buffered until response completion")), 1500);
+    try {
+        await ready.promise;
+        assert.deepEqual(observed, ["Thinking 🧠"], "an incomplete closing delimiter is not reasoning text");
+    } finally {
+        clearTimeout(timer);
+        send(`${closing.slice(3)}Answer. <think>literal suffix</think>`, "stop");
+        controller.enqueue(new TextEncoder().encode("data: [DONE]\n\n"));
+        controller.close();
+        const response = await result;
+        assert.equal(response.assistant.reasoning, "Thinking 🧠");
+        assert.equal(response.assistant.content, "Answer. <think>literal suffix</think>");
+        assert.equal(observed.join(""), "Thinking 🧠", "completion does not replay streamed reasoning");
+        if (template) assert.equal(response.grammarEvidence?.input, `${opening}Thinking 🧠${closing}Answer. <think>literal suffix</think>`);
+    }
+});
+
 test("{§provider-tagged-reasoning} explicit think-tags project content without estimating token attribution", async () => {
     const config = { ...injectedBase, reasoningResponseStyle: "think-tags" as const, rawBody: true };
     const p = testProvider(config);
@@ -1089,6 +1128,17 @@ test("{§provider-tagged-reasoning} explicit think-tags project content without
     assert.match(JSON.stringify(response.rawBody), /nk>12345/);
 });
 
+test("{§provider-tagged-reasoning} structured streamed reasoning keeps tagged content literal", async () => {
+    installFetch([{ choices: [{ delta: { content: "<think>literal</think>", reasoning_content: "Native thought." }, finish_reason: "stop" }] }]);
+    const observed: string[] = [];
+    const response = await testProvider({ ...injectedBase, reasoningResponseStyle: "think-tags" }).generate({
+        workerId: "native-control", messages: [], observeReasoning: (delta) => observed.push(delta),
+    });
+    assert.equal(response.assistant.reasoning, "Native thought.");
+    assert.equal(response.assistant.content, "<think>literal</think>");
+    assert.deepEqual(observed, ["Native thought."]);
+});
+
 test("{§provider-tagged-reasoning} explicit think-tags projects one buffered leading envelope", async () => {
     installFetchJson({
         model: "m",
@@ -1201,7 +1251,7 @@ test("{§provider-tagged-reasoning} verbatim, non-leading, and structured-reason
 });
 
 test("{§provider-tagged-reasoning} grammar evidence retains the exact pre-projection tagged sentence", async () => {
-    const content = "<think>🧠reason</think>## PLAN0\n\n### SEND0 (TERM)\ndone";
+    const content = "<think>🧠reason</think>```SEND\ndone\n```\n```TASK\n[{\"content\":\"Task completed.\",\"status\":\"completed\"}]\n```";
     const config = {
         ...injectedBase,
         contextWindow: 640,
@@ -1219,7 +1269,7 @@ test("{§provider-tagged-reasoning} grammar evidence retains the exact pre-proje
     });
 
     assert.equal(response.assistant.reasoning, "🧠reason");
-    assert.equal(response.assistant.content, "## PLAN0\n\n### SEND0 (TERM)\ndone");
+    assert.equal(response.assistant.content, "```SEND\ndone\n```\n```TASK\n[{\"content\":\"Task completed.\",\"status\":\"completed\"}]\n```");
     assert.deepEqual(response.grammarEvidence, {
         input: content,
         contentStart: [..."<think>🧠reason</think>"].length,
@@ -1516,7 +1566,7 @@ test("sampling passthrough guards contract invariants: n/tools/caps stripped, pl
     assert.equal(body.service_tier, "flex");
 });
 
-test("template reasoning returns the exact pre-projection grammar sentence ({§gbnf-response-observation})", async () => {
+test("template reasoning returns the exact pre-projection grammar sentence ({§provider-grammar-evidence})", async () => {
     const p = testProvider({ model: "m", url: "http://x/v1/chat/completions", contextWindow: 640, outputBudget: 224, reasoningBudget: 64, fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: 64 }, retryAttempts: 0, reasoningStyle: "template", grammarStyle: "llamacpp" });
     const grammarInput = "<|channel>thought\ncon🙂sider<channel|>x";
     const calls = installFetch([{ choices: [{ delta: { content: grammarInput } }] }]);
@@ -1724,7 +1774,7 @@ test("grammar transport 'none' (default): the grammar is never sent — no silen
     assert.equal("response_format" in body, false);
 });
 
-// — exact pre-projection grammar evidence ({§gbnf-response-observation}) —
+// — exact pre-projection grammar evidence ({§provider-grammar-evidence}) —
 
 const grammarProvider = () => testProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, grammarStyle: "llamacpp", source: "provider:test" });
 const streamingContent = (content: string) => installFetch([{ choices: [{ delta: { content }, finish_reason: "stop" }] }]);
@@ -1776,39 +1826,24 @@ test("provider evidence does not depend on the local validator understanding the
     assert.equal(res.notices, undefined);
 });
 
-// — PLURNK_PROVIDERS_GBNF_DEBUG: validate the grammar, withhold it, and preserve the observation —
-
-test("gbnfDebug marks an unconstrained observation as not transported", async () => {
-    const p = testProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, grammarStyle: "llamacpp", gbnfDebug: true, source: "provider:test" });
-    const calls = installFetch([{ choices: [{ delta: { content: "ok" }, finish_reason: "stop" }] }]);
-    const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' });
-    const body = JSON.parse(calls[0].init.body as string);
-    assert.equal("grammar" in body, false);
-    assert.equal(body.repeat_penalty, 1.15);
-    assert.equal(res.assistant.content, "ok");
-    assert.deepEqual(res.grammarEvidence, { input: "ok", contentStart: 0, transported: false });
-    assert.equal(res.notices, undefined);
-});
-
-test("gbnfDebug preserves conflicting bytes without a provider verdict", async () => {
-    const p = testProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, grammarStyle: "llamacpp", gbnfDebug: true, source: "provider:test" });
-    const calls = installFetch([{ choices: [{ delta: { content: "xon-conforming output" }, finish_reason: "stop" }] }]);
-    const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' });
-    assert.equal(res.assistant.content, "xon-conforming output");
-    assert.deepEqual(res.grammarEvidence, { input: "xon-conforming output", contentStart: 0, transported: false });
-    assert.equal(res.notices, undefined);
-    const body = JSON.parse(calls[0].init.body as string);
-    assert.equal("grammar" in body, false);
-});
-
-test("gbnfDebug: an INVALID grammar throws before any wire call — it never reaches the model", async () => {
-    const p = testProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, grammarStyle: "llamacpp", gbnfDebug: true });
-    const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
-    await assert.rejects(
-        () => p.generate({ workerId: "r", messages: [], grammar: 'foo ::= "a"' }), // no `root` rule → invalid GBNF
-        /grammar validation \(PLURNK_PROVIDERS_GBNF_DEBUG\): invalid GBNF/,
-    );
-    assert.equal(calls.length, 0); // fail-hard before the fetch — grammar never transported
+// — {§provider-grammar-transport}: the operator's grammar rides a llama-style route verbatim, never another —
+
+test("an operator grammar reaches the request body verbatim under llama style and is absent under every other style", async () => {
+    const grammar = 'root ::= "ok" | "fine"\n# an operator-written rail\n';
+    const styles = ["none", "llamacpp"] as const;
+    for (const grammarStyle of styles) {
+        const calls = installFetchJson({ ...jsonChoice, choices: [{ message: { role: "assistant", content: "ok" }, finish_reason: "stop" }] });
+        const p = testProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, streaming: false, grammarStyle });
+        const res = await p.generate({ workerId: "r", messages: [], grammar });
+        const body = JSON.parse(String(calls[0]!.init.body)) as { grammar?: unknown };
+        if (grammarStyle === "llamacpp") {
+            assert.equal(body.grammar, grammar, "the file's text, byte for byte");
+            assert.deepEqual(res.grammarEvidence, { input: "ok", contentStart: 0, transported: true });
+        } else {
+            assert.equal("grammar" in body, false, "no grammar field on a route without transport");
+            assert.equal(res.grammarEvidence, undefined);
+        }
+    }
 });
 
 // — meta bag: verbatim provider metadata —
@@ -2020,7 +2055,7 @@ test("generate fail-hards on a missing or empty workerId", async () => {
     await assert.rejects(() => (p.generate as (a: object) => Promise<unknown>)({ messages: [] }), /workerId is required/);
 });
 
-test("messages pass through verbatim — the provider injects no turn (PLAN lives in the grammar, never a provider prefill)", async () => {
+test("messages pass through verbatim — the provider injects no turn (turn structure belongs to the grammar, never provider prefill)", async () => {
     const p = testProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
     const calls = installFetch([{ choices: [{ delta: { content: "out" } }] }]);
     const input = [{ role: "user" as const, content: "hi" }];
@@ -2927,3 +2962,29 @@ test("a manual-reasoning model rejects an envelope below its provider minimum be
     );
     assert.equal(calls, 0);
 });
+
+// {§provider-usage-refusal} (#580) — through the provider: the response is delivered, its
+// accounting is an honest unknown, and the refused counters are durable evidence, not a 503.
+test("a response whose usage counters contradict each other is delivered with unknown cost, never retried as a network failure", async () => {
+    const usage = { prompt_tokens: 1, completion_tokens: 5, total_tokens: 6, completion_tokens_details: { reasoning_tokens: 7 } };
+    installFetchJson({
+        id: "response-1", object: "chat.completion", created: 1, model: "served-model",
+        choices: [{ index: 0, message: { role: "assistant", content: "the answer" }, finish_reason: "stop" }],
+        usage,
+    });
+    const p = testProvider({
+        model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 1000, temperature: null, repeatPenalty: null, reasoning: { mode: "off", budget: null }, retryAttempts: 0,
+        streaming: false,
+        estimateCost: (known) => known === undefined
+            ? { kind: "unknown", reason: "the provider response reported no normalized usage" }
+            : { kind: "estimated", amount: { amount: "1", currency: "USD" }, source: "test estimator" },
+    });
+    const response = await p.generate({ workerId: "accounted", messages: [{ role: "user", content: "q" }] });
+    assert.equal(response.assistant.content, "the answer");
+    assert.equal(response.accounting.length, 1);
+    assert.equal(response.accounting[0]?.outcome, "response");
+    assert.equal(response.accounting[0]?.usage, undefined, "no counters are reported as known");
+    assert.deepEqual(response.accounting[0]?.cost, { kind: "unknown", reason: "the provider response reported no normalized usage" });
+    const raw = response.assistantRaw as { usageRefusal?: { reason: string; usage: unknown } };
+    assert.deepEqual(raw.usageRefusal, { reason: "provider usage.outputTokenDetails.textTokens must be a non-negative safe integer", usage }, "the durable response carries the refused counters");
+});

package/src/AiSdkProvider.ts

@@ -27,12 +27,12 @@ import { validateProviderUsage } from "./usage.ts";
 import { assessRequestCapacity, effectiveInputCapacity, effectiveOutputBudget, effectiveReasoningBudget } from "./capacity.ts";
 import { nativeFixedEffort } from "./reasoning-effort.ts";
 import AiSdkRequestBody from "./AiSdkRequestBody.ts";
+import LeadingReasoning from "./LeadingReasoning.ts";
 
 export type ProviderFetch = typeof globalThis.fetch;
 
 // {§provider-connectivity} — an AbortSignal is advisory: a wedged transport that never observes it can
-// hang the await past the deadline (#505). This backstops the deadline the same way an embedding request
-// bounds a wedged adapter (#463): once the signal fires, a well-behaved transport unwinds and settles its
+// hang the await past the deadline (#505). Once the signal fires, a well-behaved transport unwinds and settles its
 // own attempt (and accounting) within a short grace, and that path wins the race untouched; only a
 // transport still wedged after the grace is force-rejected with the signal's own reason, so the existing
 // operation/cancellation classification is unchanged. The grace is unwind slack, not a second deadline.
@@ -125,7 +125,6 @@ export type AiSdkProviderConfig = {
     // Optional provider-configured service tier. Unlike caller sampling, this is
     // a fixed deployment choice and therefore wins on every request.
     serviceTier?: string;
-    gbnfDebug?: boolean;                        // PLURNK_PROVIDERS_GBNF_DEBUG: validate the grammar locally + throw on invalid, but DON'T transport it (run unconstrained); default false
     streaming?: boolean;                        // SSE transport (default true); false → one non-streamed JSON
     firstPartyMetadata?: boolean;              // forward per-turn attributions + client as Plurnk-* headers (plurnk only); default false
     apiKeyRejectedMessage?: string;            // friendly hint when a present key is 401/403-rejected (distinct from unset); default undefined
@@ -239,66 +238,6 @@ const stripTrailingSpecial = (content: string, marker: string): string => {
     return out;
 };
 
-type TaggedReasoningProjection = {
-    readonly content: string;
-    readonly reasoning: string;
-    readonly projected: boolean;
-    readonly contentStart: number;
-};
-
-const projectLeadingReasoning = (
-    content: string,
-    structuredReasoning: string,
-    opening: string,
-    closing: string,
-): TaggedReasoningProjection => {
-    if (structuredReasoning.length > 0 || !content.startsWith(opening)) {
-        return { content, reasoning: structuredReasoning, projected: false, contentStart: 0 };
-    }
-    const closingIndex = content.indexOf(closing, opening.length);
-    if (closingIndex === -1) {
-        return {
-            content: "",
-            reasoning: content.slice(opening.length),
-            projected: true,
-            contentStart: [...content].length,
-        };
-    }
-    const suffixStart = closingIndex + closing.length;
-    return {
-        content: content.slice(suffixStart),
-        reasoning: content.slice(opening.length, closingIndex),
-        projected: true,
-        contentStart: [...content.slice(0, suffixStart)].length,
-    };
-};
-
-// {§provider-tagged-reasoning} Only the model-contract position is structural:
-// one exact leading envelope. Parsing after stream assembly keeps SSE and JSON
-// on one path and leaves later literal tags in the visible suffix untouched.
-const projectTaggedReasoning = (
-    content: string,
-    structuredReasoning: string,
-    style: ReasoningResponseStyle,
-): TaggedReasoningProjection => style === "think-tags"
-    ? projectLeadingReasoning(content, structuredReasoning, "<think>", "</think>")
-    : { content, reasoning: structuredReasoning, projected: false, contentStart: 0 };
-
-// llama-server's template reasoning parser can project either supported leading
-// reasoning envelope out of the OpenAI-compatible response. Grammar evidence
-// needs the sentence before that lossy projection, so constrained template turns
-// request it verbatim and split the observed enclosure here.
-const projectTemplateReasoning = (content: string): TaggedReasoningProjection => {
-    for (const [opening, closing] of [
-        ["<|channel>thought\n", "<channel|>"],
-        ["<think>\n", "</think>"],
-    ] as const) {
-        if (content.startsWith(opening)) return projectLeadingReasoning(content, "", opening, closing);
-    }
-    return { content, reasoning: "", projected: false, contentStart: 0 };
-};
-
-
 const providerWarningMessage = (warning: CallWarning): string => {
     switch (warning.type) {
         case "unsupported":
@@ -356,7 +295,6 @@ export default class AiSdkProvider implements Provider {
     #systemCacheProviderOptions: AiSdkProviderOptions | undefined;
     #reasoningResponseProviderOptions: AiSdkProviderOptions | undefined;
     #serviceTier: string | undefined;
-    #gbnfDebug: boolean;
     #streaming: boolean;
     #firstPartyMetadata: boolean;
     #supportsSlotPinning: boolean;
@@ -479,7 +417,6 @@ export default class AiSdkProvider implements Provider {
             throw new Error(`${this.#source}: reasoning response options conflict with cache-affinity option ${this.#cacheAffinity.provider}.${this.#cacheAffinity.name}`);
         }
         this.#serviceTier = config.serviceTier;
-        this.#gbnfDebug = config.gbnfDebug ?? false;
         this.#streaming = config.streaming ?? true;
         this.#firstPartyMetadata = config.firstPartyMetadata ?? false;
         this.#apiKeyRejectedMessage = config.apiKeyRejectedMessage;
@@ -686,11 +623,10 @@ export default class AiSdkProvider implements Provider {
         // ({§provider-failure-normalization}).
         signal?.throwIfAborted();
 
-        // Grammar handling ({§gbnf-response-observation}). Debug validates the
-        // supplied grammar before the call but withholds it from the backend.
+        // Grammar transport ({§provider-grammar-transport}): an operator's grammar rides a
+        // llama-style route verbatim and is never sent on any other style.
         const wantGrammar = grammar !== undefined && this.#grammarStyle !== "none";
-        if (wantGrammar && this.#gbnfDebug) this.#requestBody.assertGrammarValid(grammar!);
-        const sendGrammar = wantGrammar && !this.#gbnfDebug ? grammar : undefined;
+        const sendGrammar = wantGrammar ? grammar : undefined;
         const preserveGrammarSentence = wantGrammar
             && this.#reasoningStyle === "template";
 
@@ -767,12 +703,25 @@ export default class AiSdkProvider implements Provider {
         let recoveredAfterOutput = false;
         const executeRequest = async () => {
             let requestReasoningStream = "";
+            let structuredReasoning = false;
+            const envelopes = preserveGrammarSentence ? LeadingReasoning.TEMPLATE
+                : this.#reasoningResponseStyle === "think-tags" ? LeadingReasoning.THINK : [];
+            const liveProjection = emitReasoning !== undefined && envelopes.length > 0 ? new LeadingReasoning(envelopes) : undefined;
             const observeRequestReasoning = emitReasoning === undefined
                 ? undefined
                 : (delta: string): void => {
                     requestReasoningStream += delta;
                     emitReasoning(delta);
                 };
+            const observers = {
+                ...(observeRequestReasoning === undefined ? {} : { observeReasoning: (delta: string): void => {
+                    structuredReasoning = true;
+                    observeRequestReasoning(delta);
+                } }),
+                ...(liveProjection === undefined ? {} : { observeText: (delta: string): void => {
+                    if (!structuredReasoning) observeRequestReasoning!(liveProjection.push(delta));
+                } }),
+            };
             let settle: ProviderRequestSettlement | undefined;
             try {
                 settle = await observeRequest?.({
@@ -839,7 +788,7 @@ export default class AiSdkProvider implements Provider {
                         streamIdleTimeoutMs: this.#streamIdleTimeoutMs,
                         streaming: this.#streaming,
                         captureRawBody: this.#rawBody,
-                        ...(observeRequestReasoning === undefined ? {} : { observeReasoning: observeRequestReasoning }),
+                        ...observers,
                     })
                     : await executeAiSdkModel({
                         languageModel: this.#languageModel,
@@ -853,7 +802,7 @@ export default class AiSdkProvider implements Provider {
                         streamIdleTimeoutMs: this.#streamIdleTimeoutMs,
                         streaming: this.#streaming,
                         captureRawBody: this.#rawBody,
-                        ...(observeRequestReasoning === undefined ? {} : { observeReasoning: observeRequestReasoning }),
+                        ...observers,
                         temperature: this.#tuningFloors
                             ? (typeof sampling?.temperature === "number" ? sampling.temperature : this.#temperature ?? undefined)
                             : typeof sampling?.temperature === "number" ? sampling.temperature : undefined,
@@ -887,6 +836,7 @@ export default class AiSdkProvider implements Provider {
                 );
                 throw error;
             }
+            if (!structuredReasoning && liveProjection !== undefined) observeRequestReasoning!(liveProjection.finish());
             successfulReasoningStream = requestReasoningStream;
             await settleAccounting(
                 "response",
@@ -950,13 +900,9 @@ export default class AiSdkProvider implements Provider {
         if (this.#eosText !== undefined) raw.content = stripTrailingSpecial(raw.content, this.#eosText);
 
         const grammarInput = raw.content;
-        const projectedReasoning = preserveGrammarSentence && !raw.reasoningProjected
-            ? projectTemplateReasoning(raw.content)
-            : projectTaggedReasoning(
-                raw.content,
-                raw.reasoning,
-                this.#reasoningResponseStyle,
-            );
+        const projectedReasoning = LeadingReasoning.project(raw.content, raw.reasoning,
+            preserveGrammarSentence && !raw.reasoningProjected ? LeadingReasoning.TEMPLATE
+                : this.#reasoningResponseStyle === "think-tags" ? LeadingReasoning.THINK : []);
 
         // Preserve the exact pre-projection response. Constrained template turns
         // request `reasoning_format: "none"`, so even an empty channel and any

package/src/AiSdkRequestBody.ts

@@ -2,7 +2,6 @@
 import type { ProviderCallKind, ReasoningPolicy } from "./types.ts";
 import type { JSONValue } from "ai";
 import { type Reasoning } from "./env.ts";
-import { validateGbnf } from "@plurnk/gbnf";
 import { fixedEffort } from "./reasoning-effort.ts";
 import type { ReasoningStyle, CompatibleReasoningEffort, GrammarStyle, CacheAffinity, AiSdkProviderOptions } from "./AiSdkProvider.ts";
 
@@ -224,7 +223,7 @@ export default class AiSdkRequestBody {
     // bookkeeping so a long-lived daemon never grows the map unboundedly —
     // an evicted-and-returning run simply re-pins, worst case one cold prefill.
 
-    // Optional local llama-server GBNF transport ({§gbnf-response-observation}). Unsupported
+    // Optional local llama-server GBNF transport ({§provider-grammar-transport}). Unsupported
     // backends receive no grammar-related field.
     grammarBody(grammar: string | undefined): Record<string, unknown> {
         if (grammar === undefined) return {};
@@ -401,19 +400,5 @@ export default class AiSdkRequestBody {
     }
 
 
-    // PLURNK_PROVIDERS_GBNF_DEBUG ({§gbnf-response-observation}): validate the supplied GBNF locally and fail
-    // hard if it's malformed, BEFORE any wire call — and the grammar is NOT
-    // transported, so the request runs unconstrained. A debug aid to catch invalid
-    // grammars (e.g. while editing the plurnk grammar) without a model round-trip;
-    // off in production. `validateGbnf(grammar, "")` parses the grammar + resolves
-    // its root, throwing iff the grammar itself is invalid (the empty input's
-    // verdict is irrelevant — we only care that parsing succeeded).
-    assertGrammarValid(grammar: string): void {
-        try {
-            validateGbnf(grammar, "");
-        } catch (cause) {
-            throw new Error(`grammar validation (PLURNK_PROVIDERS_GBNF_DEBUG): invalid GBNF — ${(cause as Error).message}`, { cause });
-        }
-    }
 
 }

package/src/LeadingReasoning.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import LeadingReasoning from "./LeadingReasoning.ts";
+
+test("{§provider-tagged-reasoning}: every delimiter split preserves exact reasoning and the suffix", () => {
+    for (const envelopes of [LeadingReasoning.THINK, LeadingReasoning.TEMPLATE]) {
+        for (const [opening, closing] of envelopes) {
+            const thought = "Decision 🧠\nA < B.\n";
+            const suffix = "Answer with literal <think>tags</think>.";
+            for (const ended of [true, false]) {
+                const input = `${opening}${thought}${ended ? closing + suffix : closing.slice(0, 3)}`;
+                const expected = thought + (ended ? "" : closing.slice(0, 3));
+                for (let split = 0; split <= input.length; split++) {
+                    const parser = new LeadingReasoning(envelopes);
+                    const observed = parser.push(input.slice(0, split)) + parser.push(input.slice(split)) + parser.finish();
+                    assert.equal(observed, expected, `${opening}: split ${split}`);
+                }
+                const settled = LeadingReasoning.project(input, "", envelopes);
+                assert.equal(settled.reasoning, expected);
+                assert.equal(settled.content, ended ? suffix : "");
+                assert.equal(settled.contentStart, [...input].length - [...settled.content].length);
+            }
+        }
+    }
+});
+
+test("{§provider-tagged-reasoning}: an incomplete opener, later tags, and structured reasoning stay literal", () => {
+    for (const input of ["<thi", " <think>text</think>", "prefix <think>text</think>", ""]) {
+        assert.deepEqual(LeadingReasoning.project(input, "", LeadingReasoning.THINK), { content: input, reasoning: "", projected: false, contentStart: 0 });
+    }
+    assert.deepEqual(LeadingReasoning.project("<think>literal</think>", "native", LeadingReasoning.THINK), {
+        content: "<think>literal</think>", reasoning: "native", projected: false, contentStart: 0,
+    });
+});

package/src/LeadingReasoning.ts

@@ -0,0 +1,87 @@
+export type ReasoningEnvelope = readonly [opening: string, closing: string];
+
+// {§provider-tagged-reasoning} One leading envelope, shared by incremental
+// observation and settled response projection. Only an undecided delimiter is held.
+export default class LeadingReasoning {
+    static readonly THINK: readonly ReasoningEnvelope[] = [["<think>", "</think>"]];
+    static readonly TEMPLATE: readonly ReasoningEnvelope[] = [
+        ["<|channel>thought\n", "<channel|>"],
+        ["<think>\n", "</think>"],
+    ];
+
+    readonly #envelopes: readonly ReasoningEnvelope[];
+    #pending = "";
+    #closing: string | null = null;
+    #closed = false;
+    #projected = false;
+    #reasoning = "";
+    #content = "";
+    #contentStart = 0;
+
+    constructor(envelopes: readonly ReasoningEnvelope[]) {
+        this.#envelopes = envelopes;
+    }
+
+    push(text: string): string {
+        if (this.#closed) {
+            this.#content += text;
+            return "";
+        }
+        this.#pending += text;
+        if (this.#closing === null) {
+            const envelope = this.#envelopes.find(([opening]) => this.#pending.startsWith(opening));
+            if (envelope === undefined) {
+                if (!this.#envelopes.some(([opening]) => opening.startsWith(this.#pending))) {
+                    this.#content = this.#pending;
+                    this.#pending = "";
+                    this.#closed = true;
+                }
+                return "";
+            }
+            const [opening, closing] = envelope;
+            this.#pending = this.#pending.slice(opening.length);
+            this.#closing = closing;
+            this.#projected = true;
+            this.#contentStart = [...opening].length;
+        }
+        const end = this.#pending.indexOf(this.#closing);
+        if (end !== -1) {
+            const delta = this.#emit(this.#pending.slice(0, end));
+            this.#contentStart += [...this.#closing].length;
+            this.#content = this.#pending.slice(end + this.#closing.length);
+            this.#pending = "";
+            this.#closed = true;
+            return delta;
+        }
+        let held = Math.min(this.#pending.length, this.#closing.length - 1);
+        while (held > 0 && !this.#pending.endsWith(this.#closing.slice(0, held))) held--;
+        const split = this.#pending.length - held;
+        const delta = this.#emit(this.#pending.slice(0, split));
+        this.#pending = this.#pending.slice(split);
+        return delta;
+    }
+
+    finish(): string {
+        const delta = this.#projected ? this.#emit(this.#pending) : "";
+        if (!this.#projected) this.#content += this.#pending;
+        this.#pending = "";
+        this.#closed = true;
+        return delta;
+    }
+
+    #emit(delta: string): string {
+        this.#reasoning += delta;
+        this.#contentStart += [...delta].length;
+        return delta;
+    }
+
+    static project(content: string, reasoning: string, envelopes: readonly ReasoningEnvelope[]): {
+        content: string; reasoning: string; projected: boolean; contentStart: number;
+    } {
+        if (reasoning.length > 0) return { content, reasoning, projected: false, contentStart: 0 };
+        const parser = new LeadingReasoning(envelopes);
+        parser.push(content);
+        parser.finish();
+        return { content: parser.#content, reasoning: parser.#reasoning, projected: parser.#projected, contentStart: parser.#contentStart };
+    }
+}

package/src/ProviderRegistry.test.ts

@@ -1,6 +1,22 @@
 import test, { mock } from "node:test";
 import { strict as assert } from "node:assert";
 import { instantiateProvider, loadActiveProvider, resetDiscoveryCache } from "./ProviderRegistry.ts";
+import { resolveModel } from "@plurnk/plurnk-models";
+import { calculateCostUsdDecimal } from "./usage.ts";
+
+// A rate literal breaks at every catalog refresh (the 1.17.0 stamp moved DeepSeek's rates); the
+// claim under test is that the estimate is the catalog's rates applied to the reported usage.
+const catalogRatesOf = (provider: string, model: string) => {
+    const cost = resolveModel(provider, model)?.info.cost;
+    if (cost === undefined) throw new Error(`${provider}/${model} has no catalog rates`);
+    return {
+        input: cost.inputPer1M,
+        output: cost.outputPer1M,
+        ...(cost.reasoningPer1M === undefined ? {} : { reasoning: cost.reasoningPer1M }),
+        ...(cost.cacheReadPer1M === undefined ? {} : { cacheRead: cost.cacheReadPer1M }),
+        ...(cost.cacheWritePer1M === undefined ? {} : { cacheWrite: cost.cacheWritePer1M }),
+    };
+};
 import type { PluginAttributionContext } from "@plurnk/plurnk-meta";
 
 const mapOf = (entries: Record<string, string>, skipped: Record<string, string> = {}) =>
@@ -279,9 +295,11 @@ test("{§deepseek-reasoning-request} #157: direct DeepSeek composes catalog fact
         totalTokens: 12,
         inputTokenDetails: { noCacheTokens: 2, cacheReadTokens: 8 },
     });
+    const expected = calculateCostUsdDecimal(response.accounting[0]!.usage!, catalogRatesOf("deepseek", "deepseek-v4-flash"));
+    assert.match(String(expected), /^0\.0*[1-9]/, "the catalog prices this usage");
     assert.deepEqual(response.accounting[0]?.cost, {
         kind: "estimated",
-        amount: { amount: "0.0000008624", currency: "USD" },
+        amount: { amount: expected, currency: "USD" },
         source: "Models.dev catalog rates",
     });
     mock.restoreAll();

package/src/aiSdkTransport.test.ts

@@ -360,3 +360,59 @@ test("normalizeRetryAttemptError — only provider-directed waits retry: 429, Re
     });
     assert.equal((normalizeRetryAttemptError(bareServerError) as APICallError).isRetryable, false, "a bare 5xx surfaces at once for the engine's recovery");
 });
+
+// {§provider-usage-refusal} (#580) — the provider's counters disagree with themselves; the
+// exchange is not the casualty.
+test("inconsistent usage counters refuse normalization without failing the response, in both shapes", async (t) => {
+    const usage = { prompt_tokens: 1, completion_tokens: 5, total_tokens: 6, completion_tokens_details: { reasoning_tokens: 7 } };
+    await t.test("non-streamed", async () => {
+        const result = await executeOpenAICompatible({
+            ...request,
+            fetch: async () => new Response(JSON.stringify({
+                id: "response-1", object: "chat.completion", created: 1, model: "served-model",
+                choices: [{ index: 0, message: { role: "assistant", content: "answer" }, finish_reason: "stop" }],
+                usage,
+            }), { headers: { "content-type": "application/json" } }),
+        });
+        assert.equal(result.content, "answer", "the model's answer survives the provider's bookkeeping");
+        assert.equal(result.usage, undefined, "no counter is invented, clamped, or zeroed");
+        assert.deepEqual(result.usageRefusal, {
+            reason: "provider usage.outputTokenDetails.textTokens must be a non-negative safe integer",
+            usage,
+        }, "the counters as reported ride beside the refusal");
+        assert.deepEqual(result.chargeEvidence.usage, usage, "charge evidence still carries the wire usage");
+    });
+    await t.test("streamed", async () => {
+        const chunks = [
+            { id: "r", object: "chat.completion.chunk", created: 1, model: "served-model", choices: [{ index: 0, delta: { content: "answer" }, finish_reason: null }] },
+            { id: "r", object: "chat.completion.chunk", created: 1, model: "served-model", choices: [{ index: 0, delta: {}, finish_reason: "stop" }], usage },
+        ];
+        const result = await executeOpenAICompatible({
+            ...request,
+            streaming: true,
+            fetch: async () => new Response(new ReadableStream({
+                start(controller) {
+                    for (const chunk of chunks) controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\n\n`));
+                    controller.enqueue(new TextEncoder().encode("data: [DONE]\n\n"));
+                    controller.close();
+                },
+            }), { headers: { "content-type": "text/event-stream" } }),
+        });
+        assert.equal(result.content, "answer");
+        assert.equal(result.usage, undefined);
+        assert.equal(result.usageRefusal?.reason, "provider usage.outputTokenDetails.textTokens must be a non-negative safe integer");
+        assert.deepEqual(result.usageRefusal?.usage, usage);
+    });
+    await t.test("consistent counters still normalize", async () => {
+        const result = await executeOpenAICompatible({
+            ...request,
+            fetch: async () => new Response(JSON.stringify({
+                id: "response-1", object: "chat.completion", created: 1, model: "served-model",
+                choices: [{ index: 0, message: { role: "assistant", content: "answer" }, finish_reason: "stop" }],
+                usage: { prompt_tokens: 1, completion_tokens: 5, total_tokens: 6, completion_tokens_details: { reasoning_tokens: 2 } },
+            }), { headers: { "content-type": "application/json" } }),
+        });
+        assert.deepEqual(result.usage, { inputTokens: 1, outputTokens: 5, totalTokens: 6, outputTokenDetails: { textTokens: 3, reasoningTokens: 2 } });
+        assert.equal(result.usageRefusal, undefined);
+    });
+});