@plurnk/plurnk-providers 1.3.12 → 1.4.0

package/src/env.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { parseRequiredInt, parseOptionalInt, requireEnv, reasoningFromEnv, tokenRatesFromEnv } from "./env.ts";
+import { parseRequiredInt, parseOptionalInt, requireEnv, reasoningFromEnv, reasoningResponseStyleFromEnv, tokenRatesFromEnv } from "./env.ts";
 
 test("parseRequiredInt: parses a non-negative integer", () => {
     assert.equal(parseRequiredInt("600000", "PLURNK_PROVIDERS_FETCH_TIMEOUT", "openai"), 600000);
@@ -29,7 +29,7 @@ test("parseOptionalInt: rejects fractional and negative values", () => {
     assert.throws(() => parseOptionalInt("-8", "PLURNK_PROVIDERS_CONTEXT_WINDOW", "openai"), /must be a non-negative integer/);
 });
 
-test("reasoningFromEnv: activation modes parse; budget required IFF on; fail-hard on everything else (#33)", () => {
+test("reasoningFromEnv: activation modes parse; budget required IFF on; fail-hard on everything else", () => {
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "off" }, "openai"), { mode: "off", budget: null });
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "adaptive" }, "openai"), { mode: "adaptive", budget: null });
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on", PLURNK_PROVIDERS_REASONING_BUDGET: "4096" }, "openai"), { mode: "on", budget: 4096 });
@@ -40,6 +40,19 @@ test("reasoningFromEnv: activation modes parse; budget required IFF on; fail-har
     assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on", PLURNK_PROVIDERS_REASONING_BUDGET: "1.5" }, "openai"), /positive integer/);
 });
 
+test("{§provider-tagged-reasoning} response style is explicit and invalid values fail at the provider boundary", () => {
+    assert.equal(reasoningResponseStyleFromEnv({}, "cloudflare"), "verbatim");
+    assert.equal(reasoningResponseStyleFromEnv({
+        PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE: "think-tags",
+    }, "cloudflare"), "think-tags");
+    assert.throws(
+        () => reasoningResponseStyleFromEnv({
+            PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE: "auto",
+        }, "cloudflare"),
+        /cloudflare provider: PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE must be "verbatim" or "think-tags" \(got "auto"\)/,
+    );
+});
+
 test("requireEnv: returns the value or throws a named error", () => {
     assert.equal(requireEnv("sk-x", "OPENAI_API_KEY", "openai"), "sk-x");
     assert.throws(() => requireEnv(undefined, "GROQ_API_KEY", "groq"), /groq provider: GROQ_API_KEY must be set/);
@@ -79,15 +92,17 @@ test("scopeEnvToAlias: suffixed knob wins, bare is the fallback, other aliases i
         PLURNK_PROVIDERS_REASONING: "off",
         PLURNK_PROVIDERS_REASONING_turboderp: "on",
         PLURNK_PROVIDERS_REASONING_BUDGET_TURBODERP: "4096", // case-folds like PLURNK_MODEL_ keys
-        PLURNK_PROVIDERS_CONTEXT_WINDOW_turboderp: "8000", // #525 gate knob — the client window cap
+        PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE_TURBODERP: "think-tags",
+        PLURNK_PROVIDERS_CONTEXT_WINDOW_turboderp: "8000",
         PLURNK_PROVIDERS_COMPLETION_RESERVE_turboderp: "4096",
         PLURNK_PROVIDERS_CONTEXT_WINDOW_other: "1",
     } as NodeJS.ProcessEnv;
     const scoped = scopeEnvToAlias(env, "turboderp");
     assert.equal(scoped.PLURNK_PROVIDERS_REASONING, "on");
     assert.equal(scoped.PLURNK_PROVIDERS_REASONING_BUDGET, "4096");
-    assert.equal(scoped.PLURNK_PROVIDERS_CONTEXT_WINDOW, "8000"); // #525: the alias-scoped window cap promotes to bare (the release-gate knob)
-    assert.equal(scoped.PLURNK_PROVIDERS_COMPLETION_RESERVE, "4096"); // the #507 reserves promote too
+    assert.equal(scoped.PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE, "think-tags");
+    assert.equal(scoped.PLURNK_PROVIDERS_CONTEXT_WINDOW, "8000");
+    assert.equal(scoped.PLURNK_PROVIDERS_COMPLETION_RESERVE, "4096");
     assert.equal(scopeEnvToAlias(env, "plain").PLURNK_PROVIDERS_REASONING, "off"); // fallback intact
 });
 
