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

package/src/registry/vercel-ai-gateway.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
@@ -5,7 +6,7 @@ const AUTH_URL = "https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway%2Fapi
 
 export async function loginVercelAiGateway(options: OAuthController): Promise<string> {
 	if (!options.onPrompt) {
-		throw new Error("Vercel AI Gateway login requires onPrompt callback");
+		throw new AIError.OnPromptRequiredError("Vercel AI Gateway");
 	}
 
 	options.onAuth?.({
@@ -19,12 +20,12 @@ export async function loginVercelAiGateway(options: OAuthController): Promise<st
 	});
 
 	if (options.signal?.aborted) {
-		throw new Error("Login cancelled");
+		throw new AIError.LoginCancelledError();
 	}
 
 	const trimmed = apiKey.trim();
 	if (!trimmed) {
-		throw new Error("API key is required");
+		throw new AIError.ApiKeyRequiredError();
 	}
 
 	return trimmed;

package/src/registry/vllm.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { OAuthController, OAuthLoginCallbacks, OAuthProvider } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
@@ -8,7 +9,7 @@ const DEFAULT_LOCAL_TOKEN = "vllm-local";
 
 export async function loginVllm(options: OAuthController): Promise<string> {
 	if (!options.onPrompt) {
-		throw new Error(`${PROVIDER_ID} login requires onPrompt callback`);
+		throw new AIError.OnPromptRequiredError(PROVIDER_ID);
 	}
 	options.onAuth?.({
 		url: AUTH_URL,
@@ -20,7 +21,7 @@ export async function loginVllm(options: OAuthController): Promise<string> {
 		allowEmpty: true,
 	});
 	if (options.signal?.aborted) {
-		throw new Error("Login cancelled");
+		throw new AIError.LoginCancelledError();
 	}
 	const trimmed = apiKey.trim();
 	return trimmed || DEFAULT_LOCAL_TOKEN;

package/src/stream.ts

@@ -2,6 +2,7 @@ import * as crypto from "node:crypto";
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { scheduler } from "node:timers/promises";
 import type { Effort } from "@oh-my-pi/pi-catalog/effort";
 import { isVertexExpressOpenAIUrl, isVertexRawPredictUrl } from "@oh-my-pi/pi-catalog/hosts";
 import {
@@ -12,10 +13,12 @@ import {
 	resolveWireModelId,
 } from "@oh-my-pi/pi-catalog/model-thinking";
 import { CATALOG_PROVIDERS, type ProviderCatalogEntry } from "@oh-my-pi/pi-catalog/provider-models";
-import { $env, $pickenv, extractHttpStatusFromError, getConfigRootDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import { $env, $pickenv, getConfigRootDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import { getCustomApi } from "./api-registry";
 import { AUTH_RETRY_STEPS, isApiKeyResolver, resolveRetryKey } from "./auth-retry";
-import { ProviderHttpError } from "./errors";
+import * as AIError from "./error";
+import { ProviderHttpError } from "./error";
+import { isUsageLimitOutcome } from "./error/rate-limit";
 import type { BedrockOptions } from "./providers/amazon-bedrock";
 import type { AnthropicOptions } from "./providers/anthropic";
 import type { CursorOptions } from "./providers/cursor";
@@ -53,7 +56,6 @@ import {
 	streamOpenAIResponses,
 } from "./providers/register-builtins";
 import { isSyntheticModel, streamSynthetic } from "./providers/synthetic";
-import { isUsageLimitOutcome } from "./rate-limit-utils";
 import { PROVIDER_REGISTRY } from "./registry";
 import type {
 	Api,
@@ -269,7 +271,7 @@ async function acquireProviderInFlightLock(provider: string, signal?: AbortSigna
 	await fs.mkdir(path.dirname(lockDir), { recursive: true });
 
 	while (true) {
-		if (signal?.aborted) throw signal.reason ?? new Error("Provider request aborted before dispatch");
+		if (signal?.aborted) throw signal.reason ?? new AIError.AbortError("Provider request aborted before dispatch");
 		try {
 			await fs.mkdir(lockDir);
 			const lockIdentity = await readProviderInFlightLockIdentity(lockDir);
@@ -374,7 +376,8 @@ async function signalProviderInFlightWaiters(provider: string): Promise<void> {
 }
 
 function waitForProviderInFlightSignal(provider: string, signal?: AbortSignal): Promise<void> {
-	if (signal?.aborted) return Promise.reject(signal.reason ?? new Error("Provider request aborted before dispatch"));
+	if (signal?.aborted)
+		return Promise.reject(signal.reason ?? new AIError.AbortError("Provider request aborted before dispatch"));
 	const signalPath = providerInFlightSignalPath(provider);
 	const waitStarted = Date.now();
 	const { promise, resolve, reject } = Promise.withResolvers<void>();
@@ -390,7 +393,7 @@ function waitForProviderInFlightSignal(provider: string, signal?: AbortSignal):
 		settle();
 	};
 	const onAbort = () => {
-		finish(() => reject(signal?.reason ?? new Error("Provider request aborted before dispatch")));
+		finish(() => reject(signal?.reason ?? new AIError.AbortError("Provider request aborted before dispatch")));
 	};
 	signal?.addEventListener("abort", onAbort, { once: true });
 	try {
@@ -446,7 +449,7 @@ async function acquireProviderInFlightSlot(
 	if (limit === undefined) return async () => {};
 	let loggedWait = false;
 	while (true) {
-		if (signal?.aborted) throw signal.reason ?? new Error("Provider request aborted before dispatch");
+		if (signal?.aborted) throw signal.reason ?? new AIError.AbortError("Provider request aborted before dispatch");
 		const lease = await tryAcquireProviderInFlightLease(provider, limit, signal);
 		if (lease) return () => releaseProviderInFlightLease(provider, lease);
 		if (!loggedWait) {
@@ -508,7 +511,7 @@ function withProviderInFlightLimit<TOptions extends Pick<StreamOptions, "signal"
 				logger.debug("Provider in-flight limit wait completed", { provider: model.provider, limit });
 			}
 			if (options?.signal?.aborted) {
-				throw options.signal.reason ?? new Error("Provider request aborted before dispatch");
+				throw options.signal.reason ?? new AIError.AbortError("Provider request aborted before dispatch");
 			}
 			const inner = dispatch();
 			try {
@@ -710,7 +713,7 @@ function streamDispatch<TApi extends Api>(
 	if (isGitLabDuoModel(model)) {
 		const apiKey = requestOptions.apiKey || getEnvApiKey(model.provider);
 		if (!apiKey) {
-			throw new Error(`No API key for provider: ${model.provider}`);
+			throw new AIError.MissingApiKeyError(model.provider);
 		}
 		return streamGitLabDuo(model, context, {
 			...(requestOptions as SimpleStreamOptions),
@@ -721,7 +724,7 @@ function streamDispatch<TApi extends Api>(
 	if (model.api === "gitlab-duo-agent") {
 		const apiKey = (requestOptions as StreamOptions | undefined)?.apiKey || getEnvApiKey(model.provider);
 		if (!apiKey) {
-			throw new Error(`No API key for provider: ${model.provider}`);
+			throw new AIError.MissingApiKeyError(model.provider);
 		}
 		return streamGitLabDuoWorkflow(model as Model<"gitlab-duo-agent">, context, {
 			...(requestOptions as StreamOptions | undefined),
@@ -739,7 +742,7 @@ function streamDispatch<TApi extends Api>(
 
 	const apiKey = requestOptions.apiKey || getEnvApiKey(model.provider);
 	if (!apiKey) {
-		throw new Error(`No API key for provider: ${model.provider}`);
+		throw new AIError.MissingApiKeyError(model.provider);
 	}
 	const providerOptions = isGoogleVertexAuthenticatedModel(model)
 		? {
@@ -823,17 +826,61 @@ function streamDispatch<TApi extends Api>(
 			return streamDevin(model as Model<"devin-agent">, context, providerOptions as DevinOptions);
 
 		default:
-			throw new Error(`Unhandled API: ${api}`);
+			throw new AIError.ConfigurationError(`Unhandled API: ${api}`);
 	}
 }
 
+/** Thinking-loop re-samples spent before {@link resolveWithThinkingLoopCook} cooks. */
+const THINKING_LOOP_MAX_ABORTS = 3;
+const THINKING_LOOP_RETRY_BASE_DELAY_MS = 500;
+const THINKING_LOOP_RETRY_MAX_DELAY_MS = 8_000;
+
+/**
+ * Resolve a completion, re-sampling a thinking-loop stall up to
+ * {@link THINKING_LOOP_MAX_ABORTS} times before letting it cook. The loop guard
+ * raises an empty `stopReason: "error"` stall on each guarded attempt; this
+ * result-path consumer re-dispatches a fresh request per stall and, once the abort
+ * budget is spent, runs one final pass with the guard disabled so a stubborn loop
+ * returns the model's raw output instead of a fatal stall. Non-stall results —
+ * including genuine errors — return immediately; a caller abort during backoff
+ * propagates so cancellation surfaces as an abort, never a stale stall result.
+ */
+async function resolveWithThinkingLoopCook(
+	signal: AbortSignal | undefined,
+	dispatch: () => AssistantMessageEventStream,
+	cook: () => AssistantMessageEventStream,
+): Promise<AssistantMessage> {
+	let message = await dispatch().result();
+	let thinkingLoopRetry = AIError.is(message.errorId, AIError.Flag.ThinkingLoop);
+	for (let attempt = 0; thinkingLoopRetry && attempt < THINKING_LOOP_MAX_ABORTS - 1; attempt += 1) {
+		// A caller abort surfaces as a thrown abort (never the stall, which would
+		// misclassify as a 502): throwIfAborted before backoff, and scheduler.wait
+		// rejects if the abort lands mid-delay.
+		signal?.throwIfAborted();
+		const delay = Math.min(THINKING_LOOP_RETRY_BASE_DELAY_MS * 2 ** attempt, THINKING_LOOP_RETRY_MAX_DELAY_MS);
+		await scheduler.wait(delay, { signal });
+		message = await dispatch().result();
+		thinkingLoopRetry =
+			message.stopReason === "error" &&
+			message.content.length === 0 &&
+			AIError.is(message.errorId, AIError.Flag.ThinkingLoop);
+	}
+	if (!thinkingLoopRetry) return message;
+	signal?.throwIfAborted();
+	// Abort budget spent and still looping: let it cook with the guard disabled.
+	return cook().result();
+}
+
 export async function complete<TApi extends Api>(
 	model: Model<TApi>,
 	context: Context,
 	options?: OptionsForApi<TApi>,
 ): Promise<AssistantMessage> {
-	const s = stream(model, context, options);
-	return s.result();
+	return resolveWithThinkingLoopCook(
+		options?.signal,
+		() => stream(model, context, options),
+		() => stream(model, context, { ...options, loopGuard: { ...options?.loopGuard, enabled: false } }),
+	);
 }
 
 type AuthRetryFailure = {
@@ -845,7 +892,7 @@ type AuthRetryFailure = {
 function extractStatusFromAssistantError(message: AssistantMessage): number | undefined {
 	if (message.errorStatus !== undefined) return message.errorStatus;
 	if (!message.errorMessage) return undefined;
-	return extractHttpStatusFromError({ message: message.errorMessage });
+	return AIError.status({ message: message.errorMessage });
 }
 
 function isRetryableUpstreamError(error: unknown, status: number | undefined, message: string | undefined): boolean {
@@ -868,7 +915,9 @@ function isRetryableUpstreamError(error: unknown, status: number | undefined, me
 function createAssistantAuthError(message: AssistantMessage): Error {
 	const text = message.errorMessage ?? "Provider authentication failed";
 	const status = extractStatusFromAssistantError(message);
-	return status === undefined ? new Error(text) : new ProviderHttpError(text, status);
+	return status === undefined
+		? new AIError.ProviderResponseError(text, { kind: "runtime" })
+		: new ProviderHttpError(text, status);
 }
 
 function emitBufferedEvents(stream: AssistantMessageEventStream, events: AssistantMessageEvent[]): void {
@@ -937,7 +986,7 @@ export function streamSimple<TApi extends Api>(
 					captureAuthFailure &&
 					isRetryableUpstreamError(
 						error,
-						extractHttpStatusFromError(error),
+						AIError.status(error),
 						error instanceof Error ? error.message : undefined,
 					)
 				) {
@@ -965,7 +1014,7 @@ export function streamSimple<TApi extends Api>(
 				// A thrown resolver is a broker/OAuth/network failure, not a missing
 				// key — surface the cause instead of masking it as "No API key".
 				outer.fail(
-					new Error(
+					new AIError.ConfigurationError(
 						`Failed to resolve API key for provider ${model.provider}: ${error instanceof Error ? error.message : String(error)}`,
 						{ cause: error },
 					),
@@ -973,7 +1022,7 @@ export function streamSimple<TApi extends Api>(
 				return;
 			}
 			if (lastKey === undefined) {
-				outer.fail(new Error(`No API key for provider: ${model.provider}`));
+				outer.fail(new AIError.MissingApiKeyError(model.provider));
 				return;
 			}
 			let failure = await runAttempt(lastKey, true);
@@ -1034,7 +1083,7 @@ export function streamSimple<TApi extends Api>(
 	const apiKey =
 		(typeof requestOptions?.apiKey === "string" ? requestOptions.apiKey : undefined) || getEnvApiKey(model.provider);
 	if (!apiKey) {
-		throw new Error(`No API key for provider: ${model.provider}`);
+		throw new AIError.MissingApiKeyError(model.provider);
 	}
 
 	// GitLab Duo - wraps Anthropic/OpenAI behind GitLab AI Gateway direct access tokens
@@ -1087,8 +1136,11 @@ export async function completeSimple<TApi extends Api>(
 	context: Context,
 	options?: SimpleStreamOptions,
 ): Promise<AssistantMessage> {
-	const s = streamSimple(model, context, options);
-	return s.result();
+	return resolveWithThinkingLoopCook(
+		options?.signal,
+		() => streamSimple(model, context, options),
+		() => streamSimple(model, context, { ...options, loopGuard: { ...options?.loopGuard, enabled: false } }),
+	);
 }
 
 const MIN_OUTPUT_TOKENS = 1024;
@@ -1441,6 +1493,7 @@ function mapOptionsForApi<TApi extends Api>(
 					openrouterVariant: options?.openrouterVariant,
 					maxTokensExplicit: rawOptions?.maxTokens !== undefined,
 					disableReasoning: options?.disableReasoning,
+					textVerbosity: options?.textVerbosity,
 				});
 			}
 			return castApi<"openai-completions">({
@@ -1475,6 +1528,7 @@ function mapOptionsForApi<TApi extends Api>(
 				openrouterVariant: options?.openrouterVariant,
 				maxTokensExplicit: rawOptions?.maxTokens !== undefined,
 				disableReasoning: options?.disableReasoning,
+				textVerbosity: options?.textVerbosity,
 			});
 
 		case "azure-openai-responses":
@@ -1493,7 +1547,8 @@ function mapOptionsForApi<TApi extends Api>(
 				toolChoice: mapOpenAiToolChoice(options?.toolChoice),
 				serviceTier: options?.serviceTier,
 				preferWebsockets: options?.preferWebsockets,
-				reasoningSummary: options?.hideThinkingSummary ? null : undefined,
+				reasoningSummary: options?.hideThinkingSummary ? null : "detailed",
+				textVerbosity: options?.textVerbosity,
 			});
 
 		case "google-generative-ai": {
@@ -1665,7 +1720,7 @@ function mapOptionsForApi<TApi extends Api>(
 			});
 		}
 		default:
-			throw new Error(`Unhandled API in mapOptionsForApi: ${model.api}`);
+			throw new AIError.ConfigurationError(`Unhandled API in mapOptionsForApi: ${model.api}`);
 	}
 }
 

package/src/types.ts

@@ -37,6 +37,7 @@ import type { OllamaChatOptions } from "./providers/ollama";
 import type { OpenAICodexResponsesOptions } from "./providers/openai-codex-responses";
 import type { OpenAICompletionsOptions } from "./providers/openai-completions";
 import type { OpenAIResponsesOptions } from "./providers/openai-responses";
+import type { kStreamingPartialJson } from "./utils/block-symbols";
 import type { AssistantMessageEventStream } from "./utils/event-stream";
 
 export type { StopDetails } from "./providers/anthropic-wire";
@@ -379,6 +380,8 @@ export interface SimpleStreamOptions extends Omit<StreamOptions, "apiKey"> {
 	 * Useful when the UI hides thinking blocks anyway and the summary is wasted bandwidth.
 	 */
 	hideThinkingSummary?: boolean;
+	/** OpenAI Responses/Codex `text.verbosity` response detail level. */
+	textVerbosity?: "low" | "medium" | "high";
 	/** Custom token budgets for thinking levels (token-based providers only) */
 	thinkingBudgets?: ThinkingBudgets;
 	/** Cursor exec handlers for local tool execution */
@@ -457,6 +460,7 @@ export interface ToolCall {
 	id: string;
 	name: string;
 	arguments: Record<string, unknown>;
+	[kStreamingPartialJson]?: string;
 	thoughtSignature?: string; // Google-specific: opaque signature for reusing thought context
 	intent?: string; // Harness-level intent metadata extracted from traced tool arguments
 	/**
@@ -537,6 +541,8 @@ export interface AssistantMessage {
 	errorMessage?: string;
 	/** HTTP status surfaced by the provider when the request failed. Populated by every provider's catch block alongside `errorMessage` so consumers (auth retry, telemetry, UI) can branch without regex-scraping the message. */
 	errorStatus?: number;
+	/** Structured machine-readable error classifier; see `utils/error-id.ts` for bit layout and helpers. */
+	errorId?: number;
 	/**
 	 * Stable identifiers for request features the provider silently dropped
 	 * during this turn (e.g. `"priority"`). Set when a server-side rejection

package/src/usage/claude.ts

@@ -1,5 +1,6 @@
 import { scheduler } from "node:timers/promises";
 import { toNumber } from "@oh-my-pi/pi-catalog/utils";
+import * as AIError from "../error";
 import { claudeCodeVersion } from "../providers/anthropic";
 import type {
 	CredentialRankingStrategy,
@@ -148,7 +149,7 @@ function hasUsageData(payload: ClaudeUsageResponse): boolean {
 }
 
 function isRetryableStatus(status: number): boolean {
-	return status === 429 || (status >= 500 && status < 600);
+	return AIError.isTransientStatus(status);
 }
 
 function isAbortError(error: unknown, signal?: AbortSignal): boolean {

package/src/usage/github-copilot.ts

@@ -6,6 +6,7 @@
 
 import { toBoolean, toNumber } from "@oh-my-pi/pi-catalog/utils";
 import { OPENCODE_HEADERS } from "@oh-my-pi/pi-catalog/wire/github-copilot";
+import * as AIError from "../error";
 import type {
 	UsageAmount,
 	UsageFetchContext,
@@ -142,7 +143,7 @@ async function fetchJson(ctx: UsageFetchContext, url: string, init: RequestInit)
 	const response = await ctx.fetch(url, init);
 	if (!response.ok) {
 		const text = await response.text();
-		throw new Error(`${response.status} ${response.statusText}: ${text}`);
+		throw new AIError.ProviderHttpError(`${response.status} ${response.statusText}: ${text}`, response.status);
 	}
 	return response.json();
 }
@@ -182,7 +183,7 @@ async function fetchInternalUsage(
 		...OPENCODE_HEADERS,
 	};
 	const data = await fetchJson(ctx, `${githubApiBaseUrl}/copilot_internal/user`, { headers, signal });
-	if (!isRecord(data)) throw new Error("Invalid Copilot usage response");
+	if (!isRecord(data)) throw new AIError.ProviderHttpError("Invalid Copilot usage response", 200);
 	return data as CopilotUsageResponse;
 }
 
@@ -206,7 +207,7 @@ async function fetchBillingUsage(
 		},
 	);
 
-	if (!isRecord(data)) throw new Error("Invalid Copilot billing usage response");
+	if (!isRecord(data)) throw new AIError.ProviderHttpError("Invalid Copilot billing usage response", 200);
 	return data as BillingUsageResponse;
 }
 

package/src/usage/google-antigravity.ts

@@ -1,4 +1,5 @@
 import { getAntigravityUserAgent } from "@oh-my-pi/pi-catalog/wire/gemini-headers";
+import * as AIError from "../error";
 import type {
 	CredentialRankingContext,
 	CredentialRankingStrategy,
@@ -181,7 +182,7 @@ async function fetchAntigravityUsage(params: UsageFetchParams, ctx: UsageFetchCo
 				break;
 			}
 
-			if (response.status === 429 || (response.status >= 500 && response.status < 600)) {
+			if (AIError.isTransientStatus(response.status)) {
 				continue;
 			}
 			break;

package/src/utils/abort.ts

@@ -1,3 +1,5 @@
+import * as AIError from "../error";
+
 export interface AbortSourceTracker {
 	requestAbortController: AbortController;
 	requestSignal: AbortSignal;
@@ -57,9 +59,9 @@ export function createAbortSourceTracker(callerSignal?: AbortSignal): AbortSourc
  */
 export function raceWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
 	if (!signal) return promise;
-	if (signal.aborted) return Promise.reject(signal.reason ?? new Error("Request was aborted"));
+	if (signal.aborted) return Promise.reject(signal.reason ?? new AIError.AbortError());
 	const { promise: aborted, reject } = Promise.withResolvers<never>();
-	const onAbort = () => reject(signal.reason ?? new Error("Request was aborted"));
+	const onAbort = () => reject(signal.reason ?? new AIError.AbortError());
 	signal.addEventListener("abort", onAbort, { once: true });
 	return Promise.race([promise, aborted]).finally(() => signal.removeEventListener("abort", onAbort));
 }

package/src/utils/block-symbols.ts

@@ -0,0 +1,32 @@
+/** Stores streamed tool-call argument JSON for live renderers and parser recovery. */
+export const kStreamingPartialJson = Symbol("provider.block.partialJson");
+
+/** Carries streamed tool-call argument JSON without exposing a string-keyed property. */
+export type StreamingPartialJsonCarrier = object & { [kStreamingPartialJson]?: string };
+
+/** Reads streamed tool-call argument JSON from a block or event snapshot. */
+export function getStreamingPartialJson(block: StreamingPartialJsonCarrier | null | undefined): string | undefined {
+	return block?.[kStreamingPartialJson];
+}
+
+/** Writes streamed tool-call argument JSON to a block or clears it with `undefined`. */
+export function setStreamingPartialJson(block: StreamingPartialJsonCarrier, value: string | undefined): void {
+	block[kStreamingPartialJson] = value;
+}
+
+/** Clears streamed tool-call argument JSON without deleting or changing object shape. */
+export function clearStreamingPartialJson(block: StreamingPartialJsonCarrier): void {
+	if (Object.hasOwn(block, kStreamingPartialJson)) block[kStreamingPartialJson] = undefined;
+}
+
+/** Stores a provider-local stream block index without exposing a string-keyed property. */
+export const kStreamingBlockIndex = Symbol("provider.block.index");
+
+/** Stores the last parsed argument prefix length for throttled streaming JSON parsing. */
+export const kStreamingLastParseLen = Symbol("provider.block.lastParseLen");
+
+/** Marks streamed tool-call arguments that already received an authoritative done payload. */
+export const kStreamingArgumentsDone = Symbol("provider.block.argumentsDone");
+
+/** Classifies Cursor's in-flight tool-call kind without leaking provider-private state. */
+export const kStreamingBlockKind = Symbol("provider.block.kind");

package/src/utils/event-stream.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { AssistantMessage, AssistantMessageEvent } from "../types";
 
 // Generic event stream class for async iteration
@@ -63,7 +64,9 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 			// end() without a terminal value must still settle result() —
 			// otherwise complete()/result() awaits hang forever.
 			this.resultSettled = true;
-			this.rejectFinalResult(new Error("Stream ended without a final result"));
+			this.rejectFinalResult(
+				new AIError.ProviderResponseError("Stream ended without a final result", { kind: "envelope" }),
+			);
 		}
 		// Notify all waiting consumers that we're done
 		while (this.waiting.length > 0) {
@@ -125,7 +128,7 @@ export class AssistantMessageEventStream extends EventStream<AssistantMessageEve
 				} else if (event.type === "error") {
 					return event.error;
 				}
-				throw new Error("Unexpected event type for final result");
+				throw new AIError.ProviderResponseError("Unexpected event type for final result", { kind: "envelope" });
 			},
 		);
 	}
@@ -133,6 +136,10 @@ export class AssistantMessageEventStream extends EventStream<AssistantMessageEve
 	override push(event: AssistantMessageEvent): void {
 		if (this.done) return;
 
+		if (event.type === "error" && event.error.stopReason === "error") {
+			AIError.classifyMessage(event.error);
+		}
+
 		// Completion resolves the final result and still emits the terminal event.
 		if (this.isComplete(event)) {
 			this.done = true;
@@ -146,13 +153,18 @@ export class AssistantMessageEventStream extends EventStream<AssistantMessageEve
 	override end(result?: AssistantMessage): void {
 		this.done = true;
 		if (result !== undefined) {
+			if (result.stopReason === "error") {
+				AIError.classifyMessage(result);
+			}
 			this.resultSettled = true;
 			this.resolveFinalResult(result);
 		} else if (!this.resultSettled) {
 			// Mirror the base class: a result-less end() must not leave
 			// result() pending forever.
 			this.resultSettled = true;
-			this.rejectFinalResult(new Error("Stream ended without a final result"));
+			this.rejectFinalResult(
+				new AIError.ProviderResponseError("Stream ended without a final result", { kind: "envelope" }),
+			);
 		}
 		this.endWaiting();
 	}

package/src/utils/http-inspector.ts

@@ -1,5 +1,6 @@
 import * as path from "node:path";
-import { extractHttpStatusFromError, getLogsDir, isBunTestRuntime } from "@oh-my-pi/pi-utils";
+import { getLogsDir, isBunTestRuntime } from "@oh-my-pi/pi-utils";
+import * as AIError from "../error/flags";
 import { isCopilotTransientModelError } from "./retry.js";
 import { formatErrorMessageWithRetryAfter } from "./retry-after.js";
 
@@ -28,8 +29,7 @@ export async function appendRawHttpRequestDumpFor400(
 	dump: RawHttpRequestDump | undefined,
 ): Promise<string> {
 	// Never persist dumps under the test runner: providers exercise the 400 path
-	// with mocked fetch responses, which would otherwise litter the real ~/.omp logs.
-	if (!dump || isBunTestRuntime() || extractHttpStatusFromError(error) !== 400) {
+	if (!dump || isBunTestRuntime() || AIError.status(error) !== 400) {
 		return message;
 	}
 
@@ -77,7 +77,7 @@ export async function finalizeErrorMessage(
  */
 export function rewriteCopilotError(errorMessage: string, error: unknown, provider: string): string {
 	if (provider !== "github-copilot") return errorMessage;
-	const status = extractHttpStatusFromError(error);
+	const status = AIError.status(error);
 	if (status === 401) {
 		return `GitHub Copilot authentication failed (HTTP 401). Your token may have been revoked. Please re-login with /login github-copilot`;
 	}

package/src/utils/idle-iterator.ts

@@ -1,4 +1,5 @@
 import { $env } from "@oh-my-pi/pi-utils";
+import * as AIError from "../error";
 
 const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 120_000;
 const DEFAULT_STREAM_FIRST_EVENT_TIMEOUT_MS = 100_000;
@@ -292,7 +293,7 @@ export async function* iterateWithIdleTimeout<T>(
 					if (activeTimeoutMs <= 0) {
 						options.onFirstItemTimeout?.();
 						closeIterator();
-						throw new Error(options.firstItemErrorMessage ?? options.errorMessage);
+						throw new AIError.StreamTimeoutError(options.firstItemErrorMessage ?? options.errorMessage);
 					}
 				}
 			} else if (options.idleTimeoutMs !== undefined && options.idleTimeoutMs > 0) {
@@ -300,7 +301,7 @@ export async function* iterateWithIdleTimeout<T>(
 				if (activeTimeoutMs <= 0) {
 					options.onIdle?.();
 					closeIterator();
-					throw new Error(options.errorMessage);
+					throw new AIError.StreamTimeoutError(options.errorMessage);
 				}
 			}
 
@@ -343,7 +344,7 @@ export async function* iterateWithIdleTimeout<T>(
 						options.onFirstItemTimeout?.();
 					}
 					closeIterator();
-					throw new Error(
+					throw new AIError.StreamTimeoutError(
 						!awaitingFirstItem ? options.errorMessage : (options.firstItemErrorMessage ?? options.errorMessage),
 					);
 				}
@@ -467,6 +468,6 @@ export async function* iterateWithTerminalGrace<T>(
 function abortReason(signal: AbortSignal): Error {
 	const reason = signal.reason;
 	if (reason instanceof Error) return reason;
-	if (typeof reason === "string") return new Error(reason);
-	return new Error("Request was aborted");
+	if (typeof reason === "string") return new AIError.AbortError(reason);
+	return new AIError.AbortError();
 }