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

package/src/registry/alibaba-coding-plan.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import * as apiKeyValidation from "./api-key-validation";
 import type { OAuthController, OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
@@ -10,7 +11,7 @@ const VALIDATION_MODEL = "qwen3.5-plus";
 
 export async function loginAlibabaCodingPlan(options: OAuthController): Promise<OAuthCredentials> {
 	if (!options.onPrompt) {
-		throw new Error("Alibaba Coding Plan login requires onPrompt callback");
+		throw new AIError.OnPromptRequiredError("Alibaba Coding Plan");
 	}
 
 	// Ask which endpoint to use
@@ -21,7 +22,7 @@ export async function loginAlibabaCodingPlan(options: OAuthController): Promise<
 
 	// Check for abort after endpoint selection (Escape returns "")
 	if (options.signal?.aborted) {
-		throw new Error("Login cancelled");
+		throw new AIError.LoginCancelledError();
 	}
 
 	const choice = endpointChoice.trim();
@@ -39,7 +40,7 @@ export async function loginAlibabaCodingPlan(options: OAuthController): Promise<
 		});
 		const trimmedUrl = customUrl.trim().replace(/\/+$/, "");
 		if (!trimmedUrl) {
-			throw new Error("Custom URL is required for option 3");
+			throw new AIError.ConfigurationError("Custom URL is required for option 3");
 		}
 		baseUrl = trimmedUrl;
 		authUrl = DEFAULT_AUTH_URL;
@@ -61,12 +62,12 @@ export async function loginAlibabaCodingPlan(options: OAuthController): Promise<
 	});
 
 	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();
 	}
 
 	options.onProgress?.("Validating API key...");

package/src/registry/api-key-login.ts

@@ -6,6 +6,7 @@
  * optionally validate it, and return the trimmed key.
  */
 
