@plurnk/plurnk-providers 1.7.0 → 1.8.0

package/src/AiSdkProvider.ts

@@ -20,11 +20,13 @@ import type {
     ProviderRequestSettlement,
     ProviderResponse,
     ProviderUsage,
+    ReasoningPolicy,
 } from "./types.ts";
 import type { ProviderCost } from "@plurnk/plurnk-contracts";
-import type { JSONValue } from "ai";
-import { MAX_PROVIDER_TIMEOUT_MS } from "./env.ts";
-import type { Reasoning, ReasoningResponseStyle } from "./env.ts";
+import { REASONING_POLICIES } from "@plurnk/plurnk-contracts";
+import type { CallWarning, JSONValue } from "ai";
+import { MAX_PROVIDER_TIMEOUT_MS, type Reasoning, type ReasoningResponseStyle } from "./env.ts";
+import { UnsupportedReasoningPolicyError } from "./types.ts";
 import {
     executeAiSdkModel,
     executeOpenAICompatible,
@@ -59,6 +61,25 @@ export type CacheAffinity =
 
 export type AiSdkProviderOptions = Record<string, Record<string, JSONValue | undefined>>;
 
+const isJsonObject = (value: JSONValue | undefined): value is Record<string, JSONValue> =>
+    typeof value === "object" && value !== null && !Array.isArray(value);
+
+const mergeJsonObjects = (
+    left: Record<string, JSONValue | undefined>,
+    right: Record<string, JSONValue | undefined>,
+): Record<string, JSONValue | undefined> => Object.fromEntries(
+    [...new Set([...Object.keys(left), ...Object.keys(right)])].map((key) => {
+        const leftValue = left[key];
+        const rightValue = right[key];
+        return [
+            key,
+            isJsonObject(leftValue) && isJsonObject(rightValue)
+                ? mergeJsonObjects(leftValue, rightValue)
+                : rightValue ?? leftValue,
+        ];
+    }),
+);
+
 export type AiSdkProviderConfig = {
     model: string;
     url?: string;                             // OpenAI-compatible chat-completions URL
@@ -75,6 +96,11 @@ export type AiSdkProviderConfig = {
     maxOutputTokens?: number | null;
     outputBudget?: number | null;
     reasoningBudget?: number | null;
+    supportedReasoningPolicies?: readonly ReasoningPolicy[];
+    // Native AI SDK projection for adaptive. `high` is the graded fallback;
+    // provider-default is reserved for a documented native option/default.
+    adaptiveReasoning?: "high" | "provider-default";
+    adaptiveReasoningProviderOptions?: AiSdkProviderOptions;
     // Native Anthropic and Bedrock SDKs interpret generic maxOutputTokens as
     // visible output and add an explicit provider reasoning budget. This marker lets the
     // adapter subtract that subset so the resulting wire cap remains PLURNK's
@@ -125,7 +151,7 @@ export type AiSdkProviderConfig = {
     requiresOutputBudget?: boolean;
     // The side-channel reasoning intent — REQUIRED, no in-code default
     // (PLURNK_PROVIDERS_REASONING + _BUDGET, read via reasoningFromEnv):
-    // { mode: off|adaptive|on, budget: optional when on }. The provider maps it
+    // { mode: off|adaptive|low|medium|high, budget: independent optional cap }.
     // to the backend's mechanism via reasoningStyle; budget is only ever an
     // explicit magnitude, never a hidden activation flag.
     reasoning: Reasoning;
@@ -265,19 +291,32 @@ const projectTemplateReasoning = (content: string): TaggedReasoningProjection =>
     return { content, reasoning: "", projected: false, contentStart: 0 };
 };
 
-// Shared budget→effort breakpoints (xai and google had identical copies).
-export const effortFromBudget = (budget: number): "low" | "medium" | "high" => {
-    if (budget <= 1000) return "low";
-    if (budget <= 4000) return "medium";
-    return "high";
+const fixedEffort = (mode: ReasoningPolicy): "low" | "medium" | "high" => {
+    if (mode === "low" || mode === "medium" || mode === "high") return mode;
+    throw new TypeError(`reasoning policy '${mode}' is not a fixed effort`);
 };
 
-// AI SDK's portable reasoning control has no boolean-enabled value. `medium`
-// is the neutral activation projection for an explicit, unqualified `on`; it
-// changes no PLURNK output budget. An operator reasoning subset, when present, remains
-// the only input to the existing magnitude-to-tier projection.
-const effortFromReasoning = (reasoning: Reasoning): "low" | "medium" | "high" =>
-    reasoning.budget === null ? "medium" : effortFromBudget(reasoning.budget);
+// Anthropic's older manual-reasoning protocol needs an absolute allowance while
+// PLURNK's durable contract names an effort. These fractions match the native
+// SDK's policy projection, but apply to PLURNK's total envelope rather than the
+// model's physical maximum. The minimum is imposed by the provider protocol.
+const MANUAL_REASONING_FRACTIONS = Object.freeze({
+    adaptive: 0.6,
+    low: 0.1,
+    medium: 0.3,
+    high: 0.6,
+} satisfies Record<Exclude<ReasoningPolicy, "off">, number>);
+const MANUAL_REASONING_MINIMUM = 1024;
+
+const providerWarningMessage = (warning: CallWarning): string => {
+    switch (warning.type) {
+        case "unsupported":
+        case "compatibility":
+            return `${warning.type} ${warning.feature}${warning.details === undefined ? "" : `: ${warning.details}`}`;
+        case "deprecated": return `deprecated ${warning.setting}: ${warning.message}`;
+        case "other": return warning.message;
+    }
+};
 
 // Body keys the provider owns — a caller's `sampling` passthrough may not set
 // these. Two families:
@@ -321,6 +360,9 @@ export default class AiSdkProvider implements Provider {
     #reasoningBudget: number | null;
     #additiveReasoningProvider: "anthropic" | "bedrock" | undefined;
     #reasoning: Reasoning;
+    #supportedReasoningPolicies: readonly ReasoningPolicy[];
+    #adaptiveReasoning: "high" | "provider-default";
+    #adaptiveReasoningProviderOptions: AiSdkProviderOptions | undefined;
     #temperature: number;
     #repeatPenalty: number;
     #frequencyPenalty: number;
@@ -390,6 +432,18 @@ export default class AiSdkProvider implements Provider {
         this.#reasoningBudget = config.reasoningBudget ?? null;
         this.#additiveReasoningProvider = config.additiveReasoningProvider;
         this.#reasoning = config.reasoning;
+        this.#supportedReasoningPolicies = Object.freeze([
+            ...new Set(config.supportedReasoningPolicies ?? REASONING_POLICIES),
+        ]);
+        this.#adaptiveReasoning = config.adaptiveReasoning ?? "high";
+        this.#adaptiveReasoningProviderOptions = config.adaptiveReasoningProviderOptions;
+        if (!this.#supportedReasoningPolicies.includes(this.#reasoning.mode)) {
+            throw new UnsupportedReasoningPolicyError(
+                config.source ?? "provider",
+                this.#reasoning.mode,
+                this.#supportedReasoningPolicies,
+            );
+        }
         // Loud guard: an out-of-date consumer (stale plugin dist) omitting the
         // required tuning fields must fail at construction, not silently send
         // undefined sampling on every grammar request.
@@ -435,6 +489,9 @@ export default class AiSdkProvider implements Provider {
         if (this.#languageModel === undefined && this.#reasoningResponseProviderOptions !== undefined) {
             throw new Error(`${this.#source}: reasoning response provider options require an AI SDK model`);
         }
+        if (this.#languageModel === undefined && this.#additiveReasoningProvider !== undefined) {
+            throw new Error(`${this.#source}: additive reasoning projection requires an AI SDK model`);
+        }
         if (this.#cacheAffinity?.target === "provider-option"
             && Object.hasOwn(
                 this.#reasoningResponseProviderOptions?.[this.#cacheAffinity.provider] ?? {},
@@ -476,16 +533,12 @@ export default class AiSdkProvider implements Provider {
             throw new Error(`${this.#source}: reasoning intent and generation envelope disagree on reasoningBudget`);
         }
         if (this.#reasoningStyle === "anthropic"
-            && this.#reasoning.mode === "on"
+            && this.#reasoning.mode !== "off"
+            && this.#reasoning.mode !== "adaptive"
             && this.#reasoning.budget === null
             && this.#reasoningBudget === null) {
             throw new Error(`${this.#source}: explicit Anthropic reasoning requires PLURNK_PROVIDERS_REASONING_BUDGET`);
         }
-        if (this.#additiveReasoningProvider !== undefined
-            && this.#reasoning.mode === "on"
-            && this.#reasoningBudget === null) {
-            throw new Error(`${this.#source}: explicit ${this.#additiveReasoningProvider} reasoning requires PLURNK_PROVIDERS_REASONING_BUDGET so the total output budget remains bounded`);
-        }
         if (this.#requiresOutputBudget === true && this.#outputBudget === null) {
             throw new Error(`${this.#source}: this backend requires a resolved PLURNK_PROVIDERS_OUTPUT_BUDGET`);
         }
@@ -515,6 +568,7 @@ export default class AiSdkProvider implements Provider {
     get maxOutputTokens(): number | null { return this.#maxOutputTokens; }
     get outputBudget(): number | null { return this.#outputBudget; }
     get reasoningBudget(): number | null { return this.#reasoningBudget; }
+    get supportedReasoningPolicies(): readonly ReasoningPolicy[] { return this.#supportedReasoningPolicies; }
     get inputCapacity(): number | null {
         return effectiveInputCapacity({
             contextWindow: this.#contextWindow,
@@ -628,7 +682,7 @@ export default class AiSdkProvider implements Provider {
             case "template": {
                 const allowance = mode === "off"
                     ? 0
-                    : mode === "on" && budget !== null ? budget : this.#reasoningBudget;
+                    : budget;
                 return {
                     chat_template_kwargs: { enable_thinking: on },
                     reasoning_format: preserveGrammarSentence ? "none" : "auto",
@@ -637,9 +691,9 @@ export default class AiSdkProvider implements Provider {
             }
             case "think": return on ? { think: true } : {};
             case "include_reasoning": return on ? { include_reasoning: true } : {};
-            // Explicit on uses the portable enabled posture or a tier derived
-            // from an explicit budget; off/adaptive omit the field.
-            case "effort": return mode === "on" ? { reasoning_effort: effortFromReasoning({ mode, budget }) } : {};
+            case "effort": return mode === "off"
+                ? {}
+                : { reasoning_effort: mode === "adaptive" ? "high" : fixedEffort(mode) };
             // Fireworks enum: OFF is sent EXPLICITLY ("none") — omission leaves a
             // reason-by-default model (DeepSeek V4: default 'high') reasoning.
             // ADAPTIVE omits the field: the backend's own default posture IS the
@@ -649,25 +703,23 @@ export default class AiSdkProvider implements Provider {
             // efforts 400.
             case "effort_explicit": return mode === "off"
                 ? { reasoning_effort: "none" }
-                : mode === "on" ? { reasoning_effort: effortFromReasoning({ mode, budget }) } : {};
+                : mode === "adaptive" ? {} : { reasoning_effort: fixedEffort(mode) };
             // {§deepseek-reasoning-request}
             case "thinking_effort": return mode === "off"
                 ? { thinking: { type: "disabled" } }
-                : mode === "on" ? {
+                : mode === "adaptive" ? { thinking: { type: "enabled" } } : {
                     thinking: { type: "enabled" },
-                    ...(budget === null ? {} : { reasoning_effort: effortFromBudget(budget) }),
-                } : {};
-            // Anthropic compat: explicit thinking object. off → disabled; on →
-            // enabled with the explicit reasoning subset; adaptive →
-            // omit (the API default).
+                    reasoning_effort: fixedEffort(mode),
+                };
+            // Anthropic-compatible native dynamic or manual budget mode.
             case "anthropic": return mode === "off"
                 ? { thinking: { type: "disabled" } }
-                : mode === "on" ? {
+                : mode === "adaptive" ? { thinking: { type: "adaptive" } } : {
                     thinking: {
                         type: "enabled",
                         budget_tokens: budget!,
                     },
-                } : {};
+                };
             case "none": return {};
         }
     }
@@ -809,22 +861,26 @@ export default class AiSdkProvider implements Provider {
 
     #requestProviderOptions(
         workerId: string,
-        reasoningBudget: number | null,
+        nativeReasoningBudget: number | null,
     ): AiSdkProviderOptions | undefined {
         const responseOptions = this.#reasoning.mode === "off"
             ? undefined
             : this.#reasoningResponseProviderOptions;
-        const nativeReasoning = this.#reasoning.mode === "on" && reasoningBudget !== null
+        const adaptiveOptions = this.#reasoning.mode === "adaptive"
+            && nativeReasoningBudget === null
+            ? this.#adaptiveReasoningProviderOptions
+            : undefined;
+        const nativeReasoning = nativeReasoningBudget !== null
             ? this.#additiveReasoningProvider === "anthropic"
-                ? { anthropic: { thinking: { type: "enabled", budgetTokens: reasoningBudget } } }
+                ? { anthropic: { thinking: { type: "enabled", budgetTokens: nativeReasoningBudget } } }
                 : this.#additiveReasoningProvider === "bedrock"
-                    ? { bedrock: { reasoningConfig: { type: "enabled", budgetTokens: reasoningBudget } } }
+                    ? { bedrock: { reasoningConfig: { type: "enabled", budgetTokens: nativeReasoningBudget } } }
                     : undefined
             : undefined;
         const options: AiSdkProviderOptions = {};
-        for (const part of [responseOptions, nativeReasoning]) {
+        for (const part of [responseOptions, adaptiveOptions, nativeReasoning]) {
             for (const [provider, values] of Object.entries(part ?? {})) {
-                options[provider] = { ...options[provider], ...values };
+                options[provider] = mergeJsonObjects(options[provider] ?? {}, values);
             }
         }
         if (this.#cacheAffinity?.target === "provider-option") {
@@ -836,16 +892,38 @@ export default class AiSdkProvider implements Provider {
 
     #nativeMaxOutputTokens(
         outputBudget: number | null,
-        reasoningBudget: number | null,
+        nativeReasoningBudget: number | null,
     ): number | undefined {
         if (outputBudget === null) return undefined;
-        return this.#additiveReasoningProvider !== undefined
-            && this.#reasoning.mode === "on"
-            && reasoningBudget !== null
-            ? outputBudget - reasoningBudget
+        return nativeReasoningBudget !== null
+            ? outputBudget - nativeReasoningBudget
             : outputBudget;
     }
 
+    #nativeReasoningBudget(
+        outputBudget: number | null,
+        configuredReasoningBudget: number | null,
+    ): number | null {
+        if (this.#additiveReasoningProvider === undefined || this.#reasoning.mode === "off") return null;
+        if (configuredReasoningBudget !== null) return configuredReasoningBudget;
+        if (this.#adaptiveReasoningProviderOptions !== undefined) return null;
+        if (outputBudget === null) {
+            throw new TypeError(
+                `${this.#source}: manual provider reasoning requires a resolved total output budget`,
+            );
+        }
+        if (outputBudget <= MANUAL_REASONING_MINIMUM) {
+            throw new TypeError(
+                `${this.#source}: total output budget must exceed the provider's ${MANUAL_REASONING_MINIMUM}-token minimum reasoning allowance`,
+            );
+        }
+        const fraction = MANUAL_REASONING_FRACTIONS[this.#reasoning.mode];
+        return Math.min(
+            outputBudget - 1,
+            Math.max(MANUAL_REASONING_MINIMUM, Math.round(outputBudget * fraction)),
+        );
+    }
+
     #accounting(
         outcome: ProviderRequestAccounting["outcome"],
         usage: ProviderUsage | undefined,
@@ -895,6 +973,10 @@ export default class AiSdkProvider implements Provider {
             );
         }
         const effectiveMaxOutputTokens = capacity.outputBudget ?? undefined;
+        const nativeReasoningBudget = this.#nativeReasoningBudget(
+            capacity.outputBudget,
+            capacity.reasoningBudget,
+        );
 
         // Assembly order = precedence: the family's sampling DEFAULTS
         // (PLURNK_PROVIDERS_TEMPERATURE — universal, measured on grammar
@@ -1008,7 +1090,7 @@ export default class AiSdkProvider implements Provider {
                     : await executeAiSdkModel({
                         languageModel: this.#languageModel,
                         headers: requestHeaders,
-                        providerOptions: this.#requestProviderOptions(workerId, capacity.reasoningBudget),
+                        providerOptions: this.#requestProviderOptions(workerId, nativeReasoningBudget),
                         systemProviderOptions: this.#systemCacheProviderOptions,
                         messages,
                         signal: operationSignal,
@@ -1032,17 +1114,12 @@ export default class AiSdkProvider implements Provider {
                                 ? sampling.stop
                                 : undefined,
                         seed: typeof sampling?.seed === "number" ? sampling.seed : undefined,
-                        maxOutputTokens: this.#nativeMaxOutputTokens(capacity.outputBudget, capacity.reasoningBudget),
+                        maxOutputTokens: this.#nativeMaxOutputTokens(capacity.outputBudget, nativeReasoningBudget),
                         reasoning: this.#reasoning.mode === "off"
                             ? "none"
                             : this.#reasoning.mode === "adaptive"
-                                ? "provider-default"
-                                : this.#additiveReasoningProvider !== undefined && capacity.reasoningBudget !== null
-                                    ? "provider-default"
-                                    : effortFromReasoning({
-                                        mode: this.#reasoning.mode,
-                                        budget: capacity.reasoningBudget,
-                                    }),
+                                ? this.#adaptiveReasoning
+                                : fixedEffort(this.#reasoning.mode),
                     });
             } catch (error) {
                 const failure = transportFailureEvidence(error);
@@ -1152,6 +1229,15 @@ export default class AiSdkProvider implements Provider {
         }
 
         let notices: ProviderNotice[] | undefined;
+        for (const warning of raw.warnings) {
+            (notices ??= []).push({
+                source: this.#source,
+                kind: "provider_warning",
+                level: "warn",
+                message: providerWarningMessage(warning),
+                position: null,
+            });
+        }
         const usage = raw.usage;
         if (sendGrammar !== undefined
             && this.tokenize !== undefined

package/src/Mock.ts

@@ -7,6 +7,7 @@
 
 import type { ChatMessage, FinishReason, GrammarEvidence, PromptTokenMeasurement, Provider, ProviderAssistant, ProviderCost, ProviderEncryptedReasoningItem, ProviderRequestAccounting, ProviderRequestCapacity, ProviderResponse, ProviderUsage } from "./types.ts";
 import { resolveGenerationEnvelopeFromEnv } from "./env.ts";
+import { REASONING_POLICIES } from "@plurnk/plurnk-contracts";
 import { validateProviderRequestAccounting } from "./accounting.ts";
 import { ProviderError } from "./errors.ts";
 import { assessRequestCapacity, effectiveInputCapacity, effectiveOutputBudget, effectiveReasoningBudget } from "./capacity.ts";
@@ -69,6 +70,7 @@ export default class Mock implements Provider {
     get maxOutputTokens(): number | null { return null; }
     get outputBudget(): number | null { return this.#outputBudget; }
     get reasoningBudget(): number | null { return this.#reasoningBudget; }
+    get supportedReasoningPolicies() { return REASONING_POLICIES; }
     get inputCapacity(): number | null {
         return effectiveInputCapacity({
             contextWindow: this.#contextWindow,

package/src/Pool.test.ts

@@ -53,6 +53,7 @@ const backend = (opts: FakeOpts = {}) => {
         maxOutputTokens: opts.maxOutputTokens ?? null,
         outputBudget: opts.outputBudget ?? null,
         reasoningBudget: opts.reasoningBudget ?? null,
+        supportedReasoningPolicies: ["off", "adaptive", "low", "medium", "high"],
         inputCapacity: effectiveInputCapacity({
             contextWindow: opts.window === undefined ? 48_000 : opts.window,
             maxInputTokens: opts.maxInputTokens ?? null,

package/src/Pool.ts

@@ -7,6 +7,7 @@ import Meta, {
     type PluginAttributionContext,
 } from "@plurnk/plurnk-meta";
 import { effectiveInputCapacity, effectiveOutputBudget, effectiveReasoningBudget, requestCapacityDecision } from "./capacity.ts";
+import type { ReasoningPolicy } from "./types.ts";
 
 // A backend-AVAILABILITY failure: the sub-provider already exhausted its OWN
 // transient retries before throwing one of these, so re-hitting the same
@@ -89,6 +90,10 @@ export default class Pool implements Provider {
     get maxOutputTokens(): number | null { return this.#minimumKnown((provider) => provider.maxOutputTokens); }
     get outputBudget(): number | null { return this.#minimumKnown((provider) => provider.outputBudget); }
     get reasoningBudget(): number | null { return this.#minimumKnown((provider) => provider.reasoningBudget); }
+    get supportedReasoningPolicies(): readonly ReasoningPolicy[] {
+        return this.#backends[0].supportedReasoningPolicies.filter((policy) =>
+            this.#backends.every((provider) => provider.supportedReasoningPolicies.includes(policy)));
+    }
     get inputCapacity(): number | null { return this.#minimumKnown((provider) => provider.inputCapacity); }
 
     // Served id / capabilities aggregate CONSERVATIVELY: a worker could land on any

package/src/ProviderRegistry.test.ts

@@ -4,7 +4,7 @@ import { instantiateProvider, loadActiveProvider, resetDiscoveryCache } from "./
 import type { PluginAttributionContext } from "@plurnk/plurnk-meta";
 
 const mapOf = (entries: Record<string, string>, skipped: Record<string, string> = {}) =>
-    async () => ({ registry: new Map(Object.entries(entries)), skipped: new Map(Object.entries(skipped)), attributions: new Map<string, string | string[]>() });
+    async () => ({ registry: new Map(Object.entries(entries)), skipped: new Map(Object.entries(skipped)), attributions: new Map<string, string | string[]>(), grammarStyles: new Map() });
 
 // Alias parsing is tested in @plurnk/plurnk-aliases (its owner). Here we
 // exercise the resolution + two-tier instantiation this module owns; the active
@@ -31,7 +31,7 @@ test("instantiateProvider: cataloged name resolves in-framework, no scan, no imp
     let scanned = false;
     const p = await instantiateProvider("openai", { ...fullEnv }, "m",
         async (s) => { imports.push(s); return {}; },
-        async () => { scanned = true; return { registry: new Map(), skipped: new Map(), attributions: new Map() }; });
+        async () => { scanned = true; return { registry: new Map(), skipped: new Map(), attributions: new Map(), grammarStyles: new Map() }; });
     assert.equal(p.model, "m");
     assert.deepEqual(imports, []); // tier 1 never touches the importer…
     assert.equal(scanned, false); // …nor the scan
@@ -77,7 +77,7 @@ test("instantiateProvider: a selected plugin composes its static and runtime att
             registry: new Map([["acme", "@acme/ai-provider"]]),
             skipped: new Map(),
             attributions: new Map([["acme", "static:provider"]]),
-            packageAttributions: new Map([["@acme/ai-provider", ["static:provider"]]]),
+            packageAttributions: new Map([["@acme/ai-provider", ["static:provider"]]]), grammarStyles: new Map(),
         }),
     );
 
@@ -107,7 +107,7 @@ test("instantiateProvider: a per-alias baseUrl drives the standard openai probe
         return new Response(JSON.stringify({ data: [] }), { status: 200 });
     });
     await instantiateProvider("openai", { ...fullEnv }, "m", // fullEnv.OPENAI_BASE_URL is http://x — the override must win
-        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() }),
+        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map(), grammarStyles: new Map() }),
         "http://hazel2:8080/v1");
     assert.ok(probed.some((u) => u === "http://hazel2:8080/v1/models"), `probe hit the override host; saw ${probed.join(", ")}`);
     assert.equal(probed.some((u) => u.startsWith("http://x")), false); // never the per-name OPENAI_BASE_URL
@@ -193,13 +193,13 @@ test("instantiateProvider: per-alias knobs scope through to the provider (per-al
     });
     const env = { ...fullEnv, PLURNK_PROVIDERS_CONTEXT_WINDOW_turbo: "12345", PLURNK_PROVIDERS_LLAMA_SERVER_turbo: "1" };
     const p = await instantiateProvider("openai", env, "m",
-        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() }),
+        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map(), grammarStyles: new Map() }),
         undefined, "turbo");
     assert.equal(p.contextWindow, 12345); // _turbo CONTEXT_WINDOW reached the provider
     assert.equal(p.constrainsOutput, true); // _turbo LLAMA_SERVER pin reached it too
     // same env, DIFFERENT alias: neither override applies
     const q = await instantiateProvider("openai", env, "m",
-        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() }),
+        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map(), grammarStyles: new Map() }),
         undefined, "plain");
     assert.equal(q.contextWindow, null);
     assert.equal(q.constrainsOutput, false);
@@ -310,7 +310,7 @@ test("a catalog provider with unknown model metadata never falls through to plug
             "cloudflare",
             {
                 CLOUDFLARE_ACCOUNT_ID: "account",
-                CLOUDFLARE_API_TOKEN: "token",
+                CLOUDFLARE_API_KEY: "token",
             },
             "vendor/model-outside-snapshot",
             async () => { throw new Error("plugin import must not run"); },
@@ -319,7 +319,7 @@ test("a catalog provider with unknown model metadata never falls through to plug
                 return {
                     registry: new Map([["cloudflare", "@plurnk/plurnk-providers-cloudflare"]]),
                     skipped: new Map(),
-                    attributions: new Map(),
+                    attributions: new Map(), grammarStyles: new Map(),
                 };
             },
         ),
@@ -334,7 +334,7 @@ test("explicit metadata constructs an out-of-snapshot Cloudflare model in the co
         "cloudflare",
         {
             CLOUDFLARE_ACCOUNT_ID: "account",
-            CLOUDFLARE_API_TOKEN: "token",
+            CLOUDFLARE_API_KEY: "token",
             PLURNK_PROVIDERS_CONTEXT_WINDOW: "128000",
         },
         "vendor/model-outside-snapshot",
@@ -344,7 +344,7 @@ test("explicit metadata constructs an out-of-snapshot Cloudflare model in the co
             return {
                 registry: new Map([["cloudflare", "@plurnk/plurnk-providers-cloudflare"]]),
                 skipped: new Map(),
-                attributions: new Map(),
+                attributions: new Map(), grammarStyles: new Map(),
             };
         },
     );
@@ -382,7 +382,7 @@ test("{§provider-tagged-reasoning} a Cloudflare model alias carries its explici
         {
             ...fullEnv,
             CLOUDFLARE_ACCOUNT_ID: "account",
-            CLOUDFLARE_API_TOKEN: "token",
+            CLOUDFLARE_API_KEY: "token",
             PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE: "verbatim",
             PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE_cfds1: "think-tags",
         },
@@ -406,7 +406,17 @@ test("two Fireworks aliases independently select default and priority service ti
     const bodies: Record<string, unknown>[] = [];
     mock.method(globalThis, "fetch", async (_url: string, init?: RequestInit) => {
         bodies.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
-        return new Response(JSON.stringify({ choices: [{ message: { content: "ok" }, finish_reason: "stop" }] }), { status: 200, headers: { "Content-Type": "application/json" } });
+        const chunk = {
+            id: "fireworks-test",
+            object: "chat.completion.chunk",
+            created: 1,
+            model: "fireworks-test",
+            choices: [{ index: 0, delta: { content: "ok" }, finish_reason: "stop" }],
+        };
+        return new Response(`data: ${JSON.stringify(chunk)}\n\ndata: [DONE]\n\n`, {
+            status: 200,
+            headers: { "content-type": "text/event-stream" },
+        });
     });
     const env = {
         ...fullEnv,
@@ -419,7 +429,7 @@ test("two Fireworks aliases independently select default and priority service ti
         PLURNK_PROVIDERS_SERVICE_TIER_standard: "default",
     };
     const imports = async () => ({});
-    const discover = async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() });
+    const discover = async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map(), grammarStyles: new Map() });
     const fast = await instantiateProvider("fireworks", env, "accounts/fireworks/routers/glm-5p2-fast", imports, discover, undefined, "fast");
     const standard = await instantiateProvider("fireworks", env, "deepseek-v4-pro", imports, discover, undefined, "standard");
     await fast.generate({ workerId: "fast-worker", messages: [] });
@@ -445,5 +455,8 @@ test("loadActiveProvider: resolves the alias cascade to an installed AI SDK prov
 });
 
 test("loadActiveProvider: throws a named error when no alias is active", async () => {
-    await assert.rejects(() => loadActiveProvider({ ...fullEnv }), /set PLURNK_MODEL to an alias/);
+    await assert.rejects(
+        () => loadActiveProvider({ ...fullEnv }),
+        /set PLURNK_MODEL to a declared alias or provider\/model route/,
+    );
 });

package/src/ProviderRegistry.ts

@@ -1,7 +1,7 @@
-// Provider instantiation + active-alias resolution. Alias PARSING (the
+// Provider instantiation + active model-route resolution. Alias parsing (the
 // PLURNK_MODEL_<alias>=<provider>/<model> cascade + PLURNK_BASEURL_<alias>
-// overrides) lives in @plurnk/plurnk-aliases — the zero-dep parser shared with
-// thin clients; this module resolves the active alias to a Provider.
+// overrides) lives in @plurnk/plurnk-aliases; this module resolves the active
+// alias-or-route selector to a Provider.
 //
 // {§provider-resolution} Models.dev catalog → PLURNK provider declaration
 // → local protocol adapter → scope-agnostic AI SDK plugin discovery. Generic
@@ -11,7 +11,7 @@
 import type { AiSdkProviderPlugin, Provider } from "./types.ts";
 import { catalogProviderFromEnv, providerFromSdkModel } from "./catalogProvider.ts";
 import { discover, type DiscoverOptions, type Discovery } from "./discover.ts";
-import { resolveActiveAlias } from "@plurnk/plurnk-aliases";
+import { resolveActiveRoute } from "@plurnk/plurnk-aliases";
 import { scopeEnvToAlias } from "./env.ts";
 import { ollamaProviderFromEnv } from "./ollama.ts";
 import { compatibleProviderFromEnv } from "./compatibleProvider.ts";
@@ -61,7 +61,7 @@ export const instantiateProvider = async (
     if (catalog !== null) return catalog;
     if (name === "ollama") return ollamaProviderFromEnv(env, model, baseUrl === undefined ? undefined : { baseUrl });
     if (name === "openai" || name === "plurnk") return compatibleProviderFromEnv(name, env, model, baseUrl);
-    const { registry, skipped, packageAttributions = new Map() } = await providerPackages(discoverFn, env);
+    const { registry, skipped, packageAttributions = new Map(), grammarStyles = new Map() } = await providerPackages(discoverFn, env);
     const specifier = registry.get(name);
     if (specifier === undefined) {
         const declined = skipped.get(name);
@@ -99,21 +99,30 @@ export const instantiateProvider = async (
         languageModel: sdkProvider.languageModel(model),
         contextWindow,
         attributions,
+        ...(grammarStyles.get(name) === undefined ? {} : { grammarStyle: grammarStyles.get(name) }),
     });
 };
 
 // Test-only: drop the memoized discovery so a fresh scan/injection runs next.
 export const resetDiscoveryCache = (): void => { discoveredCache = null; };
 
-// Boot convenience: resolve the active alias cascade and instantiate it.
+// Boot convenience: resolve the active selector and instantiate its exact route.
 export const loadActiveProvider = async (
     env: NodeJS.ProcessEnv = process.env,
     importImpl: ImportModule = importModule,
     discoverFn: DiscoverFn = discover,
 ): Promise<Provider> => {
-    const alias = resolveActiveAlias(env);
-    if (alias === null) {
-        throw new Error("no active provider: set PLURNK_MODEL to an alias declared via PLURNK_MODEL_<alias>=<provider>/<model>");
+    const route = resolveActiveRoute(env);
+    if (route === null) {
+        throw new Error("no active provider: set PLURNK_MODEL to a declared alias or provider/model route");
     }
-    return instantiateProvider(alias.provider, env, alias.model, importImpl, discoverFn, alias.baseUrl, alias.alias);
+    return instantiateProvider(
+        route.provider,
+        env,
+        route.model,
+        importImpl,
+        discoverFn,
+        route.baseUrl,
+        route.alias,
+    );
 };

package/src/accounting.test.ts

@@ -89,6 +89,10 @@ test("aggregateProviderAccounting preserves request order and only sums known fi
         },
     ]);
     assert.deepEqual(accounting.requests.map(({ provider }) => provider), ["provider:a", "provider:b"]);
-    assert.equal(accounting.usage, null, "an unknown failed request prevents fabricated totals");
-    assert.equal(accounting.costUsd, null);
+    assert.deepEqual(accounting.usage, {
+        inputTokens: 2,
+        outputTokens: 3,
+        totalTokens: 5,
+    }, "a response-less failure is skipped, never allowed to erase reported usage");
+    assert.equal(accounting.costUsd, "0.25", "a response-less failure is skipped; the expressible cost survives");
 });

package/src/accounting.ts

@@ -126,12 +126,13 @@ const sumKnown = (
     requests: readonly ProviderRequestAccounting[],
     read: (usage: ProviderUsage) => number | undefined,
 ): number | undefined => {
-    const values = requests.map((request) => request.usage === undefined
-        ? undefined
-        : read(request.usage));
-    return values.some((value) => value === undefined)
-        ? undefined
-        : (values as number[]).reduce((sum, value) => sum + value, 0);
+    // {§tokenomics-provider-usage} — aggregate usage sums every reported
+    // quantity; an unreported one (a response-less failure) is skipped, never
+    // invented as zero and never allowed to erase the reported evidence.
+    const known = requests
+        .map((request) => request.usage === undefined ? undefined : read(request.usage))
+        .filter((value): value is number => value !== undefined);
+    return known.length === 0 ? undefined : known.reduce((sum, value) => sum + value, 0);
 };
 
 export const aggregateProviderAccounting = (