@plurnk/plurnk-providers 1.16.4 → 1.17.0

package/src/aiSdkTransport.ts

@@ -89,6 +89,25 @@ const wireUsageOf = (
     return undefined;
 };
 
+// {§provider-usage-refusal} — the provider's bookkeeping is not the exchange. When the reported
+// counters cannot be normalized (a reasoning detail exceeding its output aggregate, a total that
+// contradicts its parts), the response stands, usage is unknown (never invented, clamped, or zero),
+// and the counters as reported ride beside the refusal so forensics can see what the wire said.
+export type UsageRefusal = { readonly reason: string; readonly usage: unknown };
+
+const settledUsage = (
+    values: readonly unknown[],
+    sdkUsage: LanguageModelUsage | undefined,
+): { usage?: ProviderUsage; usageRefusal?: UsageRefusal } => {
+    try {
+        const usage = wireUsageOf(values) ?? (sdkUsage === undefined ? undefined : usageOf(sdkUsage));
+        return usage === undefined ? {} : { usage };
+    } catch (cause) {
+        if (!(cause instanceof TypeError)) throw cause;
+        return { usageRefusal: { reason: cause.message, usage: wireUsageEvidenceOf(values) ?? sdkUsage } };
+    }
+};
+
 const wireUsageEvidenceOf = (values: readonly unknown[]): unknown => {
     for (let index = values.length - 1; index >= 0; index -= 1) {
         const record = recordOf(values[index]);
@@ -169,6 +188,7 @@ export type AiSdkTransportRequest = {
     streaming: boolean;
     captureRawBody: boolean;
     observeReasoning?: ProviderReasoningObserver;
+    observeText?: (delta: string) => void;
 };
 
 export type AiSdkTransportResponse = {
@@ -179,6 +199,7 @@ export type AiSdkTransportResponse = {
     finishReason: ProviderAttemptFinishReason;
     rawFinishReason?: string;
     usage?: ProviderUsage;
+    usageRefusal?: UsageRefusal;
     metadata: Record<string, unknown>;
     reasoningEncrypted: Array<{
         id: string | null;
@@ -437,7 +458,7 @@ const executeModelOnce = async (
             reasoningProjected: evidence.reasoningProjected,
             finishReason: finishReasonOf(rawFinishReason),
             ...(rawFinishReason === undefined ? {} : { rawFinishReason }),
-            usage: wireUsageOf(values) ?? usageOf(result.usage),
+            ...settledUsage(values, result.usage),
             metadata: metadataOf(values),
             reasoningEncrypted: evidence.reasoningEncrypted,
             logprobs: evidence.logprobs,
@@ -472,7 +493,10 @@ const executeModelOnce = async (
     try {
         for await (const part of result.fullStream) {
             if (part.type === "raw") rawChunks.push(part.rawValue);
-            if (part.type === "text-delta" && part.text.length > 0) outputObserved = true;
+            if (part.type === "text-delta" && part.text.length > 0) {
+                outputObserved = true;
+                request.observeText?.(part.text);
+            }
             if (part.type === "reasoning-delta" && part.text.length > 0) {
                 outputObserved = true;
                 request.observeReasoning?.(part.text);
@@ -504,7 +528,7 @@ const executeModelOnce = async (
         reasoningProjected: evidence.reasoningProjected,
         finishReason: finishReasonOf(rawFinishReason),
         ...(rawFinishReason === undefined ? {} : { rawFinishReason }),
-        usage: wireUsageOf(rawChunks) ?? usageOf(await result.usage),
+        ...settledUsage(rawChunks, await result.usage),
         metadata: metadataOf(rawChunks),
         reasoningEncrypted: evidence.reasoningEncrypted,
         logprobs: evidence.logprobs,
@@ -563,6 +587,7 @@ export const executeOpenAICompatible = async (
         streaming: request.streaming,
         captureRawBody: request.captureRawBody,
         ...(request.observeReasoning === undefined ? {} : { observeReasoning: request.observeReasoning }),
+        ...(request.observeText === undefined ? {} : { observeText: request.observeText }),
     });
 };
 
@@ -577,6 +602,7 @@ const responseBodyValues = (error: APICallError): readonly unknown[] => {
 
 export type AiSdkTransportFailureEvidence = {
     readonly usage?: ProviderUsage;
+    readonly usageRefusal?: UsageRefusal;
     readonly chargeEvidence: ProviderChargeEvidence;
     readonly status?: number;
 };
@@ -587,7 +613,7 @@ export const transportFailureEvidence = (
     const values = typeof error === "object" && error !== null
         ? streamFailureValues.get(error) ?? (APICallError.isInstance(error) ? responseBodyValues(error) : [])
         : [];
-    const usage = wireUsageOf(values);
+    const settled = settledUsage(values, undefined);
     const usageEvidence = wireUsageEvidenceOf(values);
     const charge = wireChargeEvidenceOf(values);
     const wireStatus = values
@@ -600,7 +626,7 @@ export const transportFailureEvidence = (
             ? wireStatus as number
             : undefined;
     return {
-        ...(usage === undefined ? {} : { usage }),
+        ...settled,
         chargeEvidence: {
             ...(charge === undefined ? {} : { charge }),
             ...(usageEvidence === undefined ? {} : { usage: usageEvidence }),

package/src/boundaries.test.ts

@@ -52,6 +52,7 @@ test("the OpenAI-compatible entrypoint excludes Node-owned provider machinery",
         "cost.ts",
         "env.ts",
         "errors.ts",
+        "LeadingReasoning.ts",
         "notices.ts",
         "openai.ts",
         "promptTokens.ts",

package/src/catalogProvider.test.ts

@@ -2,10 +2,27 @@ import test, { mock } from "node:test";
 import { strict as assert } from "node:assert";
 import { once } from "node:events";
 import { createServer } from "node:http";
-import { catalogProviderFromEnv, providerFromSdkModel } from "./catalogProvider.ts";
+import { catalogProviderFromEnv, catalogReasoningPolicies, providerFromSdkModel } from "./catalogProvider.ts";
+import { lookupProvider, resolveModel } from "@plurnk/plurnk-models";
+import { calculateCostUsdDecimal } from "./usage.ts";
+
+// A rate literal breaks at every catalog refresh (the 1.17.0 stamp moved DeepSeek's rates); the
+// claim under test is that the estimate is the catalog's rates applied to the reported usage.
+const catalogRatesOf = (provider: string, model: string) => {
+    const cost = resolveModel(provider, model)?.info.cost;
+    if (cost === undefined) throw new Error(`${provider}/${model} has no catalog rates`);
+    return {
+        input: cost.inputPer1M,
+        output: cost.outputPer1M,
+        ...(cost.reasoningPer1M === undefined ? {} : { reasoning: cost.reasoningPer1M }),
+        ...(cost.cacheReadPer1M === undefined ? {} : { cacheRead: cost.cacheReadPer1M }),
+        ...(cost.cacheWritePer1M === undefined ? {} : { cacheWrite: cost.cacheWritePer1M }),
+    };
+};
 import { withProviderDefaults } from "./defaults.ts";
 import type { LanguageModel } from "ai";
 import { resetEmittedWarnings } from "./warnings.ts";
+import { UnsupportedReasoningPolicyError } from "./types.ts";
 
 const env = {
     OPENAI_API_KEY: "test-key",
@@ -104,6 +121,73 @@ test("provider adapters advertise only reasoning policies they can preserve", ()
     assert.deepEqual(gemini?.supportedReasoningPolicies, ["adaptive", "low", "medium", "high"], "Gemini 3's mandatory minimum is not advertised as off");
 });
 
+test("{§provider-reasoning-policy}: catalog discovery and construction agree on native and compatible routes", () => {
+    const fetch = mock.method(globalThis, "fetch", () => {
+        throw new Error("capability discovery and construction require no provider request");
+    });
+    const configured = withProviderDefaults({
+        ...env,
+        DEEPSEEK_API_KEY: "test-key",
+        GEMINI_API_KEY: "test-key",
+        MISTRAL_API_KEY: "test-key",
+        CLOUDFLARE_ACCOUNT_ID: "test-account",
+        CLOUDFLARE_API_KEY: "test-key",
+        PLURNK_PROVIDERS_REASONING: "adaptive",
+        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_STYLE: "effort_required",
+    });
+    for (const [name, model] of [
+        ["openai", "gpt-4.1-mini"],
+        ["google", "gemini-3.7-flash"],
+        ["mistral", "mistral-small-latest"],
+        ["deepseek", "deepseek-v4-flash"],
+        ["cloudflare-workers-ai", "@cf/qwen/qwen3.8-27b"],
+        ["cloudflare-workers-ai", "@cf/ibm-granite/granite-4.0-h-micro"],
+        ["cloudflare-workers-ai", "@cf/zai-org/glm-5.3-flash"],
+    ]) {
+        const providerInfo = lookupProvider(name);
+        const info = resolveModel(name, model)?.info;
+        assert.ok(providerInfo);
+        assert.ok(info);
+        for (const declaration of ["", "medium,high,max"]) {
+            const key = `PLURNK_PROVIDERS_PROVIDER_${name.replaceAll(/[^a-zA-Z0-9]/g, "_").toUpperCase()}_REASONING_EFFORTS`;
+            const localEnv = { ...configured, [key]: declaration };
+            const provider = catalogProviderFromEnv(name, localEnv, model);
+            assert.ok(provider);
+            assert.deepEqual(
+                catalogReasoningPolicies(providerInfo, info, localEnv),
+                provider.supportedReasoningPolicies,
+                `${name}/${model} with declared efforts ${JSON.stringify(declaration)}`,
+            );
+        }
+    }
+    assert.equal(fetch.mock.callCount(), 0);
+});
+
+test("{§provider-reasoning-policy}: discovery never offers a fixed effort the installed transport rejects", () => {
+    const info = resolveModel("deepseek", "deepseek-v4-flash")?.info;
+    assert.ok(info);
+    const declared = withProviderDefaults({
+        ...env,
+        PLURNK_PROVIDERS_REASONING: "adaptive",
+        PLURNK_PROVIDERS_PROVIDER_OPENAI_REASONING_EFFORTS: "medium,xhigh",
+        PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_EFFORTS: "medium,xhigh",
+    });
+    for (const [name, expected] of [
+        ["openai", ["off", "adaptive", "low", "medium", "high", "xhigh"]],
+        ["openrouter", ["off", "adaptive", "low", "medium", "high"]],
+    ] as const) {
+        const catalog = lookupProvider(name);
+        assert.ok(catalog);
+        assert.deepEqual(catalogReasoningPolicies(catalog, info, declared), expected);
+        assert.throws(() => providerFromSdkModel({
+            name, model: "fixture", contextWindow: 32_768, info,
+            env: { ...declared, PLURNK_PROVIDERS_REASONING: "max" },
+            languageModel: { specificationVersion: "v4" } as LanguageModel,
+            sdkPackage: catalog.npm,
+        }), UnsupportedReasoningPolicyError);
+    }
+});
+
 test("Models.dev controls Cloudflare's exact effort vocabulary", async () => {
     const bodies: Record<string, unknown>[] = [];
     mock.method(globalThis, "fetch", async (_input: string | URL | Request, init?: RequestInit) => {
@@ -357,7 +441,7 @@ test("xAI's native chat contract requests its strongest cataloged effort and cap
     });
 });
 
-test("Cerebras explicit reasoning activation needs no operator effort or token budget", async () => {
+test("Cerebras explicit and adaptive reasoning do not invent a token budget", async () => {
     let body: Record<string, unknown> | undefined;
     mock.method(globalThis, "fetch", async (_input: string | URL | Request, init?: RequestInit) => {
         body = JSON.parse(String(init?.body)) as Record<string, unknown>;
@@ -366,21 +450,21 @@ test("Cerebras explicit reasoning activation needs no operator effort or token b
                 id: "chatcmpl-cerebras",
                 object: "chat.completion.chunk",
                 created: 1,
-                model: "gemma-4-31b",
+                model: "qwen-3.8-27b",
                 choices: [{ index: 0, delta: { reasoning: "consider" }, finish_reason: null }],
             })}`,
             `data: ${JSON.stringify({
                 id: "chatcmpl-cerebras",
                 object: "chat.completion.chunk",
                 created: 2,
-                model: "gemma-4-31b",
+                model: "qwen-3.8-27b",
                 choices: [{ index: 0, delta: { content: "done" }, finish_reason: "stop" }],
             })}`,
             `data: ${JSON.stringify({
                 id: "chatcmpl-cerebras",
                 object: "chat.completion.chunk",
                 created: 3,
-                model: "gemma-4-31b",
+                model: "qwen-3.8-27b",
                 choices: [],
                 usage: {
                     prompt_tokens: 2,
@@ -393,20 +477,22 @@ test("Cerebras explicit reasoning activation needs no operator effort or token b
         ].join("\n\n"), { headers: { "content-type": "text/event-stream" } });
     });
 
-    const provider = catalogProviderFromEnv("cerebras", {
-        ...env,
-        CEREBRAS_API_KEY: "test-key",
-        PLURNK_PROVIDERS_REASONING: "high",
-    }, "gemma-4-31b");
-    const result = await provider?.generate({
-        workerId: "worker",
-        messages: [{ role: "user", content: "hello" }],
-    });
+    for (const policy of ["high", "adaptive"] as const) {
+        const provider = catalogProviderFromEnv("cerebras", {
+            ...env,
+            CEREBRAS_API_KEY: "test-key",
+            PLURNK_PROVIDERS_REASONING: policy,
+        }, "qwen-3.8-27b");
+        const result = await provider?.generate({
+            workerId: "worker",
+            messages: [{ role: "user", content: "hello" }],
+        });
 
-    assert.equal(body?.reasoning_effort, "high", "the native SDK preserves the explicit durable effort");
-    assert.equal("thinking_budget_tokens" in (body ?? {}), false, "activation does not invent a token budget");
-    assert.equal(result?.assistant.reasoning, "consider");
-    assert.equal(result?.accounting[0]?.usage?.outputTokenDetails?.reasoningTokens, 1);
+        assert.equal(body?.reasoning_effort, "high", `${policy} reaches the native SDK as high`);
+        assert.equal("thinking_budget_tokens" in (body ?? {}), false, "activation does not invent a token budget");
+        assert.equal(result?.assistant.reasoning, "consider");
+        assert.equal(result?.accounting[0]?.usage?.outputTokenDetails?.reasoningTokens, 1);
+    }
 });
 
 test("Meta Muse adaptive reasoning is requested even when the endpoint returns no readable trace", async () => {
@@ -807,9 +893,11 @@ test("Models.dev is the only fallback rate table", async () => {
     }, "deepseek-v4-flash");
     assert.notEqual(cataloged, null);
     const catalogedResponse = await cataloged!.generate({ workerId: "cataloged", messages: [] });
+    const catalogAmount = calculateCostUsdDecimal(catalogedResponse.accounting[0]!.usage!, catalogRatesOf("deepseek", "deepseek-v4-flash"));
+    assert.match(String(catalogAmount), /^0\.0*[1-9]/, "the catalog prices this usage");
     assert.deepEqual(catalogedResponse.accounting[0]?.cost, {
         kind: "estimated",
-        amount: { amount: "0.00012712", currency: "USD" },
+        amount: { amount: catalogAmount, currency: "USD" },
         source: "Models.dev catalog rates",
     });
 
@@ -854,9 +942,11 @@ test("{§operator-cost-override} declared rates overlay the catalog and the sour
         PLURNK_PROVIDERS_COST: "input=0.22,output=0.66,cacheRead=0.007",
     }, "deepseek-v4-flash");
     const response = await overridden!.generate({ workerId: "overridden", messages: [] });
+    const overriddenAmount = calculateCostUsdDecimal(response.accounting[0]!.usage!, { ...catalogRatesOf("deepseek", "deepseek-v4-flash"), input: 0.22, output: 0.66, cacheRead: 0.007 });
+    assert.notEqual(overriddenAmount, calculateCostUsdDecimal(response.accounting[0]!.usage!, catalogRatesOf("deepseek", "deepseek-v4-flash")), "the override changes the price");
     assert.deepEqual(response.accounting[0]?.cost, {
         kind: "estimated",
-        amount: { amount: "0.0002148", currency: "USD" },
+        amount: { amount: overriddenAmount, currency: "USD" },
         source: "operator PLURNK_PROVIDERS_COST override over Models.dev catalog rates",
     });
     mock.restoreAll();

package/src/catalogProvider.ts

@@ -3,6 +3,7 @@ import {
     resolveModel,
     type ModelInfo,
     type ModelReasoningEffort,
+    type ProviderInfo,
 } from "@plurnk/plurnk-models";
 import {
     costOverrideFromEnv,
@@ -176,6 +177,41 @@ const supportedReasoningPolicies = ({
     return activationPolicies;
 };
 
+const reasoningCapabilities = (
+    name: string,
+    env: NodeJS.ProcessEnv,
+    info: ModelInfo | undefined,
+    native: boolean,
+    sdkPackage?: string,
+) => {
+    const declaredEfforts = declaredEffortsFromEnv(env, name);
+    const declaredStyle = info?.reasoning === false ? "none" : reasoningStyleFromEnv(env, name) ?? "none";
+    const style = info?.reasoningOptions !== undefined
+        && (declaredStyle === "effort" || declaredStyle === "effort_required")
+        && catalogEfforts(info, declaredEfforts).length === 0
+        ? "none"
+        : declaredStyle;
+    const [first, ...rest] = supportedReasoningPolicies({ info, native, style, declared: declaredEfforts })
+        .filter((policy) => (!native || policy !== "max")
+            && (sdkPackage !== "@openrouter/ai-sdk-provider" || policy !== "xhigh"));
+    if (first === undefined) throw new TypeError(`${name} provider: no portable reasoning policy is representable`);
+    return {
+        declaredEfforts,
+        style,
+        policies: [first, ...rest] satisfies [ReasoningPolicy, ...ReasoningPolicy[]],
+    };
+};
+
+// {§provider-reasoning-policy} Read-only discovery and construction share admission;
+// the compatible SDK package is the only catalog transport without a native model.
+export const catalogReasoningPolicies = (
+    provider: ProviderInfo,
+    info: ModelInfo,
+    env: NodeJS.ProcessEnv,
+): readonly [ReasoningPolicy, ...ReasoningPolicy[]] => reasoningCapabilities(
+    provider.id, env, info, provider.npm !== "@ai-sdk/openai-compatible", provider.npm,
+).policies;
+
 const adaptiveReasoningProjection = ({
     sdkPackage,
     model,
@@ -276,15 +312,9 @@ export const providerFromSdkModel = ({
     );
     const reasoning = reasoningFromEnv(env, name, envelope.reasoningBudget);
     const reasoningCapable = info?.reasoning === true;
-    const declaredEfforts = declaredEffortsFromEnv(env, name);
-    const declaredReasoningStyle = info?.reasoning === false
-        ? "none"
-        : reasoningStyleFromEnv(env, name) ?? "none";
-    const reasoningStyle = info?.reasoningOptions !== undefined
-        && (declaredReasoningStyle === "effort" || declaredReasoningStyle === "effort_required")
-        && catalogEfforts(info, declaredEfforts).length === 0
-        ? "none"
-        : declaredReasoningStyle;
+    const { declaredEfforts, style: reasoningStyle, policies } = reasoningCapabilities(
+        name, env, info, languageModel !== undefined, sdkPackage,
+    );
     const adaptiveReasoning = adaptiveReasoningProjection({
         sdkPackage,
         model,
@@ -351,12 +381,7 @@ export const providerFromSdkModel = ({
         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,
-            style: reasoningStyle,
-            declared: declaredEfforts,
-        }),
+        supportedReasoningPolicies: policies,
         ...adaptiveReasoning,
         ...(compatibleAdaptiveReasoning === undefined ? {} : { compatibleAdaptiveReasoning }),
         ...(compatibleOffReasoning === undefined ? {} : { compatibleOffReasoning }),
@@ -386,9 +411,6 @@ export const providerFromSdkModel = ({
         estimateCost,
         source: providerSource(name),
         ...(grammarStyle === undefined ? {} : { grammarStyle }),
-        gbnfDebug: env.PLURNK_PROVIDERS_GBNF_DEBUG !== undefined
-            && env.PLURNK_PROVIDERS_GBNF_DEBUG !== ""
-            && env.PLURNK_PROVIDERS_GBNF_DEBUG !== "0",
         ...dataCaptureFromEnv(env, name),
     });
 };

package/src/compatibleProvider.ts

@@ -215,9 +215,6 @@ export const compatibleProviderFromEnv = async (
         errorDetailLimit: parseRequiredInt(env.PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT, "PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT", provider),
         source: providerSource(provider),
         grammarStyle,
-        gbnfDebug: env.PLURNK_PROVIDERS_GBNF_DEBUG !== undefined
-            && env.PLURNK_PROVIDERS_GBNF_DEBUG !== ""
-            && env.PLURNK_PROVIDERS_GBNF_DEBUG !== "0",
         ...dataCaptureFromEnv(env, provider),
         firstPartyMetadata: provider === "plurnk",
         normalizeCost: provider === "plurnk" ? plurnkCostNormalizer : undefined,

package/src/env.test.ts

@@ -211,6 +211,7 @@ test("every PROVIDERS_KNOBS entry appears in the shipped .env.defaults", async (
     const missing = PROVIDERS_KNOBS.filter((k) => !defaults.includes(k));
     assert.deepEqual([...missing], [], "knobs read by code but undeclared in .env.defaults");
     assert.ok(defaults.includes("PLURNK_PROVIDERS_GBNF="), "GBNF (service-read, providers-namespace) must be declared with its default");
+    assert.equal(defaults.includes("PLURNK_PROVIDERS_GBNF_DEBUG"), false, "the debug knob is gone with the generator (#588)");
 });
 
 // The family word is REASONING (industry standard). Old names fail hard

package/src/env.ts

@@ -243,7 +243,7 @@ export const resolveGenerationEnvelopeFromEnv = (
 //   PLURNK_PROVIDERS_REASONING_BUDGET  optional reasoning subset of the total
 //     output budget, used for tier/budget mapping where the backend supports it.
 // The provider maps intent to the backend's mechanism; the consumer states
-// intent, never mechanism. PLAN is a separate public complete-Plan record.
+// intent, never mechanism. TASK inventory is separate from provider reasoning.
 export type Reasoning = { mode: ReasoningPolicy; budget: number | null };
 
 export const parseReasoningPolicy = (value: unknown, label: string): ReasoningPolicy => {
@@ -316,7 +316,6 @@ export const PROVIDERS_KNOBS = Object.freeze([
     "PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH",
     "PLURNK_PROVIDERS_PROBE_ATTEMPTS",
     "PLURNK_PROVIDERS_PROBE_DELAY",
-    "PLURNK_PROVIDERS_GBNF_DEBUG",
     "PLURNK_PROVIDERS_TOP_LOGPROBS",
     "PLURNK_PROVIDERS_RAWBODY",
 ]);

package/src/errors.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { APICallError, RetryError } from "ai";
+import { APICallError, JSONParseError, RetryError, TypeValidationError } from "ai";
 import { ProviderError, ProviderTimeoutError, classifyProviderError, toProviderError } from "./errors.ts";
 import type { ProviderAttempt } from "./types.ts";
 import { providerSource } from "./notices.ts";
@@ -15,6 +15,22 @@ const apiError = (statusCode: number, responseBody = "body") => new APICallError
 
 const SOURCE_PATTERN = /^[a-z]+(:[a-z][a-z0-9-]*)?$/;
 
+test("HTTP request rejection preserves its cause without becoming a response-contract strike", () => {
+    for (const status of [400, 404, 405, 422]) {
+        const message = "The requested model is not available on this endpoint.";
+        const cause = apiError(status, JSON.stringify({ error: { message } }));
+        Object.defineProperty(cause, "message", { value: message });
+        const failure = toProviderError(cause, "provider:example");
+        assert.equal(failure.kind, "request_rejected");
+        assert.equal(failure.status, status);
+        assert.equal(failure.message, message);
+        assert.equal(failure.problem.detail, message);
+        assert.equal(failure.problem.retryable, false);
+        assert.equal(failure.cause, cause);
+    }
+    assert.equal(classifyProviderError(apiError(200)).kind, "invalid_response", "a malformed successful response still violates the response contract");
+});
+
 test("providerSource produces a schema-valid colon-namespaced source", () => {
     assert.equal(providerSource("openai"), "provider:openai");
     assert.match(providerSource("openrouter"), SOURCE_PATTERN);
@@ -34,8 +50,8 @@ test("classifyProviderError maps HTTP status to kind", () => {
     assert.equal(k(500), "network_failure");
     assert.equal(k(503), "network_failure");
     assert.equal(k(413), "capacity_exceeded");
-    assert.equal(k(400), "invalid_response");
-    assert.equal(k(404), "invalid_response");
+    assert.equal(k(400), "request_rejected");
+    assert.equal(k(404), "request_rejected");
 });
 
 test("capacity normalization prefers structured provider codes and keeps generic 400s distinct", () => {
@@ -53,7 +69,7 @@ test("capacity normalization prefers structured provider codes and keeps generic
     assert.equal(normalized.problem.providerStatus, 400);
     assert.equal(classifyProviderError(apiError(400, JSON.stringify({
         error: { type: "invalid_request_error", code: "bad_temperature", message: "bad temperature" },
-    }))).kind, "invalid_response");
+    }))).kind, "request_rejected");
 });
 
 test("provider retry directives survive HTTP failure normalization", () => {
@@ -69,11 +85,11 @@ test("provider retry directives survive HTTP failure normalization", () => {
     assert.equal(error.problem.retryable, false);
 });
 
-test("classifyProviderError: a 422 flagged grammar_invalid is distinct; other 422s are invalid responses", () => {
+test("classifyProviderError: a 422 flagged grammar_invalid is distinct from other request rejections", () => {
     const rejected = apiError(422, JSON.stringify({ error: { type: "grammar_invalid", message: "non-conforming emission rejected: ..." } }));
     assert.equal(classifyProviderError(rejected).kind, "grammar_invalid");
-    assert.equal(classifyProviderError(apiError(422, JSON.stringify({ error: { type: "invalid_request_error" } }))).kind, "invalid_response");
-    assert.equal(classifyProviderError(apiError(422, "<html>Bad</html>")).kind, "invalid_response");
+    assert.equal(classifyProviderError(apiError(422, JSON.stringify({ error: { type: "invalid_request_error" } }))).kind, "request_rejected");
+    assert.equal(classifyProviderError(apiError(422, "<html>Bad</html>")).kind, "request_rejected");
 });
 
 test("classifyProviderError treats non-HTTP errors as network_failure", () => {
@@ -225,3 +241,38 @@ test("retry exhaustion retains the exact inner deadline phase", () => {
     assert.equal(error.problem.timeoutPhase, "attempt");
     assert.equal(error.problem.timeoutMs, 10);
 });
+
+// {§provider-failure-cause} — the SDK wraps every processing failure of a 2xx body in one message;
+// the durable Problem keeps a bounded classification of what actually happened underneath.
+const processingFailure = (cause: Error) => new APICallError({
+    message: "Failed to process successful response",
+    url: "https://example.test/v1/chat/completions",
+    requestBodyValues: {},
+    statusCode: 200,
+    responseHeaders: { authorization: "Bearer never-copied", "x-request-id": "req_1" },
+    cause,
+});
+
+test("#593: a terminated body, invalid JSON, a schema-invalid body, and an internal fault are told apart in durable evidence", () => {
+    const terminated = toProviderError(processingFailure(new TypeError("terminated")), "provider:test", 512);
+    assert.equal(terminated.problem.providerKind, "network_failure");
+    assert.deepEqual(terminated.problem.cause, { causeKind: "transport_terminated", causeName: "TypeError", causeMessage: "terminated" });
+
+    const parse = toProviderError(processingFailure(new JSONParseError({ text: "<html>502 Bad Gateway</html>".repeat(40), cause: new SyntaxError("Unexpected token <") })), "provider:test", 512);
+    assert.equal(parse.problem.providerKind, "invalid_response");
+    assert.deepEqual(parse.problem.cause, { causeKind: "invalid_json", causeName: "AI_JSONParseError", causeMessage: "JSON parsing failed (1120 characters)" });
+    assert.doesNotMatch(JSON.stringify(parse.problem), /Bad Gateway/, "the payload never enters the Problem");
+
+    const schema = toProviderError(processingFailure(new TypeValidationError({ value: { choices: "not-an-array", secret: "sk-live" }, cause: new Error("Expected array, received string at choices\nmore lines") })), "provider:test", 512);
+    assert.equal(schema.problem.providerKind, "invalid_response");
+    assert.deepEqual(schema.problem.cause, { causeKind: "schema_invalid", causeName: "AI_TypeValidationError", causeMessage: "Type validation failed: Expected array, received string at choices" });
+    assert.doesNotMatch(JSON.stringify(schema.problem), /sk-live|not-an-array/, "the value never enters the Problem");
+
+    const internal = toProviderError(processingFailure(new RangeError("Invalid array length\n    at Array.push (stack frame)")), "provider:test", 512);
+    assert.deepEqual(internal.problem.cause, { causeKind: "internal", causeName: "RangeError", causeMessage: "Invalid array length" });
+    assert.doesNotMatch(JSON.stringify(internal.problem), /stack frame|authorization|Bearer|req_1/, "no stack, no headers");
+
+    const bounded = toProviderError(processingFailure(new Error("x".repeat(100))), "provider:test", 8);
+    assert.equal((bounded.problem.cause as { causeMessage: string }).causeMessage, "xxxxxxxx...", "the cause message honours the configured detail limit");
+    assert.equal(toProviderError(apiError(502), "provider:test", 512).problem.cause, undefined, "an error without a cause reports none");
+});

package/src/errors.ts

@@ -1,4 +1,4 @@
-import { APICallError, RetryError } from "ai";
+import { APICallError, InvalidResponseDataError, JSONParseError, RetryError, TypeValidationError } from "ai";
 import { ProviderError } from "./providerError.ts";
 import type { ProviderErrorKind } from "./providerError.ts";
 import type { ProviderRequestCapacity } from "./types.ts";
@@ -81,6 +81,34 @@ const preview = (value: unknown, limit: number | undefined): string => {
         : text;
 };
 
+export type ProviderFailureCauseKind = "transport_terminated" | "invalid_json" | "schema_invalid" | "invalid_response_data" | "internal";
+
+export interface ProviderFailureCause {
+    readonly causeKind: ProviderFailureCauseKind;
+    readonly causeName: string;
+    readonly causeMessage: string;
+}
+
+const firstLine = (text: string): string => text.split("\n")[0]?.trim() ?? "";
+
+// {§provider-failure-cause} — what the SDK wrapped. "Failed to process successful response" is
+// the SDK's one message for a body that terminated, a body that was not JSON, a body that failed
+// the response schema, and its own internal faults; the durable Problem keeps a bounded
+// classification of the cause so forensics can tell them apart. The SDK's parse and validation
+// messages embed the payload, so those two report shape, never text.
+const failureCause = (err: APICallError, detailLimit: number | undefined): ProviderFailureCause | null => {
+    const cause = err.cause;
+    if (!(cause instanceof Error)) return null;
+    if (peerTerminated(cause)) return { causeKind: "transport_terminated", causeName: cause.name, causeMessage: preview(firstLine(cause.message), detailLimit) };
+    if (JSONParseError.isInstance(cause)) return { causeKind: "invalid_json", causeName: cause.name, causeMessage: `JSON parsing failed (${cause.text.length} characters)` };
+    if (TypeValidationError.isInstance(cause)) {
+        const inner = cause.cause instanceof Error ? firstLine(cause.cause.message) : "";
+        return { causeKind: "schema_invalid", causeName: cause.name, causeMessage: inner === "" ? "Type validation failed" : `Type validation failed: ${preview(inner, detailLimit)}` };
+    }
+    if (InvalidResponseDataError.isInstance(cause)) return { causeKind: "invalid_response_data", causeName: cause.name, causeMessage: preview(firstLine(cause.message), detailLimit) };
+    return { causeKind: "internal", causeName: cause.name, causeMessage: preview(firstLine(cause.message), detailLimit) };
+};
+
 export const classifyProviderError = (
     err: unknown,
     detailLimit?: number,
@@ -94,6 +122,31 @@ export const classifyProviderError = (
         };
     }
     if (APICallError.isInstance(err)) {
+        const classified = classifyApiCallError(err, detailLimit);
+        const cause = failureCause(err, detailLimit);
+        return cause === null ? classified : { ...classified, extensions: { ...(classified.extensions ?? {}), cause } };
+    }
+    const wire = err as { message?: unknown; type?: unknown };
+    if (wire?.type === "grammar_invalid") {
+        return {
+            kind: "grammar_invalid",
+            message: typeof wire.message === "string"
+                ? preview(wire.message, detailLimit)
+                : "The provider rejected the response grammar.",
+        };
+    }
+    const error = err as { message?: string };
+    return {
+        kind: "network_failure",
+        message: preview(
+            (error?.message ?? String(err)) || "The provider request failed.",
+            detailLimit,
+        ),
+    };
+};
+
+const classifyApiCallError = (err: APICallError, detailLimit: number | undefined): ClassifiedProviderError => {
+    {
         const timeout = providerTimeoutOf(err);
         if (timeout !== null) {
             return {
@@ -146,25 +199,9 @@ export const classifyProviderError = (
         if (status === 422 && wire.type === "grammar_invalid") {
             return { kind: "grammar_invalid", message };
         }
+        if (status >= 400 && status < 500) return { kind: "request_rejected", message };
         return { kind: "invalid_response", message };
     }
-    const wire = err as { message?: unknown; type?: unknown };
-    if (wire?.type === "grammar_invalid") {
-        return {
-            kind: "grammar_invalid",
-            message: typeof wire.message === "string"
-                ? preview(wire.message, detailLimit)
-                : "The provider rejected the response grammar.",
-        };
-    }
-    const error = err as { message?: string };
-    return {
-        kind: "network_failure",
-        message: preview(
-            (error?.message ?? String(err)) || "The provider request failed.",
-            detailLimit,
-        ),
-    };
 };
 
 export const toProviderError = (

package/src/index.ts

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