+import * as AIError from "../error";
 import {
 	validateAnthropicCompatibleApiKey,
 	validateApiKeyAgainstModelsEndpoint,
@@ -52,7 +53,7 @@ export type ApiKeyLoginConfig = {
 export function createApiKeyLogin(config: ApiKeyLoginConfig): (options: OAuthController) => Promise<string> {
 	return async function login(options: OAuthController): Promise<string> {
 		if (!options.onPrompt) {
-			throw new Error(`${config.providerLabel} login requires onPrompt callback`);
+			throw new AIError.OnPromptRequiredError(config.providerLabel);
 		}
 
 		options.onAuth?.({
@@ -66,12 +67,12 @@ export function createApiKeyLogin(config: ApiKeyLoginConfig): (options: OAuthCon
 		});
 
 		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();
 		}
 
 		if (config.validation) {

package/src/registry/api-key-validation.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { FetchImpl } from "../types";
 
 type OpenAICompatibleValidationOptions = {
@@ -78,7 +79,7 @@ export async function validateOpenAICompatibleApiKey(options: OpenAICompatibleVa
 	const message = details
 		? `${options.provider} API key validation failed (${response.status}): ${details}`
 		: `${options.provider} API key validation failed (${response.status})`;
-	throw new Error(message);
+	throw new AIError.ApiKeyRequiredError(message);
 }
 
 /**
@@ -119,7 +120,7 @@ export async function validateAnthropicCompatibleApiKey(options: AnthropicCompat
 	const message = details
 		? `${options.provider} API key validation failed (${response.status}): ${details}`
 		: `${options.provider} API key validation failed (${response.status})`;
-	throw new Error(message);
+	throw new AIError.ApiKeyRequiredError(message);
 }
 
 /**
@@ -156,5 +157,5 @@ export async function validateApiKeyAgainstModelsEndpoint(options: ModelListVali
 	const message = details
 		? `${options.provider} API key validation failed (${response.status}): ${details}`
 		: `${options.provider} API key validation failed (${response.status})`;
-	throw new Error(message);
+	throw new AIError.ApiKeyRequiredError(message);
 }

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

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
@@ -11,7 +12,7 @@ const AUTH_URL = "https://developers.cloudflare.com/ai-gateway/configuration/aut
  */
 export async function loginCloudflareAiGateway(options: OAuthController): Promise<string> {
 	if (!options.onPrompt) {
-		throw new Error("Cloudflare AI Gateway login requires onPrompt callback");
+		throw new AIError.OnPromptRequiredError("Cloudflare AI Gateway");
 	}
 
 	options.onAuth?.({
@@ -26,12 +27,12 @@ export async function loginCloudflareAiGateway(options: OAuthController): Promis
 	});
 
 	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/coreweave.ts

@@ -1,5 +1,6 @@
 import { coreWeaveProjectHeaders } from "@oh-my-pi/pi-catalog/wire/coreweave";
 import { $env } from "@oh-my-pi/pi-utils";
+import * as AIError from "../error";
 import { createApiKeyLogin } from "./api-key-login";
 import type { OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
@@ -10,7 +11,7 @@ const PROJECT_SETUP_INSTRUCTIONS =
 function requireCoreWeaveProjectHeaders(): Record<string, string> {
 	const headers = coreWeaveProjectHeaders($env);
 	if (!headers) {
-		throw new Error(
+		throw new AIError.ConfigurationError(
 			"CoreWeave Serverless Inference requires OpenAI-Project. Set COREWEAVE_PROJECT=<team>/<project> before running /login coreweave.",
 		);
 	}

package/src/registry/deepseek.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import { createApiKeyLogin } from "./api-key-login";
 import type { OAuthController, OAuthLoginCallbacks, OAuthPrompt } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
@@ -22,7 +23,7 @@ export function normalizeDeepSeekApiKey(raw: string): string {
 	}
 	const stripped = trimmed.replace(/^bearer\b\s*/i, "");
 	if (!stripped) {
-		throw new Error("DeepSeek API key is empty after stripping Bearer prefix");
+		throw new AIError.ApiKeyRequiredError("DeepSeek API key is empty after stripping Bearer prefix");
 	}
 	return stripped;
 }

package/src/registry/google-antigravity.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
@@ -11,7 +12,7 @@ export const googleAntigravityProvider = {
 	},
 	refreshToken: async (credentials: OAuthCredentials) => {
 		if (!credentials.projectId) {
-			throw new Error("Antigravity credentials missing projectId");
+			throw new AIError.ConfigurationError("Antigravity credentials missing projectId");
 		}
 		const { refreshAntigravityToken } = await import("./oauth/google-antigravity");
 		return refreshAntigravityToken(credentials.refresh, credentials.projectId);

package/src/registry/google-gemini-cli.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
@@ -11,7 +12,7 @@ export const googleGeminiCliProvider = {
 	},
 	refreshToken: async (credentials: OAuthCredentials) => {
 		if (!credentials.projectId) {
-			throw new Error("Google Cloud credentials missing projectId");
+			throw new AIError.ConfigurationError("Google Cloud credentials missing projectId");
 		}
 		const { refreshGoogleCloudToken } = await import("./oauth/google-gemini-cli");
 		return refreshGoogleCloudToken(credentials.refresh, credentials.projectId);

package/src/registry/kagi.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
@@ -11,7 +12,7 @@ const AUTH_URL = "https://kagi.com/settings/api";
  */
 export async function loginKagi(options: OAuthController): Promise<string> {
 	if (!options.onPrompt) {
-		throw new Error("Kagi login requires onPrompt callback");
+		throw new AIError.OnPromptRequiredError("Kagi");
 	}
 
 	options.onAuth?.({
@@ -26,12 +27,12 @@ export async function loginKagi(options: OAuthController): Promise<string> {
 	});
 
 	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/kilo.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { OAuthController, OAuthCredentials } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
@@ -25,9 +26,17 @@ export async function loginKilo(callbacks: OAuthController): Promise<OAuthCreden
 
 	if (!initiateResponse.ok) {
 		if (initiateResponse.status === 429) {
-			throw new Error("Too many pending authorization requests. Please try again later.");
+			throw new AIError.OAuthError("Too many pending authorization requests. Please try again later.", {
+				kind: "polling",
+				provider: "kilo",
+				status: initiateResponse.status,
+			});
 		}
-		throw new Error(`Failed to initiate device authorization: ${initiateResponse.status}`);
+		throw new AIError.OAuthError(`Failed to initiate device authorization: ${initiateResponse.status}`, {
+			kind: "device-auth",
+			provider: "kilo",
+			status: initiateResponse.status,
+		});
 	}
 
 	const initiateData = (await initiateResponse.json()) as KiloDeviceAuthCodeResponse;
@@ -35,7 +44,10 @@ export async function loginKilo(callbacks: OAuthController): Promise<OAuthCreden
 	const verificationUrl = initiateData.verificationUrl;
 	const expiresInSeconds = initiateData.expiresIn;
 	if (!userCode || !verificationUrl || typeof expiresInSeconds !== "number" || expiresInSeconds <= 0) {
-		throw new Error("Kilo device authorization response missing required fields");
+		throw new AIError.OAuthError("Kilo device authorization response missing required fields", {
+			kind: "validation",
+			provider: "kilo",
+		});
 	}
 
 	callbacks.onAuth?.({
@@ -46,7 +58,7 @@ export async function loginKilo(callbacks: OAuthController): Promise<OAuthCreden
 	const deadline = Date.now() + expiresInSeconds * 1000;
 	while (Date.now() < deadline) {
 		if (callbacks.signal?.aborted) {
-			throw new Error("Login cancelled");
+			throw new AIError.LoginCancelledError();
 		}
 
 		const pollResponse = await fetchImpl(`${KILO_DEVICE_AUTH_BASE_URL}/codes/${encodeURIComponent(userCode)}`);
@@ -55,13 +67,20 @@ export async function loginKilo(callbacks: OAuthController): Promise<OAuthCreden
 			continue;
 		}
 		if (pollResponse.status === 403) {
-			throw new Error("Authorization was denied");
+			throw new AIError.OAuthError("Authorization was denied", { kind: "device-auth", provider: "kilo" });
 		}
 		if (pollResponse.status === 410) {
-			throw new Error("Authorization code expired. Please try again.");
+			throw new AIError.OAuthError("Authorization code expired. Please try again.", {
+				kind: "device-auth",
+				provider: "kilo",
+			});
 		}
 		if (!pollResponse.ok) {
-			throw new Error(`Failed to poll device authorization: ${pollResponse.status}`);
+			throw new AIError.OAuthError(`Failed to poll device authorization: ${pollResponse.status}`, {
+				kind: "polling",
+				provider: "kilo",
+				status: pollResponse.status,
+			});
 		}
 
 		const pollData = (await pollResponse.json()) as KiloDeviceAuthPollResponse;
@@ -73,16 +92,19 @@ export async function loginKilo(callbacks: OAuthController): Promise<OAuthCreden
 			};
 		}
 		if (pollData.status === "denied") {
-			throw new Error("Authorization was denied");
+			throw new AIError.OAuthError("Authorization was denied", { kind: "device-auth", provider: "kilo" });
 		}
 		if (pollData.status === "expired") {
-			throw new Error("Authorization code expired. Please try again.");
+			throw new AIError.OAuthError("Authorization code expired. Please try again.", {
+				kind: "device-auth",
+				provider: "kilo",
+			});
 		}
 
 		await Bun.sleep(POLL_INTERVAL_MS);
 	}
 
-	throw new Error("Authentication timed out. Please try again.");
+	throw new AIError.OAuthError("Authentication timed out. Please try again.", { kind: "timeout", provider: "kilo" });
 }
 
 export const kiloProvider = {

package/src/registry/litellm.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
@@ -11,7 +12,7 @@ const AUTH_URL = "https://docs.litellm.ai/docs/proxy/deploy";
  */
 export async function loginLiteLLM(options: OAuthController): Promise<string> {
 	if (!options.onPrompt) {
-		throw new Error("LiteLLM login requires onPrompt callback");
+		throw new AIError.OnPromptRequiredError("LiteLLM");
 	}
 
 	options.onAuth?.({
@@ -26,12 +27,12 @@ export async function loginLiteLLM(options: OAuthController): Promise<string> {
 	});
 
 	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/llama-cpp.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
@@ -8,7 +9,7 @@ const DEFAULT_LOCAL_TOKEN = "llama-cpp-local";
 
 export async function loginLlamaCpp(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 loginLlamaCpp(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/registry/lm-studio.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
@@ -6,7 +7,7 @@ export const DEFAULT_LOCAL_TOKEN = "lm-studio-local";
 
 export async function loginLmStudio(options: OAuthController): Promise<string> {
 	if (!options.onPrompt) {
-		throw new Error(`${PROVIDER_ID} login requires onPrompt callback`);
+		throw new AIError.OnPromptRequiredError(PROVIDER_ID);
 	}
 
 	const apiKey = await options.onPrompt({
@@ -16,7 +17,7 @@ export async function loginLmStudio(options: OAuthController): Promise<string> {
 	});
 
 	if (options.signal?.aborted) {
-		throw new Error("Login cancelled");
+		throw new AIError.LoginCancelledError();
 	}
 
 	const trimmed = apiKey.trim();

package/src/registry/nvidia.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../error";
 import { validateOpenAICompatibleApiKey } from "./api-key-validation";
 import type { OAuthController, OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
@@ -9,7 +10,7 @@ const PROVIDER_ID = "nvidia";
 
 export async function loginNvidia(options: OAuthController): Promise<string> {
 	if (!options.onPrompt) {
-		throw new Error("NVIDIA login requires onPrompt callback");
+		throw new AIError.OnPromptRequiredError("NVIDIA");
 	}
 
 	options.onAuth?.({
@@ -23,12 +24,12 @@ export async function loginNvidia(options: OAuthController): Promise<string> {
 	});
 
 	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();
 	}
 
 	options.onProgress?.("Validating API key (optional)...");
@@ -42,10 +43,9 @@ export async function loginNvidia(options: OAuthController): Promise<string> {
 			fetch: options.fetch,
 		});
 	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		const statusMatch = message.match(/\((\d{3})\)/);
-		const statusCode = statusMatch?.[1];
-		if (statusCode === "401" || statusCode === "403") {
+		// A real auth rejection (401/403) is fatal; any other validation-endpoint
+		// failure is non-fatal — skip validation and trust the supplied key.
+		if (AIError.is(AIError.classify(error), AIError.Flag.AuthFailed)) {
 			throw error;
 		}
 		options.onProgress?.("Skipping NVIDIA validation endpoint; continuing with provided API key.");

package/src/registry/oauth/anthropic.ts

@@ -2,6 +2,7 @@
  * Anthropic OAuth flow (Claude Pro/Max)
  */
 
+import * as AIError from "../../error";
 import { claudeCodeVersion } from "../../providers/anthropic";
 import type { FetchImpl } from "../../types";
 import { OAuthCallbackFlow } from "./callback-server";
@@ -59,7 +60,10 @@ async function postJson(
 
 	const responseBody = await response.text();
 	if (!response.ok) {
-		throw new Error(`HTTP request failed. status=${response.status}; url=${url}; body=${responseBody}`);
+		throw new AIError.ProviderHttpError(
+			`HTTP request failed. status=${response.status}; url=${url}; body=${responseBody}`,
+			response.status,
+		);
 	}
 	return responseBody;
 }
@@ -88,8 +92,9 @@ function parseOAuthTokenResponse(responseBody: string, operation: string): Anthr
 	try {
 		return JSON.parse(responseBody) as AnthropicTokenResponse;
 	} catch (error) {
-		throw new Error(
+		throw new AIError.OAuthError(
 			`Anthropic ${operation} returned invalid JSON. url=${TOKEN_URL}; body=${responseBody}; details=${formatErrorDetails(error)}`,
+			{ kind: "validation", provider: "anthropic", cause: error },
 		);
 	}
 }
@@ -131,14 +136,18 @@ async function fetchBootstrapIdentity(
 	});
 	const responseBody = await response.text();
 	if (!response.ok) {
-		throw new Error(`HTTP request failed. status=${response.status}; url=${url}; body=${responseBody}`);
+		throw new AIError.ProviderHttpError(
+			`HTTP request failed. status=${response.status}; url=${url}; body=${responseBody}`,
+			response.status,
+		);
 	}
 	let data: AnthropicBootstrapResponse;
 	try {
 		data = JSON.parse(responseBody) as AnthropicBootstrapResponse;
 	} catch (error) {
-		throw new Error(
+		throw new AIError.OAuthError(
 			`Anthropic bootstrap returned invalid JSON. url=${url}; body=${responseBody}; details=${formatErrorDetails(error)}`,
+			{ kind: "validation", provider: "anthropic", cause: error },
 		);
 	}
 	const accountUuid = data.oauth_account?.account_uuid;
@@ -227,8 +236,9 @@ export class AnthropicOAuthFlow extends OAuthCallbackFlow {
 				this.#fetch,
 			);
 		} catch (error) {
-			throw new Error(
+			throw new AIError.OAuthError(
 				`Token exchange request failed. url=${TOKEN_URL}; redirect_uri=${redirectUri}; response_type=authorization_code; details=${formatErrorDetails(error)}`,
+				{ kind: "token-exchange", provider: "anthropic", cause: error },
 			);
 		}
 
@@ -278,7 +288,14 @@ export async function refreshAnthropicToken(
 			},
 		);
 	} catch (error) {
-		throw new Error(`Anthropic token refresh request failed. url=${TOKEN_URL}; details=${formatErrorDetails(error)}`);
+		throw new AIError.OAuthError(
+			`Anthropic token refresh request failed. url=${TOKEN_URL}; details=${formatErrorDetails(error)}`,
+			{
+				kind: "token-refresh",
+				provider: "anthropic",
+				cause: error,
+			},
+		);
 	}
 
 	const data = parseOAuthTokenResponse(responseBody, "token refresh");

package/src/registry/oauth/callback-server.ts

@@ -10,6 +10,7 @@
  * - generateAuthUrl(): Build provider-specific authorization URL
  * - exchangeToken(): Exchange authorization code for tokens
  */
+import * as AIError from "../../error";
 import templateHtml from "./oauth.html" with { type: "text" };
 import type { OAuthController, OAuthCredentials } from "./types";
 
@@ -127,7 +128,7 @@ export abstract class OAuthCallbackFlow {
 			return { server, redirectUri };
 		} catch {
 			if (this.redirectUri) {
-				throw new Error(
+				throw new AIError.ConfigurationError(
 					`OAuth callback port ${this.preferredPort} unavailable; cannot fall back to a random port when oauth.redirectUri is set`,
 				);
 			}
@@ -143,8 +144,9 @@ export abstract class OAuthCallbackFlow {
 	 * Create HTTP server for OAuth callback.
 	 */
 	#createServer(port: number, expectedState: string): Bun.Server<unknown> {
+		const hostname = this.callbackHostname === DEFAULT_HOSTNAME ? undefined : this.callbackHostname;
 		return Bun.serve({
-			hostname: this.callbackHostname,
+			...(hostname === undefined ? {} : { hostname }),
 			port,
 			reusePort: false,
 			fetch: req => this.#handleCallback(req, expectedState),
@@ -214,7 +216,7 @@ export abstract class OAuthCallbackFlow {
 			signal.addEventListener("abort", () => {
 				this.#callbackResolve = undefined;
 				this.#callbackReject = undefined;
-				reject(new Error(`OAuth callback cancelled: ${signal.reason}`));
+				reject(new AIError.LoginCancelledError(`OAuth callback cancelled: ${signal.reason}`));
 			});
 		});
 

package/src/registry/oauth/cursor.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../../error";
 import { generatePKCE } from "./pkce";
 import type { OAuthCredentials } from "./types";
 
@@ -63,16 +64,26 @@ export async function pollCursorAuth(
 				};
 			}
 
-			throw new Error(`Poll failed: ${response.status}`);
+			throw new AIError.OAuthError(`Poll failed: ${response.status}`, {
+				kind: "polling",
+				provider: "cursor",
+				status: response.status,
+			});
 		} catch {
 			consecutiveErrors++;
 			if (consecutiveErrors >= 3) {
-				throw new Error("Too many consecutive errors during Cursor auth polling");
+				throw new AIError.OAuthError("Too many consecutive errors during Cursor auth polling", {
+					kind: "polling",
+					provider: "cursor",
+				});
 			}
 		}
 	}
 
-	throw new Error("Cursor authentication polling timeout");
+	throw new AIError.OAuthError("Cursor authentication polling timeout", {
+		kind: "timeout",
+		provider: "cursor",
+	});
 }
 
 export async function loginCursor(
@@ -107,7 +118,10 @@ export async function refreshCursorToken(apiKeyOrRefreshToken: string): Promise<
 
 	if (!response.ok) {
 		const error = await response.text();
-		throw new Error(`Cursor token refresh failed: ${error}`);
+		throw new AIError.OAuthError(`Cursor token refresh failed: ${error}`, {
+			kind: "token-refresh",
+			provider: "cursor",
+		});
 	}
 
 	const data = (await response.json()) as {

package/src/registry/oauth/devin.ts

@@ -1,3 +1,4 @@
+import * as AIError from "../../error";
 import { OAuthCallbackFlow } from "./callback-server";
 import { generatePKCE } from "./pkce";
 import type { OAuthController, OAuthCredentials } from "./types";
@@ -54,7 +55,10 @@ class DevinOAuthFlow extends OAuthCallbackFlow {
 
 	async exchangeToken(code: string): Promise<OAuthCredentials> {
 		if (!this.#pkce) {
-			throw new Error("Devin PKCE verifier was not initialized");
+			throw new AIError.OAuthError("Devin PKCE verifier was not initialized", {
+				kind: "configuration",
+				provider: "devin",
+			});
 		}
 		const token = await exchangeDevinCliToken(code, this.#pkce.verifier, this.ctrl.fetch);
 
@@ -87,12 +91,19 @@ export async function exchangeDevinCliToken(
 
 	if (!response.ok) {
 		const error = await response.text();
-		throw new Error(`Devin CLI token exchange failed: ${response.status} ${error}`.trim());
+		throw new AIError.OAuthError(`Devin CLI token exchange failed: ${response.status} ${error}`.trim(), {
+			kind: "token-exchange",
+			provider: "devin",
+			status: response.status,
+		});
 	}
 
 	const data = (await response.json()) as { token?: unknown };
 	if (typeof data.token !== "string" || data.token.length === 0) {
-		throw new Error("Devin CLI token exchange returned an empty token");
+		throw new AIError.OAuthError("Devin CLI token exchange returned an empty token", {
+			kind: "validation",
+			provider: "devin",
+		});
 	}
 	return data.token;
 }