@plurnk/plurnk-providers 1.13.0 → 1.14.1

package/src/ProviderRegistry.test.ts

@@ -208,7 +208,7 @@ test("instantiateProvider: per-alias knobs scope through to the provider (per-al
 
 test("public construction applies the package floor to a sparse consumer environment", async () => {
     const provider = await instantiateProvider(
-        "fireworks",
+        "fireworks-ai",
         { FIREWORKS_API_KEY: "fw" },
         "deepseek-v4-pro-0813",
         async () => ({}),
@@ -290,7 +290,7 @@ test("{§deepseek-reasoning-request} #157: direct DeepSeek composes catalog fact
 test("an explicit malformed cache-affinity override still fails at its owning contract", async () => {
     await assert.rejects(
         () => instantiateProvider(
-            "fireworks",
+            "fireworks-ai",
             {
                 FIREWORKS_API_KEY: "fw",
                 PLURNK_PROVIDERS_CACHE_AFFINITY: "malformed",
@@ -299,7 +299,7 @@ test("an explicit malformed cache-affinity override still fails at its owning co
             async () => ({}),
             mapOf({}),
         ),
-        /fireworks provider: PLURNK_PROVIDERS_CACHE_AFFINITY must be "0" or "1"/,
+        /fireworks-ai provider: PLURNK_PROVIDERS_CACHE_AFFINITY must be "0" or "1"/,
     );
 });
 
@@ -307,7 +307,7 @@ test("a catalog provider with unknown model metadata never falls through to plug
     let scanned = false;
     await assert.rejects(
         () => instantiateProvider(
-            "cloudflare",
+            "cloudflare-workers-ai",
             {
                 CLOUDFLARE_ACCOUNT_ID: "account",
                 CLOUDFLARE_API_KEY: "token",
@@ -317,13 +317,13 @@ test("a catalog provider with unknown model metadata never falls through to plug
             async () => {
                 scanned = true;
                 return {
-                    registry: new Map([["cloudflare", "@plurnk/plurnk-providers-cloudflare"]]),
+                    registry: new Map([["cloudflare-workers-ai", "@plurnk/plurnk-providers-cloudflare"]]),
                     skipped: new Map(),
                     attributions: new Map(), grammarStyles: new Map(),
                 };
             },
         ),
-        /cloudflare provider: context window unresolved for "vendor\/model-outside-snapshot" — set PLURNK_PROVIDERS_CONTEXT_WINDOW or update the Models.dev snapshot/,
+        /cloudflare-workers-ai provider: context window unresolved for "vendor\/model-outside-snapshot" — set PLURNK_PROVIDERS_CONTEXT_WINDOW or update the Models.dev snapshot/,
     );
     assert.equal(scanned, false);
 });
@@ -331,7 +331,7 @@ test("a catalog provider with unknown model metadata never falls through to plug
 test("explicit metadata constructs an out-of-snapshot Cloudflare model in the consolidated transport", async () => {
     let scanned = false;
     const provider = await instantiateProvider(
-        "cloudflare",
+        "cloudflare-workers-ai",
         {
             CLOUDFLARE_ACCOUNT_ID: "account",
             CLOUDFLARE_API_KEY: "token",
@@ -342,7 +342,7 @@ test("explicit metadata constructs an out-of-snapshot Cloudflare model in the co
         async () => {
             scanned = true;
             return {
-                registry: new Map([["cloudflare", "@plurnk/plurnk-providers-cloudflare"]]),
+                registry: new Map([["cloudflare-workers-ai", "@plurnk/plurnk-providers-cloudflare"]]),
                 skipped: new Map(),
                 attributions: new Map(), grammarStyles: new Map(),
             };
@@ -378,7 +378,7 @@ test("{§provider-tagged-reasoning} a Cloudflare model alias carries its explici
         return new Response(body, { status: 200, headers: { "Content-Type": "text/event-stream" } });
     });
     const provider = await instantiateProvider(
-        "cloudflare",
+        "cloudflare-workers-ai",
         {
             ...fullEnv,
             CLOUDFLARE_ACCOUNT_ID: "account",
@@ -424,15 +424,15 @@ test("two Fireworks aliases independently select default and priority service ti
         FIREWORKS_BASE_URL: "https://api.fireworks.ai/inference/v1",
         FIREWORKS_API_KEY: "fw",
         PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192",
-        PLURNK_PROVIDERS_PROVIDER_FIREWORKS_REASONING_STYLE: "effort_explicit",
+        PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_STYLE: "effort_explicit",
         PLURNK_PROVIDERS_TOP_LOGPROBS: "2",
         PLURNK_PROVIDERS_SERVICE_TIER_fast: "priority",
         PLURNK_PROVIDERS_SERVICE_TIER_standard: "default",
     };
     const imports = async () => ({});
     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-0813", imports, discover, undefined, "standard");
+    const fast = await instantiateProvider("fireworks-ai", env, "accounts/fireworks/routers/glm-5p2-fast", imports, discover, undefined, "fast");
+    const standard = await instantiateProvider("fireworks-ai", env, "deepseek-v4-pro-0813", imports, discover, undefined, "standard");
     await fast.generate({ workerId: "fast-worker", messages: [] });
     await standard.generate({ workerId: "standard-worker", messages: [] });
     assert.deepEqual(bodies.map((body) => body.service_tier), ["priority", "default"]);

package/src/aiSdkTransport.test.ts

@@ -300,3 +300,38 @@ test("normalizeRetryAttemptError — attempt, first-content, and stream-idle dea
     const operation = new ProviderTimeoutError("operation", 2700000);
     assert.equal(normalizeRetryAttemptError(operation), operation);
 });
+
+test("normalizeRetryAttemptError — a 2xx APICallError without a directive becomes retryable; a directive outranks; non-2xx untouched (#446)", () => {
+    const garbage = new APICallError({
+        message: "Failed to process successful response",
+        url: "https://api.example/v1/chat/completions",
+        requestBodyValues: {},
+        statusCode: 200,
+        responseBody: "not json",
+        isRetryable: false,
+    });
+    const normalized = normalizeRetryAttemptError(garbage) as APICallError;
+    assert.ok(APICallError.isInstance(normalized));
+    assert.equal(normalized.isRetryable, true, "2xx invalid-response consumes the retry budget");
+    assert.equal(normalized.cause, garbage, "the original failure rides as the cause");
+    assert.equal(normalized.statusCode, 200);
+
+    const directed = new APICallError({
+        message: "Failed to process successful response",
+        url: "https://api.example/v1/chat/completions",
+        requestBodyValues: {},
+        statusCode: 200,
+        responseHeaders: { "x-should-retry": "false" },
+        isRetryable: false,
+    });
+    assert.equal((normalizeRetryAttemptError(directed) as APICallError).isRetryable, false, "an explicit directive outranks the 2xx default");
+
+    const clientError = new APICallError({
+        message: "bad request",
+        url: "https://api.example/v1/chat/completions",
+        requestBodyValues: {},
+        statusCode: 400,
+        isRetryable: false,
+    });
+    assert.equal(normalizeRetryAttemptError(clientError), clientError, "non-2xx stays untouched");
+});

package/src/aiSdkTransport.ts

@@ -282,6 +282,26 @@ export const normalizeRetryAttemptError = (error: unknown): unknown => {
         return error;
     }
     const directed = retryDirective(error.statusCode, error.responseHeaders ?? {});
+    // A 2xx APICallError with no explicit retry directive is a provider
+    // invalid-response: the exchange succeeded and the body was unusable (a
+    // serializer hiccup, a truncated frame). That is the same transient class as
+    // a transport failure and consumes the same bounded retry budget; an explicit
+    // `x-should-retry` directive outranks this default, and the terminal
+    // classification after the budget stays the non-retryable 502 (#446).
+    if (directed === null
+        && typeof error.statusCode === "number" && error.statusCode >= 200 && error.statusCode < 300
+        && error.isRetryable !== true) {
+        return retainStreamFailureValues(error, new APICallError({
+            message: error.message,
+            url: error.url,
+            requestBodyValues: error.requestBodyValues,
+            statusCode: error.statusCode,
+            responseHeaders: error.responseHeaders,
+            responseBody: error.responseBody,
+            cause: error,
+            isRetryable: true,
+        }));
+    }
     if (directed === null || directed === error.isRetryable) return error;
     return retainStreamFailureValues(error, new APICallError({
         message: error.message,

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", "low", "high"]);
+    assert.deepEqual(deepseek?.supportedReasoningPolicies, ["off", "adaptive", "low", "high", "max"]);
 
     assert.throws(
         () => catalogProviderFromEnv("deepseek", {
@@ -72,7 +72,7 @@ test("provider adapters advertise only reasoning policies they can preserve", ()
         XAI_API_KEY: "test-key",
         PLURNK_PROVIDERS_REASONING: "adaptive",
     }, "grok-4.6");
-    assert.deepEqual(grok?.supportedReasoningPolicies, ["adaptive", "low", "medium", "high"], "Grok 4.6 cannot disable reasoning");
+    assert.deepEqual(grok?.supportedReasoningPolicies, ["adaptive", "low", "medium", "high", "xhigh"], "Grok 4.6 cannot disable reasoning");
 
     const gemini = catalogProviderFromEnv("google", {
         ...env,
@@ -101,29 +101,29 @@ test("Models.dev controls Cloudflare's exact effort vocabulary", async () => {
         ...env,
         CLOUDFLARE_ACCOUNT_ID: "account",
         CLOUDFLARE_API_KEY: "token",
-        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_REASONING_STYLE: "effort_required",
+        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_STYLE: "effort_required",
     };
-    const low = catalogProviderFromEnv("cloudflare", {
+    const low = catalogProviderFromEnv("cloudflare-workers-ai", {
         ...cloudflareEnv,
         PLURNK_PROVIDERS_REASONING: "low",
     }, "@cf/qwen/qwen3.8-27b");
-    assert.deepEqual(low?.supportedReasoningPolicies, ["adaptive", "low", "medium"]);
+    assert.deepEqual(low?.supportedReasoningPolicies, ["adaptive", "low", "medium", "xhigh"]);
     await low?.generate({ workerId: "cloudflare-low", messages: [{ role: "user", content: "hello" }] });
 
-    const adaptive = catalogProviderFromEnv("cloudflare", {
+    const adaptive = catalogProviderFromEnv("cloudflare-workers-ai", {
         ...cloudflareEnv,
         PLURNK_PROVIDERS_REASONING: "adaptive",
     }, "@cf/qwen/qwen3.8-27b");
     await adaptive?.generate({ workerId: "cloudflare-adaptive", messages: [{ role: "user", content: "hello" }] });
 
-    const nonReasoning = catalogProviderFromEnv("cloudflare", {
+    const nonReasoning = catalogProviderFromEnv("cloudflare-workers-ai", {
         ...cloudflareEnv,
         PLURNK_PROVIDERS_REASONING: "adaptive",
     }, "@cf/ibm-granite/granite-4.0-h-micro");
     assert.deepEqual(nonReasoning?.supportedReasoningPolicies, ["off", "adaptive"]);
     await nonReasoning?.generate({ workerId: "cloudflare-granite", messages: [{ role: "user", content: "hello" }] });
 
-    const ungradedReasoner = catalogProviderFromEnv("cloudflare", {
+    const ungradedReasoner = catalogProviderFromEnv("cloudflare-workers-ai", {
         ...cloudflareEnv,
         PLURNK_PROVIDERS_REASONING: "adaptive",
     }, "@cf/zai-org/glm-5.3-flash");
@@ -132,11 +132,11 @@ test("Models.dev controls Cloudflare's exact effort vocabulary", async () => {
 
     assert.deepEqual(bodies.map((body) => body.reasoning_effort), ["low", "xhigh", undefined, undefined]);
     assert.throws(
-        () => catalogProviderFromEnv("cloudflare", cloudflareEnv, "@cf/qwen/qwen3.8-27b"),
+        () => catalogProviderFromEnv("cloudflare-workers-ai", cloudflareEnv, "@cf/qwen/qwen3.8-27b"),
         /reasoning policy 'off' is unsupported; supported policies: adaptive, low, medium/,
     );
     assert.throws(
-        () => catalogProviderFromEnv("cloudflare", {
+        () => catalogProviderFromEnv("cloudflare-workers-ai", {
             ...cloudflareEnv,
             PLURNK_PROVIDERS_REASONING: "high",
         }, "@cf/qwen/qwen3.8-27b"),
@@ -163,31 +163,31 @@ test("an operator-declared effort vocabulary extends Models.dev's for a provider
         ...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",
+        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_STYLE: "effort_required",
+        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_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");
+    const low = catalogProviderFromEnv("cloudflare-workers-ai", { ...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");
+    const adaptive = catalogProviderFromEnv("cloudflare-workers-ai", { ...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", {
+    const withOff = catalogProviderFromEnv("cloudflare-workers-ai", {
         ...declaredEnv,
-        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_REASONING_EFFORTS: "none,high",
+        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_EFFORTS: "none,high",
     }, "@cf/qwen/qwen3.8-27b");
-    assert.deepEqual(withOff?.supportedReasoningPolicies, ["off", "adaptive", "low", "medium", "high"]);
+    assert.deepEqual(withOff?.supportedReasoningPolicies, ["off", "adaptive", "low", "medium", "high", "xhigh"]);
     // 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");
+    const nonReasoning = catalogProviderFromEnv("cloudflare-workers-ai", { ...declaredEnv, PLURNK_PROVIDERS_REASONING: "adaptive" }, "@cf/ibm-granite/granite-4.0-h-micro");
     assert.deepEqual(nonReasoning?.supportedReasoningPolicies, ["off", "adaptive"]);
     assert.throws(
-        () => catalogProviderFromEnv("cloudflare", {
+        () => catalogProviderFromEnv("cloudflare-workers-ai", {
             ...declaredEnv,
-            PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_REASONING_EFFORTS: "low,turbo",
+            PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_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/,
+        /PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_EFFORTS has invalid value "turbo"; declarable efforts: none, minimal, low, medium, high, xhigh, max/,
     );
 });
 
@@ -686,6 +686,60 @@ test("native provider routes project their documented cache controls through the
             content: "changing user packet",
         });
     });
+
+    await t.test("{§provider-reasoning-policy} a resolved reasoning budget reaches the OpenRouter wire as max_tokens", async () => {
+        let call: { body: Record<string, unknown> } | undefined;
+        const server = createServer(async (request, response) => {
+            const chunks: Buffer[] = [];
+            for await (const chunk of request) chunks.push(Buffer.from(chunk));
+            call = { body: JSON.parse(Buffer.concat(chunks).toString("utf8")) as Record<string, unknown> };
+            response.writeHead(200, { "content-type": "text/event-stream" });
+            response.end([
+                `data: ${JSON.stringify({
+                    id: "response",
+                    object: "chat.completion.chunk",
+                    created: 1,
+                    model: "served",
+                    choices: [{ index: 0, delta: { content: "ok" }, finish_reason: "stop" }],
+                })}`,
+                "data: [DONE]",
+            ].join("\n\n"));
+        });
+        server.listen(0, "127.0.0.1");
+        await once(server, "listening");
+        t.after(() => new Promise<void>((resolve, reject) => {
+            server.close((error) => error === undefined ? resolve() : reject(error));
+        }));
+        const address = server.address();
+        if (address === null || typeof address === "string") {
+            throw new Error("OpenRouter budget-capture server did not bind a TCP address");
+        }
+        const budgetEnv = {
+            ...env,
+            OPENROUTER_API_KEY: "test-key",
+            OPENROUTER_HTTP_REFERER: "https://github.com/plurnk/plurnk-service",
+            OPENROUTER_APP_TITLE: "Plurnk",
+            PLURNK_PROVIDERS_REASONING_BUDGET: "2048",
+        };
+        const adaptive = catalogProviderFromEnv("openrouter", {
+            ...budgetEnv,
+            PLURNK_PROVIDERS_REASONING: "adaptive",
+        }, "anthropic/claude-sonnet-4.6", `http://127.0.0.1:${address.port}/api/v1`);
+        await adaptive?.generate({
+            workerId: "openrouter-budget",
+            messages: [{ role: "user", content: "budgeted" }],
+        });
+        assert.deepEqual(call?.body.reasoning, { max_tokens: 2048 });
+        const fixed = catalogProviderFromEnv("openrouter", {
+            ...budgetEnv,
+            PLURNK_PROVIDERS_REASONING: "low",
+        }, "anthropic/claude-sonnet-4.6", `http://127.0.0.1:${address.port}/api/v1`);
+        await fixed?.generate({
+            workerId: "openrouter-budget",
+            messages: [{ role: "user", content: "budgeted" }],
+        });
+        assert.deepEqual(call?.body.reasoning, { effort: "low" }, "a fixed policy keeps the effort form");
+    });
 });
 
 test("cataloged unknown model fails unless its context is explicit", () => {
@@ -749,3 +803,51 @@ test("Models.dev is the only fallback rate table", async () => {
         reason: "Models.dev has no complete rate for this model",
     });
 });
+
+test("{§operator-cost-override} declared rates overlay the catalog and the source names the override", async () => {
+    mock.method(globalThis, "fetch", async () => new Response([
+        `data: ${JSON.stringify({
+            id: "response",
+            model: "served",
+            choices: [{ index: 0, delta: { content: "ok" }, finish_reason: "stop" }],
+        })}`,
+        `data: ${JSON.stringify({
+            id: "response",
+            model: "served",
+            choices: [],
+            usage: {
+                prompt_tokens: 1_000,
+                prompt_tokens_details: { cached_tokens: 400 },
+                completion_tokens: 100,
+                total_tokens: 1_150,
+            },
+        })}`,
+        "data: [DONE]",
+    ].join("\n\n"), { headers: { "content-type": "text/event-stream" } }));
+    const overridden = catalogProviderFromEnv("deepseek", {
+        ...env,
+        DEEPSEEK_API_KEY: "test-key",
+        PLURNK_PROVIDERS_REASONING: "adaptive",
+        PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_STYLE: "thinking_effort",
+        PLURNK_PROVIDERS_COST: "input=0.22,output=0.66,cacheRead=0.007",
+    }, "deepseek-v4-flash");
+    const response = await overridden!.generate({ workerId: "overridden", messages: [] });
+    assert.deepEqual(response.accounting[0]?.cost, {
+        kind: "estimated",
+        amount: { amount: "0.0002148", currency: "USD" },
+        source: "operator PLURNK_PROVIDERS_COST override over Models.dev catalog rates",
+    });
+    mock.restoreAll();
+});
+
+test("(#458) declared efforts union into the supported set under the models.dev-id prefix", () => {
+    const provider = catalogProviderFromEnv("fireworks-ai", {
+        ...env,
+        FIREWORKS_API_KEY: "test-key",
+        PLURNK_PROVIDERS_REASONING: "adaptive",
+        PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_STYLE: "effort_explicit",
+        PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_EFFORTS: "low,high,max",
+    }, "accounts/fireworks/models/glm-5p3-flash");
+    // (#474) "max" joined the portable vocabulary; "off" still requires a declared "none".
+    assert.deepEqual(provider?.supportedReasoningPolicies, ["adaptive", "low", "high", "max"]);
+});

package/src/catalogProvider.ts

@@ -5,6 +5,7 @@ import {
     type ModelReasoningEffort,
 } from "@plurnk/plurnk-models";
 import {
+    costOverrideFromEnv,
     contextWindowFromEnv,
     effectiveContextWindow,
     dataCaptureFromEnv,
@@ -133,7 +134,8 @@ const catalogSupportedReasoningPolicies = ({
             || (catalogSupportsToggle(info) && compatibleToggleStyles.has(style));
     return REASONING_POLICIES.filter((policy) => policy === "adaptive"
         || policy === "off" && off
-        || (policy === "low" || policy === "medium" || policy === "high")
+        || (policy === "low" || policy === "medium" || policy === "high"
+                || policy === "xhigh" || policy === "max")
             && effortTransport
             && efforts.has(policy));
 };
@@ -289,7 +291,7 @@ export const providerFromSdkModel = ({
         : "none" as const;
 
     const catalogCost = info?.cost;
-    const rates = catalogCost === undefined ? null : {
+    const catalogRates = catalogCost === undefined ? null : {
         input: catalogCost.inputPer1M,
         output: catalogCost.outputPer1M,
         ...(catalogCost.reasoningPer1M === undefined
@@ -302,8 +304,23 @@ export const providerFromSdkModel = ({
             ? {}
             : { cacheWrite: catalogCost.cacheWritePer1M }),
     };
+    // {§operator-cost-override} (#461): the catalog is the starting point; a declared
+    // override merges over it, and the estimate's source names the overlay.
+    const costOverride = costOverrideFromEnv(env, name);
+    if (costOverride !== null && catalogRates === null
+        && (costOverride.input === undefined || costOverride.output === undefined)) {
+        throw new Error(
+            `${name} provider: PLURNK_PROVIDERS_COST without catalog rates must declare input and output`,
+        );
+    }
+    const rates = costOverride === null
+        ? catalogRates
+        : { ...(catalogRates ?? {}), ...costOverride } as NonNullable<typeof catalogRates>;
+    const rateSource = costOverride === null
+        ? "Models.dev catalog rates"
+        : "operator PLURNK_PROVIDERS_COST override over Models.dev catalog rates";
     const estimateCost = (usage: Parameters<typeof estimateProviderCost>[0]) =>
-        estimateProviderCost(usage, rates, "Models.dev catalog rates");
+        estimateProviderCost(usage, rates, rateSource);
     const affinityEnabled = cacheAffinityFromEnv(env, name);
     const cacheWritePolicy = cacheWritePolicyFromEnv(env, name);
 
@@ -319,6 +336,8 @@ export const providerFromSdkModel = ({
         maxOutputTokens,
         outputBudget: envelope.outputBudget,
         reasoningBudget: reasoning.budget,
+        // #457 — a catalog-declared toggle control makes `adaptive` an explicit enable.
+        reasoningToggle: info?.reasoningOptions?.some((option) => option.type === "toggle") === true,
         supportedReasoningPolicies: supportedReasoningPolicies({
             info,
             native: languageModel !== undefined,
@@ -377,9 +396,6 @@ export const catalogProviderFromEnv = (
         );
     }
     const wireModel = resolved?.id ?? model;
-    const sdk = createSdkModel(name, wireModel, env, baseUrlOverride, reasoningFromEnv(env, name).mode);
-    if (sdk === null) return null;
-
     const info = resolved?.info;
     const contextWindow = effectiveContextWindow(contextOverride, info?.contextWindow ?? null);
     if (contextWindow === null) {
@@ -387,6 +403,17 @@ export const catalogProviderFromEnv = (
             `${name} provider: context window unresolved for "${wireModel}" — set PLURNK_PROVIDERS_CONTEXT_WINDOW or update the Models.dev snapshot`,
         );
     }
+    const maxOutputTokens = info?.maxOutputTokens === undefined
+        ? null
+        : Math.min(info.maxOutputTokens, contextWindow);
+    const reasoning = reasoningFromEnv(
+        env,
+        name,
+        generationEnvelopeFromEnv(env, name, contextWindow, maxOutputTokens).reasoningBudget,
+    );
+    const sdk = createSdkModel(name, wireModel, env, baseUrlOverride, reasoning.mode, reasoning.budget);
+    if (sdk === null) return null;
+
     return providerFromSdkModel({
         name,
         env,

package/src/env.test.ts

@@ -1,6 +1,8 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
 import {
+    scopeEnvToAlias,
+    costOverrideFromEnv,
     cacheAffinityFromEnv,
     cacheWritePolicyFromEnv,
     generationEnvelopeFromEnv,
@@ -55,19 +57,19 @@ test("reasoningFromEnv: durable policy is independent from an optional explicit
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "high" }, "openai", 4096), { mode: "high", budget: 4096 });
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "adaptive" }, "openai", 4096), { mode: "adaptive", budget: 4096 });
     assert.throws(() => reasoningFromEnv({}, "openai"), /PLURNK_PROVIDERS_REASONING must be set/);
-    assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "8192" }, "openai"), /must be one of "off", "adaptive", "low", "medium", "high"/); // the old numeric habit fails loudly
+    assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "8192" }, "openai"), /must be one of "off", "adaptive", "low", "medium", "high", "xhigh", "max"/); // the old numeric habit fails loudly
 });
 
 test("{§provider-tagged-reasoning} response style is explicit and invalid values fail at the provider boundary", () => {
-    assert.equal(reasoningResponseStyleFromEnv({}, "cloudflare"), "verbatim");
+    assert.equal(reasoningResponseStyleFromEnv({}, "cloudflare-workers-ai"), "verbatim");
     assert.equal(reasoningResponseStyleFromEnv({
         PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE: "think-tags",
-    }, "cloudflare"), "think-tags");
+    }, "cloudflare-workers-ai"), "think-tags");
     assert.throws(
         () => reasoningResponseStyleFromEnv({
             PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE: "auto",
-        }, "cloudflare"),
-        /cloudflare provider: PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE must be "verbatim" or "think-tags" \(got "auto"\)/,
+        }, "cloudflare-workers-ai"),
+        /cloudflare-workers-ai provider: PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE must be "verbatim" or "think-tags" \(got "auto"\)/,
     );
 });
 
@@ -97,7 +99,7 @@ test("the generic prompt-cache-key knob is retired rather than retained as a com
         () => cacheAffinityFromEnv({
             PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "1",
             PLURNK_PROVIDERS_CACHE_AFFINITY: "1",
-        }, "fireworks"),
+        }, "fireworks-ai"),
         /PLURNK_PROVIDERS_PROMPT_CACHE_KEY was renamed to PLURNK_PROVIDERS_CACHE_AFFINITY/,
     );
 });
@@ -225,16 +227,16 @@ test("still-set old THINKING names fail hard with the rename pointer", () => {
 });
 
 test("reasoning policy accepts only the exact portable durable vocabulary", () => {
-    for (const mode of ["off", "adaptive", "low", "medium", "high"] as const) {
+    for (const mode of ["off", "adaptive", "low", "medium", "high", "xhigh", "max"] as const) {
         assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: mode }, "openai"), {
             mode,
             budget: null,
         });
     }
-    for (const retired of ["on", "minimal", "xhigh"]) {
+    for (const retired of ["on", "minimal", "ultra"]) {
         assert.throws(
             () => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: retired }, "openai"),
-            /must be one of "off", "adaptive", "low", "medium", "high"/,
+            /must be one of "off", "adaptive", "low", "medium", "high", "xhigh", "max"/,
         );
     }
 });
@@ -312,3 +314,18 @@ test("a retired envelope knob is refused in its per-alias form too, naming the k
         /PLURNK_PROVIDERS_REASONING_RESERVE_rtxgemma is retired/,
     );
 });
+
+test("{§operator-cost-override} costOverrideFromEnv parses the catalog vocabulary and refuses drift", () => {
+    assert.equal(costOverrideFromEnv({}, "x"), null);
+    assert.deepEqual(
+        costOverrideFromEnv({ PLURNK_PROVIDERS_COST: "input=0.22, output=0.66,cacheRead=0.007" }, "x"),
+        { input: 0.22, output: 0.66, cacheRead: 0.007 },
+    );
+    assert.throws(() => costOverrideFromEnv({ PLURNK_PROVIDERS_COST: "cache_read=0.007" }, "x"), /key=value over input, output, reasoning, cacheRead, cacheWrite/);
+    assert.throws(() => costOverrideFromEnv({ PLURNK_PROVIDERS_COST: "input=" }, "x"), /non-negative per-1M-token USD rate/);
+    assert.throws(() => costOverrideFromEnv({ PLURNK_PROVIDERS_COST: "input=-1" }, "x"), /non-negative/);
+    assert.throws(() => costOverrideFromEnv({ PLURNK_PROVIDERS_COST: "input=0.1,input=0.2" }, "x"), /repeats input/);
+    // Alias-scoped like every provider knob.
+    const scoped = scopeEnvToAlias({ PLURNK_PROVIDERS_COST_deepdumb: "input=0.44,output=1.32" }, "deepdumb");
+    assert.deepEqual(costOverrideFromEnv(scoped, "x"), { input: 0.44, output: 1.32 });
+});

package/src/env.ts

@@ -291,6 +291,7 @@ export const reasoningFromEnv = (
 // facts (API keys, canonical endpoints) remain vendor-named; the per-alias
 // endpoint override stays PLURNK_BASEURL_<alias> (its existing precedent).
 export const PROVIDERS_KNOBS = Object.freeze([
+    "PLURNK_PROVIDERS_COST",
     "PLURNK_PROVIDERS_OUTPUT_BUDGET",
     "PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE",
     "PLURNK_PROVIDERS_REASONING_BUDGET",
@@ -330,6 +331,34 @@ export const PROVIDERS_KNOBS = Object.freeze([
 // same parser — e.g. service loop policy or prompt projection — without
 // reimplementing the suffix/collision rules. Default stays the
 // providers-family list; provider call sites pass nothing.
+// {§operator-cost-override} (#461) — Models.dev is the rate starting point; the
+// operator overlays exact per-1M-token USD rates when a provider reprices ahead
+// of the catalog. Format: comma-separated key=value over the catalog vocabulary
+// (input, output, reasoning, cacheRead, cacheWrite). Alias-scoped like every
+// provider knob.
+const COST_OVERRIDE_KEYS = Object.freeze(["input", "output", "reasoning", "cacheRead", "cacheWrite"] as const);
+export type CostOverride = Partial<Record<(typeof COST_OVERRIDE_KEYS)[number], number>>;
+export const costOverrideFromEnv = (env: NodeJS.ProcessEnv, label: string): CostOverride | null => {
+    const name = "PLURNK_PROVIDERS_COST";
+    const raw = env[name];
+    if (raw === undefined || raw.trim().length === 0) return null;
+    const out: Partial<Record<string, number>> = {};
+    for (const part of raw.split(",")) {
+        const [key, value, ...rest] = part.split("=").map((piece) => piece.trim());
+        if (rest.length > 0 || key === undefined || value === undefined
+            || !(COST_OVERRIDE_KEYS as readonly string[]).includes(key)) {
+            throw new Error(`${label} provider: ${name} entries are key=value over ${COST_OVERRIDE_KEYS.join(", ")} (per-1M-token USD); got ${JSON.stringify(part)}`);
+        }
+        if (key in out) throw new Error(`${label} provider: ${name} repeats ${key}`);
+        const parsed = Number(value);
+        if (value.length === 0 || !Number.isFinite(parsed) || parsed < 0) {
+            throw new Error(`${label} provider: ${name} ${key} must be a non-negative per-1M-token USD rate; got ${JSON.stringify(value)}`);
+        }
+        out[key] = parsed;
+    }
+    return out as CostOverride;
+};
+
 export const scopeEnvToAlias = (env: NodeJS.ProcessEnv, alias: string, knobs: readonly string[] = PROVIDERS_KNOBS): NodeJS.ProcessEnv => {
     const folded = alias.toLowerCase();
     const out: NodeJS.ProcessEnv = { ...env };

package/src/providerDefaults.test.ts

@@ -2,7 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { lookupProvider, providerIdMap } from "@plurnk/plurnk-models";
+import { lookupProvider } from "@plurnk/plurnk-models";
 
 const defaultsPath = fileURLToPath(new URL("../.env.defaults", import.meta.url));
 const declarations = readFileSync(defaultsPath, "utf8")
@@ -19,16 +19,17 @@ const providerFact = (key: string): { provider: string; fact: string } | null =>
 };
 
 test("{§provider-fact-authority} package defaults never redefine cataloged provider facts", () => {
-    const ids = providerIdMap();
+    // (#459) the env prefix IS the Models.dev id, underscored; probe both spellings.
     for (const { key, value } of declarations) {
         const fact = providerFact(key);
         if (fact === null) continue;
-        const catalogId = ids[fact.provider] ?? fact.provider;
-        assert.equal(
-            lookupProvider(catalogId),
-            null,
-            `package default '${key}=${value}' redefines a Models.dev-cataloged provider fact (${catalogId})`,
-        );
+        for (const candidate of new Set([fact.provider, fact.provider.replaceAll("_", "-")])) {
+            assert.equal(
+                lookupProvider(candidate),
+                null,
+                `package default '${key}=${value}' redefines a Models.dev-cataloged provider fact (${candidate})`,
+            );
+        }
     }
 });