@plurnk/plurnk-providers 1.14.0 → 1.14.2

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/env.test.ts

@@ -57,7 +57,7 @@ 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", () => {
@@ -227,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"/,
         );
     }
 });

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/sdkModels.ts

@@ -328,6 +328,12 @@ const openRouterReasoningSettings = (
         if (reasoningBudget !== null) return { reasoning: { max_tokens: reasoningBudget } };
         return reasoningCapable ? { reasoning: { enabled: true } } : {};
     }
+    // OpenRouter documents effort none/low/medium/high; xhigh/max reach this
+    // seam only if a catalog row declares them — refuse with the gap named
+    // rather than ship an unverified wire value (#474 widens on evidence).
+    if (reasoning === "xhigh" || reasoning === "max") {
+        throw new TypeError(`openrouter reasoning effort '${reasoning}' is not a documented wire value`);
+    }
     return { reasoning: { effort: reasoning === "off" ? "none" : reasoning } };
 };
 

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;
 }