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

package/src/auth-broker/discover.ts

@@ -15,6 +15,7 @@ import {
 } from "@oh-my-pi/pi-utils";
 import { YAML } from "bun";
 import { AuthStorage } from "../auth-storage";
+import * as AIError from "../error";
 import { AuthBrokerClient } from "./client";
 import { RemoteAuthCredentialStore } from "./remote-store";
 import { readAuthBrokerSnapshotCache, writeAuthBrokerSnapshotCache } from "./snapshot-cache";
@@ -137,7 +138,8 @@ export async function resolveAuthBrokerConfig(
 	const token =
 		(envToken && envToken.length > 0 ? envToken : undefined) ?? configToken ?? (await readTokenFile()) ?? undefined;
 	if (!token) {
-		throw new Error(
+		throw new AIError.MissingApiKeyError(
+			undefined,
 			`OMP_AUTH_BROKER_URL is set (${url}) but no bearer token is available. ` +
 				`Set OMP_AUTH_BROKER_TOKEN, the \`auth.broker.token\` config entry, or place one at ${getAuthBrokerTokenFilePath()}.`,
 		);
@@ -190,7 +192,10 @@ export async function discoverAuthStorage(options: DiscoverAuthStorageOptions =
 		}
 		if (!initialSnapshot) {
 			const initialResult = await client.fetchSnapshot();
-			if (initialResult.status !== 200) throw new Error("Auth broker returned no initial snapshot");
+			if (initialResult.status !== 200)
+				throw new AIError.AuthBrokerError("Auth broker returned no initial snapshot", {
+					status: initialResult.status,
+				});
 			initialSnapshot = initialResult.snapshot;
 			persist?.(initialSnapshot);
 		}

package/src/auth-broker/remote-store.ts

@@ -17,6 +17,7 @@ import {
 	REMOTE_REFRESH_SENTINEL,
 	type StoredAuthCredential,
 } from "../auth-storage";
+import * as AIError from "../error";
 import type { OAuthCredentials } from "../registry/oauth/types";
 import type { Provider } from "../types";
 import type { UsageReport } from "../usage";
@@ -313,26 +314,26 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	async markCredentialSuspect(credentialId: number, opts: { signal?: AbortSignal } = {}): Promise<void> {
 		const { entry } = await this.#client.refreshCredential(credentialId, opts.signal);
 		if (entry.credential.type !== "oauth") {
-			throw new Error(`Broker returned non-OAuth credential for id=${credentialId}`);
+			throw new AIError.AuthBrokerError(`Broker returned non-OAuth credential for id=${credentialId}`);
 		}
 		this.#applyCredentialEntry(entry);
 		this.#maybeRefreshSnapshot("suspect credential refresh");
 	}
 
 	replaceAuthCredentialsForProvider(_provider: string, _credentials: AuthCredential[]): StoredAuthCredential[] {
-		throw new Error(
+		throw new AIError.AuthBrokerError(
 			"RemoteAuthCredentialStore is read-only on the client. Use `omp auth-broker login <provider>` to mutate credentials.",
 		);
 	}
 
 	upsertAuthCredentialForProvider(_provider: string, _credential: AuthCredential): StoredAuthCredential[] {
-		throw new Error(
+		throw new AIError.AuthBrokerError(
 			"RemoteAuthCredentialStore is read-only on the client. Use `omp auth-broker login <provider>` to mutate credentials.",
 		);
 	}
 
 	deleteAuthCredentialsForProvider(_provider: string, _disabledCause: string): void {
-		throw new Error(
+		throw new AIError.AuthBrokerError(
 			"RemoteAuthCredentialStore is read-only on the client. Use `omp auth-broker logout <provider>` to mutate credentials.",
 		);
 	}
@@ -487,7 +488,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 			});
 		}
 		if (entry.credential.type !== "oauth") {
-			throw new Error(`Broker returned non-OAuth credential for id=${credentialId}`);
+			throw new AIError.AuthBrokerError(`Broker returned non-OAuth credential for id=${credentialId}`);
 		}
 		const refreshed = entry.credential;
 		return {
@@ -538,11 +539,11 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	 */
 	#raceWithSignal<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
 		if (!signal) return promise;
-		if (signal.aborted) return Promise.reject(new Error("auth-broker request aborted"));
+		if (signal.aborted) return Promise.reject(new AIError.AbortError("auth-broker request aborted"));
 		return new Promise<T>((resolve, reject) => {
 			const onAbort = (): void => {
 				signal.removeEventListener("abort", onAbort);
-				reject(new Error("auth-broker request aborted"));
+				reject(new AIError.AbortError("auth-broker request aborted"));
 			};
 			signal.addEventListener("abort", onAbort, { once: true });
 			promise.then(

package/src/auth-gateway/server.ts

@@ -22,12 +22,13 @@ import { Effort } from "@oh-my-pi/pi-catalog/effort";
 import { extractHttpStatusFromError, extractRetryHint, logger } from "@oh-my-pi/pi-utils";
 import type { ApiKeyResolver } from "../auth-retry";
 import type { AuthStorage } from "../auth-storage";
+import { classifyGatewayError } from "../error/gateway";
+import { isUsageLimitOutcome } from "../error/rate-limit";
 import * as anthropicMessages from "../providers/anthropic-messages-server";
 import * as openaiChat from "../providers/openai-chat-server";
 import * as openaiResponses from "../providers/openai-responses-server";
 import * as piNative from "../providers/pi-native-server";
-import { isUsageLimitError, isUsageLimitOutcome } from "../rate-limit-utils";
-import { streamSimple } from "../stream";
+import { completeSimple, streamSimple } from "../stream";
 import type { Api, AssistantMessageEventStream, Context, Model, SimpleStreamOptions } from "../types";
 import { deterministicUuid } from "../utils/deterministic-id";
 import { parseBind } from "../utils/parse-bind";
@@ -192,95 +193,6 @@ function buildStreamOptions(parsed: ParsedFormatRequest, api: Api, signal: Abort
 	return opts;
 }
 
-/**
- * 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): { status: number; type: string; message: string } {
-	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."; pi-ai's central `isUsageLimitError` 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 were seeing when their
-		// account hit its cap.
-		isUsageLimitError(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): { status: number; type: string; message: string } {
-	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;
-}
-
 /**
  * Hook fired by {@link streamSimple} when the upstream request fails in a
  * way that's rotatable — today that's HTTP 401 (credential is bad) and
@@ -525,20 +437,10 @@ async function handleFormatEndpoint(
 		peer,
 	});
 
-	let events: AssistantMessageEventStream;
-	try {
-		if (controller.signal.aborted) return clientClosedResponse(route);
-		events = streamSimple(model, parsed.context, streamOpts);
-	} catch (error) {
-		const classified = classifyGatewayError(error);
-		logger.warn("auth-gateway streamSimple threw", { format: route.label, error: classified.message, peer });
-		return route.module.formatError(classified.status, classified.type, classified.message);
-	}
-
 	if (!parsed.stream) {
 		try {
 			if (controller.signal.aborted) return clientClosedResponse(route);
-			const message = await events.result();
+			const message = await completeSimple(model, parsed.context, streamOpts);
 			if (message.stopReason === "aborted" || message.stopReason === "error") {
 				const errorMessage =
 					message.errorMessage ??
@@ -552,7 +454,7 @@ async function handleFormatEndpoint(
 				if (message.stopReason === "aborted") {
 					return route.module.formatError(499, "request_aborted", errorMessage);
 				}
-				const classified = classifyGatewayError(new Error(errorMessage));
+				const classified = classifyGatewayError(errorMessage);
 				return route.module.formatError(classified.status, classified.type, errorMessage);
 			}
 			return json(200, route.module.encodeResponse(message, parsed.modelId));
@@ -567,6 +469,16 @@ async function handleFormatEndpoint(
 			return route.module.formatError(classified.status, classified.type, classified.message);
 		}
 	}
+
+	let events: AssistantMessageEventStream;
+	try {
+		if (controller.signal.aborted) return clientClosedResponse(route);
+		events = streamSimple(model, parsed.context, streamOpts);
+	} catch (error) {
+		const classified = classifyGatewayError(error);
+		logger.warn("auth-gateway streamSimple threw", { format: route.label, error: classified.message, peer });
+		return route.module.formatError(classified.status, classified.type, classified.message);
+	}
 	if (controller.signal.aborted) return clientClosedResponse(route);
 
 	const sseStream = route.module.encodeStream(events, parsed.modelId, parsed.options, {
@@ -700,20 +612,10 @@ async function handlePiNative(bootOpts: AuthGatewayBootOptions, req: Request, pe
 		peer,
 	});
 
-	let events: AssistantMessageEventStream;
-	try {
-		if (controller.signal.aborted) return aborted();
-		events = streamSimple(model, parsed.context, streamOpts);
-	} catch (error) {
-		const classified = classifyGatewayError(error);
-		logger.warn("auth-gateway streamSimple threw", { format: "pi-native", error: classified.message, peer });
-		return piNative.formatError(classified.status, classified.type, classified.message);
-	}
-
 	if (!parsed.stream) {
 		try {
 			if (controller.signal.aborted) return aborted();
-			const message = await events.result();
+			const message = await completeSimple(model, parsed.context, streamOpts);
 			if (message.stopReason === "aborted" || message.stopReason === "error") {
 				const errorMessage =
 					message.errorMessage ??
@@ -727,7 +629,7 @@ async function handlePiNative(bootOpts: AuthGatewayBootOptions, req: Request, pe
 				if (message.stopReason === "aborted") {
 					return piNative.formatError(499, "request_aborted", errorMessage);
 				}
-				const classified = classifyGatewayError(new Error(errorMessage));
+				const classified = classifyGatewayError(errorMessage);
 				return piNative.formatError(classified.status, classified.type, errorMessage);
 			}
 			return json(200, { message });
@@ -738,6 +640,16 @@ async function handlePiNative(bootOpts: AuthGatewayBootOptions, req: Request, pe
 			return piNative.formatError(classified.status, classified.type, classified.message);
 		}
 	}
+
+	let events: AssistantMessageEventStream;
+	try {
+		if (controller.signal.aborted) return aborted();
+		events = streamSimple(model, parsed.context, streamOpts);
+	} catch (error) {
+		const classified = classifyGatewayError(error);
+		logger.warn("auth-gateway streamSimple threw", { format: "pi-native", error: classified.message, peer });
+		return piNative.formatError(classified.status, classified.type, classified.message);
+	}
 	if (controller.signal.aborted) return aborted();
 
 	const sseStream = piNative.encodeStream(events, parsed.modelId, parsed.options, {

package/src/auth-retry.ts

@@ -1,6 +1,6 @@
-import { extractHttpStatusFromError } from "@oh-my-pi/pi-utils";
 import type { OAuthAccess } from "./auth-storage";
-import { isUsageLimitOutcome } from "./rate-limit-utils";
+import * as AIError from "./error";
+import { isAuthRetryableError } from "./error/auth-classify";
 
 /**
  * Context passed to an {@link ApiKeyResolver} on each resolution attempt.
@@ -70,23 +70,8 @@ export function seedApiKeyResolver(seed: string | undefined, resolver: ApiKeyRes
 	};
 }
 
-/**
- * Classifies whether an error should trigger a credential refresh/rotation
- * retry: a hard `401`, body-classified usage limit (Codex
- * `usage_limit_reached`, Anthropic account rate-limit, Google
- * `resource_exhausted`, OpenAI `insufficient_quota`, …), or a bare `429`
- * whose payload did not preserve a richer quota code. Transient 429s
- * (`Too many requests`, per-minute caps) classify as `RATE_LIMIT_EXCEEDED`
- * via {@link parseRateLimitReason} and stay in the upstream-backoff lane.
- */
-export function isAuthRetryableError(error: unknown): boolean {
-	const status = extractHttpStatusFromError(error);
-	if (status === 401) return true;
-	const message = error instanceof Error ? error.message : typeof error === "string" ? error : undefined;
-	const embeddedStatus = message ? extractHttpStatusFromError({ message }) : undefined;
-	if (embeddedStatus === 401) return true;
-	return isUsageLimitOutcome(status ?? embeddedStatus, message);
-}
+// Re-exported from the error module (its new home); see error/auth-classify.ts.
+export { isAuthRetryableError };
 
 /**
  * The ordered `lastChance` values for the retry steps after the initial
@@ -130,7 +115,7 @@ export async function withAuth<T>(
 	opts?: { isAuthError?: (error: unknown) => boolean; signal?: AbortSignal; missingKeyMessage?: string },
 ): Promise<T> {
 	const isAuthError = opts?.isAuthError ?? isAuthRetryableError;
-	const missingKey = (): Error => new Error(opts?.missingKeyMessage ?? "No API key available");
+	const missingKey = (): Error => new AIError.MissingApiKeyError(undefined, opts?.missingKeyMessage);
 
 	if (!isApiKeyResolver(key)) {
 		if (key === undefined) throw missingKey();
@@ -225,7 +210,10 @@ export async function withOAuthAccess<T>(
 
 	let lastAccess = opts?.seed ?? (await storage.getOAuthAccess(provider, sessionId, { signal }));
 	if (!lastAccess) {
-		throw new Error(opts?.missingAccessMessage ?? `No OAuth credential available for provider: ${provider}`);
+		throw new AIError.MissingApiKeyError(
+			provider,
+			opts?.missingAccessMessage ?? `No OAuth credential available for provider: ${provider}`,
+		);
 	}
 
 	const resolveStep = async (lastChance: boolean, error: unknown): Promise<OAuthAccess | undefined> => {

package/src/auth-storage.ts

@@ -10,9 +10,10 @@
 import { Database, type Statement } from "bun:sqlite";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { extractHttpStatusFromError, getAgentDbPath, logger } from "@oh-my-pi/pi-utils";
+import { getAgentDbPath, logger } from "@oh-my-pi/pi-utils";
 import type { ApiKeyResolver } from "./auth-retry";
-import { isUsageLimitOutcome } from "./rate-limit-utils";
+import * as AIError from "./error";
+import { isUsageLimitOutcome } from "./error/rate-limit";
 import { getProviderDefinition, PASTE_CODE_LOGIN_PROVIDERS } from "./registry";
 import { getOAuthApiKey, getOAuthProvider, refreshOAuthToken } from "./registry/oauth";
 import type { OAuthController, OAuthCredentials, OAuthProvider, OAuthProviderId } from "./registry/oauth/types";
@@ -558,36 +559,9 @@ const OAUTH_REFRESH_SKEW_MS = 60_000;
  */
 const MAX_PENDING_DISABLED_EVENTS = 32;
 
-/**
- * Classify an OAuth refresh error as a definitive credential failure (the
- * refresh token is dead — re-login required) versus a transient blip
- * (network/5xx — retry next sweep).
- *
- * Anchored at module scope so all three refresh sites — in-stream
- * {@link AuthStorage.getApiKey}, the usage probe in
- * {@link AuthStorage.fetchUsageReports}, and the auth-broker background
- * refresher — disable rows on the same criteria. A drifting classifier
- * between sites would let stale last-good usage reports surface indefinitely
- * while streaming requests correctly tear the row down.
- */
-const OAUTH_DEFINITIVE_FAILURE_REGEX =
-	/invalid_grant|invalid_token|unauthorized_client|\brevoked\b|refresh[\s_]?token.*expired/i;
-// Transient: network blips, rate limits, gateway/5xx, and infra denials
-// (WAF / egress 403, permission / account-verification) — block-and-retry,
-// never tear the credential down for these.
-const OAUTH_TRANSIENT_FAILURE_REGEX =
-	/timeout|network|fetch failed|ECONN(?:REFUSED|RESET)|ETIMEDOUT|EAI_AGAIN|socket hang up|\b(?:408|425|429|5\d{2})\b|rate.?limit|too many requests|temporar|unavailable|forbidden|permission_denied|cloudflare|captcha/i;
-// A bare 401 from an OAuth token endpoint means the stored grant/client is
-// dead. 403 is deliberately excluded: it is overwhelmingly WAF / egress
-// rate-limit / permission / account-verification — none of which mean the
-// refresh token itself is invalid.
-const OAUTH_HTTP_AUTH_REGEX = /\b401\b/;
-
-export function isDefinitiveOAuthFailure(errorMsg: string): boolean {
-	if (OAUTH_DEFINITIVE_FAILURE_REGEX.test(errorMsg)) return true;
-	if (OAUTH_HTTP_AUTH_REGEX.test(errorMsg) && !OAUTH_TRANSIENT_FAILURE_REGEX.test(errorMsg)) return true;
-	return false;
-}
+// Re-exported from the error module (its new home) to preserve the public
+// `@oh-my-pi/pi-ai` entrypoint and the in-module call sites below.
+export { isDefinitiveOAuthFailure } from "./error/auth-classify";
 
 /**
  * Outcome of {@link AuthStorage.markUsageLimitReached}.
@@ -811,11 +785,11 @@ function parseUsageCacheEntry<T>(raw: string): UsageCacheEntry<T> | undefined {
  */
 function raceUsageWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
 	if (!signal) return promise;
-	if (signal.aborted) return Promise.reject(new Error("usage fetch aborted"));
+	if (signal.aborted) return Promise.reject(new AIError.AbortError("usage fetch aborted"));
 	return new Promise<T>((resolve, reject) => {
 		const onAbort = (): void => {
 			signal.removeEventListener("abort", onAbort);
-			reject(new Error("usage fetch aborted"));
+			reject(new AIError.AbortError("usage fetch aborted"));
 		};
 		signal.addEventListener("abort", onAbort, { once: true });
 		promise.then(
@@ -837,9 +811,9 @@ function raceCredentialRefreshWithSignal<T>(
 	message = "credential refresh aborted",
 ): Promise<T> {
 	if (!signal) return promise;
-	if (signal.aborted) return Promise.reject(new Error(message));
+	if (signal.aborted) return Promise.reject(new AIError.AbortError(message));
 	const abort = Promise.withResolvers<never>();
-	const onAbort = (): void => abort.reject(new Error(message));
+	const onAbort = (): void => abort.reject(new AIError.AbortError(message));
 	signal.addEventListener("abort", onAbort, { once: true });
 	return Promise.race([promise, abort.promise]).finally(() => {
 		signal.removeEventListener("abort", onAbort);
@@ -1901,7 +1875,7 @@ export class AuthStorage {
 		// Built-in registry first, then runtime-registered extension providers.
 		const def = getProviderDefinition(provider) ?? getOAuthProvider(provider);
 		if (!def?.login) {
-			throw new Error(`Unknown OAuth provider: ${provider}`);
+			throw new AIError.ConfigurationError(`Unknown OAuth provider: ${provider}`);
 		}
 		const result = await def.login({
 			onAuth: ctrl.onAuth,
@@ -2177,7 +2151,7 @@ export class AuthStorage {
 					// (including its already-elapsed `resetsAt`). CAS-disable the row and
 					// clear the cache so the credential drops out of the report instead of
 					// freezing in place until the user notices and re-logs in.
-					if (isDefinitiveOAuthFailure(errorMsg)) {
+					if (AIError.isDefinitiveOAuthFailure(errorMsg)) {
 						const credentialId = this.#findStoredCredentialIdForUsageCredential(
 							request.provider,
 							request.credential,
@@ -3464,7 +3438,10 @@ export class AuthStorage {
 			const customProvider = getOAuthProvider(provider);
 			if (customProvider) {
 				if (!customProvider.refreshToken) {
-					throw new Error(`OAuth provider "${provider}" does not support token refresh`);
+					throw new AIError.OAuthError(`OAuth provider "${provider}" does not support token refresh`, {
+						kind: "configuration",
+						provider,
+					});
 				}
 				refreshPromise = customProvider.refreshToken(credential);
 			} else {
@@ -3478,14 +3455,20 @@ export class AuthStorage {
 		let onAbort: (() => void) | undefined;
 		const cancellation = Promise.withResolvers<never>();
 		timeout = setTimeout(
-			() => cancellation.reject(new Error(`OAuth token refresh timed out for provider: ${provider}`)),
+			() =>
+				cancellation.reject(
+					new AIError.OAuthError(`OAuth token refresh timed out for provider: ${provider}`, {
+						kind: "timeout",
+						provider,
+					}),
+				),
 			DEFAULT_OAUTH_REFRESH_TIMEOUT_MS,
 		);
 		if (signal) {
 			if (signal.aborted) {
-				cancellation.reject(new Error("OAuth token refresh aborted by caller"));
+				cancellation.reject(new AIError.AbortError("OAuth token refresh aborted by caller"));
 			} else {
-				onAbort = () => cancellation.reject(new Error("OAuth token refresh aborted by caller"));
+				onAbort = () => cancellation.reject(new AIError.AbortError("OAuth token refresh aborted by caller"));
 				signal.addEventListener("abort", onAbort, { once: true });
 			}
 		}
@@ -3691,7 +3674,7 @@ export class AuthStorage {
 			const errorMsg = String(error);
 			// Only remove credentials for definitive auth failures
 			// Keep credentials for transient errors (network, 5xx) and block temporarily
-			const isDefinitiveFailure = isDefinitiveOAuthFailure(errorMsg);
+			const isDefinitiveFailure = AIError.isDefinitiveOAuthFailure(errorMsg);
 
 			logger.warn("OAuth token refresh failed", {
 				provider,
@@ -4251,7 +4234,7 @@ export class AuthStorage {
 		if (!sessionCredential) return false;
 
 		const error = options?.error;
-		const status = extractHttpStatusFromError(error);
+		const status = AIError.status(error);
 		const message = error instanceof Error ? error.message : typeof error === "string" ? error : undefined;
 		if (isUsageLimitOutcome(status, message)) {
 			return (
@@ -4388,7 +4371,9 @@ export class AuthStorage {
 			if (index === -1) continue;
 			const target = entries[index];
 			if (target.credential.type !== "oauth") {
-				throw new Error(`Credential ${id} is not OAuth (provider=${provider}, type=${target.credential.type})`);
+				throw new AIError.ValidationError(
+					`Credential ${id} is not OAuth (provider=${provider}, type=${target.credential.type})`,
+				);
 			}
 			// The exact credential we are about to refresh — captured before the
 			// await so a definitive failure can CAS-disable the row against the
@@ -4404,7 +4389,7 @@ export class AuthStorage {
 				// A definitively-dead grant tears the row down here, where the
 				// attempted credential is known. CAS on the persisted credential so a
 				// peer/login rotation in flight leaves the freshly-rotated row intact.
-				if (isDefinitiveOAuthFailure(String(error))) {
+				if (AIError.isDefinitiveOAuthFailure(String(error))) {
 					// CAS-loss (false) means a peer/login rotated the row mid-refresh, so
 					// our #data copy is stale — reload so the next caller serves the
 					// freshly-rotated credential rather than the dead token we attempted.
@@ -4437,7 +4422,7 @@ export class AuthStorage {
 			// -1 means the row was disabled/removed mid-refresh — surface that as a
 			// miss rather than implying a live row the snapshot won't contain.
 			if (this.#replaceCredentialById(provider, id, updated) === -1) {
-				throw new Error(`No credential with id=${id}`);
+				throw new AIError.ValidationError(`No credential with id=${id}`);
 			}
 			return {
 				id,
@@ -4446,7 +4431,7 @@ export class AuthStorage {
 				identityKey: resolveCredentialIdentityKey(provider, updated),
 			};
 		}
-		throw new Error(`No credential with id=${id}`);
+		throw new AIError.ValidationError(`No credential with id=${id}`);
 	}
 
 	/**
@@ -4869,7 +4854,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 				}
 			}
 		}
-		throw new Error(
+		throw new AIError.ConfigurationError(
 			`Failed to open auth database at '${dbPath}' after ${maxAttempts} attempts: ${lastBusyError?.message}`,
 			{ cause: lastBusyError },
 		);

package/src/dialect/demotion.ts

@@ -0,0 +1,31 @@
+import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
+import { getDialectDefinition } from "./factory";
+
+/**
+ * Wrap a prior-turn reasoning string for demotion into native conversation
+ * history — the cross-provider / cross-model case where the target cannot replay
+ * it as a structured thinking block (verified end-to-end against Gemini 3: a
+ * replayed unsigned `thought` part is schema-accepted but silently discarded —
+ * neither recalled nor influencing generation).
+ *
+ * The reasoning is rendered in the TARGET model's canonical inline thinking
+ * delimiters so it reads as reasoning in that model's own idiom instead of bare
+ * prose the model might continue. Harmony and Gemma are the exception: their
+ * `renderThinking` emits chat-template control tokens (`<|channel|>analysis`,
+ * `<|channel>thought`) that must not appear inside a structured native message,
+ * so they fall back to a plain `<think>` block. Every other dialect's thinking
+ * form is inline-safe XML tags or a markdown fence.
+ *
+ * The result ends with a trailing newline so the block stays separated from the
+ * turn's reply text when the wire encoder concatenates parts.
+ *
+ * Distinct from {@link DialectDefinition.renderThinking}, which targets the
+ * owned-dialect *text transport* where those control tokens are legal.
+ */
+export function renderDemotedThinking(modelId: string, text: string): string {
+	if (!text) return "";
+	text = text.toWellFormed();
+	const dialect = preferredDialect(modelId);
+	if (dialect === "harmony" || dialect === "gemma") return `<think>\n${text}\n</think>\n`;
+	return `${getDialectDefinition(dialect).renderThinking(text)}\n`;
+}

package/src/dialect/factory.ts

@@ -7,7 +7,6 @@ import harmonyDefinition from "./harmony";
 import hermesDefinition from "./hermes";
 import kimiDefinition from "./kimi";
 import minimaxDefinition from "./minimax";
-import piDefinition from "./pi";
 import qwen3Definition from "./qwen3";
 import type { Dialect, DialectDefinition, InbandScanner, InbandScannerOptions } from "./types";
 import xmlDefinition from "./xml";
@@ -21,7 +20,6 @@ const DIALECT_DEFINITIONS: Record<Dialect, DialectDefinition> = {
 	deepseek: deepseekDefinition,
 	minimax: minimaxDefinition,
 	harmony: harmonyDefinition,
-	pi: piDefinition,
 	qwen3: qwen3Definition,
 	gemini: geminiDefinition,
 	gemma: gemmaDefinition,

package/src/dialect/index.ts

@@ -1,5 +1,6 @@
 export * from "./catalog";
 export * from "./coercion";
+export * from "./demotion";
 export * from "./examples";
 export * from "./factory";
 export * from "./history";
@@ -10,4 +11,5 @@ export * from "./owned-stream";
 // consumer needs (the legacy markdown `/dump` reuses its `<thinking>` envelope
 // unwrap), so re-export only that symbol rather than `export *`-ing the rest.
 export { renderDelimitedThinking } from "./rendering";
+export * from "./thinking";
 export * from "./types";

package/src/dialect/owned-stream.ts

@@ -19,7 +19,6 @@ const RESPONSE_OPEN_TOKENS: Record<Dialect, readonly string[]> = {
 	minimax: ["<function_results>", "<tool_response>"],
 	deepseek: ["<｜tool▁outputs▁begin｜>", "<｜tool▁output▁begin｜>"],
 	harmony: ["<|start|>functions."],
-	pi: ["‡‡"],
 	qwen3: ["<tool_response>"],
 	gemini: ["```tool_outputs"],
 	gemma: ["<|tool_response>"],

package/src/dialect/thinking.ts

@@ -1,18 +1,30 @@
 import { partialSuffixOverlapAny } from "./coercion";
 import type { InbandScanEvent, InbandScanner } from "./types";
 
-const THINK_OPEN = "<think>";
-const THINK_CLOSE = "</think>";
-const THINKING_OPEN = "<thinking>";
-const THINKING_CLOSE = "</thinking>";
-const TAGS = [
-	{ open: THINK_OPEN, close: THINK_CLOSE },
-	{ open: THINKING_OPEN, close: THINKING_CLOSE },
-] as const;
-const OPENS = [THINK_OPEN, THINKING_OPEN] as const;
-
 type Tag = { readonly open: string; readonly close: string };
 
+/**
+ * Every dialect's in-band thinking section in its canonical `renderThinking`
+ * form (see the sibling `./*.ts` scanners). {@link ThinkingInbandScanner} heals
+ * reasoning a model leaked into its visible text channel back into thinking
+ * events, whichever dialect idiom the leak used.
+ *
+ * Plain (attribute-free) delimiters only — matching what `renderThinking`
+ * emits and what models leak in practice. Attributed or namespaced XML thinking
+ * tags (`<thinking signature="…">`, `antml:thinking`) are recovered by the owned
+ * anthropic-dialect parser, not this text-channel healing fallback.
+ */
+const TAGS: readonly Tag[] = [
+	{ open: "<think>", close: "</think>" }, // deepseek, glm, hermes, kimi, qwen3 (and anthropic/minimax/xml)
+	{ open: "<thinking>", close: "</thinking>" }, // anthropic, minimax, xml
+	{ open: "<scratchpad>", close: "</scratchpad>" }, // anthropic
+	{ open: "```thinking\n", close: "```" }, // gemini fenced thinking
+	{ open: "<|channel>thought\n", close: "<channel|>" }, // gemma reasoning channel
+	{ open: "<|start|>assistant<|channel|>analysis<|message|>", close: "<|end|>" }, // harmony analysis (rendered)
+	{ open: "<|channel|>analysis<|message|>", close: "<|end|>" }, // harmony analysis (bare leak)
+];
+const OPENS = TAGS.map(tag => tag.open);
+
 export class ThinkingInbandScanner implements InbandScanner {
 	#buffer = "";
 	#closeTag = "";