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

package/src/error/auth.ts

@@ -0,0 +1,48 @@
+import { attach, create, Flag } from "./flags";
+
+/**
+ * No API key / credential was available to dispatch a request.
+ *
+ * The default message preserves the historical `"No API key for provider: X"`
+ * wording, which {@link Flag.AuthFailed}'s regex (`no api key`) keys off — but
+ * the flag is also attached structurally so classification never depends on the
+ * exact phrasing.
+ */
+export class MissingApiKeyError extends Error {
+	readonly provider: string | undefined;
+
+	constructor(provider?: string, message?: string) {
+		super(message ?? (provider ? `No API key for provider: ${provider}` : "No API key available"));
+		this.name = "MissingApiKeyError";
+		this.provider = provider;
+		attach(this, create(Flag.AuthFailed));
+	}
+}
+
+/** A user-facing login flow required an `onPrompt` callback that was not supplied. */
+export class OnPromptRequiredError extends Error {
+	constructor(providerLabel: string) {
+		super(`${providerLabel} login requires onPrompt callback`);
+		this.name = "OnPromptRequiredError";
+	}
+}
+
+/** An interactive login asked for an API key but the user supplied an empty value. */
+export class ApiKeyRequiredError extends Error {
+	constructor(message = "API key is required") {
+		super(message);
+		this.name = "ApiKeyRequiredError";
+	}
+}
+
+/**
+ * A user cancelled an interactive login / device flow. Classified as an abort
+ * so it is never surfaced as a retryable transient failure.
+ */
+export class LoginCancelledError extends Error {
+	constructor(message = "Login cancelled") {
+		super(message);
+		this.name = "LoginCancelledError";
+		attach(this, create(Flag.Abort));
+	}
+}

package/src/error/aws.ts

@@ -0,0 +1,31 @@
+/** Which AWS credential-resolution path failed. */
+export type AwsCredentialsErrorKind =
+	/** No usable credential source resolved (chain exhausted). */
+	| "resolution"
+	/** SSO cache token missing (`aws sso login` not run). */
+	| "sso-token-missing"
+	/** SSO cache token present but expired. */
+	| "sso-token-expired"
+	/** SSO `GetRoleCredentials` call failed or returned no role. */
+	| "sso-role"
+	/** External `credential_process` failed, timed out, or emitted bad output. */
+	| "credential-process";
+
+/** A failure resolving AWS credentials for the Bedrock provider. */
+export class AwsCredentialsError extends Error {
+	readonly kind: AwsCredentialsErrorKind;
+
+	constructor(message: string, kind: AwsCredentialsErrorKind, options?: { cause?: unknown }) {
+		super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "AwsCredentialsError";
+		this.kind = kind;
+	}
+}
+
+/** A malformed AWS event-stream frame (bad length, CRC mismatch, unknown header type). */
+export class EventStreamFrameError extends Error {
+	constructor(detail: string) {
+		super(`eventstream: ${detail}`);
+		this.name = "EventStreamFrameError";
+	}
+}

package/src/error/classes.ts

