@plurnk/plurnk-providers 1.11.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-providers",
-    "version": "1.11.0",
+    "version": "1.12.0",
     "description": "PLURNK's stable model-provider contract and AI SDK adapter.",
     "keywords": [
         "plurnk",
@@ -71,6 +71,7 @@
         "prepack": "npm run build"
     },
     "dependencies": {
+        "@ai-sdk/provider": "^4.0.8",
         "@ai-sdk/amazon-bedrock": "^5.0.0",
         "@ai-sdk/anthropic": "^4.0.0",
         "@ai-sdk/cerebras": "^3.0.0",
@@ -83,11 +84,11 @@
         "@ai-sdk/togetherai": "^3.0.0",
         "@ai-sdk/xai": "^4.0.0",
         "@openrouter/ai-sdk-provider": "^3.0.0",
-        "@plurnk/gbnf": "1.11.0",
-        "@plurnk/plurnk-aliases": "1.11.0",
-        "@plurnk/plurnk-contracts": "1.11.0",
-        "@plurnk/plurnk-meta": "1.11.0",
-        "@plurnk/plurnk-models": "1.11.0",
+        "@plurnk/gbnf": "1.12.0",
+        "@plurnk/plurnk-aliases": "1.12.0",
+        "@plurnk/plurnk-contracts": "1.12.0",
+        "@plurnk/plurnk-meta": "1.12.0",
+        "@plurnk/plurnk-models": "1.12.0",
         "ai": "^7.0.37",
         "zod": "^4.4.3"
     },

package/src/AiSdkProvider.ts

@@ -52,6 +52,9 @@ export type ProviderFetch = typeof globalThis.fetch;
 // mapping retains any backend-specific omission/explicit-disable constraint.
 export type ReasoningStyle = "none" | "think" | "include_reasoning" | "effort" | "effort_explicit" | "effort_required" | "thinking_effort" | "template" | "anthropic";
 
+export type NativeReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
+export type CompatibleReasoningEffort = NativeReasoningEffort | "max";
+
 // GBNF transport is a local llama-server capability. "none" means no
 // service-managed constrained sampling; endpoint-owned settings are not inferred.
 export type GrammarStyle = "none" | "llamacpp";
