@oh-my-pi/pi-ai 16.2.1 → 16.2.2

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,56 @@
+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";
+		if (this.kind === "content-blocked") attach(this, create(Flag.ProviderFinishError));
+	}
+}
+
+/** 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/{rate-limit-utils.ts → error/rate-limit.ts}

@@ -131,7 +131,7 @@ export function isUsageLimitStatus(status: number | undefined): boolean {
  *     credentials.
  */
 export function isUsageLimitOutcome(status: number | undefined, message: string | undefined): boolean {
-	if (message && isUsageLimitError(message)) return true;
+	if (message && matchesUsageLimitText(message)) return true;
 	if (!isUsageLimitStatus(status)) return false;
 	if (!message || isOpaqueStatusBody(message)) return true;
 	return parseRateLimitReason(message) === "QUOTA_EXHAUSTED";
@@ -143,13 +143,19 @@ export function isUsageLimitOutcome(status: number | undefined, message: string
  * generic punctuation. Anything else (retry hints, capacity wording, error
  * descriptions) is informative enough to defer to the classifier.
  */
-function isOpaqueStatusBody(message: string): boolean {
+export function isOpaqueStatusBody(message: string): boolean {
 	const cleaned = message
 		.replace(/\b429\b/g, "")
 		.replace(/\b(?:http|https|status|error|code|response|message)\b/gi, "");
 	return !/[a-z\d]{3,}/i.test(cleaned);
 }
 
-export function isUsageLimitError(errorMessage: string): boolean {
+/**
+ * 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) || ACCOUNT_RATE_LIMIT_PATTERN.test(errorMessage);
 }

package/src/error/retryable.ts

@@ -0,0 +1,70 @@
+import { isRetryableError, isUnexpectedSocketCloseMessage } from "@oh-my-pi/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_not_supported`). */
+	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));
+	}
+}

package/src/index.ts

@@ -6,7 +6,7 @@ export type { AuthGatewayBootOptions, ModelResolver } from "./auth-gateway/serve
 export * from "./auth-gateway/types";
 export * from "./auth-retry";
 export * from "./auth-storage";
-export * from "./errors";
+export * from "./error/rate-limit";
 export * from "./provider-details";
 export * from "./providers/anthropic";
 export * from "./providers/anthropic-client";
@@ -24,7 +24,6 @@ export * from "./providers/openai-codex-responses";
 export * from "./providers/openai-completions";
 export * from "./providers/openai-responses";
 export * from "./providers/synthetic";
-export * from "./rate-limit-utils";
 export * from "./registry";
 export * from "./stream";
 export * from "./types";
@@ -43,7 +42,6 @@ export * from "./usage/zai";
 export * from "./utils/anthropic-auth";
 export * from "./utils/event-stream";
 export * from "./utils/openrouter-headers";
-export * from "./utils/overflow";
 export * from "./utils/retry";
 export * from "./utils/schema";
 export * from "./utils/thinking-loop";

package/src/providers/amazon-bedrock.ts

@@ -10,15 +10,9 @@
 import type { Effort } from "@oh-my-pi/pi-catalog/effort";
 import { mapEffortToAnthropicAdaptiveEffort, requireSupportedEffort } from "@oh-my-pi/pi-catalog/model-thinking";
 import { calculateCost } from "@oh-my-pi/pi-catalog/models";
