@plurnk/plurnk-providers 1.5.0 → 1.6.1

package/src/env.ts

@@ -8,6 +8,16 @@ export const parseRequiredInt = (raw: string | undefined, name: string, label: s
     return n;
 };
 
+export const MAX_PROVIDER_TIMEOUT_MS = 2_147_483_647;
+
+export const parseTimeoutMs = (raw: string | undefined, name: string, label: string): number => {
+    const timeoutMs = parseRequiredInt(raw, name, label);
+    if (timeoutMs > MAX_PROVIDER_TIMEOUT_MS) {
+        throw new Error(`${label} provider: ${name} must be at most ${MAX_PROVIDER_TIMEOUT_MS} milliseconds (got "${raw}")`);
+    }
+    return timeoutMs;
+};
+
 export const parseOptionalInt = (raw: string | undefined, name: string, label: string): number | null => {
     if (raw === undefined || raw.length === 0) return null;
     const n = Number(raw);
@@ -34,15 +44,6 @@ export const requireEnv = (raw: string | undefined, name: string, label: string)
     return raw;
 };
 
-export const promptCacheKeyFromEnv = (env: NodeJS.ProcessEnv, label: string): boolean => {
-    const name = "PLURNK_PROVIDERS_PROMPT_CACHE_KEY";
-    const value = env[name];
-    if (value !== "0" && value !== "1") {
-        throw new Error(`${label} provider: ${name} must be "0" or "1"`);
-    }
-    return value === "1";
-};
-
 // {§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