@@ -103,7 +118,7 @@ test("scopeEnvToAlias: aliases with underscores resolve; a bare knob is never mi
     assert.equal(scopeEnvToAlias(env, "budget").PLURNK_PROVIDERS_REASONING, "off"); // collision guard
 });
 
-test("#36 dataCaptureFromEnv: both knobs OFF by default, ON when set (TOP_LOGPROBS = the OpenAI top_logprobs count)", async () => {
+test("dataCaptureFromEnv: both knobs OFF by default, ON when set (TOP_LOGPROBS = the OpenAI top_logprobs count)", async () => {
     const { dataCaptureFromEnv } = await import("./env.ts");
     assert.deepEqual(dataCaptureFromEnv({} as NodeJS.ProcessEnv, "x"), { topLogprobs: null, rawBody: false });
     assert.deepEqual(dataCaptureFromEnv({ PLURNK_PROVIDERS_RAWBODY: "0" } as NodeJS.ProcessEnv, "x"), { topLogprobs: null, rawBody: false });
@@ -120,7 +135,7 @@ test("OpenAI-lexicon shed: a still-set PLURNK_PROVIDERS_LOGPROB fails hard with
     );
 });
 
-test("#472 contextWindowFromEnv: reads the new name, sheds CONTEXT_SIZE hard, null when unset", async () => {
+test("contextWindowFromEnv: reads the new name, sheds CONTEXT_SIZE hard, null when unset", async () => {
     const { contextWindowFromEnv } = await import("./env.ts");
     assert.equal(contextWindowFromEnv({ PLURNK_PROVIDERS_CONTEXT_WINDOW: "131072" } as NodeJS.ProcessEnv, "openai"), 131072);
     assert.equal(contextWindowFromEnv({} as NodeJS.ProcessEnv, "openai"), null);
@@ -130,7 +145,7 @@ test("#472 contextWindowFromEnv: reads the new name, sheds CONTEXT_SIZE hard, nu
     );
 });
 
-test("scopeEnvToAlias: a caller-supplied knob list scopes CONSUMER vars (service window partition)", async () => {
+test("scopeEnvToAlias: a caller-supplied knob list scopes consumer-owned vars", async () => {
     const { scopeEnvToAlias } = await import("./env.ts");
     const SERVICE_KNOBS = ["PLURNK_SERVICE_MAX_TURNS", "PLURNK_SERVICE_LOOP_TIMEOUT", "PLURNK_SERVICE_EXEC_HOLD_MS", "PLURNK_SERVICE_SAFETY"];
     const env = {
@@ -150,7 +165,7 @@ test("scopeEnvToAlias: a caller-supplied knob list scopes CONSUMER vars (service
     assert.equal(mixed.PLURNK_PROVIDERS_REASONING, "off");
 });
 
-test("#36 capture knobs are per-alias scopable: enable on a scraping alias, serving alias stays clean", async () => {
+test("capture knobs are per-alias scopable: enable on a scraping alias, serving alias stays clean", async () => {
     const { scopeEnvToAlias, dataCaptureFromEnv } = await import("./env.ts");
     const env = {
         PLURNK_PROVIDERS_TOP_LOGPROBS_fireslow: "3",
@@ -160,10 +175,10 @@ test("#36 capture knobs are per-alias scopable: enable on a scraping alias, serv
     assert.deepEqual(dataCaptureFromEnv(scopeEnvToAlias(env, "grokfast"), "x"), { topLogprobs: null, rawBody: false });
 });
 
-// Reader-declares (#44 ecosystem standard): every knob the code reads appears in
+// Every knob the code reads appears in
 // the shipped .env.defaults — set (the floor) or commented (documented optional).
 // The file IS the operator documentation; this keeps it from drifting off the code.
-test("#44: every PROVIDERS_KNOBS entry appears in the shipped .env.defaults", async () => {
+test("every PROVIDERS_KNOBS entry appears in the shipped .env.defaults", async () => {
     const { readFileSync } = await import("node:fs");
     const { PROVIDERS_KNOBS } = await import("./env.ts");
     const defaults = readFileSync(new URL("../.env.defaults", import.meta.url), "utf8");
@@ -172,37 +187,37 @@ test("#44: every PROVIDERS_KNOBS entry appears in the shipped .env.defaults", as
     assert.ok(defaults.includes("PLURNK_PROVIDERS_GBNF="), "GBNF (service-read, providers-namespace) must be declared with its default");
 });
 
-// #399: the family word is REASONING (industry standard). Old names fail hard
+// The family word is REASONING (industry standard). Old names fail hard
 // with the migration pointer — never silently coexist with the new floor.
-test("#399: still-set old THINKING names fail hard with the rename pointer", () => {
+test("still-set old THINKING names fail hard with the rename pointer", () => {
     assert.throws(
         () => reasoningFromEnv({ PLURNK_PROVIDERS_THINKING: "on", PLURNK_PROVIDERS_REASONING: "adaptive" }, "openai"),
-        /PLURNK_PROVIDERS_THINKING was renamed to PLURNK_PROVIDERS_REASONING \(#399\)/,
+        /PLURNK_PROVIDERS_THINKING was renamed to PLURNK_PROVIDERS_REASONING \(provider configuration contract\)/,
     );
     assert.throws(
         () => reasoningFromEnv({ PLURNK_PROVIDERS_THINKING_CAPACITY: "4096", PLURNK_PROVIDERS_REASONING: "adaptive" }, "openai"),
-        /PLURNK_PROVIDERS_THINKING_CAPACITY was renamed to PLURNK_PROVIDERS_REASONING_BUDGET \(#399\)/,
+        /PLURNK_PROVIDERS_THINKING_CAPACITY was renamed to PLURNK_PROVIDERS_REASONING_BUDGET \(provider configuration contract\)/,
     );
 });
 
-test("#399: the shipped floor activates reasoning by default (adaptive — owner ruling)", async () => {
+test("the shipped floor activates reasoning by default (adaptive)", async () => {
     const { readFileSync } = await import("node:fs");
     const defaults = readFileSync(new URL("../.env.defaults", import.meta.url), "utf8");
     assert.ok(defaults.includes("PLURNK_PROVIDERS_REASONING=adaptive"), "floor must ship REASONING=adaptive");
     assert.ok(!defaults.match(/^PLURNK_PROVIDERS_REASONING_BUDGET=/m), "no shipped magnitude — budget is on-mode only");
 });
 
-test("#567: the shipped DRY floor stays off while retaining the measured alias-safe shape", async () => {
+test("the shipped DRY floor is off and claims no universally safe shape", async () => {
     const { readFileSync } = await import("node:fs");
     const defaults = readFileSync(new URL("../.env.defaults", import.meta.url), "utf8");
-    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_MULTIPLIER=0$/m, "one-model tuning is not a universal sampler floor");
-    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_BASE=1\.75$/m);
-    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH=32$/m, "the measured identifier-safe shape remains available for alias opt-in");
+    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_MULTIPLIER=0$/m, "a fidelity-corrupting sampler cannot be a portable floor");
+    assert.doesNotMatch(defaults, /^PLURNK_PROVIDERS_DRY_BASE=/m);
+    assert.doesNotMatch(defaults, /^PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH=/m);
 });
 
-// -- #507: envelope reserves (owner-ruled migration from PLURNK_SERVICE_*) --
+// -- {§provider-generation-envelope} --
 
-test("#507 envelopeFromEnv: percentages and absolutes parse; missing/invalid fail hard", async () => {
+test("envelopeFromEnv: percentages and absolutes parse; missing/invalid fail hard", async () => {
     const { envelopeFromEnv } = await import("./env.ts");
     assert.deepEqual(
         envelopeFromEnv({ PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "4096" } as NodeJS.ProcessEnv, "x"),
@@ -213,7 +228,7 @@ test("#507 envelopeFromEnv: percentages and absolutes parse; missing/invalid fai
     assert.throws(() => envelopeFromEnv({ PLURNK_PROVIDERS_REASONING_RESERVE: "-5", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%" } as NodeJS.ProcessEnv, "x"), /positive integer token count/);
 });
 
-test("#507 envelope knobs are per-alias scopable (measured envelope per box)", async () => {
+test("envelope knobs are per-alias scopable (measured envelope per box)", async () => {
     const { scopeEnvToAlias, envelopeFromEnv } = await import("./env.ts");
     const env = {
         PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",

package/src/env.ts

@@ -43,7 +43,7 @@ export const promptCacheKeyFromEnv = (env: NodeJS.ProcessEnv, label: string): bo
     return value === "1";
 };
 
-// Old-name shed (the #399/#472 lexicon renames): a still-set retired knob fails
+// {§provider-configuration} A still-set retired knob fails
 // hard pointing at its successor — never silently coexists with the new floor.
 // The retired names appear ONLY as this function's ARGUMENTS at the call sites
 // (each lexicon-allow), never as a live identifier.
@@ -52,7 +52,8 @@ const shedRenamed = (env: NodeJS.ProcessEnv, oldName: string, newName: string, l
     if (stale !== undefined && stale.length > 0) throw new Error(`${label} provider: ${oldName} was renamed to ${newName} (${ref}); update the env`);
 };
 
-// Data-capture knobs (#36), read identically by every provider (standard AND
+// {§provider-evidence} Data-capture knobs are read identically by every provider
+// (standard AND
 // plugin) so the opt-in surface is one source of truth. Both OFF by default —
 // the flag is the isolation, so serving turns request and carry nothing.
 //   PLURNK_PROVIDERS_TOP_LOGPROBS   "off" or a non-negative int = the OpenAI
@@ -71,17 +72,29 @@ export const dataCaptureFromEnv = (env: NodeJS.ProcessEnv, label: string): { top
     };
 };
 
-// The context-window pin (SPEC §4) under its OpenAI-lexicon name (#472) — the
-// industry term is "context window" (OpenAI/Anthropic docs, models.dev
-// contextWindow); CONTEXT_SIZE was home-grown. One reader for base AND
-// plugins, so the shed fires everywhere the knob is honored.
+// {§model-fact-resolution} — one context-window reader for every provider path;
+// the retired CONTEXT_SIZE spelling fails visibly at the same boundary.
 export const contextWindowFromEnv = (env: NodeJS.ProcessEnv, label: string): number | null => {
-    shedRenamed(env, "PLURNK_PROVIDERS_CONTEXT_SIZE", "PLURNK_PROVIDERS_CONTEXT_WINDOW", label, "the industry term, #472"); // lexicon-allow
+    shedRenamed(env, "PLURNK_PROVIDERS_CONTEXT_SIZE", "PLURNK_PROVIDERS_CONTEXT_WINDOW", label, "{§model-fact-resolution}"); // lexicon-allow
     return parseOptionalInt(env.PLURNK_PROVIDERS_CONTEXT_WINDOW, "PLURNK_PROVIDERS_CONTEXT_WINDOW", label);
 };
 
+// {§model-fact-resolution} — an operator value caps known model physics and
+// declares the window only when no natural value is known.
+export function effectiveContextWindow(operatorCap: number | null, naturalWindow: number): number;
+export function effectiveContextWindow(operatorCap: number | null, naturalWindow: number | null): number | null;
+export function effectiveContextWindow(operatorCap: number | null, naturalWindow: number | null): number | null {
+    return operatorCap === null
+        ? naturalWindow
+        : naturalWindow === null
+            ? operatorCap
+            : Math.min(operatorCap, naturalWindow);
+}
+
 export type ProviderTokenRates = { input: number; cached: number; output: number };
 
+// {§model-fact-resolution} — any explicit rate opts into one complete operator
+// estimate; cached input alone may default to the explicit input rate.
 export const tokenRatesFromEnv = (env: NodeJS.ProcessEnv, label: string): ProviderTokenRates | null => {
     const inputName = "PLURNK_PROVIDERS_INPUT_USD_PER_MILLION";
     const cachedName = "PLURNK_PROVIDERS_CACHE_READ_USD_PER_MILLION";
@@ -99,13 +112,11 @@ export const tokenRatesFromEnv = (env: NodeJS.ProcessEnv, label: string): Provid
     };
 };
 
-// The generation-envelope reserves (#507, owner-ruled migration): how much of a
+// {§provider-generation-envelope} How much of a
 // DETECTED context window is reserved for reasoning and for completion — the
 // remainder (minus the consumer's own packing-safety margin) is the prompt
 // budget. Provider-owned: the window is a provider fact and these are amounts OF
-// it; the former PLURNK_SERVICE_{CONTEXT_WINDOW,REASONING,COMPLETION} knobs were
-// provider quantities wearing a service prefix (born as #352 packet parameters
-// before this surface existed). Each knob accepts a percentage of the window
+// it. Each knob accepts a percentage of the window
 // ("10%") or an absolute token count ("4096"); the floor ships percentages so
 // every window-advertising endpoint (llama-server n_ctx, the plurnk.ai router,
 // a cataloged cloud model) arrives at sane defaults with ZERO operator tuning.
@@ -151,21 +162,35 @@ export const resolveEnvelopeFromEnv = (env: NodeJS.ProcessEnv, window: number |
     };
 };
 
-// The side-channel reasoning knobs (SPEC §4, #32/#33) — ACTIVATION and BUDGET
+// {§provider-configuration} The side-channel reasoning knobs — activation and budget
 // are separate vars, so a numeric budget can never silently flip wire flags:
 //   PLURNK_PROVIDERS_REASONING           off | adaptive | on   (REQUIRED, fail-hard)
 //   PLURNK_PROVIDERS_REASONING_BUDGET  positive int, REQUIRED iff REASONING=on —
-//     the magnitude for tier/budget mapping. On llama.cpp the ENFORCEMENT is the
-//     box's --reasoning-budget launch flag (per-request numerics are ignored):
-//     env budget and launch flag are the same number, changed together.
+//     the magnitude for tier/budget mapping. On llama-server it is the explicit
+//     request-scoped allowance and cannot exceed the physical reasoning reserve.
 // The provider maps intent to the backend's mechanism; the consumer states
-// intent, never mechanism. (In-DSL PLAN reasoning is a grammar concern.)
+// intent, never mechanism. PLAN is a separate public intended-goals record.
 export type ReasoningMode = "off" | "adaptive" | "on";
 export type Reasoning = { mode: ReasoningMode; budget: number | null };
 
+export type ReasoningResponseStyle = "verbatim" | "think-tags";
+
+export const reasoningResponseStyleFromEnv = (
+    env: NodeJS.ProcessEnv,
+    label: string,
+): ReasoningResponseStyle => {
+    const name = "PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE";
+    const raw = env[name];
+    if (raw === undefined || raw.length === 0) return "verbatim";
+    if (raw !== "verbatim" && raw !== "think-tags") {
+        throw new Error(`${label} provider: ${name} must be "verbatim" or "think-tags" (got "${raw}")`);
+    }
+    return raw;
+};
+
 export const reasoningFromEnv = (env: NodeJS.ProcessEnv, label: string): Reasoning => {
-    shedRenamed(env, "PLURNK_PROVIDERS_THINKING", "PLURNK_PROVIDERS_REASONING", label, "#399"); // lexicon-allow
-    shedRenamed(env, "PLURNK_PROVIDERS_THINKING_CAPACITY", "PLURNK_PROVIDERS_REASONING_BUDGET", label, "#399"); // lexicon-allow
+    shedRenamed(env, "PLURNK_PROVIDERS_THINKING", "PLURNK_PROVIDERS_REASONING", label, "provider configuration contract"); // lexicon-allow
+    shedRenamed(env, "PLURNK_PROVIDERS_THINKING_CAPACITY", "PLURNK_PROVIDERS_REASONING_BUDGET", label, "provider configuration contract"); // lexicon-allow
     const name = "PLURNK_PROVIDERS_REASONING";
     const raw = env[name];
     if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set (off | adaptive | on)`);
@@ -189,6 +214,7 @@ export const reasoningFromEnv = (env: NodeJS.ProcessEnv, label: string): Reasoni
 export const PROVIDERS_KNOBS = Object.freeze([
     "PLURNK_PROVIDERS_REASONING_RESERVE",
     "PLURNK_PROVIDERS_COMPLETION_RESERVE",
+    "PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE",
     "PLURNK_PROVIDERS_REASONING_BUDGET",
     "PLURNK_PROVIDERS_REASONING",
     "PLURNK_PROVIDERS_CONTEXT_WINDOW",
@@ -196,6 +222,7 @@ export const PROVIDERS_KNOBS = Object.freeze([
     "PLURNK_PROVIDERS_CACHE_READ_USD_PER_MILLION",
     "PLURNK_PROVIDERS_OUTPUT_USD_PER_MILLION",
     "PLURNK_PROVIDERS_RETRY_ATTEMPTS",
+    "PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT",
     "PLURNK_PROVIDERS_FETCH_TIMEOUT",
     "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT",
     "PLURNK_PROVIDERS_LLAMA_SERVER",

package/src/errors.test.ts

@@ -0,0 +1,148 @@
+import test from "node:test";
+import { strict as assert } from "node:assert";
+import { APICallError, RetryError } from "ai";
+import { ProviderError, classifyProviderError, toProviderError } from "./errors.ts";
+import type { ProviderAttempt } from "./types.ts";
+import { providerSource } from "./notices.ts";
+
+const apiError = (statusCode: number, responseBody = "body") => new APICallError({
+    message: `request failed (${statusCode})`,
+    url: "https://example.test/v1/chat/completions",
+    requestBodyValues: {},
+    statusCode,
+    responseBody,
+});
+
+const SOURCE_PATTERN = /^[a-z]+(:[a-z][a-z0-9-]*)?$/;
+
+test("providerSource produces a schema-valid colon-namespaced source", () => {
+    assert.equal(providerSource("openai"), "provider:openai");
+    assert.match(providerSource("openrouter"), SOURCE_PATTERN);
+    assert.equal(providerSource("@scope/custom_provider"), "provider:scope-custom-provider");
+    assert.equal(providerSource("2fast"), "provider:p-2fast");
+    assert.throws(() => providerSource(""), /must name a provider/);
+});
+
+test("classifyProviderError maps HTTP status to kind", () => {
+    const k = (status: number) => classifyProviderError(apiError(status)).kind;
+    assert.equal(k(401), "unauthorized");
+    assert.equal(k(403), "unauthorized");
+    assert.equal(k(402), "quota_exceeded");
+    assert.equal(k(429), "rate_limit");
+    assert.equal(k(500), "network_failure");
+    assert.equal(k(503), "network_failure");
+    assert.equal(k(400), "invalid_response");
+    assert.equal(k(404), "invalid_response");
+});
+
+test("classifyProviderError: a 422 flagged grammar_invalid is distinct; other 422s are invalid responses", () => {
+    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");
+});
+
+test("classifyProviderError treats non-HTTP errors as network_failure", () => {
+    assert.equal(classifyProviderError(new TypeError("fetch failed")).kind, "network_failure");
+    const timeout = Object.assign(new Error("timed out"), { name: "TimeoutError" });
+    assert.equal(classifyProviderError(timeout).kind, "network_failure");
+});
+
+test("ProviderError carries a validated RFC 9457 Problem Details object", () => {
+    const e = new ProviderError("provider:openai", "rate_limit", "OpenAI 429 - slow down", { status: 429 });
+    assert.deepEqual(e.problem, {
+        type: "https://problems.plurnk.dev/provider/openai/rate-limit",
+        title: "Rate limit",
+        status: 429,
+        detail: "OpenAI 429 - slow down",
+        providerKind: "rate_limit",
+        stage: "provider-request",
+        retryable: true,
+    });
+    assert.match(e.source, SOURCE_PATTERN);
+    assert.ok(e instanceof Error);
+    assert.equal(e.status, 429);
+});
+
+test("ProviderError marks failures that require changed external state as non-retryable", () => {
+    const unauthorized = new ProviderError("provider:openai", "unauthorized", "Invalid API key.");
+    assert.equal(unauthorized.problem.retryable, false);
+    assert.equal(unauthorized.problem.stage, "provider-request");
+});
+
+test("#161: ProviderError carries resource-interrupted attempt evidence outside Problem Details", () => {
+    const attempt = {
+        assistant: {
+            content: "partial",
+            reasoning: null,
+            usage: { prompt: 3, completion: 1, reasoning: 0, cached: 0, total: 4 },
+            finishReason: "resource_interrupted",
+            model: "served-model",
+        },
+        assistantRaw: { rawFinishReason: "insufficient_system_resource" },
+    } as ProviderAttempt;
+    const error = new ProviderError(
+        "provider:deepseek",
+        "resource_interrupted",
+        "The provider interrupted generation because inference resources were unavailable.",
+        {
+            attempt,
+            extensions: {
+                stage: "provider-response",
+                finishReason: "resource_interrupted",
+                rawFinishReason: "insufficient_system_resource",
+            },
+        },
+    );
+
+    assert.equal(error.attempt, attempt);
+    assert.deepEqual(error.problem, {
+        type: "https://problems.plurnk.dev/provider/deepseek/resource-interrupted",
+        title: "Resource interrupted",
+        status: 503,
+        detail: "The provider interrupted generation because inference resources were unavailable.",
+        providerKind: "resource_interrupted",
+        stage: "provider-response",
+        retryable: false,
+        finishReason: "resource_interrupted",
+        rawFinishReason: "insufficient_system_resource",
+    });
+});
+
+test("toProviderError classifies and tags an HTTP error with the source + status", () => {
+    const cause = apiError(401, "no key");
+    const pe = toProviderError(cause, "provider:groq");
+    assert.equal(pe.kind, "unauthorized");
+    assert.equal(pe.source, "provider:groq");
+    assert.equal(pe.status, 401);
+    assert.equal(pe.cause, cause);
+});
+
+test("toProviderError passes an existing ProviderError through unchanged", () => {
+    const original = new ProviderError("provider:xai", "rate_limit", "429");
+    assert.equal(toProviderError(original, "provider:other"), original);
+});
+
+test("provider diagnostics are bounded without losing structured failure facts", () => {
+    const cause = apiError(502);
+    Object.defineProperty(cause, "message", { value: "abcdefghij" });
+    const error = toProviderError(cause, "provider:test", 4);
+    assert.equal(error.problem.detail, "abcd...");
+    assert.equal(error.problem.status, 502);
+    assert.equal(error.problem.providerKind, "network_failure");
+    assert.equal(error.cause, cause);
+});
+
+test("retry exhaustion is explicit and does not recommend another automatic replay", () => {
+    const failures = [apiError(429), apiError(429), apiError(429)];
+    const cause = new RetryError({
+        message: "Failed after 3 attempts.",
+        reason: "maxRetriesExceeded",
+        errors: failures,
+    });
+    const error = toProviderError(cause, "provider:test");
+    assert.equal(error.problem.retryable, false);
+    assert.equal(error.problem.attempts, 3);
+    assert.equal(error.problem.retryExhausted, true);
+    assert.equal(error.cause, cause);
+});

package/src/errors.ts

@@ -0,0 +1,207 @@
+import { Problems, type ProblemDetails } from "@plurnk/plurnk-contracts";
+import { APICallError, RetryError } from "ai";
+import { providerSource } from "./notices.ts";
+import type { ProviderAttempt } from "./types.ts";
+
+export type ProviderErrorKind =
+    | "rate_limit"
+    | "network_failure"
+    | "model_refused"
+    | "invalid_response"
+    | "unauthorized"
+    | "quota_exceeded"
+    | "grammar_invalid"
+    | "resource_interrupted";
+
+export interface ClassifiedProviderError {
+    kind: ProviderErrorKind;
+    message: string;
+    retryable?: boolean;
+    attempts?: number;
+    retryExhausted?: boolean;
+}
+
+const defaultStatus = (kind: ProviderErrorKind): number => {
+    switch (kind) {
+        case "unauthorized": return 401;
+        case "quota_exceeded": return 402;
+        case "rate_limit": return 429;
+        case "model_refused":
+        case "grammar_invalid": return 422;
+        case "invalid_response": return 502;
+        case "network_failure":
+        case "resource_interrupted": return 503;
+    }
+};
+
+const retryable = (kind: ProviderErrorKind): boolean => {
+    switch (kind) {
+        case "rate_limit":
+        case "network_failure":
+            return true;
+        case "invalid_response":
+        case "grammar_invalid":
+        case "resource_interrupted":
+        case "model_refused":
+        case "unauthorized":
+        case "quota_exceeded":
+            return false;
+    }
+};
+
+const buildProblem = (
+    source: string,
+    kind: ProviderErrorKind,
+    message: string,
+    status: number,
+    extensions: Readonly<Record<string, unknown>>,
+    retryableOverride: boolean | undefined,
+): ProblemDetails => {
+    const code: Record<ProviderErrorKind, string> = {
+        rate_limit: "rate-limit",
+        network_failure: "network-failure",
+        model_refused: "model-refused",
+        invalid_response: "invalid-response",
+        unauthorized: "unauthorized",
+        quota_exceeded: "quota-exceeded",
+        grammar_invalid: "grammar-invalid",
+        resource_interrupted: "resource-interrupted",
+    };
+    return Problems.create(source, code[kind], status, message, {
+        providerKind: kind,
+        stage: "provider-request",
+        retryable: retryableOverride ?? retryable(kind),
+        ...extensions,
+    });
+};
+
+// A provider operation failed before a completed exchange existed. An
+// interrupted response may still carry attempt evidence for its consumer.
+// The standardized Problem is the public failure contract; kind remains the
+// provider pool's routing discriminator and is repeated as a Problem extension.
+export class ProviderError extends Error {
+    readonly source: string;
+    readonly kind: ProviderErrorKind;
+    readonly problem: ProblemDetails;
+    readonly attempt?: ProviderAttempt;
+
+    constructor(
+        source: string,
+        kind: ProviderErrorKind,
+        message: string,
+        options: {
+            status?: number | null;
+            cause?: unknown;
+            retryable?: boolean;
+            extensions?: Readonly<Record<string, unknown>>;
+            attempt?: ProviderAttempt;
+        } = {},
+    ) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "ProviderError";
+        this.source = providerSource(source);
+        this.kind = kind;
+        this.attempt = options.attempt;
+        const status = options.status !== null && options.status !== undefined
+            && Number.isInteger(options.status) && options.status >= 400 && options.status <= 599
+            ? options.status
+            : defaultStatus(kind);
+        this.problem = buildProblem(
+            this.source,
+            kind,
+            message,
+            status,
+            options.extensions ?? {},
+            options.retryable,
+        );
+    }
+
+    get status(): number {
+        return this.problem.status;
+    }
+}
+
+const wireErrorType = (body: string): string | null => {
+    try {
+        const { error } = JSON.parse(body) as { error?: { type?: unknown } };
+        return typeof error?.type === "string" ? error.type : null;
+    } catch {
+        return null;
+    }
+};
+
+const preview = (value: unknown, limit: number | undefined): string => {
+    const text = value instanceof Error ? value.message : String(value);
+    return limit !== undefined && text.length > limit
+        ? `${text.slice(0, limit)}...`
+        : text;
+};
+
+export const classifyProviderError = (
+    err: unknown,
+    detailLimit?: number,
+): ClassifiedProviderError => {
+    if (RetryError.isInstance(err)) {
+        return {
+            ...classifyProviderError(err.lastError, detailLimit),
+            retryable: false,
+            attempts: err.errors.length,
+            retryExhausted: err.reason === "maxRetriesExceeded",
+        };
+    }
+    if (APICallError.isInstance(err)) {
+        const status = err.statusCode ?? 0;
+        const message = err.message.trim().length > 0
+            ? preview(err.message, detailLimit)
+            : "The provider request failed without a diagnostic message.";
+        const body = err.responseBody ?? "";
+        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 };
+        if (status >= 500) return { kind: "network_failure", message };
+        if (status === 422 && wireErrorType(body) === "grammar_invalid") {
+            return { kind: "grammar_invalid", 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 = (
+    err: unknown,
+    source: string,
+    detailLimit?: number,
+): ProviderError => {
+    if (err instanceof ProviderError) return err;
+    const underlying = RetryError.isInstance(err) ? err.lastError : err;
+    const classified = classifyProviderError(err, detailLimit);
+    const { kind, message } = classified;
+    const status = APICallError.isInstance(underlying) ? underlying.statusCode ?? null : null;
+    return new ProviderError(source, kind, message, {
+        status,
+        cause: err,
+        retryable: classified.retryable,
+        extensions: {
+            ...(classified.attempts === undefined ? {} : { attempts: classified.attempts }),
+            ...(classified.retryExhausted === undefined
+                ? {}
+                : { retryExhausted: classified.retryExhausted }),
+        },
+    });
+};