@@ -98,9 +101,15 @@ export type AiSdkProviderConfig = {
     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";
+    // Native AI SDK projection for adaptive. Models.dev supplies the route's
+    // admissible values; provider-default is reserved for a documented native
+    // dynamic option/default or a route with no caller-selectable effort.
+    adaptiveReasoning?: NativeReasoningEffort | "provider-default";
+    // OpenAI-compatible effort transports accept route-native values beyond
+    // the AI SDK's generic vocabulary. These are still catalog facts, not
+    // provider-name branches.
+    compatibleAdaptiveReasoning?: CompatibleReasoningEffort | "provider-default";
+    compatibleOffReasoning?: "none";
     adaptiveReasoningProviderOptions?: AiSdkProviderOptions;
     // Native Anthropic and Bedrock SDKs interpret generic maxOutputTokens as
     // visible output and add an explicit provider reasoning budget. This marker lets the
@@ -369,7 +378,9 @@ export default class AiSdkProvider implements Provider {
     #additiveReasoningProvider: "anthropic" | "bedrock" | undefined;
     #reasoning: Reasoning;
     #supportedReasoningPolicies: readonly ReasoningPolicy[];
-    #adaptiveReasoning: "high" | "provider-default";
+    #adaptiveReasoning: NativeReasoningEffort | "provider-default";
+    #compatibleAdaptiveReasoning: CompatibleReasoningEffort | "provider-default";
+    #compatibleOffReasoning: "none" | undefined;
     #adaptiveReasoningProviderOptions: AiSdkProviderOptions | undefined;
     #temperature: number;
     #repeatPenalty: number;
@@ -444,6 +455,8 @@ export default class AiSdkProvider implements Provider {
             ...new Set(config.supportedReasoningPolicies ?? REASONING_POLICIES),
         ]);
         this.#adaptiveReasoning = config.adaptiveReasoning ?? "high";
+        this.#compatibleAdaptiveReasoning = config.compatibleAdaptiveReasoning ?? "high";
+        this.#compatibleOffReasoning = config.compatibleOffReasoning;
         this.#adaptiveReasoningProviderOptions = config.adaptiveReasoningProviderOptions;
         if (!this.#supportedReasoningPolicies.includes(this.#reasoning.mode)) {
             throw new UnsupportedReasoningPolicyError(
@@ -700,13 +713,31 @@ export default class AiSdkProvider implements Provider {
             case "think": return on ? { think: true } : {};
             case "include_reasoning": return on ? { include_reasoning: true } : {};
             case "effort": return mode === "off"
-                ? {}
-                : { reasoning_effort: mode === "adaptive" ? "high" : fixedEffort(mode) };
-            // Graded reasoning is mandatory: adaptive uses PLURNK's high fallback,
-            // fixed levels preserve their intent, and construction rejects off.
-            case "effort_required": return {
-                reasoning_effort: mode === "adaptive" ? "high" : fixedEffort(mode),
-            };
+                ? this.#compatibleOffReasoning === undefined
+                    ? {}
+                    : { reasoning_effort: this.#compatibleOffReasoning }
+                : mode === "adaptive"
+                    ? this.#compatibleAdaptiveReasoning === "provider-default"
+                        ? {}
+                        : { reasoning_effort: this.#compatibleAdaptiveReasoning }
+                    : { reasoning_effort: fixedEffort(mode) };
+            // Graded reasoning is mandatory when the route advertises an effort
+            // value. Cataloged routes supply the exact strongest legal value;
+            // construction rejects an unsupported off or fixed policy.
+            case "effort_required": {
+                if (mode === "off") {
+                    if (this.#compatibleOffReasoning === undefined) {
+                        throw new TypeError(`${this.#source}: required reasoning effort has no off projection`);
+                    }
+                    return { reasoning_effort: this.#compatibleOffReasoning };
+                }
+                if (mode === "adaptive") {
+                    return this.#compatibleAdaptiveReasoning === "provider-default"
+                        ? {}
+                        : { reasoning_effort: this.#compatibleAdaptiveReasoning };
+                }
+                return { reasoning_effort: 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

package/src/accounting.test.ts

@@ -120,3 +120,42 @@ test("aggregateProviderAccounting omits unknown nested usage fields from its JSO
         outputTokenDetails: { reasoningTokens: 2 },
     });
 });
+
+test("aggregateProviderAccounting does not invent complete detail partitions across heterogeneous requests", () => {
+    const accounting = aggregateProviderAccounting([
+        {
+            provider: "provider:detailed",
+            model: "m",
+            outcome: "response",
+            usage: {
+                inputTokens: 2,
+                outputTokens: 0,
+                totalTokens: 2,
+                inputTokenDetails: {
+                    noCacheTokens: 2,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                },
+            },
+            cost: { kind: "unknown", reason: "no direct cost" },
+        },
+        {
+            provider: "provider:totals-only",
+            model: "m",
+            outcome: "response",
+            usage: { inputTokens: 4, outputTokens: 0, totalTokens: 4 },
+            cost: { kind: "unknown", reason: "no direct cost" },
+        },
+    ]);
+
+    assert.deepEqual(accounting.usage, {
+        inputTokens: 6,
+        outputTokens: 0,
+        totalTokens: 6,
+        inputTokenDetails: {
+            noCacheTokens: 2,
+            cacheReadTokens: 0,
+            cacheWriteTokens: 0,
+        },
+    });
+});

package/src/accounting.ts

@@ -132,7 +132,12 @@ const sumKnown = (
     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);
+    if (known.length === 0) return undefined;
+    const sum = known.reduce((total, value) => total + value, 0);
+    if (!Number.isSafeInteger(sum)) {
+        throw new TypeError("aggregate provider usage exceeds the safe-integer range");
+    }
+    return sum;
 };
 
 export const aggregateProviderAccounting = (
@@ -179,16 +184,20 @@ export const aggregateProviderAccounting = (
             ...(textTokens === undefined ? {} : { textTokens }),
             ...(reasoningTokens === undefined ? {} : { reasoningTokens }),
         };
-    const usage = inputTokens === undefined && outputTokens === undefined && totalTokens === undefined
+    // Each physical request was validated above. Aggregate fields deliberately
+    // sum their own known evidence independently: heterogeneous providers may
+    // report different detail subsets, so the projection must not reinterpret
+    // their union as one complete per-request partition.
+    const usage: ProviderUsage | null = inputTokens === undefined && outputTokens === undefined && totalTokens === undefined
         && inputTokenDetails === undefined && outputTokenDetails === undefined
         ? null
-        : validateProviderUsage({
+        : {
             ...(inputTokens === undefined ? {} : { inputTokens }),
             ...(outputTokens === undefined ? {} : { outputTokens }),
             ...(totalTokens === undefined ? {} : { totalTokens }),
             ...(inputTokenDetails === undefined ? {} : { inputTokenDetails }),
             ...(outputTokenDetails === undefined ? {} : { outputTokenDetails }),
-        });
+        };
     return {
         requests: [...requests],
         usage,

package/src/catalogProvider.test.ts

@@ -48,7 +48,7 @@ test("provider adapters advertise only reasoning policies they can preserve", ()
         PLURNK_PROVIDERS_REASONING: "adaptive",
         PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_STYLE: "thinking_effort",
     }, "deepseek-v4-flash");
-    assert.deepEqual(deepseek?.supportedReasoningPolicies, ["off", "adaptive", "high"]);
+    assert.deepEqual(deepseek?.supportedReasoningPolicies, ["off", "adaptive", "low", "high"]);
 
     assert.throws(
         () => catalogProviderFromEnv("deepseek", {
@@ -57,7 +57,7 @@ test("provider adapters advertise only reasoning policies they can preserve", ()
             PLURNK_PROVIDERS_REASONING: "medium",
             PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_STYLE: "thinking_effort",
         }, "deepseek-v4-flash"),
-        /reasoning policy 'medium' is unsupported; supported policies: off, adaptive, high/,
+        /reasoning policy 'medium' is unsupported; supported policies: off, adaptive, low, high/,
     );
 
     const mistral = catalogProviderFromEnv("mistral", {
@@ -82,7 +82,7 @@ test("provider adapters advertise only reasoning policies they can preserve", ()
     assert.deepEqual(gemini?.supportedReasoningPolicies, ["adaptive", "low", "medium", "high"], "Gemini 3's mandatory minimum is not advertised as off");
 });
 
-test("Cloudflare graded reasoning sends exact effort and never advertises unsupported off", async () => {
+test("Models.dev controls Cloudflare's exact effort vocabulary", async () => {
     const bodies: Record<string, unknown>[] = [];
     mock.method(globalThis, "fetch", async (_input: string | URL | Request, init?: RequestInit) => {
         bodies.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
@@ -91,7 +91,7 @@ test("Cloudflare graded reasoning sends exact effort and never advertises unsupp
                 id: "cloudflare-effort",
                 object: "chat.completion.chunk",
                 created: 1,
-                model: "@cf/zai-org/glm-5.3-flash",
+                model: "@cf/qwen/qwen3.8-27b",
                 choices: [{ index: 0, delta: { content: "done" }, finish_reason: "stop" }],
             })}`,
             "data: [DONE]",
@@ -106,14 +106,14 @@ test("Cloudflare graded reasoning sends exact effort and never advertises unsupp
     const low = catalogProviderFromEnv("cloudflare", {
         ...cloudflareEnv,
         PLURNK_PROVIDERS_REASONING: "low",
-    }, "@cf/zai-org/glm-5.3-flash");
-    assert.deepEqual(low?.supportedReasoningPolicies, ["adaptive", "low", "medium", "high"]);
+    }, "@cf/qwen/qwen3.8-27b");
+    assert.deepEqual(low?.supportedReasoningPolicies, ["adaptive", "low", "medium"]);
     await low?.generate({ workerId: "cloudflare-low", messages: [{ role: "user", content: "hello" }] });
 
     const adaptive = catalogProviderFromEnv("cloudflare", {
         ...cloudflareEnv,
         PLURNK_PROVIDERS_REASONING: "adaptive",
-    }, "@cf/zai-org/glm-5.3-flash");
+    }, "@cf/qwen/qwen3.8-27b");
     await adaptive?.generate({ workerId: "cloudflare-adaptive", messages: [{ role: "user", content: "hello" }] });
 
     const nonReasoning = catalogProviderFromEnv("cloudflare", {
@@ -123,10 +123,71 @@ test("Cloudflare graded reasoning sends exact effort and never advertises unsupp
     assert.deepEqual(nonReasoning?.supportedReasoningPolicies, ["off", "adaptive"]);
     await nonReasoning?.generate({ workerId: "cloudflare-granite", messages: [{ role: "user", content: "hello" }] });
 
-    assert.deepEqual(bodies.map((body) => body.reasoning_effort), ["low", "high", undefined]);
+    const ungradedReasoner = catalogProviderFromEnv("cloudflare", {
+        ...cloudflareEnv,
+        PLURNK_PROVIDERS_REASONING: "adaptive",
+    }, "@cf/zai-org/glm-5.3-flash");
+    assert.deepEqual(ungradedReasoner?.supportedReasoningPolicies, ["adaptive"]);
+    await ungradedReasoner?.generate({ workerId: "cloudflare-ungraded", messages: [{ role: "user", content: "hello" }] });
+
+    assert.deepEqual(bodies.map((body) => body.reasoning_effort), ["low", "xhigh", undefined, undefined]);
+    assert.throws(
+        () => catalogProviderFromEnv("cloudflare", cloudflareEnv, "@cf/qwen/qwen3.8-27b"),
+        /reasoning policy 'off' is unsupported; supported policies: adaptive, low, medium/,
+    );
     assert.throws(
-        () => catalogProviderFromEnv("cloudflare", cloudflareEnv, "@cf/zai-org/glm-5.3-flash"),
-        /reasoning policy 'off' is unsupported; supported policies: adaptive, low, medium, high/,
+        () => catalogProviderFromEnv("cloudflare", {
+            ...cloudflareEnv,
+            PLURNK_PROVIDERS_REASONING: "high",
+        }, "@cf/qwen/qwen3.8-27b"),
+        /reasoning policy 'high' is unsupported; supported policies: adaptive, low, medium/,
+    );
+});
+
+test("an operator-declared effort vocabulary extends Models.dev's for a provider's reasoning routes (#439)", async () => {
+    const bodies: Record<string, unknown>[] = [];
+    mock.method(globalThis, "fetch", async (_input: string | URL | Request, init?: RequestInit) => {
+        bodies.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
+        return new Response([
+            `data: ${JSON.stringify({
+                id: "cloudflare-declared",
+                object: "chat.completion.chunk",
+                created: 1,
+                model: "@cf/zai-org/glm-5.3-flash",
+                choices: [{ index: 0, delta: { content: "done" }, finish_reason: "stop" }],
+            })}`,
+            "data: [DONE]",
+        ].join("\n\n"), { headers: { "content-type": "text/event-stream" } });
+    });
+    const declaredEnv = {
+        ...env,
+        CLOUDFLARE_ACCOUNT_ID: "account",
+        CLOUDFLARE_API_KEY: "token",
+        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_REASONING_STYLE: "effort_required",
+        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_REASONING_EFFORTS: "low, medium,high",
+    };
+    // Models.dev lists this route as reasoning with no effort vocabulary; the declaration supplies one.
+    const low = catalogProviderFromEnv("cloudflare", { ...declaredEnv, PLURNK_PROVIDERS_REASONING: "low" }, "@cf/zai-org/glm-5.3-flash");
+    assert.deepEqual(low?.supportedReasoningPolicies, ["adaptive", "low", "medium", "high"]);
+    await low?.generate({ workerId: "declared-low", messages: [{ role: "user", content: "hello" }] });
+    const adaptive = catalogProviderFromEnv("cloudflare", { ...declaredEnv, PLURNK_PROVIDERS_REASONING: "adaptive" }, "@cf/zai-org/glm-5.3-flash");
+    await adaptive?.generate({ workerId: "declared-adaptive", messages: [{ role: "user", content: "hello" }] });
+    assert.deepEqual(bodies.map((body) => body.reasoning_effort), ["low", "high"], "a fixed level keeps its name; adaptive takes the strongest declared effort");
+    // A declared `none` admits `off` on an effort transport; the catalog's own vocabulary stays in the union.
+    const withOff = catalogProviderFromEnv("cloudflare", {
+        ...declaredEnv,
+        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_REASONING_EFFORTS: "none,high",
+    }, "@cf/qwen/qwen3.8-27b");
+    assert.deepEqual(withOff?.supportedReasoningPolicies, ["off", "adaptive", "low", "medium", "high"]);
+    // The declaration never turns a non-reasoning route into a reasoning one.
+    const nonReasoning = catalogProviderFromEnv("cloudflare", { ...declaredEnv, PLURNK_PROVIDERS_REASONING: "adaptive" }, "@cf/ibm-granite/granite-4.0-h-micro");
+    assert.deepEqual(nonReasoning?.supportedReasoningPolicies, ["off", "adaptive"]);
+    assert.throws(
+        () => catalogProviderFromEnv("cloudflare", {
+            ...declaredEnv,
+            PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_REASONING_EFFORTS: "low,turbo",
+        }, "@cf/zai-org/glm-5.3-flash"),
+        /PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_REASONING_EFFORTS has invalid value "turbo"; declarable efforts: none, minimal, low, medium, high, xhigh, max/,
     );
 });
 
@@ -201,7 +262,7 @@ test("official AI SDK provider owns the native request while PLURNK owns call se
     assert.equal(calls[0]?.body.prompt_cache_key, "worker", "the official OpenAI SDK projects the documented affinity key");
 });
 
-test("xAI's native chat contract affirmatively requests adaptive high and caps the complete reasoning response", async () => {
+test("xAI's native chat contract requests its strongest cataloged effort and caps the complete reasoning response", async () => {
     let call: { headers: Headers; body: Record<string, unknown> } | undefined;
     mock.method(globalThis, "fetch", async (_input: string | URL | Request, init?: RequestInit) => {
         call = {
@@ -254,7 +315,7 @@ test("xAI's native chat contract affirmatively requests adaptive high and caps t
     });
 
     assert.equal(call?.body.max_completion_tokens, 16);
-    assert.equal(call?.body.reasoning_effort, "high", "adaptive is affirmative on xAI's graded route");
+    assert.equal(call?.body.reasoning_effort, "xhigh", "adaptive uses the strongest route-advertised generic effort");
     assert.equal("max_tokens" in (call?.body ?? {}), false);
     assert.equal(call?.headers.get("x-grok-conv-id"), "xai-worker");
     assert.equal(result?.assistant.reasoning, "consider");
@@ -365,7 +426,7 @@ test("Meta Muse adaptive reasoning is requested even when the endpoint returns n
         messages: [{ role: "user", content: "hello" }],
     });
 
-    assert.equal(body?.reasoning_effort, "high");
+    assert.equal(body?.reasoning_effort, "xhigh");
     assert.equal(result?.assistant.reasoning, null);
     assert.equal(result?.accounting[0]?.usage?.outputTokenDetails?.reasoningTokens, 37);
 });
@@ -504,6 +565,7 @@ test("native Anthropic adaptive policy uses adaptive thinking rather than a fixe
             contextWindow: 16_384,
             maxOutputTokens: 8_192,
             reasoning: true,
+            reasoningOptions: [{ type: "toggle" }],
             attachment: true,
             toolCall: true,
             modalities: { input: ["text", "image"], output: ["text"] },
@@ -635,8 +697,10 @@ test("cataloged unknown model fails unless its context is explicit", () => {
         ...env,
         XAI_API_KEY: "test-key",
         PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192",
+        PLURNK_PROVIDERS_REASONING: "adaptive",
     }, "not-in-the-catalog");
     assert.equal(provider?.contextWindow, 8192);
+    assert.deepEqual(provider?.supportedReasoningPolicies, ["off", "adaptive"]);
 });
 
 test("Models.dev is the only fallback rate table", async () => {
@@ -662,6 +726,8 @@ test("Models.dev is the only fallback rate table", async () => {
     const cataloged = catalogProviderFromEnv("deepseek", {
         ...env,
         DEEPSEEK_API_KEY: "test-key",
+        PLURNK_PROVIDERS_REASONING: "adaptive",
+        PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_STYLE: "thinking_effort",
     }, "deepseek-v4-flash");
     assert.notEqual(cataloged, null);
     const catalogedResponse = await cataloged!.generate({ workerId: "cataloged", messages: [] });
@@ -675,6 +741,7 @@ test("Models.dev is the only fallback rate table", async () => {
         ...env,
         XAI_API_KEY: "test-key",
         PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192",
+        PLURNK_PROVIDERS_REASONING: "adaptive",
     }, "not-in-the-catalog");
     const uncatalogedResponse = await uncataloged!.generate({ workerId: "uncataloged", messages: [] });
     assert.deepEqual(uncatalogedResponse.accounting[0]?.cost, {

package/src/catalogProvider.ts

@@ -1,4 +1,9 @@
-import { lookupProvider, resolveModel, type ModelInfo } from "@plurnk/plurnk-models";
+import {
+    lookupProvider,
+    resolveModel,
+    type ModelInfo,
+    type ModelReasoningEffort,
+} from "@plurnk/plurnk-models";
 import {
     contextWindowFromEnv,
     effectiveContextWindow,
@@ -12,7 +17,13 @@ import {
     reasoningFromEnv,
     reasoningResponseStyleFromEnv,
 } from "./env.ts";
-import AiSdkProvider, { type AiSdkProviderConfig, type GrammarStyle, type ReasoningStyle } from "./AiSdkProvider.ts";
+import AiSdkProvider, {
+    type AiSdkProviderConfig,
+    type CompatibleReasoningEffort,
+    type GrammarStyle,
+    type NativeReasoningEffort,
+    type ReasoningStyle,
+} from "./AiSdkProvider.ts";
 import { configuredProviderInfo, createSdkModel } from "./sdkModels.ts";
 import { providerSource } from "./notices.ts";
 import type { Provider, ProviderCostNormalizer } from "./types.ts";
@@ -40,23 +51,92 @@ const reasoningStyleFromEnv = (
     return value as ReasoningStyle;
 };
 
+// {§provider-reasoning-policy} — the operator's affirmative declaration of efforts a provider's
+// reasoning routes accept beyond Models.dev; the daemon adds none on its own (#439).
+const DECLARABLE_EFFORTS: ReadonlySet<ModelReasoningEffort> = new Set([
+    "none", "minimal", "low", "medium", "high", "xhigh", "max",
+]);
+const declaredEffortsFromEnv = (
+    env: NodeJS.ProcessEnv,
+    name: string,
+): readonly ModelReasoningEffort[] => {
+    const prefix = name.replaceAll(/[^a-zA-Z0-9]/g, "_").toUpperCase();
+    const key = `PLURNK_PROVIDERS_PROVIDER_${prefix}_REASONING_EFFORTS`;
+    const value = env[key];
+    if (value === undefined || value.trim().length === 0) return [];
+    const efforts = value.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+    const invalid = efforts.find((effort) => !DECLARABLE_EFFORTS.has(effort as ModelReasoningEffort));
+    if (invalid !== undefined) {
+        throw new Error(`${name} provider: ${key} has invalid value "${invalid}"; declarable efforts: ${[...DECLARABLE_EFFORTS].join(", ")}`);
+    }
+    return [...new Set(efforts as ModelReasoningEffort[])];
+};
 const activationPolicies = Object.freeze(["off", "adaptive"] as const);
 const deepSeekPolicies = Object.freeze(["off", "adaptive", "high"] as const);
-const adaptiveOnly = Object.freeze(["adaptive"] as const);
 const reasoningWithoutOff = Object.freeze(["adaptive", "low", "medium", "high"] as const);
 
-const mistralSupportsEffort = (model: string): boolean =>
-    model === "mistral-small-latest"
-    || model === "mistral-small-2603"
-    || model === "mistral-medium-3"
-    || model === "mistral-medium-3.5";
+const reasoningEffortOrder = Object.freeze([
+    "minimal", "low", "medium", "high", "xhigh", "max",
+] as const);
+const nativeReasoningEfforts = new Set<NativeReasoningEffort>([
+    "minimal", "low", "medium", "high", "xhigh",
+]);
+const compatibleReasoningEfforts = new Set<CompatibleReasoningEffort>(reasoningEffortOrder);
+const compatibleEffortStyles = new Set<ReasoningStyle>([
+    "effort", "effort_explicit", "effort_required", "thinking_effort",
+]);
+const compatibleToggleStyles = new Set<ReasoningStyle>([
+    "think", "include_reasoning", "effort_explicit", "thinking_effort", "template", "anthropic",
+]);
+
+const catalogEfforts = (
+    info: ModelInfo,
+    declared: readonly ModelReasoningEffort[] = [],
+): readonly ModelReasoningEffort[] => [
+    ...new Set([
+        ...(info.reasoningOptions
+            ?.filter((option) => option.type === "effort")
+            .flatMap((option) => option.values) ?? []),
+        ...declared,
+    ]),
+];
 
-const xaiReasoningIsModelFixed = (model: string): boolean =>
-    /^grok-4\.20(?:-\d{4})?-(?:non-)?reasoning$/.test(model);
+const strongestCatalogEffort = <T extends NativeReasoningEffort | CompatibleReasoningEffort>(
+    info: ModelInfo,
+    supported: ReadonlySet<T>,
+    declared: readonly ModelReasoningEffort[] = [],
+): T | undefined => {
+    const values = new Set(catalogEfforts(info, declared));
+    return reasoningEffortOrder.findLast((effort) => supported.has(effort as T) && values.has(effort)) as T | undefined;
+};
+
+const catalogSupportsToggle = (info: ModelInfo): boolean =>
+    info.reasoningOptions?.some((option) => option.type === "toggle") === true;
 
-const googleReasoningCannotBeOff = (model: string): boolean =>
-    /^gemini-2\.5-pro(?:-|$)/i.test(model)
-    || /^gemini-(?:[3-9]|\d{2})[.-]/i.test(model);
+const catalogSupportedReasoningPolicies = ({
+    info,
+    native,
+    style,
+    declared,
+}: {
+    info: ModelInfo;
+    native: boolean;
+    style: ReasoningStyle;
+    declared: readonly ModelReasoningEffort[];
+}): readonly ReasoningPolicy[] => {
+    if (!info.reasoning) return activationPolicies;
+    const efforts = new Set(catalogEfforts(info, declared));
+    const effortTransport = native || compatibleEffortStyles.has(style);
+    const off = native
+        ? efforts.has("none") || catalogSupportsToggle(info)
+        : (efforts.has("none") && compatibleEffortStyles.has(style))
+            || (catalogSupportsToggle(info) && compatibleToggleStyles.has(style));
+    return REASONING_POLICIES.filter((policy) => policy === "adaptive"
+        || policy === "off" && off
+        || (policy === "low" || policy === "medium" || policy === "high")
+            && effortTransport
+            && efforts.has(policy));
+};
 
 const anthropicSupportsAdaptiveThinking = (model: string): boolean =>
     /claude-(?:opus-(?:4-[678]|5)|sonnet-(?:4-6|5)|fable-5)/.test(model);
@@ -65,29 +145,18 @@ const supportedReasoningPolicies = ({
     info,
     native,
     style,
-    sdkPackage,
-    model,
+    declared,
 }: {
     info?: ModelInfo;
     native: boolean;
     style: ReasoningStyle;
-    sdkPackage?: string;
-    model: string;
+    declared: readonly ModelReasoningEffort[];
 }): readonly ReasoningPolicy[] => {
     if (info !== undefined && info.reasoning !== true) return activationPolicies;
-    if (native) {
-        if (sdkPackage === "@ai-sdk/mistral") {
-            return mistralSupportsEffort(model) ? deepSeekPolicies : adaptiveOnly;
-        }
-        if (sdkPackage === "@ai-sdk/xai") {
-            if (xaiReasoningIsModelFixed(model)) return adaptiveOnly;
-            if (model === "grok-4.6") return reasoningWithoutOff;
-        }
-        if (sdkPackage === "@ai-sdk/google" && googleReasoningCannotBeOff(model)) {
-            return reasoningWithoutOff;
-        }
-        return REASONING_POLICIES;
+    if (info?.reasoningOptions !== undefined) {
+        return catalogSupportedReasoningPolicies({ info, native, style, declared });
     }
+    if (native) return activationPolicies;
     if (style === "effort" || style === "effort_explicit") return REASONING_POLICIES;
     if (style === "effort_required") return reasoningWithoutOff;
     if (style === "thinking_effort") return deepSeekPolicies;
@@ -98,10 +167,14 @@ const adaptiveReasoningProjection = ({
     sdkPackage,
     model,
     reasoningCapable,
+    info,
+    declared,
 }: {
     sdkPackage?: string;
     model: string;
     reasoningCapable: boolean;
+    info?: ModelInfo;
+    declared: readonly ModelReasoningEffort[];
 }): Pick<AiSdkProviderConfig, "adaptiveReasoning" | "adaptiveReasoningProviderOptions"> => {
     if (!reasoningCapable) return { adaptiveReasoning: "provider-default" };
     if (sdkPackage === "@ai-sdk/google" && /^gemini-2\.5(?:-|$)/i.test(model)) {
@@ -128,13 +201,12 @@ const adaptiveReasoningProjection = ({
             },
         };
     }
-    if (sdkPackage === "@ai-sdk/mistral" && !mistralSupportsEffort(model)) {
-        return { adaptiveReasoning: "provider-default" };
-    }
-    if (sdkPackage === "@ai-sdk/xai" && xaiReasoningIsModelFixed(model)) {
-        return { adaptiveReasoning: "provider-default" };
+    if (info?.reasoningOptions !== undefined) {
+        return {
+            adaptiveReasoning: strongestCatalogEffort(info, nativeReasoningEfforts, declared) ?? "provider-default",
+        };
     }
-    return { adaptiveReasoning: "high" };
+    return { adaptiveReasoning: "provider-default" };
 };
 
 export const providerFromSdkModel = ({
@@ -191,14 +263,30 @@ export const providerFromSdkModel = ({
     );
     const reasoning = reasoningFromEnv(env, name, envelope.reasoningBudget);
     const reasoningCapable = info?.reasoning === true;
-    const reasoningStyle = info?.reasoning === false
+    const declaredEfforts = declaredEffortsFromEnv(env, name);
+    const declaredReasoningStyle = info?.reasoning === false
         ? "none"
         : reasoningStyleFromEnv(env, name) ?? "none";
+    const reasoningStyle = info?.reasoningOptions !== undefined
+        && (declaredReasoningStyle === "effort" || declaredReasoningStyle === "effort_required")
+        && catalogEfforts(info, declaredEfforts).length === 0
+        ? "none"
+        : declaredReasoningStyle;
     const adaptiveReasoning = adaptiveReasoningProjection({
         sdkPackage,
         model,
         reasoningCapable,
+        info,
+        declared: declaredEfforts,
     });
+    const compatibleAdaptiveReasoning = languageModel !== undefined || info?.reasoningOptions === undefined
+        ? undefined
+        : strongestCatalogEffort(info, compatibleReasoningEfforts, declaredEfforts) ?? "provider-default";
+    const compatibleOffReasoning = languageModel !== undefined
+        || info === undefined
+        || !catalogEfforts(info, declaredEfforts).includes("none")
+        ? undefined
+        : "none" as const;
 
     const catalogCost = info?.cost;
     const rates = catalogCost === undefined ? null : {
@@ -235,10 +323,11 @@ export const providerFromSdkModel = ({
             info,
             native: languageModel !== undefined,
             style: reasoningStyle,
-            sdkPackage,
-            model,
+            declared: declaredEfforts,
         }),
         ...adaptiveReasoning,
+        ...(compatibleAdaptiveReasoning === undefined ? {} : { compatibleAdaptiveReasoning }),
+        ...(compatibleOffReasoning === undefined ? {} : { compatibleOffReasoning }),
         ...(additiveReasoningProvider === undefined || !reasoningCapable
             ? {}
             : { additiveReasoningProvider }),

package/src/index.ts

@@ -45,7 +45,8 @@ export {
     loadActiveProvider,
     resetDiscoveryCache,
 } from "./ProviderRegistry.ts";
-export { providerReadiness } from "./sdkModels.ts";
+export { createEmbeddingModel, providerReadiness } from "./sdkModels.ts";
+export type { EmbeddingModelResolution } from "./sdkModels.ts";
 
 // Scope-agnostic plugin discovery ({§plugin-family-kind}).
 export { discover } from "./discover.ts";