-import {
-	$env,
-	$flag,
-	extractHttpStatusFromError,
-	fetchWithRetry,
-	parseStreamingJson,
-	parseStreamingJsonThrottled,
-} from "@oh-my-pi/pi-utils";
-import { ProviderHttpError } from "../errors";
+import { $env, $flag, fetchWithRetry, parseStreamingJson, parseStreamingJsonThrottled } from "@oh-my-pi/pi-utils";
+import { renderDemotedThinking } from "../dialect/demotion";
+import * as AIError from "../error";
 import type {
 	Api,
 	AssistantMessage,
@@ -36,8 +30,14 @@ import type {
 	ToolResultMessage,
 } from "../types";
 import { normalizeToolCallId, resolveCacheRetention } from "../utils";
+import {
+	clearStreamingPartialJson,
+	kStreamingBlockIndex,
+	kStreamingLastParseLen,
+	kStreamingPartialJson,
+} from "../utils/block-symbols";
 import { AssistantMessageEventStream } from "../utils/event-stream";
-import { appendRawHttpRequestDumpFor400, type RawHttpRequestDump } from "../utils/http-inspector";
+import type { RawHttpRequestDump } from "../utils/http-inspector";
 import { armPreResponseTimeout, getStreamFirstEventTimeoutMs } from "../utils/idle-iterator";
 import { toolWireSchema } from "../utils/schema/wire";
 import { invalidateAwsCredentialCache, resolveAwsCredentials } from "./aws-credentials";
@@ -45,11 +45,6 @@ import { decodeEventStream } from "./aws-eventstream";
 import { signRequest } from "./aws-sigv4";
 import { transformMessages } from "./transform-messages";
 
-/** Non-2xx response (or in-stream exception event) from the Bedrock runtime API. */
-export class BedrockApiError extends ProviderHttpError {
-	override readonly name = "BedrockApiError";
-}
-
 export type BedrockThinkingDisplay = "summarized" | "omitted";
 
 export interface BedrockOptions extends StreamOptions {
@@ -164,9 +159,9 @@ function resolveBedrockRegion(modelId: string, options: BedrockOptions): string
 }
 
 type Block = (TextContent | ThinkingContent | ToolCall) & {
-	index?: number;
-	partialJson?: string;
-	lastParseLen?: number;
+	[kStreamingBlockIndex]?: number;
+	[kStreamingPartialJson]?: string;
+	[kStreamingLastParseLen]?: number;
 };
 
 // ---------- Bedrock wire-format types ----------
@@ -288,7 +283,7 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 	const stream = new AssistantMessageEventStream();
 
 	(async () => {
-		const startTime = Date.now();
+		const startTime = performance.now();
 		let firstTokenTime: number | undefined;
 
 		const output: AssistantMessage = {
@@ -421,11 +416,15 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 					invalidateAwsCredentialCache({ profile: options.profile, region });
 				}
 				const errBody = await response.text().catch(() => "");
-				throw new BedrockApiError(`Bedrock HTTP ${response.status}: ${errBody.slice(0, 1000)}`, response.status, {
-					headers: response.headers,
-				});
+				throw new AIError.BedrockApiError(
+					`Bedrock HTTP ${response.status}: ${errBody.slice(0, 1000)}`,
+					response.status,
+					{
+						headers: response.headers,
+					},
+				);
 			}
-			if (!response.body) throw new Error("Bedrock response has no body");
+			if (!response.body) throw new AIError.BedrockApiError("Bedrock response has no body", response.status);
 
 			// Track first event for the abort/diagnostic path (currently informational).
 			for await (const message of decodeEventStream(response.body)) {
@@ -437,14 +436,12 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 					const payload = safeParsePayload(message.payload) as { message?: string } | undefined;
 					const errorMessage = payload?.message || new TextDecoder().decode(message.payload);
 					const text = `${exceptionType}: ${errorMessage}`;
-					throw exceptionType === "validationException"
-						? new BedrockApiError(text, 400, { code: exceptionType })
-						: new Error(text);
+					throw new AIError.BedrockApiError(text, 400, { code: exceptionType });
 				}
 				if (messageType === "error") {
 					const code = message.headers[":error-code"] || "UnknownError";
 					const errorMessage = message.headers[":error-message"] || new TextDecoder().decode(message.payload);
-					throw new Error(`${code}: ${errorMessage}`);
+					throw new AIError.BedrockApiError(`${code}: ${errorMessage}`, 400, { code });
 				}
 				if (messageType !== "event") continue;
 
@@ -456,18 +453,21 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 						// no-op: first event marker is implicit by stream entry.
 						const ev = payload as MessageStartEvent;
 						if (ev.role !== "assistant") {
-							throw new Error("Unexpected assistant message start but got user message start instead");
+							throw new AIError.BedrockApiError(
+								"Unexpected assistant message start but got user message start instead",
+								0,
+							);
 						}
 						stream.push({ type: "start", partial: output });
 						break;
 					}
 					case "contentBlockStart": {
-						if (!firstTokenTime) firstTokenTime = Date.now();
+						if (!firstTokenTime) firstTokenTime = performance.now();
 						handleContentBlockStart(payload as ContentBlockStartEvent, blocks, output, stream, sentinelInjected);
 						break;
 					}
 					case "contentBlockDelta": {
-						if (!firstTokenTime) firstTokenTime = Date.now();
+						if (!firstTokenTime) firstTokenTime = performance.now();
 						handleContentBlockDelta(payload as ContentBlockDeltaEvent, blocks, output, stream);
 						break;
 					}
@@ -496,23 +496,20 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 				}
 			}
 
