@linxiraos/pi-ai 1.0.0

package/src/error/gateway.ts

@@ -0,0 +1,96 @@
+import { isUsageLimit } from "./flags";
+
+/** A gateway-facing classification of an arbitrary upstream/internal error. */
+export interface GatewayErrorClassification {
+	status: number;
+	type: string;
+	message: string;
+}
+
+/**
+ * Classify an upstream / gateway-internal error into a status code and a
+ * format-neutral type. The order is intentional:
+ *
+ *  1. Honour an explicit numeric `status` property on the thrown error.
+ *  2. Parse a status code embedded in the message string. Provider errors
+ *     virtually always carry one (`Google API error (400): …`, `HTTP 429`,
+ *     `status=503`) and the embedded value is authoritative.
+ *  3. Fall through to **word-boundaried** substring heuristics. The old
+ *     `lower.includes("rate")` test famously matched `GenerateContentRequest`,
+ *     surfacing every Google 400 as a 429 `rate_limit_error`. The patterns here
+ *     all require boundaries so they don't collide with provider field names.
+ */
+export function classifyGatewayError(err: unknown): GatewayErrorClassification {
+	const message = err instanceof Error ? err.message : String(err);
+
+	// 1. Custom pi-ai errors may attach a numeric `status` property.
+	const statusProp =
+		typeof err === "object" && err !== null && typeof (err as { status?: unknown }).status === "number"
+			? (err as { status: number }).status | 0
+			: undefined;
+	if (statusProp !== undefined) return bucketStatus(statusProp, message);
+
+	if (err instanceof Error && err.name === "AbortError") return { status: 499, type: "request_aborted", message };
+
+	// 2. Status code embedded in the message. Requires a contextual keyword
+	// (`HTTP`, `API error`, `status`, …) or a leading `(NNN)` token so we
+	// don't trip on incidental three-digit numbers ("took 200ms").
+	const embedded = extractEmbeddedStatus(message);
+	if (embedded !== undefined) return bucketStatus(embedded, message);
+
+	// 3. Word-boundaried substring heuristics.
+	if (/\baborted\b|\babort signal\b/i.test(message)) {
+		return { status: 499, type: "request_aborted", message };
+	}
+	if (
+		// Match rate-limit phrasings before auth wording: some providers
+		// describe throttling as "unauthorized due to rate limit".
+		// Keep boundaries so this does not collide with
+		// `GenerateContentRequest`, `accelerate`, `iterate`, `deprecated`, etc.
+		/\brate[- _]?limit(?:s|ed|ing)?\b|\bquota(?:_exceeded| exceeded)?\b|\btoo[- _]many[- _]requests\b/i.test(
+			message,
+		) ||
+		// Usage-limit phrasings emit no embedded status. Codex friendly text
+		// reads "You have hit your ChatGPT usage limit … Try again in ~158
+		// min."; the central usage-limit classifier already encodes every known
+		// provider variant, so reuse it instead of forking the regex. Without
+		// this branch the classifier falls through to the default
+		// 502/upstream_error, which is what callers saw when their account
+		// hit its cap.
+		isUsageLimit(message)
+	) {
+		return { status: 429, type: "rate_limit_error", message };
+	}
+	if (/\b(?:unauthorized|forbidden)\b/i.test(message)) {
+		return { status: 401, type: "authentication_error", message };
+	}
+	if (/\b(?:unsupported|invalid_request|invalid request|bad request|malformed)\b/i.test(message)) {
+		return { status: 400, type: "invalid_request_error", message };
+	}
+	return { status: 502, type: "upstream_error", message };
+}
+
+function bucketStatus(status: number, message: string): GatewayErrorClassification {
+	if (status === 401 || status === 403) return { status, type: "authentication_error", message };
+	if (status === 429) return { status, type: "rate_limit_error", message };
+	if (status >= 400 && status < 500) return { status, type: "invalid_request_error", message };
+	if (status >= 500) return { status, type: "upstream_error", message };
+	return { status: 502, type: "upstream_error", message };
+}
+
+/**
+ * Pull a status code from common error-message shapes. Returns undefined when
+ * no contextual keyword is present, so we never guess at incidental numbers.
+ */
+function extractEmbeddedStatus(message: string): number | undefined {
+	// `Google API error (400)`, `OpenAI API error (429): …`, `(503)`
+	// `HTTP 429: too many requests`
+	// `status: 503`, `status_code=429`, `status=400`
+	const re = /(?:\bHTTP\b|\bAPI error\b|\bstatus(?:[- _]?code)?\b)\s*[:=]?\s*\(?\s*(\d{3})\b|\((\d{3})\)/i;
+	const m = message.match(re);
+	if (!m) return undefined;
+	const raw = m[1] ?? m[2];
+	if (!raw) return undefined;
+	const code = Number.parseInt(raw, 10);
+	return Number.isFinite(code) && code >= 100 && code < 600 ? code : undefined;
+}

package/src/error/index.ts

@@ -0,0 +1,14 @@
+export * from "./abort";
+export * from "./auth";
+export * from "./auth-classify";
+export * from "./aws";
+export * from "./classes";
+export * from "./finalize";
+export * from "./flags";
+export * from "./format";
+export * from "./gateway";
+export * from "./oauth";
+export * from "./provider";
+export * from "./rate-limit";
+export * from "./retryable";
+export * from "./validation";

package/src/error/oauth.ts

@@ -0,0 +1,58 @@
+import { attach, create, Flag } from "./flags";
+
+/**
+ * What stage of an OAuth / device-code login flow failed. Discriminates the
+ * single {@link OAuthError} class so login flows don't each mint a bespoke
+ * error type.
+ */
+export type OAuthErrorKind =
+	/** Token-exchange / refresh / discovery HTTP response was non-2xx or unparseable. */
+	| "http"
+	/** Response body was missing required fields (token, account id, endpoints, …). */
+	| "validation"
+	/** Authorization-code → token exchange failed. */
+	| "token-exchange"
+	/** Refresh-token grant failed. */
+	| "token-refresh"
+	/** Device-code / authorization polling failed (server error, too many retries). */
+	| "polling"
+	/** The flow exceeded its deadline (device-code expiry, polling timeout). */
+	| "timeout"
+	/** Device authorization was denied or cancelled by the user/provider. */
+	| "device-auth"
+	/** Misconfiguration (bad redirect URI, missing projectId, callback bind, …). */
+	| "configuration"
+	/** Cloud project provisioning / onboarding (loadCodeAssist, onboardUser). */
+	| "provisioning"
+	/** OIDC / endpoint discovery failed. */
+	| "discovery";
+
+export interface OAuthErrorOptions {
+	kind?: OAuthErrorKind;
+	provider?: string;
+	status?: number;
+	cause?: unknown;
+}
+
+/**
+ * A failure inside an interactive OAuth / device-code login flow. The `kind`
+ * pinpoints the stage. Timeout/polling are classified transient; everything
+ * else is a hard auth failure so the credential layer does not silently retry.
+ */
+export class OAuthError extends Error {
+	readonly kind: OAuthErrorKind;
+	readonly provider: string | undefined;
+	readonly status: number | undefined;
+
+	constructor(message: string, options: OAuthErrorOptions = {}) {
+		super(message, options.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "OAuthError";
+		this.kind = options.kind ?? "http";
+		this.provider = options.provider;
+		this.status = options.status;
+		attach(
+			this,
+			this.kind === "timeout" || this.kind === "polling" ? create(Flag.Transient) : create(Flag.AuthFailed),
+		);
+	}
+}

package/src/error/provider.ts

@@ -0,0 +1,63 @@
+import { ProviderHttpError } from "./classes";
+import { attach, create, Flag } from "./flags";
+
+/** Which part of a provider exchange produced a non-HTTP error. */
+export type ProviderResponseErrorKind =
+	/** Stream closed before a terminal completion/response event. */
+	| "incomplete-stream"
+	/** Terminal event carried an error / unexpected stop reason. */
+	| "output"
+	/** Response body was empty/missing when content was required. */
+	| "empty-body"
+	/** Malformed wire envelope (unexpected message ordering / shape). */
+	| "envelope"
+	/** Content was blocked by a provider safety filter. */
+	| "content-blocked"
+	/** Runtime/namespace resolution or other provider-internal failure. */
+	| "runtime";
+
+export interface ProviderResponseErrorOptions {
+	provider?: string;
+	kind?: ProviderResponseErrorKind;
+	cause?: unknown;
+}
+
+/**
+ * A non-HTTP provider failure: a truncated stream, an error stop reason, an
+ * empty body, a malformed envelope, or a runtime fault. For non-2xx HTTP
+ * responses use {@link ProviderHttpError} (or a provider subclass) instead.
+ */
+export class ProviderResponseError extends Error {
+	readonly provider: string | undefined;
+	readonly kind: ProviderResponseErrorKind;
+
+	constructor(message: string, options: ProviderResponseErrorOptions = {}) {
+		super(message, options.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "ProviderResponseError";
+		this.provider = options.provider;
+		this.kind = options.kind ?? "output";
+		// A safety filter block is terminal and intentionally non-retryable.
+		if (this.kind === "content-blocked") attach(this, create(Flag.ContentBlocked));
+		// An incomplete stream (connection dropped / truncated before any terminal
+		// event) or an empty body never produced any content — the request didn't
+		// complete, so it is safe to retry and eligible for model fallback. The
+		// retry layer's replay-unsafe guard still blocks a retry when partial tool
+		// output was already emitted.
+		else if (this.kind === "incomplete-stream" || this.kind === "empty-body") attach(this, create(Flag.Transient));
+	}
+}
+
+/** Non-2xx response from the Devin API. */
+export class DevinApiError extends ProviderHttpError {
+	override readonly name = "DevinApiError";
+}
+
+/** Non-2xx response from the GitLab Duo direct-access API. */
+export class GitLabDuoApiError extends ProviderHttpError {
+	override readonly name = "GitLabDuoApiError";
+}
+
+/** Non-2xx response from the GitLab Duo Workflow API. */
+export class GitLabDuoWorkflowApiError extends ProviderHttpError {
+	override readonly name = "GitLabDuoWorkflowApiError";
+}

package/src/error/rate-limit.ts

@@ -0,0 +1,303 @@
+/**
+ * Rate limit reason classification and backoff calculation utilities.
+ * Ported from opencode-antigravity-auth plugin for consistency.
+ */
+
+export type RateLimitReason =
+	| "QUOTA_EXHAUSTED"
+	| "RATE_LIMIT_EXCEEDED"
+	| "CONCURRENT_LIMIT"
+	| "MODEL_CAPACITY_EXHAUSTED"
+	| "SERVER_ERROR"
+	| "UNKNOWN";
+
+const QUOTA_EXHAUSTED_BACKOFF_MS = 30 * 60 * 1000; // 30 min
+const RATE_LIMIT_EXCEEDED_BACKOFF_MS = 30 * 1000; // 30s
+const CONCURRENT_LIMIT_BACKOFF_MS = 5 * 1000; // 5s
+const MODEL_CAPACITY_BASE_MS = 45 * 1000; // 45s base
+const MODEL_CAPACITY_JITTER_MS = 30 * 1000; // ±15s
+const SERVER_ERROR_BACKOFF_MS = 20 * 1000; // 20s
+
+const ACCOUNT_RATE_LIMIT_PATTERN =
+	/\baccount(?:'s)?\b[^\n]{0,80}\brate.?limit\b|\brate.?limit\b[^\n]{0,80}\baccount\b/i;
+const INSUFFICIENT_BALANCE_PATTERN = /insufficient.?balance/i;
+const SPEND_LIMIT_PATTERN = /spend.?limit/i;
+const SUBSCRIPTION_CAP_PATTERN =
+	/\b(?:subscription|plan|membership)\b[^\n]{0,80}\b(?:rate.?limits?|quota|cap)\b|\b(?:rate.?limits?|quota|cap)\b[^\n]{0,80}\b(?:subscription|plan|membership)\b/i;
+const TRANSIENT_INTERVAL_RATE_LIMIT_PATTERN = /\bper\s+(?:second|minute)\b/i;
+
+function matchesSubscriptionCapText(errorMessage: string): boolean {
+	return SUBSCRIPTION_CAP_PATTERN.test(errorMessage) && !TRANSIENT_INTERVAL_RATE_LIMIT_PATTERN.test(errorMessage);
+}
+const OPENROUTER_DAILY_FREE_LIMIT_PATTERN = /\bfree[-_ ]models[-_ ]per[-_ ]day\b/i;
+// gRPC/Connect end-streams carry the status as its name (`resource_exhausted`),
+// while HTTP bodies use the phrase ("resource exhausted"). Strip either form
+// before classifying explicit details; an otherwise opaque status is transient
+// model capacity, while quota/rate-limit/server wording remains authoritative.
+const RESOURCE_EXHAUSTED_PATTERN = /resource.?exhausted/gi;
+const CONCURRENT_LIMIT_PATTERN =
+	// Require an actual cap signal near "concurrent". "Too many concurrent
+	// requests" is itself a cap signal; bare feature rejections such as
+	// "concurrent invocation is not supported" remain excluded.
+	/\btoo many\s+concurren\w*\s+(?:requests?|invocations?)\b|\bconcurren\w*\b[^\n]{0,60}\b(?:limit|quota|exceed\w*|reach\w*)\b|\b(?:limit|quota|exceed\w*|reach\w*)\b[^\n]{0,60}\bconcurren\w*\b|\bconcurren[a-z]*[-_](?:[a-z]+[_-])*(?:limit|quota|exceed\w*|reach\w*)/i;
+const ACCOUNT_SCOPED_403_PATTERN =
+	// The bare "limit will reset" / "will reset in" phrasing also appears on
+	// statusless per-minute transients ("Rate limit will reset in 30 seconds"),
+	// so gate the reset-window alternative on account-specific wording (Devin's
+	// "Your limit will reset in …"); the overall/account qualifiers arm above
+	// already covers the rest.
+	/\b(?:overall|account|organization|team|workspace)\b[^\n]{0,40}\b(?:message |request )?rate.?limit\b|\byour\b[^\n]{0,30}\b(?:limit )?will reset\b/i;
+// Simplified Chinese account-quota exhaustion phrasing. Zhipu Coding Plan
+// returns e.g. "429 已达到 5 小时的使用上限。您的限额将在 2026-08-06 20:06:00 重置。"
+// (type=1308) when the 5h window is spent; other CN providers use 额度已用完 /
+// 配额已耗尽 / 余额不足. These are persistent account-local caps that must
+// rotate to a sibling credential, not transient rate limits, so they are
+// matched before the RATE_LIMIT_EXCEEDED branch. The 上限 arm is anchored on
+// the 使用 token: a rate/concurrency cap phrased as 每分钟请求数已达上限 /
+// 并发请求数已达上限 / 速率达到上限 (no 使用) must NOT match, or it would burn a
+// healthy sibling credential as a false quota. "速率限制" is absent for the
+// same reason.
+const CN_QUOTA_EXHAUSTED_PATTERN = /使用.{0,30}?上限|(?:额度|配额)已?(?:用|耗)(?:完|尽)|限额.{0,30}重置|余额不足/;
+// Simplified Chinese rate/concurrency caps can contain both 使用 and 上限, but
+// remain transient rather than account quota exhaustion.
+const CN_TRANSIENT_CAP_PATTERN =
+	/速率.{0,30}上限|频率.{0,30}上限|每分钟.{0,30}上限|并发.{0,30}上限|使用.{0,30}(?:速率|频率|每分钟|并发).{0,30}上限/;
+// Common Simplified Chinese throttle phrasing. Consulted by
+// isOpaqueStatusBody so CN transients stay in the provider backoff lane instead
+// of rotating through the opaque-429 fallback.
+const CN_THROTTLE_PATTERN = /速率(?:限制|过快)|频率(?:过高|过快)|过于频繁|稍后[重再]试/;
+
+/**
+ * Classify a rate-limit error message into a reason category.
+ * Priority order: explicit details in a resource-exhausted error > QUOTA
+ * (Antigravity "quota will reset") > CONCURRENT_LIMIT > MODEL_CAPACITY >
+ * QUOTA (account) > RATE_LIMIT > QUOTA (generic) > SERVER_ERROR > bare resource-exhausted > UNKNOWN.
+ *
+ * Bare "resource exhausted" / "resource_exhausted" maps to MODEL_CAPACITY (transient, short wait).
+ * Explicit details such as "quota exceeded" retain their normal classification.
+ */
+export function parseRateLimitReason(errorMessage: string): RateLimitReason {
+	const lowerWithStatus = errorMessage.toLowerCase();
+	const lower = lowerWithStatus.replace(RESOURCE_EXHAUSTED_PATTERN, "");
+	const hasResourceExhaustedStatus = lower !== lowerWithStatus;
+
+	// Antigravity / Cloud Code Assist surface multi-hour daily-quota exhaustion as
+	// "You have exhausted your capacity on this model. Your quota will reset after …".
+	// The literal "capacity" used to pre-empt the QUOTA branch even though "quota
+	// will reset" is the long-wait signal — short-circuit here before the
+	// MODEL_CAPACITY fallthrough so credential rotation (not 60s backoff) kicks in.
+	if (lower.includes("quota will reset") || lower.includes("exhausted your capacity")) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	// Simplified Chinese quota-exhaustion phrasing (Zhipu Coding Plan and other
+	// CN providers). Must precede the MODEL_CAPACITY / RATE_LIMIT branches so an
+	// account-local cap rotates instead of backing off as a transient.
+	if (CN_QUOTA_EXHAUSTED_PATTERN.test(errorMessage) && !CN_TRANSIENT_CAP_PATTERN.test(errorMessage)) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (CONCURRENT_LIMIT_PATTERN.test(errorMessage)) {
+		return "CONCURRENT_LIMIT";
+	}
+
+	if (lower.includes("capacity") || lower.includes("overloaded") || lower.includes("529") || lower.includes("503")) {
+		return "MODEL_CAPACITY_EXHAUSTED";
+	}
+
+	if (ACCOUNT_RATE_LIMIT_PATTERN.test(errorMessage)) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (SPEND_LIMIT_PATTERN.test(errorMessage)) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (matchesSubscriptionCapText(errorMessage)) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (OPENROUTER_DAILY_FREE_LIMIT_PATTERN.test(errorMessage)) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (
+		lower.includes("per minute") ||
+		lower.includes("rate limit") ||
+		lower.includes("too many requests") ||
+		lower.includes("presque")
+	) {
+		return "RATE_LIMIT_EXCEEDED";
+	}
+
+	if (
+		lower.includes("exhausted") ||
+		lower.includes("quota") ||
+		lower.includes("usage limit") ||
+		// xAI SuperGrok: HTTP 403 "run out of credits" / spending-limit is an
+		// account-local cap — rotate, don't treat as auth failure.
+		lower.includes("run out of credits") ||
+		lower.includes("out of credits") ||
+		lower.includes("spending-limit") ||
+		lower.includes("spending limit") ||
+		INSUFFICIENT_BALANCE_PATTERN.test(errorMessage)
+	) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (lower.includes("500") || lower.includes("internal error") || lower.includes("internal server error")) {
+		return "SERVER_ERROR";
+	}
+
+	if (hasResourceExhaustedStatus) {
+		return "MODEL_CAPACITY_EXHAUSTED";
+	}
+
+	return "UNKNOWN";
+}
+
+/**
+ * Calculate backoff delay in ms for a given rate limit reason.
+ * MODEL_CAPACITY gets jitter to prevent thundering herd.
+ */
+export function calculateRateLimitBackoffMs(reason: RateLimitReason): number {
+	switch (reason) {
+		case "QUOTA_EXHAUSTED":
+			return QUOTA_EXHAUSTED_BACKOFF_MS;
+		case "RATE_LIMIT_EXCEEDED":
+			return RATE_LIMIT_EXCEEDED_BACKOFF_MS;
+		case "CONCURRENT_LIMIT":
+			return CONCURRENT_LIMIT_BACKOFF_MS;
+		case "MODEL_CAPACITY_EXHAUSTED":
+			return MODEL_CAPACITY_BASE_MS + Math.random() * MODEL_CAPACITY_JITTER_MS;
+		case "SERVER_ERROR":
+			return SERVER_ERROR_BACKOFF_MS;
+		default:
+			return QUOTA_EXHAUSTED_BACKOFF_MS; // conservative default
+	}
+}
+
+/** Detect usage/quota limit errors in error messages (persistent, requires credential switch). */
+const USAGE_LIMIT_PATTERN =
+	/usage.?limit|usage_limit_reached|usage_not_included|limit_reached|quota.?(?:exceeded|reached|insufficient)|额度不足|额度耗尽|resource.?exhausted|exhausted your capacity|quota will reset|insufficient.?(?:balance|quota)|balance.?exhausted|run out of credits|out of credits|spending[- _]?limit|personal-team-blocked/i;
+
+/**
+ * HTTP status codes that, absent richer body classification, represent an
+ * account-local usage cap rather than a bad credential or a transient blip.
+ * HTTP 402 Payment Required is categorically an account-billing cap (xAI
+ * Grok Build "usage balance exhausted", DeepSeek "Insufficient Balance",
+ * OpenRouter credit exhaustion) — never a transient blip or bad credential.
+ * Always combine with {@link isUsageLimitOutcome} when a message is available
+ * — a 429 carrying transient rate-limit wording is NOT a usage cap.
+ */
+export function isUsageLimitStatus(status: number | undefined): boolean {
+	return status === 429 || status === 402;
+}
+
+/**
+ * Returns true for failures that should burn one credential and rotate to a
+ * sibling account. Decision tree:
+ *
+ *  1. Body matches {@link isUsageLimitError} (Codex `usage_limit_reached`,
+ *     Anthropic account rate-limit, Google `resource_exhausted`, OpenAI
+ *     `insufficient_quota`, …) → rotate.
+ *  2. Status is not a usage-limit status (429/402) → backoff (caller's domain).
+ *  3. Body is absent or {@link isOpaqueStatusBody opaque} (just the status,
+ *     empty JSON, HTTP framing only) → rotate conservatively: the server
+ *     gave us nothing else to go on.
+ *  4. Body has content → defer to {@link parseRateLimitReason}. `QUOTA_EXHAUSTED`
+ *     rotates; for the categorical 402 billing cap a `CONCURRENT_LIMIT` body
+ *     also rotates (the cap is concurrent-worded but the status is still an
+ *     exhausted billing cap). `RATE_LIMIT_EXCEEDED` (`Too many requests`,
+ *     per-minute caps), `MODEL_CAPACITY_EXHAUSTED` (`Service overloaded`),
+ *     `SERVER_ERROR`, and `UNKNOWN` (`Please retry in 5s`) stay in the
+ *     provider's own backoff layer so transient 429s don't burn sibling
+ *     credentials.
+ */
+export function isUsageLimitOutcome(status: number | undefined, message: string | undefined): boolean {
+	// Concurrency caps are shed-and-backoff, not credential-rotatable — but only
+	// for quota-worded 429 / other statuses. HTTP 402 is categorically an
+	// account-billing cap, so a 402 whose body happens to mention concurrency is
+	// still an exhausted billing cap and must rotate; gate the exclusion on the
+	// status not being that categorical billing cap.
+	const isBillingCapStatus = status === 402;
+	if (isConcurrencyCapExclusion(status, message)) return false;
+	if (message && matchesUsageLimitText(message)) return true;
+	// A 403 is normally an auth failure, but several providers deliver an
+	// account-scoped cap with it (Devin/Codeium Connect `permission_denied`,
+	// GitHub Copilot). Devin's end-of-stream Connect trailer carries no HTTP
+	// status at all (it arrives as a `permission_denied` ValidationError), so
+	// accept an undefined status too — but only when the body names a cap that
+	// resets, never on a bare 403, which stays an auth failure.
+	if ((status === 403 || status === undefined) && message && isAccountScopedCapText(message)) return true;
+	if (!isUsageLimitStatus(status)) return false;
+	if (!message || isOpaqueStatusBody(message)) return true;
+	const reason = parseRateLimitReason(message);
+	// For the categorical 402 billing cap a concurrency-worded body is still an
+	// exhausted cap (rotate); for 429 / other only QUOTA_EXHAUSTED rotates.
+	return reason === "QUOTA_EXHAUSTED" || (isBillingCapStatus && reason === "CONCURRENT_LIMIT");
+}
+
+/**
+ * A usage-limit status body is opaque when it carries no signal beyond the
+ * status itself — empty, whitespace-only, the status digits with HTTP/JSON
+ * framing, or generic punctuation. Anything else (retry hints, capacity
+ * wording, error descriptions) is informative enough to defer to the
+ * classifier.
+ */
+export function isOpaqueStatusBody(message: string): boolean {
+	const cleaned = message
+		.replace(/\b(?:429|402)\b/g, "")
+		.replace(/\b(?:http|https|status|error|code|response|message)\b/gi, "");
+	// A body is informative when the text classifier can act on it. Any Latin
+	// word or Simplified Chinese phrasing the classifier recognizes (quota
+	// exhaustion or a throttle) defers to parseRateLimitReason; a body that
+	// is only status digits / HTTP framing is opaque and rotates conservatively.
+	// A Han-only body the classifier cannot interpret (e.g. Japanese Kanji
+	// quota text, since Japanese is out of scope) must stay opaque so the
+	// opaque-429 fallback still rotates. This keeps the exception scoped to
+	// text we actually classify, rather than to any Han ideograph.
+	return (
+		!/[a-z\d]{3,}/i.test(cleaned) &&
+		!CN_QUOTA_EXHAUSTED_PATTERN.test(cleaned) &&
+		!CN_TRANSIENT_CAP_PATTERN.test(cleaned) &&
+		!CN_THROTTLE_PATTERN.test(cleaned)
+	);
+}
+
+/**
+ * Internal text matcher for usage/quota-limit phrasing. NOT part of the public
+ * API — callers classify through {@link import("./flags").isUsageLimit} (the
+ * flag accessor). `flags.ts` consumes this to populate `Flag.UsageLimit`, and
+ * {@link isUsageLimitOutcome} uses it for the account-rotation decision.
+ */
+export function matchesUsageLimitText(errorMessage: string): boolean {
+	return (
+		USAGE_LIMIT_PATTERN.test(errorMessage) ||
+		(CN_QUOTA_EXHAUSTED_PATTERN.test(errorMessage) && !CN_TRANSIENT_CAP_PATTERN.test(errorMessage)) ||
+		SPEND_LIMIT_PATTERN.test(errorMessage) ||
+		ACCOUNT_RATE_LIMIT_PATTERN.test(errorMessage) ||
+		matchesSubscriptionCapText(errorMessage) ||
+		OPENROUTER_DAILY_FREE_LIMIT_PATTERN.test(errorMessage)
+	);
+}
+
+/**
+ * Account-scoped cap phrasing delivered on a 403 (or a statusless Connect
+ * trailer): "Reached overall message rate limit", "Your limit will reset in …".
+ * Kept separate from {@link matchesUsageLimitText} because the bare wording is
+ * ambiguous without the 403 / statusless-account context; consumed by both
+ * {@link isUsageLimitOutcome} (rotation decision) and `flags.ts` (Flag.UsageLimit).
+ */
+export function isAccountScopedCapText(message: string): boolean {
+	return ACCOUNT_SCOPED_403_PATTERN.test(message);
+}
+
+/**
+ * A concurrency cap on a non-billing status is shed-and-backoff, not
+ * credential-rotatable. This mirrors the exclusion in {@link isUsageLimitOutcome}
+ * for the 403 auth-retry entry points. A 402 remains a categorical billing cap.
+ */
+export function isConcurrencyCapExclusion(status: number | undefined, message: string | undefined): boolean {
+	return message !== undefined && parseRateLimitReason(message) === "CONCURRENT_LIMIT" && status !== 402;
+}

package/src/error/retryable.ts

@@ -0,0 +1,70 @@
+import { isRetryableError, isUnexpectedSocketCloseMessage } from "@linxiraos/pi-utils";
+import {
+	isRetryableStreamEnvelopeError,
+	isTransientStreamParseError,
+	isUsageLimit,
+	status,
+	TRANSIENT_TRANSPORT_PATTERN,
+} from "./flags";
+
+/**
+ * Whether a numeric HTTP status is in the canonical transient/retryable set:
+ * 408 (Request Timeout), 429 (Too Many Requests), and any 5xx.
+ *
+ * This is a pure predicate over a status code already in hand — distinct from
+ * {@link classify}, which inspects a whole error (including message text) and
+ * may match more. Use this when you only have a `status: number`.
+ */
+export function isTransientStatus(status: number | undefined): boolean {
+	return status !== undefined && (status === 408 || status === 429 || status >= 500);
+}
+
+// Provider-stream transient phrasings not covered by the shared
+// TRANSIENT_TRANSPORT_PATTERN (TLS record corruption, HTTP/2 peer stream
+// errors, upstream code 1302). The shared pattern already covers rate-limit /
+// overloaded / 5xx / timeout / first-event wording.
+const PROVIDER_TRANSIENT_EXTRA_PATTERN = /bad record mac|stream error.*received from peer|1302/i;
+
+function isTransientTransportMessage(message: string): boolean {
+	return message.includes("tls: bad record mac") || message.includes("type=server_error");
+}
+
+/** Hook for provider-specific transient detection that the error module must not import directly. */
+export interface ProviderRetryableHooks {
+	/** Provider id of the failing request, used to gate provider-specific checks. */
+	provider?: string;
+	/** Provider-specific transient predicate (e.g. Copilot model-availability 400s). */
+	isProviderTransient?: (error: Error) => boolean;
+}
+
+/**
+ * Whether a provider stream error should be retried against the same credential.
+ *
+ * Account-level usage/quota limits are deliberately treated as **non**-retryable
+ * here — they are owned by the credential-rotation layer (auth-gateway /
+ * `streamSimple` a/b/c policy), not this seconds-scale provider backoff.
+ *
+ * Provider-specific transient cases are injected via {@link ProviderRetryableHooks}
+ * so this stays free of provider imports.
+ */
+export function isProviderRetryableError(error: unknown, hooks: ProviderRetryableHooks = {}): boolean {
+	if (!(error instanceof Error)) return false;
+	if (hooks.isProviderTransient?.(error)) return true;
+	if (isUsageLimit(error)) return false;
+	const httpStatus = status(error);
+	if (httpStatus !== undefined && httpStatus >= 400 && httpStatus < 500 && httpStatus !== 408 && httpStatus !== 429) {
+		return false;
+	}
+	const msg = error.message.toLowerCase();
+	if (
+		isUnexpectedSocketCloseMessage(msg) ||
+		isTransientTransportMessage(msg) ||
+		TRANSIENT_TRANSPORT_PATTERN.test(msg) ||
+		PROVIDER_TRANSIENT_EXTRA_PATTERN.test(msg) ||
+		isTransientStreamParseError(error) ||
+		isRetryableStreamEnvelopeError(error)
+	) {
+		return true;
+	}
+	return isRetryableError(error);
+}

package/src/error/validation.ts

@@ -0,0 +1,44 @@
+import { attach, create, Flag } from "./flags";
+
+/**
+ * Caller-supplied input failed validation before/while building a provider
+ * request: bad request body, malformed tool arguments, unsupported content
+ * type, a schema that cannot be normalized, an unknown tool, etc.
+ *
+ * This is a programmer/config/contract error, not a transient provider fault —
+ * it is never retried.
+ */
+export class ValidationError extends Error {
+	constructor(message: string, options?: { cause?: unknown }) {
+		super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "ValidationError";
+	}
+}
+
+/** A referenced tool was not found in the active tool set. */
+export class ToolNotFoundError extends ValidationError {
+	constructor(toolName: string) {
+		super(`Tool "${toolName}" not found`);
+		this.name = "ToolNotFoundError";
+	}
+}
+
+/**
+ * Provider/auth configuration was missing or malformed (env var pointing at a
+ * missing file, missing projectId, bad bind string, mTLS half-configured, …).
+ */
+export class ConfigurationError extends Error {
+	constructor(message: string, options?: { cause?: unknown }) {
+		super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "ConfigurationError";
+	}
+}
+
+/** A request was abandoned because it exceeded a stream/idle/first-event deadline. */
+export class StreamTimeoutError extends Error {
+	constructor(message = "Request timed out.", options?: { cause?: unknown }) {
+		super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "StreamTimeoutError";
+		attach(this, create(Flag.Transient, Flag.Timeout));
+	}
+}