@@ -52,6 +53,27 @@ 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`);
 };
 
+export type CacheWritePolicy = "off" | "stable-system";
+
+export const cacheAffinityFromEnv = (env: NodeJS.ProcessEnv, label: string): boolean => {
+    const name = "PLURNK_PROVIDERS_CACHE_AFFINITY";
+    shedRenamed(env, "PLURNK_PROVIDERS_PROMPT_CACHE_KEY", name, label, "{§provider-cache-affinity}"); // lexicon-allow
+    const value = env[name];
+    if (value !== "0" && value !== "1") {
+        throw new Error(`${label} provider: ${name} must be "0" or "1"`);
+    }
+    return value === "1";
+};
+
+export const cacheWritePolicyFromEnv = (env: NodeJS.ProcessEnv, label: string): CacheWritePolicy => {
+    const name = "PLURNK_PROVIDERS_CACHE_WRITE_POLICY";
+    const value = env[name];
+    if (value !== "off" && value !== "stable-system") {
+        throw new Error(`${label} provider: ${name} must be "off" or "stable-system"`);
+    }
+    return value;
+};
+
 // {§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 —
@@ -79,8 +101,8 @@ export const contextWindowFromEnv = (env: NodeJS.ProcessEnv, label: string): num
     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.
+// {§model-fact-resolution} — an operator value caps known natural model
+// capacity and declares the envelope 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 {
@@ -91,20 +113,14 @@ export function effectiveContextWindow(operatorCap: number | null, naturalWindow
             : Math.min(operatorCap, naturalWindow);
 }
 
-// {§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. 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.
-// Per-alias suffixes override for measured envelopes; absolutes win over the
-// window derivation entirely.
-export type ReserveSpec = { percent: number } | { tokens: number };
-
-const parseReserve = (raw: string | undefined, name: string, label: string): ReserveSpec => {
-    if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set (a percentage of the window like "10%", or an absolute token count)`);
+// {§provider-generation-envelope} Generation has one total output budget. An
+// optional reasoning budget is a subset, never an additive second reserve.
+// Percentages are of the effective context window; absolutes remain useful for
+// measured local deployments. Physical model limits always cap operator policy.
+export type TokenBudgetSpec = { percent: number } | { tokens: number };
+
+const parseTokenBudget = (raw: string | undefined, name: string, label: string): TokenBudgetSpec => {
+    if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set (a percentage of the context window like "35%", or an absolute token count)`);
     const pct = /^([0-9]+(?:\.[0-9]+)?)%$/.exec(raw);
     if (pct !== null) {
         const p = Number(pct[1]);
@@ -116,37 +132,110 @@ const parseReserve = (raw: string | undefined, name: string, label: string): Res
     return { tokens: n };
 };
 
-export const envelopeFromEnv = (env: NodeJS.ProcessEnv, label: string): { reasoningReserve: ReserveSpec; completionReserve: ReserveSpec } => ({
-    reasoningReserve: parseReserve(env.PLURNK_PROVIDERS_REASONING_RESERVE, "PLURNK_PROVIDERS_REASONING_RESERVE", label),
-    completionReserve: parseReserve(env.PLURNK_PROVIDERS_COMPLETION_RESERVE, "PLURNK_PROVIDERS_COMPLETION_RESERVE", label),
-});
-
-// Resolve a ReserveSpec against a known window: absolutes stand alone; a
+// Resolve a token budget against a known window: absolutes stand alone; a
 // percentage needs the window (null when unknown — the underivable/no-cap case).
-export const resolveReserve = (spec: ReserveSpec, window: number | null): number | null =>
-    "tokens" in spec ? spec.tokens : window === null ? null : Math.round(spec.percent * window);
-
-// TOLERANT envelope read for fixtures + consumers that resolve reserves against
-// a known window and treat ABSENCE as "no claim" (null), never fail-hard —
-// unlike envelopeFromEnv (the REQUIRED provider path, fed by the shipped floor).
-// Mock uses this so the service's partition/budget suite drives the SAME
-// env→reserve resolution a real provider does, without the floor. An invalid
-// value still throws (a malformed reserve is an error, not an absence).
-export const resolveEnvelopeFromEnv = (env: NodeJS.ProcessEnv, window: number | null): { reasoningReserve: number | null; completionReserve: number | null } => {
-    const one = (raw: string | undefined, name: string): number | null =>
-        raw === undefined || raw.length === 0 ? null : resolveReserve(parseReserve(raw, name, "mock"), window);
-    return {
-        reasoningReserve: one(env.PLURNK_PROVIDERS_REASONING_RESERVE, "PLURNK_PROVIDERS_REASONING_RESERVE"),
-        completionReserve: one(env.PLURNK_PROVIDERS_COMPLETION_RESERVE, "PLURNK_PROVIDERS_COMPLETION_RESERVE"),
-    };
+export const resolveTokenBudget = (spec: TokenBudgetSpec, window: number | null): number | null =>
+    "tokens" in spec
+        ? spec.tokens
+        : window === null
+            ? null
+            : Math.max(1, Math.round(spec.percent * window));
+
+export type GenerationEnvelope = {
+    readonly outputBudget: number | null;
+    readonly reasoningBudget: number | null;
+};
+
+const shedRetiredEnvelope = (env: NodeJS.ProcessEnv, label: string): void => {
+    for (const name of ["PLURNK_PROVIDERS_REASONING_RESERVE", "PLURNK_PROVIDERS_COMPLETION_RESERVE"] as const) {
+        if (env[name] !== undefined && env[name] !== "") {
+            throw new Error(
+                `${label} provider: ${name} is retired; reasoning is now a subset of the total generation envelope. Replace the old pair with PLURNK_PROVIDERS_OUTPUT_BUDGET and optional PLURNK_PROVIDERS_REASONING_BUDGET ({§provider-generation-envelope})`,
+            );
+        }
+    }
+};
+
+const optionalTokenBudget = (
+    raw: string | undefined,
+    name: string,
+    label: string,
+): TokenBudgetSpec | null => raw === undefined || raw.length === 0
+    ? null
+    : parseTokenBudget(raw, name, label);
+
+const resolveGeneration = (
+    outputSpec: TokenBudgetSpec | null,
+    reasoningSpec: TokenBudgetSpec | null,
+    contextWindow: number | null,
+    maxOutputTokens: number | null,
+    label: string,
+): GenerationEnvelope => {
+    const requestedOutput = outputSpec === null ? null : resolveTokenBudget(outputSpec, contextWindow);
+    const physicalCaps = [contextWindow, maxOutputTokens].filter((value): value is number => value !== null);
+    const outputBudget = requestedOutput === null
+        ? null
+        : Math.min(requestedOutput, ...physicalCaps);
+    if (contextWindow !== null && outputBudget !== null && outputBudget >= contextWindow) {
+        throw new Error(
+            `${label} provider: PLURNK_PROVIDERS_OUTPUT_BUDGET (${outputBudget}) must leave positive input capacity inside the context window (${contextWindow})`,
+        );
+    }
+    const reasoningBudget = reasoningSpec === null
+        ? null
+        : resolveTokenBudget(reasoningSpec, contextWindow);
+    if (reasoningBudget !== null && outputBudget === null) {
+        throw new Error(
+            `${label} provider: PLURNK_PROVIDERS_REASONING_BUDGET requires a resolved PLURNK_PROVIDERS_OUTPUT_BUDGET; reasoning is a subset of total output`,
+        );
+    }
+    if (reasoningBudget !== null && outputBudget !== null && reasoningBudget >= outputBudget) {
+        throw new Error(
+            `${label} provider: PLURNK_PROVIDERS_REASONING_BUDGET (${reasoningBudget}) exceeds the effective PLURNK_PROVIDERS_OUTPUT_BUDGET (${outputBudget}); reasoning is a subset of total output`,
+        );
+    }
+    return { outputBudget, reasoningBudget };
+};
+
+// Standard providers receive the shipped OUTPUT_BUDGET floor and fail hard if
+// it is absent. Mock uses the tolerant sibling below so ordinary unit fixtures
+// make no generation claim unless a test deliberately configures one.
+export const generationEnvelopeFromEnv = (
+    env: NodeJS.ProcessEnv,
+    label: string,
+    contextWindow: number | null,
+    maxOutputTokens: number | null,
+): GenerationEnvelope => {
+    shedRetiredEnvelope(env, label);
+    return resolveGeneration(
+        parseTokenBudget(env.PLURNK_PROVIDERS_OUTPUT_BUDGET, "PLURNK_PROVIDERS_OUTPUT_BUDGET", label),
+        optionalTokenBudget(env.PLURNK_PROVIDERS_REASONING_BUDGET, "PLURNK_PROVIDERS_REASONING_BUDGET", label),
+        contextWindow,
+        maxOutputTokens,
+        label,
+    );
+};
+
+export const resolveGenerationEnvelopeFromEnv = (
+    env: NodeJS.ProcessEnv,
+    contextWindow: number | null,
+    maxOutputTokens: number | null = null,
+): GenerationEnvelope => {
+    shedRetiredEnvelope(env, "mock");
+    return resolveGeneration(
+        optionalTokenBudget(env.PLURNK_PROVIDERS_OUTPUT_BUDGET, "PLURNK_PROVIDERS_OUTPUT_BUDGET", "mock"),
+        optionalTokenBudget(env.PLURNK_PROVIDERS_REASONING_BUDGET, "PLURNK_PROVIDERS_REASONING_BUDGET", "mock"),
+        contextWindow,
+        maxOutputTokens,
+        "mock",
+    );
 };
 
 // {§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-server it is the explicit
-//     request-scoped allowance and cannot exceed the physical reasoning reserve.
+//   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 intended-goals record.
 export type ReasoningMode = "off" | "adaptive" | "on";
@@ -167,20 +256,18 @@ export const reasoningResponseStyleFromEnv = (
     return raw;
 };
 
-export const reasoningFromEnv = (env: NodeJS.ProcessEnv, label: string): Reasoning => {
+export const reasoningFromEnv = (
+    env: NodeJS.ProcessEnv,
+    label: string,
+    resolvedBudget: number | null = null,
+): Reasoning => {
     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)`);
     if (raw !== "off" && raw !== "adaptive" && raw !== "on") throw new Error(`${label} provider: ${name} must be one of "off", "adaptive", "on" (got "${raw}")`);
