@plurnk/plurnk-providers 1.16.5 → 1.18.0

package/docs/models.md

@@ -0,0 +1,90 @@
+# Models and generation
+
+Use a catalog route directly, or give it an alias for reusable tuning:
+
+```dotenv
+PLURNK_MODEL_fast=openrouter/qwen/qwen3-coder
+PLURNK_MODEL=fast
+PLURNK_PROVIDERS_REASONING_fast=adaptive
+```
+
+The first route segment is the provider; everything after it is the model id.
+Models.dev supplies cataloged providers' endpoints, credential-variable names,
+model limits, reasoning capabilities, and rates. The operator supplies credentials
+to the service environment. A client's environment does not configure a remote daemon.
+
+## Scope
+
+| Form | Meaning |
+| --- | --- |
+| `PLURNK_MODEL=provider/model` | Select a route without an alias. |
+| `PLURNK_MODEL_<alias>=provider/model` | Declare a named route and tuning scope. |
+| `PLURNK_BASEURL_<alias>=https://endpoint/v1` | Override that declared alias's endpoint. |
+| `PLURNK_PROVIDERS_<KNOB>_<alias>=value` | Nonempty per-alias override of the bare knob; alias case is ignored. |
+| `PLURNK_PROVIDERS_PROVIDER_<NAME>_*` | Provider-wide declaration, not per-alias tuning. |
+
+The [defaults reference](../.env.defaults) lists supported knobs and values.
+Worker model/reasoning selections persist: changing a startup default is not a
+command to retarget existing Workers. Clients expose explicit model, reasoning,
+and child-model controls; their available effort choices come from the selected route.
+
+## Capacity and reasoning
+
+```mermaid
+flowchart TD
+    Limits[Model context and input/output limits] --> Input[Available input capacity]
+    Output[Total output envelope, including reasoning] --> Input
+    Input --> Context[Core's calibrated context allowance]
+    Output --> Reasoning[Optional smaller reasoning budget]
+```
+
+- **Effort** and **budget** are independent. `adaptive` requests native dynamic
+  reasoning where supported, otherwise the supported high posture. Fixed effort
+  names must be supported by the route; an unsupported request is not silently downgraded.
+- **Output** accepts positive tokens or a percentage of context; known model
+  limits cap it. An explicit reasoning budget must be smaller than total output.
+  Leaving the reasoning budget unset does not disable reasoning.
+- **Context** is derived from the live endpoint or catalog. An operator cap can
+  shrink known capacity or declare unknown capacity, never enlarge known limits.
+  Prompt projection and initialization reasoning READ limits are separate Core policy.
+
+## Local OpenAI-compatible endpoints
+
+```dotenv
+PLURNK_MODEL_local=openai/model-name-from-endpoint
+PLURNK_BASEURL_local=http://127.0.0.1:8080/v1
+PLURNK_MODEL=local
+# Optional: your own GBNF grammar, carried verbatim to this llama-server route:
+# PLURNK_PROVIDERS_GBNF_local=~/.config/plurnk/local.gbnf
+# Optional explicit generation allowances, in tokens:
+# PLURNK_PROVIDERS_OUTPUT_BUDGET_local=8192
+# PLURNK_PROVIDERS_REASONING_BUDGET_local=4096
+```
+
+Endpoint probing supplies served-model capacity and llama-server capabilities.
+Pin `PLURNK_PROVIDERS_LLAMA_SERVER_local=1` only for a known llama-server that
+cannot be fingerprinted reliably. GBNF is optional and yours: the service ships
+no grammar profile and never validates or grades one; the file's text reaches
+the route verbatim, and configuring it on a route without grammar transport is
+an error. Parsing always applies.
+
+Sampling stays at endpoint defaults unless configured. Repetition penalties can
+fight exact source copying and grammar repetition. Measure local tuning; it is
+not a portable cloud policy. `think-tags` response interpretation is a separate
+opt-in for endpoints that emit a leading `<think>` envelope, not a reasoning switch.
+
+## Connectivity, caching, and cost
+
+| Concern | Boundary |
+| --- | --- |
+| Attempt, first-content, idle deadlines | Provider transport; a timeout surfaces a failure, not a fabricated response. |
+| Provider-directed waits | Bounded retries honor `Retry-After`; other recoverable failures return to Core. |
+| Loop recovery | Core reissues within its recovery window, then parks for a prompt or wake. |
+| Cache affinity | Stable Worker identity through documented provider controls; not a cache-hit guarantee. |
+| Explicit cache writes | Separate policy on supported routes; can affect billing. |
+| Service tier | Explicit route choice that may change price and availability. |
+| Cost | Provider monetary evidence wins; known usage and catalog rates yield an estimate, not a settled charge. |
+
+For uncataloged compatible endpoints, declare the SDK, URL, and credential-variable
+name together; the examples are in the defaults reference. A provider plugin is
+needed only when the protocol cannot be expressed by the installed adapters.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-providers",
-    "version": "1.16.5",
+    "version": "1.18.0",
     "description": "PLURNK's stable model-provider contract and AI SDK adapter.",
     "keywords": [
         "plurnk",
@@ -54,6 +54,7 @@
         "dist/**/*",
         "README.md",
         "SPEC.md",
+        "docs/**/*.md",
         ".env.defaults"
     ],
     "scripts": {
@@ -84,11 +85,10 @@
         "@ai-sdk/togetherai": "^3.0.0",
         "@ai-sdk/xai": "^4.0.0",
         "@openrouter/ai-sdk-provider": "^3.0.0",
-        "@plurnk/gbnf": "1.16.5",
-        "@plurnk/plurnk-aliases": "1.16.5",
-        "@plurnk/plurnk-contracts": "1.16.5",
-        "@plurnk/plurnk-meta": "1.16.5",
-        "@plurnk/plurnk-models": "1.16.5",
+        "@plurnk/plurnk-aliases": "1.18.0",
+        "@plurnk/plurnk-contracts": "1.18.0",
+        "@plurnk/plurnk-meta": "1.18.0",
+        "@plurnk/plurnk-models": "1.18.0",
         "ai": "^7.0.37",
         "zod": "^4.4.3"
     },

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,
+    });
+});