@plurnk/plurnk-providers 1.14.1 → 1.14.2

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,

package/src/catalogProvider.ts

@@ -10,6 +10,7 @@ import {
     effectiveContextWindow,
     dataCaptureFromEnv,
     generationEnvelopeFromEnv,
+    parseOptionalFloat,
     parseRequiredFloat,
     parseRequiredInt,
     parseTimeoutMs,
@@ -154,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 });
@@ -356,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;

package/src/compatibleProvider.ts

@@ -1,3 +1,4 @@
+import { REASONING_POLICIES } from "@plurnk/plurnk-contracts";
 import AiSdkProvider, { type GrammarStyle, type ReasoningStyle } from "./AiSdkProvider.ts";
 import {
     contextWindowFromEnv,
@@ -182,7 +183,9 @@ export const compatibleProviderFromEnv = async (
     }
     const envelope = generationEnvelopeFromEnv(env, provider, contextWindow, null);
     const reasoning = reasoningFromEnv(env, provider, envelope.reasoningBudget);
-    const supportedReasoningPolicies = ["off", "adaptive"] as const;
+    // A detected llama-server rail runs the template style: the chat template governs
+    // reasoning, so the operator's stated effort is admitted and forwarded verbatim (#483).
+    const supportedReasoningPolicies = reasoningStyle === "template" ? REASONING_POLICIES : (["off", "adaptive"] as const);
     return new AiSdkProvider({
         model,
         url,
@@ -200,8 +203,8 @@ export const compatibleProviderFromEnv = async (
         reasoning,
         reasoningResponseStyle: reasoningResponseStyleFromEnv(env, provider),
         reasoningStyle,
-        temperature: parseRequiredFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", provider, 0),
-        repeatPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_REPEAT_PENALTY, "PLURNK_PROVIDERS_REPEAT_PENALTY", provider, 0),
+        temperature: parseOptionalFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", provider, 0),
+        repeatPenalty: parseOptionalFloat(env.PLURNK_PROVIDERS_REPEAT_PENALTY, "PLURNK_PROVIDERS_REPEAT_PENALTY", provider, 0),
         frequencyPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_FREQUENCY_PENALTY, "PLURNK_PROVIDERS_FREQUENCY_PENALTY", provider, 0),
         dryMultiplier: parseOptionalFloat(env.PLURNK_PROVIDERS_DRY_MULTIPLIER, "PLURNK_PROVIDERS_DRY_MULTIPLIER", provider, 0) ?? undefined,
         dryBase: parseOptionalFloat(env.PLURNK_PROVIDERS_DRY_BASE, "PLURNK_PROVIDERS_DRY_BASE", provider, 0) ?? undefined,

package/src/errors.test.ts

@@ -126,6 +126,7 @@ test("#161: ProviderError carries resource-interrupted attempt evidence outside
             maxInputTokens: null,
             maxOutputTokens: null,
             outputBudget: null,
+            responseMax: null,
             reasoningBudget: null,
             inputCapacity: null,
             prompt: {

package/src/errors.ts

@@ -46,6 +46,17 @@ export const providerTimeoutOf = (error: unknown): ProviderTimeoutError | null =
     return null;
 };
 
+const peerTerminated = (err: unknown): boolean => {
+    const seen = new Set<unknown>();
+    let cur: unknown = err;
+    while (typeof cur === "object" && cur !== null && !seen.has(cur)) {
+        seen.add(cur);
+        if (cur instanceof TypeError && cur.message.trim().toLowerCase() === "terminated") return true;
+        cur = (cur as { cause?: unknown }).cause;
+    }
+    return false;
+};
+
 const wireError = (body: string): { type: string | null; code: string | null; message: string | null } => {
     try {
         const { error } = JSON.parse(body) as { error?: { type?: unknown } };
@@ -100,13 +111,23 @@ export const classifyProviderError = (
             : "The provider request failed without a diagnostic message.";
         const body = err.responseBody ?? "";
         const wire = wireError(body);
+        // A peer-terminated body inside a 2xx exchange is a network truth, not
+        // an invalid response — the SDK wraps Undici's TypeError("terminated")
+        // as a processing failure, but the KIND must stay engine-recoverable
+        // (#479). Walk the cause chain for the termination signature.
+        if (peerTerminated(err)) {
+            return { kind: "network_failure", message, retryable: err.isRetryable };
+        }
         if (status === 401 || status === 403) return { kind: "unauthorized", message };
         if (status === 402) return { kind: "quota_exceeded", message };
         if (status === 429) return { kind: "rate_limit", message, retryable: err.isRetryable };
         if (status === 408 || status === 409) {
             return { kind: "network_failure", message, retryable: err.isRetryable };
         }
-        if (status === 0 && err.isRetryable) return { kind: "network_failure", message };
+        // Status 0 is a transport-level failure (no HTTP exchange settled); its
+        // KIND stays network_failure regardless of the transport's retry policy
+        // (#479) — the engine's recovery keys on kind, never the retryable flag.
+        if (status === 0) return { kind: "network_failure", message, retryable: err.isRetryable };
         if (status >= 500) return { kind: "network_failure", message, retryable: err.isRetryable };
         if (status === 413 || (
             (status === 400 || status === 422)

package/src/types.ts

@@ -32,7 +32,15 @@ export class UnsupportedReasoningPolicyError extends Error {
     readonly supported: readonly ReasoningPolicy[];
 
     constructor(source: string, policy: ReasoningPolicy, supported: readonly ReasoningPolicy[]) {
-        super(`${source}: reasoning policy '${policy}' is unsupported; supported policies: ${supported.join(", ")}`);
+        // A graded-effort refusal names the operator's declaration lever (#472):
+        // the catalog is authoritative per model, and where a provider's API
+        // accepts more than its catalog entry lists, the remedy is the
+        // operator's, never a vendored fact in shipped defaults.
+        const providerName = /^provider:(.+)$/.exec(source)?.[1];
+        const lever = policy === "off" || policy === "adaptive"
+            ? ""
+            : ` If the provider's API documents this effort beyond its catalog entry, declare it: PLURNK_PROVIDERS_PROVIDER_${(providerName ?? "<NAME>").replaceAll(/[^a-zA-Z0-9<>]/g, "_").toUpperCase()}_REASONING_EFFORTS=${policy} (comma-separated).`;
+        super(`${source}: reasoning policy '${policy}' is unsupported; supported policies: ${supported.join(", ")}.${lever}`);
         this.name = "UnsupportedReasoningPolicyError";
         this.policy = policy;
         this.supported = supported;
@@ -82,6 +90,9 @@ export interface ProviderRequestCapacity {
     readonly outputBudget: number | null;
     readonly reasoningBudget: number | null;
     readonly inputCapacity: number | null;
+    // {§provider-flexed-allowance} (#482): the response allowance actually
+    // granted this request — the floor, or the exactly-measured slack above it.
+    readonly responseMax: number | null;
     readonly prompt: PromptTokenMeasurement;
 }