-    if (raw !== "on") return { mode: raw, budget: null };
-    const capName = "PLURNK_PROVIDERS_REASONING_BUDGET";
-    const capRaw = env[capName];
-    if (capRaw === undefined || capRaw.length === 0) throw new Error(`${label} provider: ${capName} must be set when ${name}=on`);
-    const n = Number(capRaw);
-    if (!Number.isInteger(n) || n <= 0) throw new Error(`${label} provider: ${capName} must be a positive integer (got "${capRaw}")`);
-    return { mode: "on", budget: n };
+    return { mode: raw, budget: raw === "off" ? null : resolvedBudget };
 };
 
 // ── Per-alias knob scoping (per-alias scoping doctrine, user 2026-07-03): PLURNK_PROVIDERS_<KNOB>[_<alias>] ──
@@ -191,22 +278,24 @@ export const reasoningFromEnv = (env: NodeJS.ProcessEnv, label: string): Reasoni
 // facts (API keys, canonical endpoints) remain vendor-named; the per-alias
 // endpoint override stays PLURNK_BASEURL_<alias> (its existing precedent).
 export const PROVIDERS_KNOBS = Object.freeze([
-    "PLURNK_PROVIDERS_REASONING_RESERVE",
-    "PLURNK_PROVIDERS_COMPLETION_RESERVE",
+    "PLURNK_PROVIDERS_OUTPUT_BUDGET",
     "PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE",
     "PLURNK_PROVIDERS_REASONING_BUDGET",
     "PLURNK_PROVIDERS_REASONING",
     "PLURNK_PROVIDERS_CONTEXT_WINDOW",
     "PLURNK_PROVIDERS_RETRY_ATTEMPTS",
     "PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT",
+    "PLURNK_PROVIDERS_OPERATION_TIMEOUT",
     "PLURNK_PROVIDERS_FETCH_TIMEOUT",
+    "PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT",
     "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT",
     "PLURNK_PROVIDERS_LLAMA_SERVER",
     "PLURNK_PROVIDERS_TEMPERATURE",
     "PLURNK_PROVIDERS_REPEAT_PENALTY",
     "PLURNK_PROVIDERS_FREQUENCY_PENALTY",
     "PLURNK_PROVIDERS_SERVICE_TIER",
-    "PLURNK_PROVIDERS_PROMPT_CACHE_KEY",
+    "PLURNK_PROVIDERS_CACHE_WRITE_POLICY",
+    "PLURNK_PROVIDERS_CACHE_AFFINITY",
     "PLURNK_PROVIDERS_REPEAT_LAST_N",
     "PLURNK_PROVIDERS_DRY_MULTIPLIER",
     "PLURNK_PROVIDERS_DRY_BASE",
@@ -225,10 +314,9 @@ export const PROVIDERS_KNOBS = Object.freeze([
 // single overlay.
 //
 // `knobs` (optional) lets a CONSUMER scope its OWN closed knob list with this
-// same parser — e.g. the service's window-partition vars (PLURNK_SERVICE_CONTEXT_WINDOW/
-// MAX_TURNS/...), so a 64k cloud envelope and a 12k gemma envelope
-// coexist per-alias without the service reimplementing the suffix/collision
-// rules. Default stays the providers-family list; my call sites pass nothing.
+// same parser — e.g. service loop policy or prompt projection — without
+// reimplementing the suffix/collision rules. Default stays the
+// providers-family list; provider call sites pass nothing.
 export const scopeEnvToAlias = (env: NodeJS.ProcessEnv, alias: string, knobs: readonly string[] = PROVIDERS_KNOBS): NodeJS.ProcessEnv => {
     const folded = alias.toLowerCase();
     const out: NodeJS.ProcessEnv = { ...env };

package/src/errors.test.ts

@@ -1,7 +1,7 @@
 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 { ProviderError, ProviderTimeoutError, classifyProviderError, toProviderError } from "./errors.ts";
 import type { ProviderAttempt } from "./types.ts";
 import { providerSource } from "./notices.ts";
 
@@ -29,12 +29,46 @@ test("classifyProviderError maps HTTP status to kind", () => {
     assert.equal(k(403), "unauthorized");
     assert.equal(k(402), "quota_exceeded");
     assert.equal(k(429), "rate_limit");
+    assert.equal(k(408), "network_failure");
+    assert.equal(k(409), "network_failure");
     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");
 });
 
+test("capacity normalization prefers structured provider codes and keeps generic 400s distinct", () => {
+    const openai = apiError(400, JSON.stringify({
+        error: {
+            type: "invalid_request_error",
+            code: "context_length_exceeded",
+            message: "maximum context length exceeded",
+        },
+    }));
+    assert.equal(classifyProviderError(openai).kind, "capacity_exceeded");
+    const normalized = toProviderError(openai, "provider:openai");
+    assert.equal(normalized.status, 413);
+    assert.equal(normalized.problem.capacityStage, "upstream");
+    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");
+});
+
+test("provider retry directives survive HTTP failure normalization", () => {
+    const final = new APICallError({
+        message: "edge router says not to replay",
+        url: "https://example.test/v1/chat/completions",
+        requestBodyValues: {},
+        statusCode: 524,
+        isRetryable: false,
+    });
+    const error = toProviderError(final, "provider:test");
+    assert.equal(error.kind, "network_failure");
+    assert.equal(error.problem.retryable, false);
+});
+
 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");
@@ -75,11 +109,31 @@ test("#161: ProviderError carries resource-interrupted attempt evidence outside
         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" },
+        accounting: [{
+            provider: "provider:deepseek",
+            model: "served-model",
+            outcome: "response",
+            usage: { inputTokens: 3, outputTokens: 1, totalTokens: 4 },
+            cost: { kind: "unknown", reason: "fixture has no monetary evidence" },
+        }],
+        capacity: {
+            decision: "defer",
+            contextWindow: null,
+            maxInputTokens: null,
+            maxOutputTokens: null,
+            outputBudget: null,
+            reasoningBudget: null,
+            inputCapacity: null,
+            prompt: {
+                kind: "unavailable",
+                source: "fixture",
+                detail: "the interrupted fixture has no preflight measurement",
+            },
+        },
     } as ProviderAttempt;
     const error = new ProviderError(
         "provider:deepseek",
@@ -96,6 +150,7 @@ test("#161: ProviderError carries resource-interrupted attempt evidence outside
     );
 
     assert.equal(error.attempt, attempt);
+    assert.deepEqual(error.accounting, attempt.accounting);
     assert.deepEqual(error.problem, {
         type: "https://problems.plurnk.dev/provider/deepseek/resource-interrupted",
         title: "Resource interrupted",
@@ -146,3 +201,26 @@ test("retry exhaustion is explicit and does not recommend another automatic repl
     assert.equal(error.problem.retryExhausted, true);
     assert.equal(error.cause, cause);
 });
+
+test("retry exhaustion retains the exact inner deadline phase", () => {
+    const failures = [1, 2].map(() => new APICallError({
+        message: "attempt timed out",
+        url: "https://example.test/v1/chat/completions",
+        requestBodyValues: {},
+        cause: new ProviderTimeoutError("attempt", 10),
+        isRetryable: true,
+    }));
+    const cause = new RetryError({
+        message: "Failed after 2 attempts.",
+        reason: "maxRetriesExceeded",
+        errors: failures,
+    });
+    const error = toProviderError(cause, "provider:test");
+    assert.equal(error.kind, "network_failure");
+    assert.equal(error.status, 503);
+    assert.equal(error.problem.retryable, false);
+    assert.equal(error.problem.attempts, 2);
+    assert.equal(error.problem.retryExhausted, true);
+    assert.equal(error.problem.timeoutPhase, "attempt");
+    assert.equal(error.problem.timeoutMs, 10);
+});

package/src/errors.ts

@@ -1,16 +1,18 @@
 import { Problems, type ProblemDetails } from "@plurnk/plurnk-contracts";
 import { APICallError, RetryError } from "ai";
 import { providerSource } from "./notices.ts";
-import type { ProviderAttempt } from "./types.ts";
+import type { ProviderAttempt, ProviderRequestAccounting, ProviderRequestCapacity } from "./types.ts";
 
 export type ProviderErrorKind =
     | "rate_limit"
     | "network_failure"
+    | "deadline_exceeded"
     | "model_refused"
     | "invalid_response"
     | "unauthorized"
     | "quota_exceeded"
     | "grammar_invalid"
+    | "capacity_exceeded"
     | "resource_interrupted";
 
 export interface ClassifiedProviderError {
@@ -19,16 +21,50 @@ export interface ClassifiedProviderError {
     retryable?: boolean;
     attempts?: number;
     retryExhausted?: boolean;
+    extensions?: Readonly<Record<string, unknown>>;
 }
 
+export type ProviderTimeoutPhase = "attempt" | "first_content" | "stream_idle" | "operation";
+
+export class ProviderTimeoutError extends Error {
+    readonly phase: ProviderTimeoutPhase;
+    readonly timeoutMs: number;
+
+    constructor(phase: ProviderTimeoutPhase, timeoutMs: number, cause?: unknown) {
+        const labels: Record<ProviderTimeoutPhase, string> = {
+            attempt: "Provider attempt",
+            first_content: "First provider content",
+            stream_idle: "Provider stream idle",
+            operation: "Provider operation",
+        };
+        super(`${labels[phase]} exceeded its ${timeoutMs} ms deadline.`, cause === undefined ? undefined : { cause });
+        this.name = "ProviderTimeoutError";
+        this.phase = phase;
+        this.timeoutMs = timeoutMs;
+    }
+}
+
+export const providerTimeoutOf = (error: unknown): ProviderTimeoutError | null => {
+    const seen = new Set<unknown>();
+    let current = error;
+    while (typeof current === "object" && current !== null && !seen.has(current)) {
+        if (current instanceof ProviderTimeoutError) return current;
+        seen.add(current);
+        current = (current as { cause?: unknown }).cause;
+    }
+    return null;
+};
+
 const defaultStatus = (kind: ProviderErrorKind): number => {
     switch (kind) {
         case "unauthorized": return 401;
         case "quota_exceeded": return 402;
+        case "capacity_exceeded": return 413;
         case "rate_limit": return 429;
         case "model_refused":
         case "grammar_invalid": return 422;
         case "invalid_response": return 502;
+        case "deadline_exceeded": return 504;
         case "network_failure":
         case "resource_interrupted": return 503;
     }
@@ -39,8 +75,10 @@ const retryable = (kind: ProviderErrorKind): boolean => {
         case "rate_limit":
         case "network_failure":
             return true;
+        case "deadline_exceeded":
         case "invalid_response":
         case "grammar_invalid":
+        case "capacity_exceeded":
         case "resource_interrupted":
         case "model_refused":
         case "unauthorized":
@@ -60,11 +98,13 @@ const buildProblem = (
     const code: Record<ProviderErrorKind, string> = {
         rate_limit: "rate-limit",
         network_failure: "network-failure",
+        deadline_exceeded: "deadline-exceeded",
         model_refused: "model-refused",
         invalid_response: "invalid-response",
         unauthorized: "unauthorized",
         quota_exceeded: "quota-exceeded",
         grammar_invalid: "grammar-invalid",
+        capacity_exceeded: "capacity-exceeded",
         resource_interrupted: "resource-interrupted",
     };
     return Problems.create(source, code[kind], status, message, {
@@ -84,6 +124,8 @@ export class ProviderError extends Error {
     readonly kind: ProviderErrorKind;
     readonly problem: ProblemDetails;
     readonly attempt?: ProviderAttempt;
+    readonly capacity?: ProviderRequestCapacity;
+    #accounting: ProviderRequestAccounting[];
 
     constructor(
         source: string,
@@ -95,6 +137,8 @@ export class ProviderError extends Error {
             retryable?: boolean;
             extensions?: Readonly<Record<string, unknown>>;
             attempt?: ProviderAttempt;
+            accounting?: readonly ProviderRequestAccounting[];
+            capacity?: ProviderRequestCapacity;
         } = {},
     ) {
         super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
@@ -102,6 +146,8 @@ export class ProviderError extends Error {
         this.source = providerSource(source);
         this.kind = kind;
         this.attempt = options.attempt;
+        this.capacity = options.capacity ?? options.attempt?.capacity;
+        this.#accounting = [...(options.accounting ?? options.attempt?.accounting ?? [])];
         const status = options.status !== null && options.status !== undefined
             && Number.isInteger(options.status) && options.status >= 400 && options.status <= 599
             ? options.status
@@ -119,17 +165,35 @@ export class ProviderError extends Error {
     get status(): number {
         return this.problem.status;
     }
+
+    get accounting(): readonly ProviderRequestAccounting[] {
+        return this.#accounting;
+    }
+
+    // A capacity pool adds the already-settled requests from prior backends as
+    // the same failure crosses that orchestration boundary.
+    prependAccounting(accounting: readonly ProviderRequestAccounting[]): void {
+        if (accounting.length > 0) this.#accounting = [...accounting, ...this.#accounting];
+    }
 }
 
-const wireErrorType = (body: string): string | null => {
+const wireError = (body: string): { type: string | null; code: string | null; message: string | null } => {
     try {
         const { error } = JSON.parse(body) as { error?: { type?: unknown } };
-        return typeof error?.type === "string" ? error.type : null;
+        const record = error as { type?: unknown; code?: unknown; message?: unknown } | undefined;
+        return {
+            type: typeof record?.type === "string" ? record.type : null,
+            code: typeof record?.code === "string" || typeof record?.code === "number" ? String(record.code) : null,
+            message: typeof record?.message === "string" ? record.message : null,
+        };
     } catch {
-        return null;
+        return { type: null, code: null, message: null };
     }
 };
 
+const CAPACITY_CODE = /^(?:context_length_exceeded|context_window_exceeded|input_too_long|prompt_too_long|request_too_large|token_limit_exceeded|max_tokens_exceeded)$/i;
+const CAPACITY_MESSAGE = /(?:maximum context length|context (?:length|window).*(?:exceed|too (?:large|long)|maximum)|(?:input|prompt|request).*(?:token|length|size).*(?:exceed|too (?:large|long)|maximum))/i;
+
 const preview = (value: unknown, limit: number | undefined): string => {
     const text = value instanceof Error ? value.message : String(value);
     return limit !== undefined && text.length > limit
@@ -150,17 +214,46 @@ export const classifyProviderError = (
         };
     }
     if (APICallError.isInstance(err)) {
+        const timeout = providerTimeoutOf(err);
+        if (timeout !== null) {
+            return {
+                kind: "network_failure",
+                message: timeout.message,
+                extensions: {
+                    timeoutPhase: timeout.phase,
+                    timeoutMs: timeout.timeoutMs,
+                },
+            };
+        }
         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 ?? "";
+        const wire = wireError(body);
         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 === 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 };
-        if (status >= 500) return { kind: "network_failure", message };
-        if (status === 422 && wireErrorType(body) === "grammar_invalid") {
+        if (status >= 500) return { kind: "network_failure", message, retryable: err.isRetryable };
+        if (status === 413 || (
+            (status === 400 || status === 422)
+            && (
+                (wire.code !== null && CAPACITY_CODE.test(wire.code))
+                || (wire.type !== null && CAPACITY_CODE.test(wire.type))
+                || CAPACITY_MESSAGE.test(wire.message ?? message)
+            )
+        )) {
+            return {
+                kind: "capacity_exceeded",
+                message,
+                extensions: status === 413 ? undefined : { providerStatus: status },
+            };
+        }
+        if (status === 422 && wire.type === "grammar_invalid") {
             return { kind: "grammar_invalid", message };
         }
         return { kind: "invalid_response", message };
@@ -188,21 +281,27 @@ export const toProviderError = (
     err: unknown,
     source: string,
     detailLimit?: number,
+    capacity?: ProviderRequestCapacity,
 ): 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;
+    const upstreamStatus = APICallError.isInstance(underlying) ? underlying.statusCode ?? null : null;
+    const status = kind === "capacity_exceeded" ? 413 : upstreamStatus;
     return new ProviderError(source, kind, message, {
         status,
         cause: err,
         retryable: classified.retryable,
         extensions: {
+            ...(classified.extensions ?? {}),
+            ...(kind === "capacity_exceeded" ? { capacityStage: "upstream" } : {}),
+            ...(capacity === undefined ? {} : { capacity }),
             ...(classified.attempts === undefined ? {} : { attempts: classified.attempts }),
             ...(classified.retryExhausted === undefined
                 ? {}
                 : { retryExhausted: classified.retryExhausted }),
         },
+        capacity,
     });
 };