-			if (options.signal?.aborted) throw new Error("Request was aborted");
+			if (options.signal?.aborted) throw new AIError.AbortError();
 
 			if (output.stopReason === "error" || output.stopReason === "aborted") {
-				throw new Error(output.errorMessage ?? "An unknown error occurred");
+				throw new AIError.BedrockApiError(output.errorMessage ?? "An unknown error occurred", 0);
 			}
 
-			output.duration = Date.now() - startTime;
+			output.duration = performance.now() - startTime;
 			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
 			stream.push({ type: "done", reason: output.stopReason, message: output });
 			stream.end();
 		} catch (error) {
 			for (const block of output.content) {
-				delete (block as Block).index;
-				delete (block as Block).partialJson;
+				if (block.type === "toolCall") clearStreamingPartialJson(block);
 			}
-			output.stopReason = options.signal?.aborted ? "aborted" : "error";
-			output.errorStatus = extractHttpStatusFromError(error);
 			const baseMessage = error instanceof Error ? error.message : JSON.stringify(error);
 			// Enrich error with thinking block diagnostics for signature-related failures
 			let diagnostics = "";
@@ -534,8 +531,12 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 					diagnostics = `\n[thinking-diag] ${JSON.stringify(thinkingBlocks)}`;
 				}
 			}
-			output.errorMessage = await appendRawHttpRequestDumpFor400(baseMessage + diagnostics, error, rawRequestDump);
-			output.duration = Date.now() - startTime;
+			const result = await AIError.finalize(error, { api: model.api, signal: options.signal, rawRequestDump });
+			output.stopReason = result.stopReason;
+			output.errorStatus = result.status;
+			output.errorId = result.id;
+			output.errorMessage = result.message + diagnostics;
+			output.duration = performance.now() - startTime;
 			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
 			stream.push({ type: "error", reason: output.stopReason, error: output });
 			stream.end();
@@ -575,8 +576,8 @@ function handleContentBlockStart(
 			id: normalizeToolCallId(start.toolUse.toolUseId || ""),
 			name: start.toolUse.name || "",
 			arguments: {},
-			partialJson: "",
-			index,
+			[kStreamingPartialJson]: "",
+			[kStreamingBlockIndex]: index,
 		};
 		output.content.push(block);
 		stream.push({ type: "toolcall_start", contentIndex: blocks.length - 1, partial: output });