@@ -0,0 +1,186 @@
+import type { CapturedHttpErrorResponse } from "../utils/http-inspector";
+
+/** Prefix on errors raised when an Anthropic SSE stream envelope is malformed. */
+export const STREAM_ENVELOPE_ERROR_PREFIX = "Anthropic stream envelope error:";
+
+/** Structured HTTP errors thrown by provider clients. */
+export interface ProviderHttpErrorOptions {
+	/** Response headers; enables `retry-after`/rate-limit extraction downstream. */
+	headers?: Headers;
+	/** Machine-readable error code from the response body (`error.code` / `error.type`). */
+	code?: string;
+	cause?: unknown;
+}
+
+/** Non-2xx HTTP response from a provider. */
+export class ProviderHttpError extends Error {
+	readonly status: number;
+	readonly headers: Headers | undefined;
+	readonly code: string | undefined;
+
+	constructor(message: string, status: number, options?: ProviderHttpErrorOptions) {
+		super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "ProviderHttpError";
+		this.status = status;
+		this.headers = options?.headers;
+		this.code = options?.code;
+	}
+}
+
+/** Non-2xx response from an OpenAI-wire endpoint, with the decoded body attached. */
+export class OpenAIHttpError extends ProviderHttpError {
+	readonly captured: CapturedHttpErrorResponse;
+
+	constructor(message: string, captured: CapturedHttpErrorResponse, code?: string, cause?: unknown) {
+		super(message, captured.status, { headers: captured.headers, code, cause });
+		this.name = "OpenAIHttpError";
+		this.captured = captured;
+	}
+
+	/**
+	 * Pull a human-readable message and machine code out of an OpenAI-style error
+	 * envelope (`{ error: { message, code, type } }`), tolerating the flat shapes
+	 * compat hosts return (`{ error: "..." }`, `{ message: "..." }`) and falling
+	 * back to the raw body text.
+	 */
+	static parseEnvelope(
+		bodyJson: unknown,
+		bodyText: string | undefined,
+	): { detail: string | undefined; code: string | undefined } {
+		if (typeof bodyJson === "object" && bodyJson !== null) {
+			const envelope = bodyJson as { error?: unknown; message?: unknown };
+			const error = envelope.error;
+			if (typeof error === "object" && error !== null) {
+				const { message, code, type } = error as { message?: unknown; code?: unknown; type?: unknown };
+				return {
+					detail: typeof message === "string" && message.length > 0 ? message : bodyText,
+					code: typeof code === "string" ? code : typeof type === "string" ? type : undefined,
+				};
+			}
+			if (typeof error === "string" && error.length > 0) {
+				return { detail: error, code: undefined };
+			}
+			if (typeof envelope.message === "string" && envelope.message.length > 0) {
+				return { detail: envelope.message, code: undefined };
+			}
+		}
+		return { detail: bodyText, code: undefined };
+	}
+}
+
+/** Non-2xx response from the Anthropic API. */
+export class AnthropicApiError extends ProviderHttpError {
+	declare readonly headers: Headers;
+	readonly requestId: string | null;
+
+	constructor(status: number, message: string, headers: Headers) {
+		super(message, status, { headers });
+		this.name = "AnthropicApiError";
+		this.requestId = headers.get("request-id");
+	}
+
+	static async fromResponse(response: Response): Promise<AnthropicApiError> {
+		const body = await response.text().catch(() => "");
+		const detail = body.trim() || "status code (no body)";
+		return new AnthropicApiError(response.status, `${response.status} ${detail}`, response.headers);
+	}
+}
+
+/** Network-level failure (DNS, TLS, socket reset) after retries were exhausted. */
+export class AnthropicConnectionError extends Error {
+	constructor(cause: unknown) {
+		super("Connection error.", { cause });
+		this.name = "AnthropicConnectionError";
+	}
+}
+
+/** No response headers arrived within the configured request timeout. */
+export class AnthropicConnectionTimeoutError extends Error {
+	constructor() {
+		super("Request timed out.");
+		this.name = "AnthropicConnectionTimeoutError";
+	}
+}
+
+/**
+ * A malformed Anthropic SSE stream envelope — events arriving out of order
+ * (before `message_start`) or otherwise violating the message-event grammar.
+ * The message is prefixed with {@link STREAM_ENVELOPE_ERROR_PREFIX} so the
+ * shared envelope predicates classify it.
+ */
+export class AnthropicStreamEnvelopeError extends Error {
+	constructor(detail: string) {
+		super(`${STREAM_ENVELOPE_ERROR_PREFIX} ${detail}`);
+		this.name = "AnthropicStreamEnvelopeError";
+	}
+}
+
+/** Non-2xx response (or in-stream exception event) from the Bedrock runtime API. */
+export class BedrockApiError extends ProviderHttpError {
+	override readonly name = "BedrockApiError";
+}
+
+/** Non-2xx response (or in-stream error chunk) from the Cloud Code Assist API. */
+export class GeminiCliApiError extends ProviderHttpError {
+	override readonly name = "GeminiCliApiError";
+}
+
+/** Non-2xx response (or in-stream error chunk) from the Google Generative Language / Vertex API. */
+export class GoogleApiError extends ProviderHttpError {
+	override readonly name = "GoogleApiError";
+}
+
+/** Non-2xx response from the Ollama `/api/chat` endpoint. */
+export class OllamaApiError extends ProviderHttpError {
+	override readonly name = "OllamaApiError";
+}
+
+/** Auth gateway HTTP failure. */
+export class AuthGatewayError extends ProviderHttpError {
+	constructor(message: string, status: number, headers?: Headers, code?: string) {
+		super(message, status, { headers, code });
+		this.name = "AuthGatewayError";
+	}
+}
+
+export class CodexWebSocketTransportError extends Error {
+	constructor(detail: string) {
+		super(`Codex websocket transport failure: ${detail}`);
+		this.name = "CodexWebSocketTransportError";
+	}
+}
+
+export class CodexWhitespaceToolCallLoopError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CodexWhitespaceToolCallLoopError";
+	}
+}
+
+export class CodexProviderStreamError extends Error {
+	readonly retryable: boolean;
+
+	constructor(message: string, options?: { retryable?: boolean; cause?: unknown }) {
+		super(message, { cause: options?.cause });
+		this.name = "CodexProviderStreamError";
+		this.retryable = options?.retryable !== false;
+	}
+}
+
+export class AuthBrokerError extends Error {
+	readonly status: number | undefined;
+	readonly body: string | undefined;
+	constructor(message: string, opts: { status?: number; body?: string; cause?: unknown } = {}) {
+		super(message, { cause: opts.cause });
+		this.name = "AuthBrokerError";
+		this.status = opts.status;
+		this.body = opts.body;
+	}
+}
+
+export class AuthBrokerStreamUnsupportedError extends AuthBrokerError {
+	constructor(message = "Auth broker does not support /v1/snapshot/stream") {
+		super(message, { status: 404 });
+		this.name = "AuthBrokerStreamUnsupportedError";
+	}
+}

