@oh-my-pi/pi-ai 18.2.0 → 18.2.1

package/src/auth-storage.ts

@@ -9,7 +9,7 @@
  */
 import { createHash } from "node:crypto";
 import { planRequirementFor } from "@oh-my-pi/pi-catalog/compat/behavior";
-import { $env, $envExact, extractRetryHint, getAgentDbPath, logger, untilAborted } from "@oh-my-pi/pi-utils";
+import { $env, $envExact, getAgentDbPath, logger, untilAborted } from "@oh-my-pi/pi-utils";
 import {
 	isSqliteCorruptionError,
 	resolveCredentialIdentityKey,
@@ -31,6 +31,7 @@ import type {
 } from "./registry/oauth/types";
 import { AUTHENTICATED_SENTINEL } from "./registry/types";
 import { getEnvApiKey, getEnvApiKeyName } from "./stream";
+import { extractProviderRetryHint } from "./utils/retry-after";
 import type { Provider } from "./types";
 import type {
 	ClientUsageIdentity,
@@ -765,6 +766,11 @@ export { isDefinitiveOAuthFailure } from "./error/auth-classify";
  * the usage report reveals. Callers that wait the account out (instead of
  * rotating) must sleep until this, not the error-text hint alone.
  *
+ * `requestedBlockedUntilMs` (epoch ms) is this mark call's initial deadline,
+ * before usage-report correction and longest-wins merging. Callers use it to
+ * distinguish the call's replaceable heuristic from a longer merged block
+ * that credential selection will continue enforcing.
+ *
  * `priorBlockedUntilMs` (epoch ms) is the live block deadline the map already
  * stored for this credential before this call. The merged `blockedUntilMs`
  * masks a pre-existing block shorter than this call's own heuristic
@@ -790,6 +796,8 @@ export interface UsageLimitMarkResult {
 	switched: boolean;
 	retryAtMs?: number;
 	blockedUntilMs?: number;
+	/** This mark call's initial deadline, before report correction and merging. */
+	requestedBlockedUntilMs?: number;
 	priorBlockedUntilMs?: number;
 	priorBlockedUntilTimed?: boolean;
 	reportResetAtMs?: number;
@@ -1353,7 +1361,7 @@ export class AuthStorage {
 	/** Tracks the last used credential per provider for a session (used for rate-limit switching). */
 	#sessionLastCredential: Map<
 		string,
-		Map<string, { type: AuthCredential["type"]; index: number; lastUsedAtMs?: number }>
+		Map<string, { type: AuthCredential["type"]; index: number; credentialId?: number; lastUsedAtMs?: number }>
 	> = new Map();
 	/** Recent bearer fingerprints resolved for each durable OAuth row; used only for delayed usage-limit attribution. */
 	#oauthBearerFingerprints: Map<string, Map<number, string[]>> = new Map();
@@ -1490,6 +1498,36 @@ export class AuthStorage {
 		return true;
 	}
 
+	/**
+	 * Adopt credentials another process committed before selecting or rotating.
+	 *
+	 * The store is shared across every omp process, but the pool is an
+	 * in-process cache refreshed only by this process's own writes. Without
+	 * this a long-running session ranks a stale pool for its whole lifetime:
+	 * `omp auth` in another terminal is invisible, rotation reports no usable
+	 * sibling while a freshly added account sits unblocked in SQLite, and the
+	 * turn degrades to the fallback chain. The auth-broker path already polls;
+	 * direct-store sessions had no equivalent.
+	 *
+	 * A poll is two cheap reads (`PRAGMA data_version` plus the auth revision)
+	 * and re-lists credentials only when another connection committed, so it
+	 * runs on every resolution rather than on a timer that would make recovery
+	 * depend on wall-clock spacing. It sits on the paths that read the pool —
+	 * OAuth selection, and the two public usage-limit entry points — and is
+	 * idempotent, so a rotation reached through `markUsageLimitReached` costs
+	 * one extra `data_version` read and no second reload.
+	 */
+	async #adoptExternalCredentialChanges(): Promise<void> {
+		if (this.#closed || this.#store.pollExternalChanges === undefined) return;
+		try {
+			await this.pollExternalChanges();
+		} catch (error) {
+			// A failed poll must not fail credential resolution: the in-memory
+			// pool is still serviceable, just possibly stale.
+			logger.debug("External credential poll failed", { error: String(error) });
+		}
+	}
+
 	onGenerationChanged(listener: (generation: number) => void): () => void {
 		this.#generationListeners.add(listener);
 		return () => {
@@ -2084,12 +2122,12 @@ export class AuthStorage {
 	): void {
 		if (!sessionId) return;
 		const nowMs = lastUsedAtMs ?? Date.now();
+		const credentialId = this.#getStoredCredentials(provider)[index]?.id;
 		const sessionMap = this.#sessionLastCredential.get(provider) ?? new Map();
-		sessionMap.set(sessionId, { type, index, lastUsedAtMs: nowMs });
+		sessionMap.set(sessionId, { type, index, credentialId, lastUsedAtMs: nowMs });
 		this.#sessionLastCredential.set(provider, sessionMap);
 
 		try {
-			const credentialId = this.#getStoredCredentials(provider)[index]?.id;
 			if (credentialId !== undefined) {
 				const cacheKey = `${SESSION_STICKY_CACHE_PREFIX}${provider}:${sessionId}`;
 				const cacheValue = JSON.stringify({
@@ -2111,11 +2149,24 @@ export class AuthStorage {
 	#getSessionCredential(
 		provider: string,
 		sessionId: string | undefined,
-	): { type: AuthCredential["type"]; index: number; lastUsedAtMs?: number } | undefined {
+	): { type: AuthCredential["type"]; index: number; credentialId?: number; lastUsedAtMs?: number } | undefined {
 		if (!sessionId) return undefined;
 		let sessionMap = this.#sessionLastCredential.get(provider);
-		if (sessionMap?.has(sessionId)) {
-			return sessionMap.get(sessionId);
+		const live = sessionMap?.get(sessionId);
+		if (live) {
+			// Another process can add or drop rows mid-session and the pool is an
+			// index-ordered snapshot, so re-resolve the pin through its durable row
+			// id: a compacted array must not point the session at a different
+			// account, and a deleted account must not hand its slot to a sibling.
+			if (live.credentialId === undefined) return live;
+			const stored = this.#getStoredCredentials(provider);
+			const actualIndex = stored.findIndex(entry => entry.id === live.credentialId);
+			if (actualIndex === -1 || stored[actualIndex]?.credential.type !== live.type) {
+				sessionMap?.delete(sessionId);
+				return undefined;
+			}
+			live.index = actualIndex;
+			return live;
 		}
 		try {
 			const cacheKey = `${SESSION_STICKY_CACHE_PREFIX}${provider}:${sessionId}`;
@@ -2149,6 +2200,7 @@ export class AuthStorage {
 				const sessionVal = {
 					type: val.type,
 					index: val.index,
+					credentialId: val.credentialId,
 					lastUsedAtMs: val.lastUsedAtMs,
 				};
 				sessionMap.set(sessionId, sessionVal);
@@ -3145,6 +3197,7 @@ export class AuthStorage {
 			onProgress: ctrl.onProgress,
 			onPrompt: ctrl.onPrompt,
 			onManualCodeInput: ctrl.onManualCodeInput ?? manualCodeInput,
+			onBrowserSession: ctrl.onBrowserSession,
 			signal: ctrl.signal,
 			fetch: ctrl.fetch,
 		});
@@ -4204,7 +4257,14 @@ export class AuthStorage {
 				const credentialType = entry.credential.type;
 				const providerKey = this.#getProviderTypeKey(provider, credentialType);
 				let blockedUntil = this.#getCredentialBlockedUntil(provider, providerKey, index, blockScopes);
-				if (blockedUntil !== undefined && provider !== "openai-codex") {
+				// A block under a scope the strategy can vouch for must still fetch
+				// a probe report, or it outlives the recovery that report would
+				// prove: no report means no reconciliation, so the credential idles
+				// until the clock runs out even after quota is restored.
+				if (
+					blockedUntil !== undefined &&
+					!this.#blockedCredentialCanHeal(provider, providerKey, index, blockScopes)
+				) {
 					return {
 						credentialId: entry.id,
 						credentialType,
@@ -4231,7 +4291,7 @@ export class AuthStorage {
 					planEligibilityByCredential.set(entry.id, getOpenAICodexPlanEligibility(report, planRequirement));
 				}
 
-				if (provider === "openai-codex") {
+				if (this.#supportsUsageBlockHealing(provider)) {
 					blockedUntil = this.#getCredentialBlockedUntil(provider, providerKey, index, blockScopes);
 				}
 				if (blockedUntil !== undefined) {
@@ -4795,6 +4855,7 @@ export class AuthStorage {
 			signal?: AbortSignal;
 		},
 	): Promise<UsageLimitMarkResult> {
+		await this.#adoptExternalCredentialChanges();
 		let sessionCredential = await this.#resolveCredentialTarget(provider, sessionId, {
 			credentialId: options?.credentialId,
 			apiKey: options?.apiKey,
@@ -4820,7 +4881,8 @@ export class AuthStorage {
 
 		const routing = this.#credentialBlockRouting(provider, credentialType, options?.modelId);
 		const now = Date.now();
-		let blockedUntil = now + (options?.retryAfterMs ?? AuthStorage.#defaultBackoffMs);
+		const requestedBlockedUntilMs = now + (options?.retryAfterMs ?? AuthStorage.#defaultBackoffMs);
+		let blockedUntil = requestedBlockedUntilMs;
 		// Heuristic/default fallbacks are guesses; provider-stated hints and
 		// report-derived extensions are timed.
 		let providerTimed = options?.providerTimed === true;
@@ -4871,7 +4933,11 @@ export class AuthStorage {
 			routing,
 			providerTimed,
 		);
-		return reportResetAtMs === undefined ? rotation : { ...rotation, reportResetAtMs };
+		return {
+			...rotation,
+			requestedBlockedUntilMs,
+			...(reportResetAtMs === undefined ? {} : { reportResetAtMs }),
+		};
 	}
 
 	#resolveWindowResetAt(window: UsageLimit["window"]): number | undefined {
@@ -5011,7 +5077,15 @@ export class AuthStorage {
 				);
 				let usage: UsageReport | null = null;
 				let usageChecked = false;
-				if (blockedUntil !== undefined && args.provider === "openai-codex") {
+				if (
+					blockedUntil !== undefined &&
+					this.#blockedCredentialCanHeal(
+						args.provider,
+						args.providerKey,
+						selection.index,
+						args.blockScopes ?? args.blockScope,
+					)
+				) {
 					usage = await this.#getUsageReport(args.provider, selection.credential, {
 						...args.options,
 						timeoutMs: this.#usageRequestTimeoutMs,
@@ -5136,6 +5210,7 @@ export class AuthStorage {
 		sessionId?: string,
 		options?: AuthApiKeyOptions,
 	): Promise<OAuthResolutionResult | undefined> {
+		await this.#adoptExternalCredentialChanges();
 		const credentials = this.#getCredentialsForProvider(provider)
 			.map((credential, index) => ({ credential, index }))
 			.filter((entry): entry is { credential: OAuthCredential; index: number } => entry.credential.type === "oauth");
@@ -5889,6 +5964,8 @@ export class AuthStorage {
 			return configKey;
 		}
 
+		await this.#adoptExternalCredentialChanges();
+
 		// Precedence: a deliberate OAuth/login credential wins, then an explicit env var,
 		// then a stored static api_key (which may be a stale broker-migrated copy) as a last resort.
 		const oauthSelection = this.#selectCredentialByType(provider, "oauth");
@@ -6164,6 +6241,32 @@ export class AuthStorage {
 		return true;
 	}
 
+	/**
+	 * Copy every stored credential affinity from one live session to another.
+	 *
+	 * The target receives its own sticky entries, so request resolution, usage
+	 * blocking, credential rotation, metadata, and persisted pins all continue
+	 * through the target session id without retaining a live dependency on the
+	 * source session.
+	 */
+	inheritSessionCredentials(sourceSessionId: string, targetSessionId: string): number {
+		if (!sourceSessionId || !targetSessionId || sourceSessionId === targetSessionId) return 0;
+		let inherited = 0;
+		for (const provider of this.#data.keys()) {
+			const credential = this.#getSessionCredential(provider, sourceSessionId);
+			if (!credential) continue;
+			this.#recordSessionCredential(
+				provider,
+				targetSessionId,
+				credential.type,
+				credential.index,
+				credential.lastUsedAtMs,
+			);
+			inherited += 1;
+		}
+		return inherited;
+	}
+
 	/**
 	 * Resolve every stored OAuth credential for `provider` independently.
 	 *
@@ -6612,6 +6715,29 @@ export class AuthStorage {
 		);
 	}
 
+	/**
+	 * Whether a fresh report could lift what currently blocks this credential.
+	 *
+	 * A strategy that names healable scopes can only vouch for those scopes, so
+	 * a live unscoped block — an Opus/Sonnet usage limit, a refresh failure —
+	 * keeps the credential unusable whatever the report says about a tier. A
+	 * probe then cannot change the outcome and must not be spent; the tier scope
+	 * heals on a later pass, once the block that actually holds the credential
+	 * has lifted. Codex heals through its meter metadata rather than named
+	 * scopes, so its blocks always qualify.
+	 */
+	#blockedCredentialCanHeal(
+		provider: Provider,
+		providerKey: string,
+		credentialIndex: number,
+		blockScopeOrScopes: string | readonly string[] | undefined,
+	): boolean {
+		if (!this.#supportsUsageBlockHealing(provider)) return false;
+		if (this.#rankingStrategyResolver?.(provider)?.healableBlockScopes === undefined) return true;
+		if (this.#getCredentialBlockedUntil(provider, providerKey, credentialIndex) !== undefined) return false;
+		return this.#getCredentialBlockedUntil(provider, providerKey, credentialIndex, blockScopeOrScopes) !== undefined;
+	}
+
 	/**
 	 * Self-heal stale usage-limit blocks: when a fresh live usage report says a
 	 * scope is below every limit gating it, drop its persisted and in-memory
@@ -6626,6 +6752,10 @@ export class AuthStorage {
 		if (credentialIndex < 0) return;
 		const strategy = this.#rankingStrategyResolver?.(provider);
 		if (provider !== "openai-codex") {
+			// Only a live report proves recovery. A broker can serve its retained
+			// last-good report for hours after `/usage` starts failing, and those
+			// healthy limits describe the account before the 429 that blocked it.
+			if (!Number.isFinite(report.fetchedAt) || Date.now() - report.fetchedAt > USAGE_REPORT_TTL_MS) return;
 			for (const { blockScope, limits } of strategy?.healableBlockScopes?.(report) ?? []) {
 				if (limits.length === 0 || this.#isUsageLimitReached(limits)) continue;
 				this.#clearHealedBlockScope(provider, providerKey, credentialId, credentialIndex, blockScope);
@@ -6861,6 +6991,7 @@ export class AuthStorage {
 			signal?: AbortSignal;
 		},
 	): Promise<boolean> {
+		await this.#adoptExternalCredentialChanges();
 		const error = options?.error;
 		const status = AIError.status(error);
 		const message = error instanceof Error ? error.message : typeof error === "string" ? error : undefined;
@@ -6870,7 +7001,7 @@ export class AuthStorage {
 			// Thread the provider-specified reset window (e.g. Devin "Your limit
 			// will reset in 13 minutes") into the block duration so the credential
 			// is not reselected and hammered while the cap remains active.
-			const retryAfterMs = extractRetryHint(undefined, message);
+			const retryAfterMs = extractProviderRetryHint(provider, message);
 			return (
 				await this.markUsageLimitReached(provider, sessionId, {
 					retryAfterMs,

package/src/error/body-error.ts

@@ -0,0 +1,310 @@
+/**
+ * In-band provider failures: upstream 429/5xx payloads that arrive inside an
+ * HTTP 200 response body, or mid-stream after the SSE headers were already sent.
+ *
+ * Providers that front a retry/queue layer — Azure OpenAI, LiteLLM-style
+ * aggregators, Bedrock-compatible shims — answer a throttled request with
+ * `200 OK` + `text/event-stream` and put the real status in the payload:
+ * `data: {"error":{"type":"rate_limit_error"}}`, `data: {"code":429}`, or a bare
+ * non-JSON frame such as `data: 429 Too Many Requests` / an nginx throttle page.
+ * Those bodies used to be either dropped silently (the stream then looked like a
+ * successful empty completion) or surfaced as an unclassified
+ * {@link ProviderResponseError} whose `errorId` stayed 0 — so `AIError.retriable`
+ * answered "terminal" and `retry.fallbackChains` never advanced, pinning the
+ * session on a provider that was merely busy.
+ *
+ * Both probes hand the classifier the structured signal it already trusts for an
+ * out-of-band failure: a {@link ProviderHttpError} carrying a status the upstream
+ * *reported*, so the two routes reach one code path. The invariants that make
+ * that safe, and that callers rely on:
+ *
+ *  - **No invented HTTP metadata.** A status is taken only from an error
+ *    `status`/`code` *field* (numeric, or a 3-digit string as compat hosts send)
+ *    or from {@link RETRYABLE_STATUS_BY_CODE}, and only for `429`/`5xx`. A status
+ *    mentioned inside error prose is never promoted to a status: 401/403 wording
+ *    stays text and cannot route the failure into the auth-retry lane.
+ *  - **No credential rotation on an unreadable body.** A `429` whose body is
+ *    empty, `{}`, or framing-only is opaque, and an opaque 429 is the conservative
+ *    rotate-to-a-sibling-credential signal. That verdict belongs to a body the
+ *    server actually sent, not to a payload we synthesised, so
+ *    {@link formatInBandMessage} substitutes {@link IN_BAND_DETAIL_PLACEHOLDER}
+ *    and the composed message always stays informative.
+ *  - **Unknown envelopes fall through.** Anything without a retryable status
+ *    field, a retryable code, or unambiguous throttle wording returns
+ *    `undefined` and keeps its pre-existing handling and message.
+ *
+ * Where no numeric status exists, the returned error keeps the upstream wording
+ * and code visible in its message instead of asserting HTTP metadata the provider
+ * never sent, and carries {@link Flag.Transient} directly: throttle spellings like
+ * `Throttled` / `Please retry` are what this probe recognises but the transport
+ * text pattern is not required to match, so the retry decision is stated rather
+ * than hoped for.
+ */
+import { ProviderHttpError } from "./classes";
+import { attach, create, Flag } from "./flags";
+import { isOpaqueStatusBody } from "./rate-limit";
+import { ProviderResponseError } from "./provider";
+
+/** Cap on synthesized message length, mirroring the transport-level `MAX_DETAIL_CHARS`. */
+const MAX_IN_BAND_DETAIL_CHARS = 4096;
+
+/**
+ * Filler used when an in-band failure frame carries no readable detail. It has
+ * to be informative prose on purpose: an opaque message on a `429` is read as
+ * "the server gave us nothing" and rotates a credential, and that judgement must
+ * never be triggered by wording of ours.
+ */
+const IN_BAND_DETAIL_PLACEHOLDER = "Provider returned an in-band provider error";
+
+/**
+ * Machine error codes that mean "shed this request and back off", mapped to the
+ * HTTP status the upstream would have used had it not wrapped the failure in a
+ * 200. Keys are compared after lower-casing, splitting camel/Pascal word
+ * boundaries, and collapsing `_`/`-`/`.`/spaces, so `Throttling.AllocationQuota`
+ * and `ThrottlingAllocationQuota` both resolve. The list is deliberately limited
+ * to throttle/overload spellings so an unlisted code keeps its pre-existing
+ * classification: request-validation failures (`invalid_request_error`) and
+ * account caps (`insufficient_quota`, `usage_limit_reached`) are never
+ * reinterpreted as retries.
+ */
+const RETRYABLE_STATUS_BY_CODE: Record<string, number> = {
+	rate_limit_error: 429,
+	rate_limit_exceeded: 429,
+	rate_limit: 429,
+	rate_limit_reached: 429,
+	rate_limited: 429,
+	ratelimit: 429,
+	too_many_requests: 429,
+	request_throttled: 429,
+	throttled: 429,
+	throttling: 429,
+	throttling_error: 429,
+	throttling_exception: 429,
+	throttling_allocation_quota: 429,
+	request_limit_exceeded: 429,
+	retry_later: 429,
+	overloaded_error: 503,
+	server_overloaded: 503,
+	model_overloaded: 503,
+	overloaded: 503,
+	service_unavailable: 503,
+	server_busy: 503,
+	high_demand: 503,
+	capacity_exceeded: 503,
+};
+
+/**
+ * Wording that identifies a throttle/overload in an error code or body. Kept as
+ * an explicit list rather than reusing the classifier's pattern, so this probe
+ * stays independent of the text rules it feeds.
+ */
+const IN_BAND_RETRYABLE_TEXT_PATTERN =
+	/\brate.?limit|too many requests|too\s+many\s+concurren|service.{0,20}unavailable|temporarily\s+unavailable|server.?error|internal.?error|overloaded|capacity|throttl|retry\s+(?:your\s+)?request|please\s+retry/i;
+
+/**
+ * A status in the position a proxy error page puts it: the very first token,
+ * optionally after an `HTTP/1.1 ` prefix. Delimited by a word boundary so
+ * identifiers (`chatcmpl-500321`, `gpt-500x`, `req500502`) cannot fabricate a
+ * status — the same hazard `error-transient-status-boundary.test.ts` guards.
+ * Prose that merely *mentions* a number (`Too many requests (401 from …)`) is
+ * deliberately not read as status metadata.
+ */
+const LEADING_STATUS_PATTERN = /^\s*(?:HTTP[/.]\d(?:\.\d)?\s+)?([45]\d{2})(?:\b|$)/i;
+
+/** Codes that mean a persistent account/billing cap or a bad request; never shed-and-retry. */
+const NON_RETRYABLE_CODE_PATTERN =
+	/insufficient.?quota|usage.?limit|quota.?(?:exceeded|reached|insufficient)|invalid_request|content_filter|context_length|context_window|billing|balance/i;
+
+/** Flags this module asserts for a body it has itself recognised as shed-and-retry. */
+const IN_BAND_FLAGS = create(Flag.Transient);
+
+function normalizeCodeToken(value: unknown): string | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	if (typeof value !== "string") return undefined;
+	const spaced = value.trim().replace(/([a-z0-9])([A-Z])/g, "$1_$2");
+	const collapsed = spaced
+		.toLowerCase()
+		.replace(/[-.\s]+/g, "_")
+		.replace(/_+/g, "_");
+	return collapsed.length > 0 ? collapsed : undefined;
+}
+
+function readInBandDetail(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	// SSE joins multi-line `data:` values with `\n`, and proxy failures arrive as
+	// HTML: flatten to one line of visible text so a synthesized message cannot
+	// smuggle markup or framing into the classifier or the terminal.
+	const flattened = value
+		.replace(/<[^>]*>/g, " ")
+		.replace(/[\u0000-\u001f\u007f]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+	if (flattened.length === 0) return undefined;
+	return flattened.length > MAX_IN_BAND_DETAIL_CHARS ? flattened.slice(0, MAX_IN_BAND_DETAIL_CHARS) : flattened;
+}
+
+/** A numeric HTTP status field, accepting the `"429"` string form compat hosts emit. */
+function readStatusField(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599) return value;
+	if (typeof value === "string" && /^\d{3}$/.test(value.trim())) {
+		const parsed = Number(value.trim());
+		return Number.isInteger(parsed) && parsed >= 100 && parsed <= 599 ? parsed : undefined;
+	}
+	return undefined;
+}
+
+/** Only `429` and genuine server faults are shed-and-retry; 4xx of any other kind is not. */
+function isRetryableStatus(status: number | undefined): status is number {
+	return status === 429 || (status !== undefined && status >= 500 && status <= 599);
+}
+
+function readLeadingStatus(text: string | undefined): number | undefined {
+	if (text === undefined) return undefined;
+	const match = LEADING_STATUS_PATTERN.exec(text);
+	return match?.[1] ? Number(match[1]) : undefined;
+}
+
+interface InBandSignal {
+	/** Numeric HTTP status the upstream reported, or implied by its error code. */
+	status?: number;
+	/** Machine code from the body (`error.code` preferred over `error.type`). */
+	code?: string;
+	/** Human-readable detail from the body. */
+	detail?: string;
+}
+
+/**
+ * Pull the failure signal out of an OpenAI-wire frame. Accepts the nested
+ * `{ error: { code, type, status, message } }` shape, the `response.error`
+ * position of Responses-API terminal events, the flat `{ code, status, message }`
+ * bodies compat hosts emit, and string envelopes (`{ error: "..." }`).
+ *
+ * `undefined` means "not an in-band failure worth retrying". The probe is
+ * intentionally narrow: a bare `type` is present on every Responses event and so
+ * never counts as a signal by itself, statuses come only from fields (never from
+ * prose), and a frame with neither a retryable status nor throttle wording is
+ * left to the caller's existing handling.
+ */
+function readInBandSignal(frame: unknown): InBandSignal | undefined {
+	if (typeof frame !== "object" || frame === null || Array.isArray(frame)) return undefined;
+	const root = frame as Record<string, unknown>;
+	const nested = root.error ?? (root.response as Record<string, unknown> | undefined)?.error;
+	// Azure-compatible gates double-wrap (`{ error: { error: { code, message } } }`).
+	// Walk at most two levels so a deep payload cannot extend the parse.
+	let error: Record<string, unknown> | undefined;
+	if (typeof nested === "object" && nested !== null) {
+		error = nested as Record<string, unknown>;
+		for (let depth = 0; depth < 2; depth++) {
+			const inner = error.error;
+			if (typeof inner !== "object" || inner === null) break;
+			error = inner as Record<string, unknown>;
+		}
+	}
+	const code = normalizeCodeToken(error?.code ?? root.code) ?? normalizeCodeToken(error?.type ?? root.type);
+	if (code !== undefined && NON_RETRYABLE_CODE_PATTERN.test(code)) return undefined;
+	// A flat retryable code/type is itself an in-band failure: Responses-API
+	// `error` events expose `{ type: "rate_limit_error" }` with no `error` member,
+	// and their handler passes the inner error object (not the whole event).
+	const retryableCode = code !== undefined && IN_BAND_RETRYABLE_TEXT_PATTERN.test(code);
+	// Only an explicit error member, a top-level status/code/message field, or a
+	// standalone throttle type can qualify a frame as a failure; ordinary chunks
+	// carry none of these. A bare `type` is present on every Responses event, so
+	// it only counts when it is itself retryable wording.
+	if (
+		!retryableCode &&
+		nested === undefined &&
+		root.status === undefined &&
+		root.code === undefined &&
+		root.message === undefined
+	) {
+		return undefined;
+	}
+	const detail =
+		readInBandDetail(error?.message) ??
+		readInBandDetail(root.message) ??
+		(typeof nested === "string" ? readInBandDetail(nested) : undefined);
+	const holder = error ?? root;
+	// Reported statuses come from fields only: the error member's `status`, its
+	// numeric `code`, then the same on the root (the flat `{ code: 429 }` /
+	// `{ status: 429 }` bodies compat hosts emit). Anything outside 429/5xx is
+	// ignored outright — an in-band `400`/`401`/`403` field must not become a
+	// synthetic HTTP contract, or a body that merely names an auth problem would
+	// route into the credential lane.
+	const reported = holder === root ? [root.status, root.code] : [holder.status, holder.code, root.status, root.code];
+	const status =
+		reported.map(readStatusField).find(isRetryableStatus) ??
+		(code !== undefined && Object.hasOwn(RETRYABLE_STATUS_BY_CODE, code)
+			? readStatusField(RETRYABLE_STATUS_BY_CODE[code])
+			: undefined);
+	if (status !== undefined) return { status, code, detail };
+	// No reported status: classify only when the upstream *message* is itself
+	// unambiguous throttle wording. A generic code alone must not qualify —
+	// Azure uses `server_error` for terminal backend failures whose
+	// `"<code>: <message>"` envelope the caller already reports (and whose text
+	// the shared transient rule already matches), so intercepting it would
+	// change an established error format without adding retry information.
+	if (detail === undefined || !IN_BAND_RETRYABLE_TEXT_PATTERN.test(detail)) return undefined;
+	return { code, detail };
+}
+
+/**
+ * Compose the message for a status-bearing in-band failure. The numeric status
+ * leads (matching `captureOpenAIHttpError`'s `"<status> <detail>"` phrasing)
+ * unless the detail already carries it as its leading token; the machine code is
+ * appended only when it adds information the text classifier or a human reader
+ * can use. A detail that leaves the whole line opaque is replaced by the
+ * placeholder, so a body we generated can never be read as "the server said
+ * nothing".
+ */
+function formatInBandMessage(status: number, detail: string | undefined, code: string | undefined): string {
+	const body = detail ?? IN_BAND_DETAIL_PLACEHOLDER;
+	const suffix =
+		code !== undefined && !/^\d+$/.test(code) && !body.toLowerCase().includes(code.toLowerCase()) ? ` (${code})` : "";
+	let message = readLeadingStatus(body) === status ? body : `${status} ${body}`;
+	if (isOpaqueStatusBody(message)) message = `${status} ${IN_BAND_DETAIL_PLACEHOLDER}`;
+	return `${message}${suffix}`;
+}
+
+/**
+ * Build the classified error for an in-band failure frame, or `undefined` when
+ * the frame is not a retryable in-band failure (in which case the caller keeps
+ * its existing handling and message).
+ *
+ * @param frame decoded SSE `data:` payload, or the `{ error, response }` subset of one
+ */
+export function createInBandProviderError(frame: unknown): Error | undefined {
+	const signal = readInBandSignal(frame);
+	if (!signal) return undefined;
+	const { status, code, detail } = signal;
+	if (isRetryableStatus(status)) {
+		return attach(new ProviderHttpError(formatInBandMessage(status, detail, code), status, { code }), IN_BAND_FLAGS);
+	}
+	if (detail === undefined && code === undefined) return undefined;
+	// Keep the upstream code visible (`(<code>)`) — it is real provider data and
+	// the same convention the Anthropic provider already uses for its
+	// `(<errorType>)` suffix.
+	return attach(
+		new ProviderResponseError(`${detail ?? IN_BAND_DETAIL_PLACEHOLDER}${code ? ` (${code})` : ""}`, {
+			kind: "runtime",
+		}),
+		IN_BAND_FLAGS,
+	);
+}
+
+/**
+ * Build the classified error for a non-JSON SSE frame: gateways and reverse
+ * proxies that answer `data: 429 Too Many Requests` or an HTML throttle page
+ * instead of an OpenAI envelope. `undefined` when the text is not recognisable
+ * as a throttle, so genuinely malformed payloads keep failing loudly.
+ */
+export function createInBandProviderErrorFromText(text: string): Error | undefined {
+	const detail = readInBandDetail(text);
+	if (detail === undefined || !IN_BAND_RETRYABLE_TEXT_PATTERN.test(detail)) return undefined;
+	const status = readLeadingStatus(detail);
+	if (isRetryableStatus(status)) {
+		return attach(new ProviderHttpError(formatInBandMessage(status, detail, undefined), status), IN_BAND_FLAGS);
+	}
+	// A proxy status line with no machine code to preserve: report the upstream
+	// text verbatim rather than padding it with wording of ours.
+	return attach(new ProviderResponseError(detail, { kind: "runtime" }), IN_BAND_FLAGS);
+}