@@ -591,13 +592,13 @@ function handleContentBlockDelta(
 ): void {
 	const contentBlockIndex = event.contentBlockIndex;
 	const delta = event.delta;
-	let index = blocks.findIndex(b => b.index === contentBlockIndex);
+	let index = blocks.findIndex(b => b[kStreamingBlockIndex] === contentBlockIndex);
 	let block = blocks[index];
 
 	if (delta?.text !== undefined) {
 		// If no text block exists yet, create one — `handleContentBlockStart` is not sent for text blocks
 		if (!block) {
-			const newBlock: Block = { type: "text", text: "", index: contentBlockIndex };
+			const newBlock: Block = { type: "text", text: "", [kStreamingBlockIndex]: contentBlockIndex };
 			output.content.push(newBlock);
 			index = blocks.length - 1;
 			block = blocks[index];
@@ -608,11 +609,11 @@ function handleContentBlockDelta(
 			stream.push({ type: "text_delta", contentIndex: index, delta: delta.text, partial: output });
 		}
 	} else if (delta?.toolUse && block?.type === "toolCall") {
-		block.partialJson = (block.partialJson || "") + (delta.toolUse.input || "");
-		const throttled = parseStreamingJsonThrottled(block.partialJson, block.lastParseLen ?? 0);
+		block[kStreamingPartialJson] = (block[kStreamingPartialJson] || "") + (delta.toolUse.input || "");
+		const throttled = parseStreamingJsonThrottled(block[kStreamingPartialJson], block[kStreamingLastParseLen] ?? 0);
 		if (throttled) {
 			block.arguments = throttled.value;
-			block.lastParseLen = throttled.parsedLen;
+			block[kStreamingLastParseLen] = throttled.parsedLen;
 		}
 		stream.push({ type: "toolcall_delta", contentIndex: index, delta: delta.toolUse.input || "", partial: output });
 	} else if (delta?.reasoningContent) {
@@ -620,7 +621,12 @@ function handleContentBlockDelta(
 		let thinkingIndex = index;
 
 		if (!thinkingBlock) {
-			const newBlock: Block = { type: "thinking", thinking: "", thinkingSignature: "", index: contentBlockIndex };
+			const newBlock: Block = {
+				type: "thinking",
+				thinking: "",
+				thinkingSignature: "",
+				[kStreamingBlockIndex]: contentBlockIndex,
+			};
 			output.content.push(newBlock);
 			thinkingIndex = blocks.length - 1;
 			thinkingBlock = blocks[thinkingIndex];
@@ -662,10 +668,9 @@ function handleContentBlockStop(
 	output: AssistantMessage,
 	stream: AssistantMessageEventStream,
 ): void {
-	const index = blocks.findIndex(b => b.index === event.contentBlockIndex);
+	const index = blocks.findIndex(b => b[kStreamingBlockIndex] === event.contentBlockIndex);
 	const block = blocks[index];
 	if (!block) return;
-	delete (block as Block).index;
 
 	switch (block.type) {
 		case "text":
@@ -675,9 +680,8 @@ function handleContentBlockStop(
 			stream.push({ type: "thinking_end", contentIndex: index, content: block.thinking, partial: output });
 			break;
 		case "toolCall":
-			block.arguments = parseStreamingJson(block.partialJson);
-			delete (block as Block).partialJson;
-			delete (block as Block).lastParseLen;
+			block.arguments = parseStreamingJson(block[kStreamingPartialJson]);
+			clearStreamingPartialJson(block);
 			stream.push({ type: "toolcall_end", contentIndex: index, toolCall: block, partial: output });
 			break;
 	}
@@ -772,7 +776,7 @@ function convertMessages(
 								contentBlocks.push({ image: createImageBlock(c.mimeType, c.data) });
 								break;
 							default:
-								throw new Error("Unknown user content type");
+								throw new AIError.ValidationError("Unknown user content type");
 						}
 					}
 					// Skip message if all blocks filtered out
@@ -820,11 +824,11 @@ function convertMessages(
 								});
 							} else {
 								// Model requires signature but we don't have one — demote to text
-								contentBlocks.push({ text: `[Thinking]: ${c.thinking.toWellFormed()}` });
+								contentBlocks.push({ text: renderDemotedThinking(model.id, c.thinking) });
 							}
 							break;
 						default:
-							throw new Error("Unknown assistant content type");
+							throw new AIError.ValidationError("Unknown assistant content type");
 					}
 				}
 				// Skip if all content blocks were filtered out
@@ -870,7 +874,7 @@ function convertMessages(
 				break;
 			}
 			default:
-				throw new Error("Unknown message role");
+				throw new AIError.ValidationError("Unknown message role");
 		}
 	}
 
@@ -1032,7 +1036,7 @@ function createImageBlock(mimeType: string, data: string): ImageBlockWire["image
 			format = "webp";
 			break;
 		default:
-			throw new Error(`Unknown image type: ${mimeType}`);
+			throw new AIError.ValidationError(`Unknown image type: ${mimeType}`);
 	}
 	return { source: { bytes: data }, format };
 }

