@plurnk/plurnk-providers 1.14.0 → 1.14.2

package/src/AiSdkProvider.ts

@@ -173,8 +173,8 @@ export type AiSdkProviderConfig = {
     // `repeatPenalty` is the FLOOR the provider manages wherever a grammar rides
     // (greedy-under-mask loops without it) — the VALUE is operator config;
     // WHERE it applies stays mechanism.
-    temperature: number;
-    repeatPenalty: number;
+    temperature: number | null;
+    repeatPenalty: number | null;
     // Anti-degeneration guard on the cloud path (grammarStyle "none"), where the
     // repeat_penalty multiplier isn't available - the OpenAI-standard frequency_penalty.
     // Optional (default 0 = off) so an out-of-date plugin that omits it just runs unguarded
@@ -310,11 +310,19 @@ const projectTemplateReasoning = (content: string): TaggedReasoningProjection =>
     return { content, reasoning: "", projected: false, contentStart: 0 };
 };
 
-const fixedEffort = (mode: ReasoningPolicy): "low" | "medium" | "high" => {
-    if (mode === "low" || mode === "medium" || mode === "high") return mode;
+const fixedEffort = (mode: ReasoningPolicy): "low" | "medium" | "high" | "xhigh" | "max" => {
+    if (mode === "low" || mode === "medium" || mode === "high" || mode === "xhigh" || mode === "max") return mode;
     throw new TypeError(`reasoning policy '${mode}' is not a fixed effort`);
 };
 
+// The native SDK effort surface tops at xhigh; admission never grants a native
+// route "max", so reaching it here is a contract violation, not a fallback site.
+const nativeFixedEffort = (mode: ReasoningPolicy): "low" | "medium" | "high" | "xhigh" => {
+    const effort = fixedEffort(mode);
+    if (effort === "max") throw new TypeError(`reasoning policy 'max' has no native SDK effort surface`);
+    return effort;
+};
+
 // 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
@@ -324,6 +332,8 @@ const MANUAL_REASONING_FRACTIONS = Object.freeze({
     low: 0.1,
     medium: 0.3,
     high: 0.6,
+    xhigh: 0.75,
+    max: 0.85,
 } satisfies Record<Exclude<ReasoningPolicy, "off">, number>);
 const MANUAL_REASONING_MINIMUM = 1024;
 
@@ -385,8 +395,8 @@ export default class AiSdkProvider implements Provider {
     #compatibleAdaptiveReasoning: CompatibleReasoningEffort | "provider-default";
     #compatibleOffReasoning: "none" | undefined;
     #adaptiveReasoningProviderOptions: AiSdkProviderOptions | undefined;
-    #temperature: number;
-    #repeatPenalty: number;
+    #temperature: number | null;
+    #repeatPenalty: number | null;
     #frequencyPenalty: number;
     #dryMultiplier: number | undefined;
     #dryBase: number | undefined;
@@ -472,8 +482,8 @@ export default class AiSdkProvider implements Provider {
         // 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.
-        if (typeof config.temperature !== "number" || typeof config.repeatPenalty !== "number") {
-            throw new Error(`${config.source ?? "provider"}: AiSdkProviderConfig requires temperature + repeatPenalty (PLURNK_PROVIDERS_TEMPERATURE / _REPEAT_PENALTY)`);
+        if (config.temperature === undefined || config.repeatPenalty === undefined) {
+            throw new Error(`${config.source ?? "provider"}: AiSdkProviderConfig requires temperature + repeatPenalty declared (PLURNK_PROVIDERS_TEMPERATURE / _REPEAT_PENALTY; null = provider default)`);
         }
         this.#temperature = config.temperature;
         this.#repeatPenalty = config.repeatPenalty;
@@ -708,8 +718,11 @@ export default class AiSdkProvider implements Provider {
                 const allowance = mode === "off"
                     ? 0
                     : budget;
+                // A fixed effort rides into the template as its own variable; adaptive
+                // and off send none and leave the template's default in force.
+                const templateEffort = mode === "off" || mode === "adaptive" ? {} : { reasoning_effort: fixedEffort(mode) };
                 return {
-                    chat_template_kwargs: { enable_thinking: on },
+                    chat_template_kwargs: { enable_thinking: on, ...templateEffort },
                     reasoning_format: preserveGrammarSentence ? "none" : "auto",
                     ...(allowance === null ? {} : { thinking_budget_tokens: allowance }),
                 };
@@ -803,9 +816,9 @@ export default class AiSdkProvider implements Provider {
     #grammarBody(grammar: string | undefined): Record<string, unknown> {
         if (grammar === undefined) return {};
         switch (this.#grammarStyle) {
-            // Greedy decoding under hard constraint loops without a repeat-penalty
-            // floor — llama.cpp spells it `repeat_penalty`.
-            case "llamacpp": return { grammar, repeat_penalty: this.#repeatPenalty };
+            // Grammar-constrained decoding can loop under the mask; a configured
+            // per-alias repeat_penalty is the measured remedy ({§provider-sampling-passthrough}).
+            case "llamacpp": return { grammar, ...(this.#repeatPenalty !== null ? { repeat_penalty: this.#repeatPenalty } : {}) };
             case "none": return {};
         }
     }
@@ -825,7 +838,7 @@ export default class AiSdkProvider implements Provider {
             // repeat_last_n window — the loop-breaking tools a llama.cpp backend serves.
             // Each rides only when its operator knob is set; absent = the box's default.
             case "llamacpp": return {
-                repeat_penalty: this.#repeatPenalty,
+                ...(this.#repeatPenalty !== null ? { repeat_penalty: this.#repeatPenalty } : {}),
                 ...(this.#repeatLastN !== undefined ? { repeat_last_n: this.#repeatLastN } : {}),
                 ...(this.#dryMultiplier !== undefined && this.#dryMultiplier > 0 ? {
                     dry_multiplier: this.#dryMultiplier,
@@ -1023,7 +1036,9 @@ export default class AiSdkProvider implements Provider {
                 { capacity, extensions: { capacityStage: "preflight", capacity } },
             );
         }
-        const effectiveMaxOutputTokens = capacity.outputBudget ?? undefined;
+        // {§provider-flexed-allowance} (#482): the wire grants the flexed
+        // allowance — the floor, or the exactly-measured slack above it.
+        const effectiveMaxOutputTokens = capacity.responseMax ?? capacity.outputBudget ?? undefined;
         const nativeReasoningBudget = this.#nativeReasoningBudget(
             capacity.outputBudget,
             capacity.reasoningBudget,
@@ -1036,7 +1051,7 @@ export default class AiSdkProvider implements Provider {
         const body: Record<string, unknown> = {
             // Floors are suppressed on router-owned-tuning providers (plurnk) —
             // the router's per-model tuning must not be overridden by client floors.
-            ...(this.#tuningFloors ? { temperature: this.#temperature, ...this.#repetitionPenaltyBody() } : {}),
+            ...(this.#tuningFloors ? { ...(this.#temperature !== null ? { temperature: this.#temperature } : {}), ...this.#repetitionPenaltyBody() } : {}),
             ...this.#samplingBody(sampling),
             ...(this.#serviceTier !== undefined ? { service_tier: this.#serviceTier } : {}),
             model: this.#model,
@@ -1172,7 +1187,7 @@ export default class AiSdkProvider implements Provider {
                         captureRawBody: this.#rawBody,
                         ...(observeRequestReasoning === undefined ? {} : { observeReasoning: observeRequestReasoning }),
                         temperature: this.#tuningFloors
-                            ? (typeof sampling?.temperature === "number" ? sampling.temperature : this.#temperature)
+                            ? (typeof sampling?.temperature === "number" ? sampling.temperature : this.#temperature ?? undefined)
                             : typeof sampling?.temperature === "number" ? sampling.temperature : undefined,
                         topP: typeof sampling?.top_p === "number" ? sampling.top_p : undefined,
                         topK: typeof sampling?.top_k === "number" ? sampling.top_k : undefined,
@@ -1191,7 +1206,7 @@ export default class AiSdkProvider implements Provider {
                             ? "none"
                             : this.#reasoning.mode === "adaptive"
                                 ? this.#adaptiveReasoning
-                                : fixedEffort(this.#reasoning.mode),
+                                : nativeFixedEffort(this.#reasoning.mode),
                     });
             } catch (error) {
                 if (transportFailureOutputObserved(error)) recoveredAfterOutput = true;
@@ -1387,9 +1402,14 @@ export default class AiSdkProvider implements Provider {
             ...(meta !== undefined ? { meta } : {}),
             ...(notices !== undefined ? { notices } : {}),
         };
-        if (capacity.outputBudget !== null
+        // {§provider-flexed-allowance} (#482): conformance judges the GRANT the
+        // wire actually sent, not the configured floor — output between the two
+        // is overflow tolerance working, never a provider fault. Run7 loop-death
+        // was this guard still holding the floor after the flex landed.
+        const grantedOutput = capacity.responseMax ?? capacity.outputBudget;
+        if (grantedOutput !== null
             && usage?.outputTokens !== undefined
-            && usage.outputTokens > capacity.outputBudget) {
+            && usage.outputTokens > grantedOutput) {
             const attempt: ProviderAttempt = {
                 assistant: { ...assistant, finishReason: raw.finishReason },
                 ...evidence,
@@ -1397,13 +1417,14 @@ export default class AiSdkProvider implements Provider {
             throw new ProviderError(
                 this.#source,
                 "invalid_response",
-                `The provider reported ${usage.outputTokens} output tokens after receiving a total output budget of ${capacity.outputBudget}.`,
+                `The provider reported ${usage.outputTokens} output tokens after receiving a granted output allowance of ${grantedOutput}.`,
                 {
                     attempt,
                     accounting,
                     extensions: {
                         stage: "provider-response",
                         outputBudget: capacity.outputBudget,
+                        grantedOutput,
                         reportedOutputTokens: usage.outputTokens,
                     },
                 },

package/src/Pool.test.ts

@@ -31,6 +31,7 @@ const RESP: ProviderResponse = {
         outputBudget: 12_000,
         reasoningBudget: null,
         inputCapacity: 36_000,
+        responseMax: 12_000,
         prompt: { kind: "exact", tokens: 0, source: "test:exact" },
     },
 };
@@ -76,6 +77,7 @@ const backend = (opts: FakeOpts = {}) => {
             outputBudget: maxOutputTokens ?? opts.outputBudget ?? null,
             reasoningBudget: opts.reasoningBudget ?? null,
             inputCapacity: null,
+            responseMax: maxOutputTokens ?? opts.outputBudget ?? null,
             prompt: opts.promptMeasurement ?? {
                 kind: "exact",
                 tokens: messages.reduce((sum, { content }) => sum + content.length, 0),

package/src/Pool.ts

@@ -190,6 +190,8 @@ export default class Pool implements Provider {
             outputBudget: minimum(envelopes.map((envelope) => envelope.outputBudget)),
             reasoningBudget: minimum(envelopes.map((envelope) => envelope.reasoningBudget)),
             inputCapacity,
+            // A pool spans members whose windows differ; it never flexes ({§provider-flexed-allowance}).
+            responseMax: minimum(envelopes.map((envelope) => envelope.outputBudget)),
             prompt: measurement,
         };
     }

package/src/aiSdkTransport.test.ts

@@ -289,19 +289,19 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
     });
 });
 
-test("normalizeRetryAttemptError — attempt, first-content, and stream-idle deadlines are retryable transients ({§provider-connectivity})", () => {
+test("normalizeRetryAttemptError — deadlines surface at once, never transport-retried ({§provider-connectivity}, #479)", () => {
     const first = normalizeRetryAttemptError(new ProviderTimeoutError("first_content", 180000));
     assert.equal(APICallError.isInstance(first), true);
-    assert.equal((first as APICallError).isRetryable, true);
+    assert.equal((first as APICallError).isRetryable, false);
     const attempt = normalizeRetryAttemptError(new ProviderTimeoutError("attempt", 60000));
-    assert.equal((attempt as APICallError).isRetryable, true);
+    assert.equal((attempt as APICallError).isRetryable, false);
     const idle = normalizeRetryAttemptError(new ProviderTimeoutError("stream_idle", 120000));
-    assert.equal((idle as APICallError).isRetryable, true);
+    assert.equal((idle as APICallError).isRetryable, false);
     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)", () => {
+test("normalizeRetryAttemptError — only provider-directed waits retry: 429, Retry-After, or a directive (#479 supersedes #446)", () => {
     const garbage = new APICallError({
         message: "Failed to process successful response",
         url: "https://api.example/v1/chat/completions",
@@ -310,28 +310,43 @@ test("normalizeRetryAttemptError — a 2xx APICallError without a directive beco
         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);
+    assert.equal(normalizeRetryAttemptError(garbage), garbage, "2xx invalid-response surfaces at once — no promoted budget (#446 superseded)");
 
     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" },
+        responseHeaders: { "x-should-retry": "true" },
         isRetryable: false,
     });
-    assert.equal((normalizeRetryAttemptError(directed) as APICallError).isRetryable, false, "an explicit directive outranks the 2xx default");
+    assert.equal((normalizeRetryAttemptError(directed) as APICallError).isRetryable, true, "an explicit directive still outranks");
 
-    const clientError = new APICallError({
-        message: "bad request",
+    const rateLimited = new APICallError({
+        message: "slow down",
         url: "https://api.example/v1/chat/completions",
         requestBodyValues: {},
-        statusCode: 400,
+        statusCode: 429,
         isRetryable: false,
     });
-    assert.equal(normalizeRetryAttemptError(clientError), clientError, "non-2xx stays untouched");
+    assert.equal((normalizeRetryAttemptError(rateLimited) as APICallError).isRetryable, true, "a 429 is the provider-directed wait");
+
+    const directedWait = new APICallError({
+        message: "maintenance",
+        url: "https://api.example/v1/chat/completions",
+        requestBodyValues: {},
+        statusCode: 503,
+        responseHeaders: { "retry-after": "1" },
+        isRetryable: true,
+    });
+    assert.equal((normalizeRetryAttemptError(directedWait) as APICallError).isRetryable, true, "Retry-After on any status is a directed wait");
+
+    const bareServerError = new APICallError({
+        message: "internal error",
+        url: "https://api.example/v1/chat/completions",
+        requestBodyValues: {},
+        statusCode: 503,
+        isRetryable: true,
+    });
+    assert.equal((normalizeRetryAttemptError(bareServerError) as APICallError).isRetryable, false, "a bare 5xx surfaces at once for the engine's recovery");
 });

package/src/aiSdkTransport.ts

@@ -29,16 +29,26 @@ const retryDirective = (
     return null;
 };
 
+// {§provider-connectivity} (#479): a Retry-After header on any status is the
+// provider directing a wait (RFC 9110 defines it on 503 exactly for this);
+// its presence, like a bare 429, earns the bounded transport retry.
+const retryAfterPresent = (
+    headers: Headers | Readonly<Record<string, string>>,
+): boolean => {
+    const raw = headers instanceof Headers
+        ? headers.get("retry-after")
+        : Object.entries(headers).find(([name]) => name.toLowerCase() === "retry-after")?.[1];
+    return raw !== undefined && raw !== null && raw.trim() !== "";
+};
+
 const errorStructure: ProviderErrorStructure<z.infer<typeof errorSchema>> = {
     errorSchema,
     errorToMessage: ({ error }) => error.message,
     isRetryable(response) {
-        return retryDirective(response.status, response.headers) ?? (
-            response.status === 408
-            || response.status === 409
-            || response.status === 429
-            || response.status >= 500
-        );
+        // {§provider-connectivity} (#479): only a provider-directed wait — 429,
+        // a Retry-After, or an explicit X-Should-Retry — earns a transport retry.
+        return retryDirective(response.status, response.headers)
+            ?? (response.status === 429 || retryAfterPresent(response.headers));
     },
 };
 
@@ -254,16 +264,16 @@ export const transportFailureOutputObserved = (error: unknown): boolean => {
 
 export const normalizeRetryAttemptError = (error: unknown): unknown => {
     if (!APICallError.isInstance(error)) {
-        // Attempt, first-content, and stream-idle deadlines are retryable network
-        // failures that consume the ordinary retry budget within the operation
-        // deadline ({§provider-connectivity}); the stall is reported, never swallowed.
+        // Attempt, first-content, and stream-idle deadlines surface on the first
+        // failure ({§provider-connectivity}, #479): the engine's {§provider-recovery}
+        // owns re-issue with backoff and park; the stall is reported, never swallowed.
         if (error instanceof ProviderTimeoutError && error.phase !== "operation") {
             return retainStreamFailureValues(error, new APICallError({
                 message: error.message,
                 url: "model:generation",
                 requestBodyValues: {},
                 cause: error,
-                isRetryable: true,
+                isRetryable: false,
             }));
         }
         // Node's Undici stream reader reports a peer-aborted HTTP/2 body as this
@@ -276,33 +286,21 @@ export const normalizeRetryAttemptError = (error: unknown): unknown => {
                 url: "model:generation",
                 requestBodyValues: {},
                 cause: error,
-                isRetryable: true,
+                isRetryable: false,
             }));
         }
         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;
+    // {§provider-connectivity} (#479): without an explicit directive the only
+    // transport-retryable failures are the provider-directed waits — a 429, or
+    // any status carrying Retry-After; those live in headers the engine never
+    // sees. Every other failure — a bare 408/409/5xx, a network error, and the
+    // 2xx invalid-response #446 once promoted — surfaces at once;
+    // {§provider-recovery} owns re-issue.
+    const policy = directed
+        ?? (error.statusCode === 429 || retryAfterPresent(error.responseHeaders ?? {}));
+    if (policy === error.isRetryable) return error;
     return retainStreamFailureValues(error, new APICallError({
         message: error.message,
         url: error.url,
@@ -311,7 +309,7 @@ export const normalizeRetryAttemptError = (error: unknown): unknown => {
         responseHeaders: error.responseHeaders,
         responseBody: error.responseBody,
         cause: error,
-        isRetryable: directed,
+        isRetryable: policy,
         data: error.data,
     }));
 };
@@ -330,7 +328,7 @@ const executeModel = async (
             url: "model:generation",
             requestBodyValues: {},
             cause: timeout,
-            isRetryable: true,
+            isRetryable: false,
         });
     }
 };

package/src/capacity.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { assessRequestCapacity, effectiveInputCapacity, effectiveOutputBudget, effectiveReasoningBudget } from "./capacity.ts";
+import { assessRequestCapacity, effectiveInputCapacity, effectiveOutputBudget, effectiveReasoningBudget, flexedResponseMax } from "./capacity.ts";
 
 test("effective output budget is caller-tightenable and physically capped", () => {
     assert.equal(effectiveOutputBudget({
@@ -90,3 +90,35 @@ test("only exact overflow rejects before provider I/O", () => {
         measurement: { kind: "upper_bound", tokens: 60, source: "bound" },
     }).decision, "admit");
 });
+
+
+test("(#482) flexedResponseMax harvests exact slack above the floor", () => {
+    assert.equal(
+        flexedResponseMax({ contextWindow: 48_000, maxOutputTokens: null, outputBudget: 8_000, promptTokens: 100, margin: 256 }),
+        47_644,
+        "small prompt: the window remainder minus margin",
+    );
+    assert.equal(
+        flexedResponseMax({ contextWindow: 48_000, maxOutputTokens: null, outputBudget: 8_000, promptTokens: 40_000, margin: 256 }),
+        8_000,
+        "a full packet keeps the guaranteed floor even when margin eats the slack",
+    );
+    assert.equal(
+        flexedResponseMax({ contextWindow: 48_000, maxOutputTokens: 16_000, outputBudget: 8_000, promptTokens: 100, margin: 256 }),
+        16_000,
+        "the model's own output cap bounds the harvest",
+    );
+    assert.equal(
+        flexedResponseMax({ contextWindow: null, maxOutputTokens: null, outputBudget: 8_000, promptTokens: 100, margin: 256 }),
+        8_000,
+        "no window, no flex",
+    );
+});
+
+test("(#482) assessRequestCapacity flexes only exact measurements", () => {
+    const base = { contextWindow: 48_000, maxInputTokens: null, maxOutputTokens: null, outputBudget: 8_000, reasoningBudget: null };
+    const exact = assessRequestCapacity({ ...base, measurement: { kind: "exact", tokens: 1_000, source: "t" } });
+    assert.equal(exact.responseMax, 48_000 - 1_000 - 256, "exact prompts harvest the slack");
+    const estimate = assessRequestCapacity({ ...base, measurement: { kind: "estimate", tokens: 1_000, source: "t", detail: "chars/2 test estimate" } });
+    assert.equal(estimate.responseMax, 8_000, "estimates keep the floor — they prove nothing about the remainder");
+});

package/src/capacity.ts

@@ -81,6 +81,34 @@ export const effectiveInputCapacity = ({
     return capacities.length === 0 ? null : Math.min(...capacities);
 };
 
+// {§provider-flexed-allowance} (#482): the configured output budget is the floor
+// curation packed the input against; window room the actual prompt left
+// unclaimed is guaranteed free and becomes response runway. Only an exact
+// prompt measurement may claim slack — an estimate proves nothing about the
+// true remainder — and the model's own maxOutputTokens still caps the grant.
+export const WIRE_FLEX_MARGIN = 256;
+
+export const flexedResponseMax = ({
+    contextWindow,
+    maxOutputTokens,
+    outputBudget,
+    promptTokens,
+    margin,
+}: {
+    contextWindow: number | null;
+    maxOutputTokens: number | null;
+    outputBudget: number | null;
+    promptTokens: number;
+    margin: number;
+}): number | null => {
+    if (outputBudget === null || contextWindow === null) return outputBudget;
+    if (!Number.isSafeInteger(promptTokens) || promptTokens < 0) {
+        throw new TypeError("promptTokens must be a non-negative safe integer");
+    }
+    const flexed = Math.max(outputBudget, contextWindow - promptTokens - margin);
+    return maxOutputTokens === null ? flexed : Math.min(flexed, Math.max(outputBudget, maxOutputTokens));
+};
+
 export const requestCapacityDecision = (
     inputCapacity: number | null,
     measurement: PromptTokenMeasurement,
@@ -126,6 +154,11 @@ export const assessRequestCapacity = ({
     }
     const prompt = assertPromptTokenMeasurement(measurement, "provider capacity");
     const inputCapacity = effectiveInputCapacity({ contextWindow, maxInputTokens, outputBudget });
+    // {§provider-flexed-allowance}: exact measurements harvest the slack; every
+    // other measurement kind keeps the floor.
+    const responseMax = prompt.kind === "exact"
+        ? flexedResponseMax({ contextWindow, maxOutputTokens, outputBudget, promptTokens: prompt.tokens, margin: WIRE_FLEX_MARGIN })
+        : outputBudget;
 
     return {
         decision: requestCapacityDecision(inputCapacity, prompt),
@@ -135,6 +168,7 @@ export const assessRequestCapacity = ({
         outputBudget,
         reasoningBudget,
         inputCapacity,
+        responseMax,
         prompt,
     };
 };

package/src/catalogProvider.test.ts

@@ -3,6 +3,7 @@ import { strict as assert } from "node:assert";
 import { once } from "node:events";
 import { createServer } from "node:http";
 import { catalogProviderFromEnv, providerFromSdkModel } from "./catalogProvider.ts";
+import { withProviderDefaults } from "./defaults.ts";
 import type { LanguageModel } from "ai";
 import { resetEmittedWarnings } from "./warnings.ts";
 
@@ -41,6 +42,27 @@ test("catalog provider resolves model physics and Models.dev USD rates", () => {
     assert.deepEqual(provider?.supportedReasoningPolicies, ["off", "adaptive"]);
 });
 
+test("(#472) an effort refusal names the operator's declaration lever with the exact key", () => {
+    assert.throws(
+        () => catalogProviderFromEnv("fireworks-ai", withProviderDefaults({
+            ...env,
+            FIREWORKS_API_KEY: "test-key",
+            PLURNK_PROVIDERS_REASONING: "low",
+        }), "accounts/fireworks/models/glm-5p3-flash"),
+        /declare it: PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_EFFORTS=low/,
+        "the refusal is actionable: it names the exact env declaration",
+    );
+    // And the lever works: the same route with the declaration constructs.
+    const declared = catalogProviderFromEnv("fireworks-ai", withProviderDefaults({
+        ...env,
+        FIREWORKS_API_KEY: "test-key",
+        PLURNK_PROVIDERS_REASONING: "low",
+        PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_EFFORTS: "low,high,max",
+    }), "accounts/fireworks/models/glm-5p3-flash");
+    assert.ok(declared, "the declared effort admits the route");
+    assert.ok(declared.supportedReasoningPolicies.includes("low"), "low is admitted through the operator's declaration");
+});
+
 test("provider adapters advertise only reasoning policies they can preserve", () => {
     const deepseek = catalogProviderFromEnv("deepseek", {
         ...env,
@@ -48,7 +70,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 +94,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,
@@ -107,7 +129,7 @@ test("Models.dev controls Cloudflare's exact effort vocabulary", async () => {
         ...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-workers-ai", {
@@ -178,7 +200,7 @@ test("an operator-declared effort vocabulary extends Models.dev's for a provider
         ...declaredEnv,
         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-workers-ai", { ...declaredEnv, PLURNK_PROVIDERS_REASONING: "adaptive" }, "@cf/ibm-granite/granite-4.0-h-micro");
     assert.deepEqual(nonReasoning?.supportedReasoningPolicies, ["off", "adaptive"]);
@@ -848,6 +870,6 @@ test("(#458) declared efforts union into the supported set under the models.dev-
         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");
-    // "max" stays outside the portable wire vocabulary; "off" requires a declared "none".
-    assert.deepEqual(provider?.supportedReasoningPolicies, ["adaptive", "low", "high"]);
+    // (#474) "max" joined the portable vocabulary; "off" still requires a declared "none".
+    assert.deepEqual(provider?.supportedReasoningPolicies, ["adaptive", "low", "high", "max"]);
 });

package/src/catalogProvider.ts

@@ -10,6 +10,7 @@ import {
     effectiveContextWindow,
     dataCaptureFromEnv,
     generationEnvelopeFromEnv,
+    parseOptionalFloat,
     parseRequiredFloat,
     parseRequiredInt,
     parseTimeoutMs,
@@ -134,7 +135,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));
 };
@@ -153,6 +155,10 @@ const supportedReasoningPolicies = ({
     style: ReasoningStyle;
     declared: readonly ModelReasoningEffort[];
 }): readonly ReasoningPolicy[] => {
+    // The template style is the operator's declaration that the rail's own chat
+    // template governs reasoning: a fixed effort rides in verbatim, native SDK or
+    // not, and a word the template does not know fails loudly on the first request.
+    if (style === "template") return REASONING_POLICIES;
     if (info !== undefined && info.reasoning !== true) return activationPolicies;
     if (info?.reasoningOptions !== undefined) {
         return catalogSupportedReasoningPolicies({ info, native, style, declared });
@@ -355,8 +361,8 @@ export const providerFromSdkModel = ({
         streamIdleTimeoutMs: parseTimeoutMs(env.PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT, "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT", name),
         reasoning,
         reasoningResponseStyle: reasoningResponseStyleFromEnv(env, name),
-        temperature: parseRequiredFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", name, 0),
-        repeatPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_REPEAT_PENALTY, "PLURNK_PROVIDERS_REPEAT_PENALTY", name, 0),
+        temperature: parseOptionalFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", name, 0),
+        repeatPenalty: parseOptionalFloat(env.PLURNK_PROVIDERS_REPEAT_PENALTY, "PLURNK_PROVIDERS_REPEAT_PENALTY", name, 0),
         frequencyPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_FREQUENCY_PENALTY, "PLURNK_PROVIDERS_FREQUENCY_PENALTY", name, 0),
         retryAttempts: parseRequiredInt(env.PLURNK_PROVIDERS_RETRY_ATTEMPTS, "PLURNK_PROVIDERS_RETRY_ATTEMPTS", name),
         errorDetailLimit: parseRequiredInt(env.PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT, "PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT", name),

package/src/compatibleProvider.test.ts

@@ -83,6 +83,18 @@ test("the server-wide DRY-off floor emits no DRY request fields", async () => {
     assert.equal("dry_allowed_length" in (body ?? {}), false);
 });
 
+test("(#483) a detected llama-server rail admits the operator's stated effort", async () => {
+    mock.method(globalThis, "fetch", async (input: string | URL | Request) => {
+        const url = String(input);
+        if (url.endsWith("/models")) return new Response(JSON.stringify({ data: [{ id: "served.gguf", meta: { n_ctx: 8192 } }] }));
+        if (url.endsWith("/props")) return new Response(JSON.stringify({ total_slots: 1 }));
+        throw new Error(`unexpected request ${url}`);
+    });
+    const provider = await compatibleProviderFromEnv("openai", { ...env, PLURNK_PROVIDERS_REASONING: "medium" }, "local");
+    assert.ok(provider.supportedReasoningPolicies.includes("medium"), "the template governs: medium is admitted on a llama-server rail");
+    assert.ok(provider.supportedReasoningPolicies.includes("low") && provider.supportedReasoningPolicies.includes("high"), "the whole policy vocabulary rides; the template refuses unknown words itself");
+});
+
 test("detected llama-server measures the complete chat request through input_tokens", async () => {
     let countUrl: string | undefined;
     let countBody: Record<string, unknown> | undefined;