package/src/error/finalize.ts

@@ -0,0 +1,69 @@
+import type { Api } from "../types";
+import type { AbortSourceTracker } from "../utils/abort";
+import type { CapturedHttpErrorResponse, RawHttpRequestDump } from "../utils/http-inspector";
+import { classify, classifyMessage, status } from "./flags";
+import { formatMessage } from "./format";
+
+/** Context a provider catch block hands to {@link finalize}. */
+export interface FinalizeOptions {
+	/** Wire API, for api-specific text classification (e.g. stale-responses items). */
+	api?: Api;
+	/** Provider id; forwarded to the message formatter for copilot rewrites. */
+	provider?: string;
+	/** Caller signal, for providers that don't run an abort tracker. */
+	signal?: AbortSignal;
+	/** Abort tracker, preferred over `signal`: distinguishes caller vs. local aborts. */
+	abortTracker?: AbortSourceTracker;
+	/** Raw request, dumped into the message for 400-class failures. */
+	rawRequestDump?: RawHttpRequestDump;
+	/** Captured non-2xx response body, used for status fallback and message detail. */
+	capturedErrorResponse?: CapturedHttpErrorResponse;
+}
+
+/** The full bundle a provider assigns onto its `AssistantMessage` error fields. */
+export interface FinalizeResult {
+	/** Structured flag id from {@link classify}. */
+	id: number;
+	/** HTTP status, from the error or the captured response. */
+	status: number | undefined;
+	/** `"aborted"` when the caller cancelled, otherwise `"error"`. */
+	stopReason: "aborted" | "error";
+	/** User-facing message from {@link formatMessage}, or a local abort reason. */
+	message: string;
+}
+
+/**
+ * Build the complete error bundle for a provider catch block, replacing the
+ * `stopReason` / `errorStatus` / `errorId` / `errorMessage` boilerplate.
+ *
+ * `stopReason` comes from the abort tracker (caller intent dominates) or, when
+ * no tracker is supplied, the raw `signal.aborted`. A local abort reason (e.g. a
+ * first-event timeout) supersedes the formatted message. Message formatting is
+ * wrapped so a formatter throw can never skip the caller's `stream.end()`.
+ */
+export async function finalize(error: unknown, opts: FinalizeOptions = {}): Promise<FinalizeResult> {
+	const aborted = opts.abortTracker ? opts.abortTracker.wasCallerAbort() : opts.signal?.aborted === true;
+	const currentStatus = status(error) ?? opts.capturedErrorResponse?.status;
+
+	let message: string;
+	try {
+		const localReason = opts.abortTracker?.getLocalAbortReason();
+		message = localReason?.message ?? (await formatMessage(error, opts));
+	} catch {
+		message = error instanceof Error ? error.message : String(error);
+	}
+
+	const id = classifyMessage({
+		api: opts.api,
+		errorId: classify(error, opts.api),
+		errorMessage: message,
+		errorStatus: currentStatus,
+	});
+
+	return {
+		id,
+		status: currentStatus,
+		stopReason: aborted ? "aborted" : "error",
+		message,
+	};
+}