package/src/providers/anthropic-client.ts

@@ -21,7 +21,11 @@
  *   with up to 25% jitter).
  */
 import { scheduler } from "node:timers/promises";
-import { ProviderHttpError } from "../errors";
+import * as AIError from "../error";
+import { AnthropicApiError, AnthropicConnectionError, AnthropicConnectionTimeoutError } from "../error";
+
+export { AnthropicApiError, AnthropicConnectionError, AnthropicConnectionTimeoutError };
+
 import type { FetchImpl } from "../types";
 import type { MessageCreateParamsStreaming } from "./anthropic-wire";
 
@@ -77,42 +81,8 @@ export interface AnthropicClientOptions {
 	fetchOptions?: AnthropicFetchOptions;
 }
 
-/** Non-2xx response from the Anthropic API. */
-export class AnthropicApiError extends ProviderHttpError {
-	declare readonly headers: Headers;
-	readonly requestId: string | null;
-
-	constructor(status: number, message: string, headers: Headers) {
-		super(message, status, { headers });
-		this.name = "AnthropicApiError";
-		this.requestId = headers.get("request-id");
-	}
-
-	static async fromResponse(response: Response): Promise<AnthropicApiError> {
-		const body = await response.text().catch(() => "");
-		const detail = body.trim() || "status code (no body)";
-		return new AnthropicApiError(response.status, `${response.status} ${detail}`, response.headers);
-	}
-}
-
-/** Network-level failure (DNS, TLS, socket reset) after retries were exhausted. */
-export class AnthropicConnectionError extends Error {
-	constructor(cause: unknown) {
-		super("Connection error.", { cause });
-		this.name = "AnthropicConnectionError";
-	}
-}
-
-/** No response headers arrived within the configured request timeout. */
-export class AnthropicConnectionTimeoutError extends Error {
-	constructor() {
-		super("Request timed out.");
-		this.name = "AnthropicConnectionTimeoutError";
-	}
-}
-
 function createAbortError(): Error {
-	return new Error("Request was aborted.");
+	return new AIError.AbortError("Request was aborted.");
 }
 
 /** `x-should-retry` override, then 408/409/429/5xx. */
@@ -121,7 +91,9 @@ function shouldRetryResponse(response: Response): boolean {
 	if (shouldRetryHeader === "true") return true;
 	if (shouldRetryHeader === "false") return false;
 	const status = response.status;
-	return status === 408 || status === 409 || status === 429 || status >= 500;
+	// Canonical transient set (408/429/5xx) plus 409, which Anthropic's client
+	// also retries.
+	return AIError.isTransientStatus(status) || status === 409;
 }
 
 /** Server-suggested delay (`retry-after-ms`, then `retry-after` seconds or HTTP date). */
@@ -260,8 +232,8 @@ export class AnthropicMessagesClient implements AnthropicMessagesClientLike {
 					await this.#backoff(attempt, undefined, callerSignal);
 					continue;
 				}
-				if (error instanceof AnthropicConnectionTimeoutError) throw error;
-				throw new AnthropicConnectionError(error);
+				if (error instanceof AIError.AnthropicConnectionTimeoutError) throw error;
+				throw new AIError.AnthropicConnectionError(error);
 			}
 
 			if (response.ok) return response;
@@ -271,7 +243,7 @@ export class AnthropicMessagesClient implements AnthropicMessagesClientLike {
 				await this.#backoff(attempt, response.headers, callerSignal);
 				continue;
 			}
-			throw await AnthropicApiError.fromResponse(response);
+			throw await AIError.AnthropicApiError.fromResponse(response);
 		}
 	}
 
@@ -300,7 +272,7 @@ export class AnthropicMessagesClient implements AnthropicMessagesClientLike {
 				signal: controller.signal,
 			});
 		} catch (error) {
-			if (timedOut && !callerSignal?.aborted) throw new AnthropicConnectionTimeoutError();
+			if (timedOut && !callerSignal?.aborted) throw new AIError.AnthropicConnectionTimeoutError();
 			throw error;
 		} finally {
 			clearTimeout(timer);