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

package/src/providers/gitlab-duo-workflow.ts

@@ -4,6 +4,7 @@ import {
 	discoverGitLabDuoWorkflowRuntimeNamespace,
 	type GitLabDuoWorkflowNamespaceSelection,
 } from "@oh-my-pi/pi-catalog/discovery/gitlab-duo-workflow";
+import * as AIError from "../error";
 import type {
 	Api,
 	AssistantMessage,
@@ -109,7 +110,7 @@ const GITLAB_DUO_WORKFLOW_GOAL_SOFT_OVERFLOW_BYTES = 1_048_576;
 const GITLAB_DUO_WORKFLOW_GOAL_HARD_OVERFLOW_BYTES = 2_000_000;
 
 // An overflow-pattern message for an oversized goal. The "prompt is too long" prefix
-// is one of the shared `OVERFLOW_PATTERNS` (packages/ai/src/utils/overflow.ts), so
+// is one of the shared overflow classifier patterns, so
 // `isContextOverflow` recognizes it and the session triggers auto-compaction instead
 // of surfacing a hard failure. Byte counts (not tokens) are reported because the
 // budget is a byte budget.
@@ -953,7 +954,7 @@ async function runGitLabDuoWorkflow(
 	state: GitLabDuoWorkflowStreamState,
 ): Promise<void> {
 	const apiKey = options.apiKey;
-	if (!apiKey) throw new Error("No API key for provider: gitlab-duo-agent");
+	if (!apiKey) throw new AIError.MissingApiKeyError("gitlab-duo-agent");
 	const baseUrl = normalizeGitLabBaseUrl(model.baseUrl || DEFAULT_GITLAB_BASE_URL);
 	const fetchImpl = options.fetch ?? fetch;
 	const providerSessionState = getGitLabDuoWorkflowProviderSessionState(
@@ -1604,16 +1605,20 @@ async function requestGitLabDuoWorkflowDirectAccess(
 		// when the assistant error exposes `errorStatus` or the message embeds an
 		// `HTTP <status>` token. A 401 `{"message":"Unauthorized"}` or a 429 quota
 		// body would otherwise surface as a hard failure with no recoverable status.
-		throw new Error(
+		throw new AIError.GitLabDuoWorkflowApiError(
 			message
 				? `GitLab Duo Workflow direct_access failed with HTTP ${response.status}: ${message}`
 				: `GitLab Duo Workflow direct_access failed with HTTP ${response.status}`,
+			response.status,
 		);
 	}
 	const payload = (await response.json()) as GitLabDirectAccessResponse;
 	const token = extractGitLabWorkflowToken(payload);
 	if (!token) {
-		throw new Error("GitLab Duo Workflow direct_access did not return credentials");
+		throw new AIError.ProviderResponseError("GitLab Duo Workflow direct_access did not return credentials", {
+			provider: "gitlab-duo-agent",
+			kind: "empty-body",
+		});
 	}
 	traceGitLabDuoWorkflow("direct_access.token", { hasToken: true });
 	const serviceEndpoint = !payload.gitlab_rails?.token && Boolean(payload.duo_workflow_service?.base_url);
@@ -1658,12 +1663,18 @@ async function createGitLabDuoWorkflow(
 		hasProjectId: Boolean(projectId),
 	});
 	if (!response.ok) {
-		throw new Error(`GitLab Duo Workflow create failed with HTTP ${response.status}`);
+		throw new AIError.GitLabDuoWorkflowApiError(
+			`GitLab Duo Workflow create failed with HTTP ${response.status}`,
+			response.status,
+		);
 	}
 	const payload = (await response.json()) as GitLabCreateWorkflowResponse;
 	const workflowId = payload.id ?? payload.workflow_id ?? payload.workflowId;
 	if (workflowId === undefined) {
-		throw new Error(`GitLab Duo Workflow create response missing workflow id (HTTP ${response.status})`);
+		throw new AIError.ProviderResponseError(
+			`GitLab Duo Workflow create response missing workflow id (HTTP ${response.status})`,
+			{ provider: "gitlab-duo-agent", kind: "empty-body" },
+		);
 	}
 	traceGitLabDuoWorkflow("workflow.create.id", { workflowId });
 	return String(workflowId);
@@ -1815,7 +1826,7 @@ export function runGitLabDuoWorkflowSocket(
 	};
 	const abort = (): void => {
 		close();
-		settle("closed", new Error("GitLab Duo Workflow request aborted"));
+		settle("closed", new AIError.AbortError("GitLab Duo Workflow request aborted"));
 	};
 	if (options.signal?.aborted) {
 		abort();
@@ -1856,7 +1867,13 @@ export function runGitLabDuoWorkflowSocket(
 	ws.onerror = event => {
 		const detail = describeGitLabDuoWorkflowSocketEvent(event);
 		traceGitLabDuoWorkflow("websocket.error", { event: detail });
-		settle("closed", new Error(`GitLab Duo Workflow WebSocket error: ${detail}`));
+		settle(
+			"closed",
+			new AIError.ProviderResponseError(`GitLab Duo Workflow WebSocket error: ${detail}`, {
+				provider: "gitlab-duo-agent",
+				kind: "runtime",
+			}),
+		);
 	};
 	ws.onclose = event => {
 		traceGitLabDuoWorkflow("websocket.close", { code: event.code, reason: event.reason });
@@ -2775,7 +2792,10 @@ export async function resolveGitLabDuoWorkflowNamespaceSelection(
 			cwd: options.cwd,
 		});
 	} catch (error) {
-		throw new Error(`GitLab Duo Workflow runtime namespace resolution failed: ${gitLabDuoWorkflowErrorText(error)}`);
+		throw new AIError.ProviderResponseError(
+			`GitLab Duo Workflow runtime namespace resolution failed: ${gitLabDuoWorkflowErrorText(error)}`,
+			{ provider: "gitlab-duo-agent", kind: "runtime" },
+		);
 	}
 }
 
@@ -3008,7 +3028,7 @@ function requireGitLabDuoWorkflowRequestID(
 	source: Record<string, unknown>,
 ): string {
 	if (requestID) return requestID;
-	throw new Error(
+	throw new AIError.ValidationError(
 		`GitLab Duo Workflow action "${actionName}" missing requestID (keys: ${Object.keys(source).slice(0, 20).join(", ")})`,
 	);
 }

package/src/providers/gitlab-duo.ts

@@ -1,4 +1,5 @@
 import { buildModel } from "@oh-my-pi/pi-catalog/build";
+import * as AIError from "../error";
 import { ANTHROPIC_THINKING, mapAnthropicToolChoice } from "../stream";
 import type { Api, Context, FetchImpl, Model, ModelSpec, SimpleStreamOptions } from "../types";
 import { AssistantMessageEventStream } from "../utils/event-stream";
@@ -198,17 +199,29 @@ async function getDirectAccessToken(
 	if (!response.ok) {
 		const detail = await response.text();
 		if (response.status === 403) {
-			throw new Error(`GitLab Duo access denied. Ensure Duo is enabled for this account. ${detail}`);
+			throw new AIError.ProviderResponseError(
+				`GitLab Duo access denied. Ensure Duo is enabled for this account. ${detail}`,
+				{ provider: "gitlab-duo", kind: "runtime" },
+			);
 		}
-		throw new Error(`Failed to get GitLab Duo direct access token: ${response.status} ${detail}`);
+		throw new AIError.GitLabDuoApiError(
+			`Failed to get GitLab Duo direct access token: ${response.status} ${detail}`,
+			response.status,
+		);
 	}
 
 	const payload = (await response.json()) as { token?: string; headers?: Record<string, string> };
 	if (!payload.token || typeof payload.token !== "string") {
-		throw new Error("GitLab Duo direct access response missing token");
+		throw new AIError.ProviderResponseError("GitLab Duo direct access response missing token", {
+			provider: "gitlab-duo",
+			kind: "envelope",
+		});
 	}
 	if (!payload.headers || typeof payload.headers !== "object") {
-		throw new Error("GitLab Duo direct access response missing headers");
+		throw new AIError.ProviderResponseError("GitLab Duo direct access response missing headers", {
+			provider: "gitlab-duo",
+			kind: "envelope",
+		});
 	}
 
 	const token: DirectAccessToken = {
@@ -239,12 +252,15 @@ export function streamGitLabDuo(
 		try {
 			const apiKey = typeof options?.apiKey === "string" ? options.apiKey : undefined;
 			if (!apiKey || !options) {
-				throw new Error("Missing GitLab access token. Run /login gitlab-duo or set GITLAB_TOKEN.");
+				throw new AIError.MissingApiKeyError(
+					undefined,
+					"Missing GitLab access token. Run /login gitlab-duo or set GITLAB_TOKEN.",
+				);
 			}
 
 			const mapping = getModelMapping(model.id);
 			if (!mapping) {
-				throw new Error(`Unsupported GitLab Duo model: ${model.id}`);
+				throw new AIError.ConfigurationError(`Unsupported GitLab Duo model: ${model.id}`);
 			}
 
 			const directAccess = await getDirectAccessToken(apiKey, options.fetch);

package/src/providers/google-auth.ts

@@ -16,6 +16,7 @@ import { Buffer } from "node:buffer";
 import * as os from "node:os";
 import * as path from "node:path";
 import { $envpos, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import * as AIError from "../error";
 import type { FetchImpl } from "../types";
 import { raceWithSignal } from "../utils/abort";
 
@@ -83,7 +84,7 @@ async function loadAdcCredentials(): Promise<{ source: string; creds: AdcFileCre
 	if (gacPath) {
 		const creds = await readJsonFile<AdcFileCredentials>(gacPath);
 		if (!creds) {
-			throw new Error(`GOOGLE_APPLICATION_CREDENTIALS points to a missing file: ${gacPath}`);
+			throw new AIError.ConfigurationError(`GOOGLE_APPLICATION_CREDENTIALS points to a missing file: ${gacPath}`);
 		}
 		return { source: `gac:${gacPath}`, creds };
 	}
@@ -103,7 +104,7 @@ function pemToPkcs8(pem: string): Uint8Array<ArrayBuffer> {
 		.replace(/-----BEGIN [^-]+-----/g, "")
 		.replace(/-----END [^-]+-----/g, "")
 		.replace(/\s+/g, "");
-	if (!body) throw new Error("Invalid PEM: empty body");
+	if (!body) throw new AIError.ConfigurationError("Invalid PEM: empty body");
 	return Uint8Array.fromBase64(body);
 }
 
@@ -193,7 +194,11 @@ async function postForToken(
 	});
 	if (!response.ok) {
 		const detail = await response.text().catch(() => "");
-		throw new Error(`Google OAuth token exchange failed (${response.status}): ${detail}`);
+		throw new AIError.OAuthError(`Google OAuth token exchange failed (${response.status}): ${detail}`, {
+			kind: "token-exchange",
+			provider: "google-vertex",
+			status: response.status,
+		});
 	}
 	return (await response.json()) as TokenResponse;
 }
@@ -239,7 +244,11 @@ async function resolveAccessTokenUncached(
 			);
 			if (!response.ok) {
 				const detail = await response.text().catch(() => "");
-				throw new Error(`Google Impersonation token exchange failed (${response.status}): ${detail}`);
+				throw new AIError.OAuthError(`Google Impersonation token exchange failed (${response.status}): ${detail}`, {
+					kind: "token-exchange",
+					provider: "google-vertex",
+					status: response.status,
+				});
 			}
 			const data = (await response.json()) as { accessToken: string; expireTime: string };
 			const expiresIn = Math.max(0, Math.floor((new Date(data.expireTime).getTime() - Date.now()) / 1000));
@@ -254,7 +263,8 @@ async function resolveAccessTokenUncached(
 	}
 	const metadata = await fetchMetadataToken(signal, fetchImpl);
 	if (metadata) return { source: "metadata", token: metadata };
-	throw new Error(
+	throw new AIError.MissingApiKeyError(
+		undefined,
 		"Vertex AI requires Application Default Credentials. Set GOOGLE_APPLICATION_CREDENTIALS, run `gcloud auth application-default login`, or run on a GCE/Cloud Run instance with a service account.",
 	);
 }

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

@@ -14,7 +14,7 @@ import {
 } from "@oh-my-pi/pi-catalog/wire/gemini-headers";
 import { extractHttpStatusFromError, fetchWithRetry, readSseJson } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
-import { ProviderHttpError } from "../errors";
+import * as AIError from "../error";
 import type {
 	Api,
 	AssistantMessage,
@@ -30,7 +30,7 @@ import type {
 import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { extractGoogleValidationUrl, formatGoogleValidationRequiredMessage } from "../utils/google-validation";
-import { appendRawHttpRequestDumpFor400, type RawHttpRequestDump } from "../utils/http-inspector";
+import type { RawHttpRequestDump } from "../utils/http-inspector";
 import { armPreResponseTimeout, getStreamFirstEventTimeoutMs } from "../utils/idle-iterator";
 // Refresh is the sole responsibility of AuthStorage (broker-aware, single-flighted);
 // the stream provider trusts the access token threaded through `options.apiKey`.
@@ -59,11 +59,6 @@ import {
  */
 export type { GoogleThinkingLevel };
 
-/** Non-2xx response (or in-stream error chunk) from the Cloud Code Assist API. */
-export class GeminiCliApiError extends ProviderHttpError {
-	override readonly name = "GeminiCliApiError";
-}
-
 function isPlanningLeakPrefix(text: string): boolean {
 	const trimmed = text.trimStart();
 	if (!trimmed.startsWith("{")) {
@@ -345,22 +340,6 @@ function shouldInjectAntigravitySystemInstruction(modelId: string): boolean {
 	return normalized.includes("claude") || normalized.includes("gemini-3");
 }
 
-/**
- * Extract a clean, user-friendly error message from Google API error response.
- * Parses JSON error responses and returns just the message field.
- */
-function extractErrorMessage(errorText: string): string {
-	try {
-		const parsed = JSON.parse(errorText) as { error?: { message?: string } };
-		if (parsed.error?.message) {
-			return parsed.error.message;
-		}
-	} catch {
-		// Not JSON, return as-is
-	}
-	return errorText;
-}
-
 const optionalCredentialString = type("unknown").pipe(raw => {
 	const out = type("string")(raw);
 	return out instanceof type.errors ? undefined : out;
@@ -406,16 +385,16 @@ export function parseGeminiCliCredentials(apiKeyRaw: string): ParsedGeminiCliCre
 	try {
 		rawCredentials = JSON.parse(apiKeyRaw);
 	} catch {
-		throw new Error(invalidCredentialsMessage);
+		throw new AIError.ValidationError(invalidCredentialsMessage);
 	}
 	const parsed = geminiCliCredentialsSchema(rawCredentials);
 	if (parsed instanceof type.errors) {
-		throw new Error(invalidCredentialsMessage);
+		throw new AIError.ValidationError(invalidCredentialsMessage);
 	}
 
 	const projectId = parsed.projectId ?? parsed.project_id;
 	if (parsed.token === undefined || projectId === undefined) {
-		throw new Error(missingCredentialsMessage);
+		throw new AIError.ValidationError(missingCredentialsMessage);
 	}
 
 	const refreshToken = parsed.refreshToken ?? parsed.refresh;
@@ -517,7 +496,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 	const stream = new AssistantMessageEventStream();
 
 	(async () => {
-		const startTime = Date.now();
+		const startTime = performance.now();
 		let firstTokenTime: number | undefined;
 
 		const output: AssistantMessage = {
@@ -542,7 +521,9 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 		try {
 			const apiKeyRaw = options?.apiKey;
 			if (!apiKeyRaw) {
-				throw new Error("Google Cloud Code Assist requires OAuth authentication. Use /login to authenticate.");
+				throw new AIError.ConfigurationError(
+					"Google Cloud Code Assist requires OAuth authentication. Use /login to authenticate.",
+				);
 			}
 
 			const isAntigravity = model.provider === "google-antigravity";
@@ -558,8 +539,9 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 				parsedCredentials.expiresAt !== undefined &&
 				Date.now() >= parsedCredentials.expiresAt
 			) {
-				throw new Error(
+				throw new AIError.OAuthError(
 					"OAuth token expired before request — please retry; AuthStorage will refresh on the next attempt.",
+					{ kind: "token-refresh", provider: model.provider },
 				);
 			}
 			const baseUrl = model.baseUrl?.trim();
@@ -646,7 +628,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			let lastResponseId: string | undefined;
 			const ensureStarted = () => {
 				if (!started) {
-					if (!firstTokenTime) firstTokenTime = Date.now();
+					if (!firstTokenTime) firstTokenTime = performance.now();
 					stream.push({ type: "start", partial: output });
 					started = true;
 				}
@@ -670,7 +652,10 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 
 			const streamResponse = async (activeResponse: Response): Promise<boolean> => {
 				if (!activeResponse.body) {
-					throw new Error("No response body");
+					throw new AIError.ProviderResponseError("No response body", {
+						provider: model.provider,
+						kind: "empty-body",
+					});
 				}
 
 				// Scoped per attempt so a failed/empty retry cannot leak its
@@ -706,16 +691,17 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 						const detail = chunk.error.message || chunk.error.status || "unknown error";
 						const message = `Cloud Code Assist stream error: ${detail}`;
 						throw typeof chunk.error.code === "number" && chunk.error.code >= 400
-							? new GeminiCliApiError(message, chunk.error.code)
-							: new Error(message);
+							? new AIError.GeminiCliApiError(message, chunk.error.code)
+							: new AIError.ProviderResponseError(message, { provider: model.provider, kind: "runtime" });
 					}
 					const responseData = chunk.response;
 					if (!responseData) continue;
 					if (responseData.responseId) lastResponseId = responseData.responseId;
 					if (!responseData.candidates?.length && responseData.promptFeedback?.blockReason) {
 						const detail = responseData.promptFeedback.blockReasonMessage;
-						throw new Error(
+						throw new AIError.ProviderResponseError(
 							`Request blocked by Google (${responseData.promptFeedback.blockReason})${detail ? `: ${detail}` : ""}`,
+							{ provider: model.provider, kind: "content-blocked" },
 						);
 					}
 
@@ -908,7 +894,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 					}
 
 					if (!response.ok) {
-						if (response.status === 429 || (response.status >= 500 && response.status < 600)) {
+						if (AIError.isTransientStatus(response.status)) {
 							if (!isLastEndpoint) {
 								continue;
 							}
@@ -921,8 +907,8 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 									"retry your request",
 									parsedCredentials.email,
 								)
-							: extractErrorMessage(errorText);
-						throw new GeminiCliApiError(
+							: errorText;
+						throw new AIError.GeminiCliApiError(
 							`Cloud Code Assist API error (${response.status}): ${errorMessage}`,
 							response.status,
 							{ headers: response.headers },
@@ -934,7 +920,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 
 					for (let emptyAttempt = 0; emptyAttempt <= MAX_EMPTY_STREAM_RETRIES; emptyAttempt++) {
 						if (options?.signal?.aborted) {
-							throw new Error("Request was aborted");
+							throw new AIError.AbortError("Request was aborted");
 						}
 
 						if (emptyAttempt > 0) {
@@ -942,11 +928,11 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 							try {
 								await scheduler.wait(backoffMs, { signal: options?.signal });
 							} catch {
-								throw new Error("Request was aborted");
+								throw new AIError.AbortError("Request was aborted");
 							}
 
 							if (!requestUrl) {
-								throw new Error("Missing request URL");
+								throw new AIError.ConfigurationError("Missing request URL");
 							}
 
 							currentResponse = await (options?.fetch ?? fetch)(requestUrl, {
@@ -958,7 +944,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 
 							if (!currentResponse.ok) {
 								const retryErrorText = await currentResponse.text();
-								throw new GeminiCliApiError(
+								throw new AIError.GeminiCliApiError(
 									`Cloud Code Assist API error (${currentResponse.status}): ${retryErrorText}`,
 									currentResponse.status,
 									{ headers: currentResponse.headers },
@@ -978,16 +964,20 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 					}
 
 					if (!receivedContent) {
-						throw new Error("Cloud Code Assist API returned an empty response");
+						throw new AIError.ProviderResponseError("Cloud Code Assist API returned an empty response", {
+							provider: model.provider,
+							kind: "empty-body",
+						});
 					}
 
 					if (options?.signal?.aborted) {
-						throw new Error("Request was aborted");
+						throw new AIError.AbortError("Request was aborted");
 					}
 
 					if (!sawFinishReason) {
-						throw new Error(
+						throw new AIError.ProviderResponseError(
 							"Cloud Code Assist stream ended without a finish reason (connection dropped or response truncated)",
+							{ provider: model.provider, kind: "incomplete-stream" },
 						);
 					}
 
@@ -1007,7 +997,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 					break;
 				} catch (error) {
 					const status = extractHttpStatusFromError(error);
-					if (status === 429 || (status !== undefined && status >= 500 && status < 600)) {
+					if (AIError.isTransientStatus(status)) {
 						if (!isLastEndpoint && !started) {
 							continue;
 						}
@@ -1017,27 +1007,23 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			}
 
 			if (output.stopReason === "aborted" || output.stopReason === "error") {
-				throw new Error(output.errorMessage ?? "An unknown error occurred");
+				throw new AIError.ProviderResponseError(output.errorMessage ?? "An unknown error occurred", {
+					provider: model.provider,
+					kind: "output",
+				});
 			}
 
-			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) {
-				if ("index" in block) {
-					delete (block as { index?: number }).index;
-				}
-			}
-			output.stopReason = options?.signal?.aborted ? "aborted" : "error";
-			output.errorStatus = extractHttpStatusFromError(error);
-			output.errorMessage = await appendRawHttpRequestDumpFor400(
-				error instanceof Error ? error.message : JSON.stringify(error),
-				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;
+			output.duration = performance.now() - startTime;
 			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
 			stream.push({ type: "error", reason: output.stopReason, error: output });
 			stream.end();