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

package/src/utils/openai-http.ts

@@ -15,7 +15,11 @@
  *   chain-state detectors, which regex over `error.message`.
  */
 import { fetchWithRetry, readSseJson, type SseEventObserver } from "@oh-my-pi/pi-utils";
-import { ProviderHttpError } from "../errors";
+import * as AIError from "../error";
+import { OpenAIHttpError } from "../error";
+
+export { OpenAIHttpError };
+
 import type { FetchImpl } from "../types";
 import type { CapturedHttpErrorResponse } from "./http-inspector";
 
@@ -28,17 +32,6 @@ const DEFAULT_MAX_ATTEMPTS = 6;
 /** Bound the `Error.message` allocation for proxy HTML error pages and the like. */
 const MAX_DETAIL_CHARS = 4096;
 
-/** 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 | undefined) {
-		super(message, captured.status, { headers: captured.headers, code });
-		this.name = "OpenAIHttpError";
-		this.captured = captured;
-	}
-}
-
 export interface OpenAIStreamRequestInit {
 	url: string;
 	headers: Record<string, string>;
@@ -88,7 +81,9 @@ export async function postOpenAIStream<TEvent>(init: OpenAIStreamRequestInit): P
 		throw await captureOpenAIHttpError(response);
 	}
 	if (!response.body) {
-		throw new Error(`OpenAI stream response has no body (status ${response.status})`);
+		throw new AIError.ProviderResponseError(`OpenAI stream response has no body (status ${response.status})`, {
+			kind: "envelope",
+		});
 	}
 	return {
 		events: readSseJson<TEvent>(response.body, init.signal, init.onSseEvent),
@@ -98,7 +93,7 @@ export async function postOpenAIStream<TEvent>(init: OpenAIStreamRequestInit): P
 }
 
 /** Decode a non-2xx response into an {@link OpenAIHttpError} without consuming it twice. */
-export async function captureOpenAIHttpError(response: Response): Promise<OpenAIHttpError> {
+export async function captureOpenAIHttpError(response: Response): Promise<AIError.OpenAIHttpError> {
 	let bodyText: string | undefined;
 	let bodyJson: unknown;
 	try {
@@ -117,41 +112,11 @@ export async function captureOpenAIHttpError(response: Response): Promise<OpenAI
 		bodyText,
 		bodyJson,
 	};
-	const { detail, code } = extractErrorDetail(bodyJson, bodyText);
+	const { detail, code } = OpenAIHttpError.parseEnvelope(bodyJson, bodyText);
 	// "status code (no body)" matches the SDK's former APIError phrasing;
 	// `finalizeErrorMessage` keys a repair path on that exact wording.
 	const message = detail
 		? `${response.status} ${detail.length > MAX_DETAIL_CHARS ? detail.slice(0, MAX_DETAIL_CHARS) : detail}`
 		: `${response.status} status code (no body)`;
-	return new OpenAIHttpError(message, captured, code);
-}
-
-/**
- * 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.
- */
-function extractErrorDetail(
-	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 };
+	return new AIError.OpenAIHttpError(message, captured, code);
 }

package/src/utils/parse-bind.ts

@@ -4,6 +4,8 @@
  * gateway used to silently allow empty hostnames; this fixes it).
  */
 
+import * as AIError from "../error";
+
 export interface ParsedBind {
 	hostname: string;
 	port: number;
@@ -11,11 +13,11 @@ export interface ParsedBind {
 
 function parsePort(raw: string, bind: string): number {
 	if (!/^\d+$/.test(raw)) {
-		throw new Error(`Invalid bind '${bind}'; port must be an integer.`);
+		throw new AIError.ConfigurationError(`Invalid bind '${bind}'; port must be an integer.`);
 	}
 	const port = Number.parseInt(raw, 10);
 	if (!Number.isFinite(port) || port < 0 || port > 65535) {
-		throw new Error(`Invalid bind '${bind}'; port out of range.`);
+		throw new AIError.ConfigurationError(`Invalid bind '${bind}'; port out of range.`);
 	}
 	return port;
 }
@@ -36,19 +38,19 @@ function parsePort(raw: string, bind: string): number {
 export function parseBind(raw: string): ParsedBind {
 	const trimmed = raw.trim();
 	if (trimmed.length === 0) {
-		throw new Error("Invalid bind; expected 'host:port' or 'port'.");
+		throw new AIError.ConfigurationError("Invalid bind; expected 'host:port' or 'port'.");
 	}
 	if (/^\d+$/.test(trimmed)) {
 		return { hostname: "127.0.0.1", port: parsePort(trimmed, raw) };
 	}
 	const lastColon = trimmed.lastIndexOf(":");
 	if (lastColon < 0) {
-		throw new Error(`Invalid bind '${raw}'; expected 'host:port' or 'port'.`);
+		throw new AIError.ConfigurationError(`Invalid bind '${raw}'; expected 'host:port' or 'port'.`);
 	}
 	const hostPart = trimmed.slice(0, lastColon);
 	const portPart = trimmed.slice(lastColon + 1);
 	if (hostPart.length === 0) {
-		throw new Error(`Invalid bind '${raw}'; host must not be empty.`);
+		throw new AIError.ConfigurationError(`Invalid bind '${raw}'; host must not be empty.`);
 	}
 	return { hostname: hostPart, port: parsePort(portPart, raw) };
 }

package/src/utils/proxy.ts

@@ -1,5 +1,6 @@
 import * as net from "node:net";
 import * as tls from "node:tls";
+import * as AIError from "../error";
 import type { FetchImpl } from "../types";
 
 /**
@@ -228,7 +229,7 @@ export async function connectProxiedSocket(proxyUrlStr: string, targetUrlStr: st
 					tlsSocket.once("error", reject);
 				} else {
 					rawSocket.destroy();
-					reject(new Error(`Proxy tunnel failed: ${firstLine}`));
+					reject(new AIError.ValidationError(`Proxy tunnel failed: ${firstLine}`));
 				}
 			}
 		};

package/src/utils/retry.ts

@@ -1,27 +1,11 @@
 import { scheduler } from "node:timers/promises";
-import { extractHttpStatusFromError, isRetryableError } from "@oh-my-pi/pi-utils";
+import { isRetryableError } from "@oh-my-pi/pi-utils";
+import { isCopilotTransientModelError, status } from "../error/flags";
 import { getHeadersFromError, getRetryAfterMsFromHeaders } from "./retry-after";
 
-/**
- * GitHub Copilot intermittently rejects preview models (gpt-5.3-codex,
- * gpt-5.4, gpt-5.4-mini, ...) with HTTP 400 `model_not_supported`, even
- * though the model is listed as enabled on the user's account via `/models`.
- *
- * Root cause: Copilot's request-routing backend is rolled out per OAuth
- * client. Our OAuth client id is shared with opencode; VS Code uses its own
- * client and sees full availability, so the same account may succeed in VS
- * Code and flap between 200/400 here. See opencode#13313 and copilot-cli#2597.
- *
- * Retrying the identical request 2-3 times almost always lands on a backend
- * that has the model, so we wrap the initial request with a short retry loop.
- */
-export function isCopilotTransientModelError(error: unknown): boolean {
-	if (extractHttpStatusFromError(error) !== 400) return false;
-	if (!error || typeof error !== "object") return false;
-	const info = error as { code?: unknown; error?: { code?: unknown } | null };
-	const code = typeof info.code === "string" ? info.code : info.error?.code;
-	return code === "model_not_supported";
-}
+// `isCopilotTransientModelError` now lives in the error module (its classifier
+// home). Re-exported here so existing `../utils/retry` importers keep working.
+export { isCopilotTransientModelError };
 
 const COPILOT_MODEL_RETRY_MAX_ATTEMPTS = 3;
 const COPILOT_MODEL_RETRY_BASE_DELAY_MS = 400;
@@ -57,8 +41,8 @@ export async function callWithCopilotModelRetry<T>(
 			if (attempt === COPILOT_MODEL_RETRY_MAX_ATTEMPTS - 1) break;
 			let delayMs = retryBaseDelayMs * (attempt + 1);
 			if (!transientModelError) {
-				const status = extractHttpStatusFromError(error);
-				if (status !== undefined) {
+				const errorStatus = status(error);
+				if (errorStatus !== undefined) {
 					// Status-bearing retryable errors (429/5xx) are only re-sent when
 					// the server told us when to come back — a blind fixed-delay retry
 					// of a rate limit just burns the remaining attempts. Status-less

package/src/utils/schema/normalize.ts

@@ -7,6 +7,7 @@
  * for each target.
  */
 import { logger } from "@oh-my-pi/pi-utils";
+import * as AIError from "../../error";
 import { dereferenceJsonSchema } from "./dereference";
 import { upgradeJsonSchemaTo202012 } from "./draft";
 import { areJsonValuesEqual, mergeCompatibleEnumSchemas, mergePropertySchemas } from "./equality";
@@ -1711,7 +1712,7 @@ export function enforceStrictSchema(
 	cache: WeakMap<Record<string, unknown>, Record<string, unknown>> = new WeakMap(),
 ): Record<string, unknown> {
 	if (!enter(schema)) {
-		throw new Error("Schema contains a circular object graph — cannot enforce strict mode");
+		throw new AIError.ValidationError("Schema contains a circular object graph — cannot enforce strict mode");
 	}
 	try {
 		const cached = cache.get(schema);
@@ -1857,7 +1858,7 @@ function enforceStrictSchemaBody(
 		!COMBINATOR_KEYS.some(key => Array.isArray(result[key])) &&
 		!isJsonObject(result.not)
 	) {
-		throw new Error("Schema node has no type, combinator, or $ref — cannot enforce strict mode");
+		throw new AIError.ValidationError("Schema node has no type, combinator, or $ref — cannot enforce strict mode");
 	}
 	return result;
 }

package/src/utils/thinking-loop.ts

@@ -10,11 +10,9 @@
  *
  * This guard watches the streamed `thinking` deltas and, on a match, terminates
  * the stream with a synthetic `error` {@link AssistantMessage} that carries
- * **no observable content**. An empty-content `stopReason: "error"` whose
- * message hits the transient-transport pattern is what `AgentSession`
- * classifies as a *retryable* stop (a contentful error stop is treated as
- * replay-unsafe and is never retried), so the turn is discarded and re-sampled
- * instead of committing the garbage transcript.
+ * **no observable content**. An empty-content `stopReason: "error"` message tagged
+ * with `AIError.Flag.ThinkingLoop` lets result consumers and `AgentSession` discard
+ * the runaway and re-sample instead of committing garbage transcript.
  *
  * Three failure shapes are detected:
  * 1. **Verbatim tail repetition** — a short unit repeated back-to-back (e.g.
@@ -33,12 +31,13 @@
  *
  * Scope is narrow: guarded Gemini/DeepSeek streams before any tool call. Native
  * thinking is checked first; assistant text can also be checked for providers
- * that surface reasoning as visible prose. On a hit, the failed turn is emitted
- * as an empty retryable stream-stall error so the session drops and re-samples
- * it instead of committing the runaway transcript. Disable with
- * `PI_NO_THINKING_LOOP_GUARD=1`.
+ * that surface reasoning as visible prose. On a hit the failed turn is emitted as
+ * an empty retryable stream-stall error; result-awaiting callers (`complete`,
+ * `completeSimple`) re-sample it a few times and then let a stubborn loop cook
+ * through one unguarded pass. Disable detection with `PI_NO_THINKING_LOOP_GUARD=1`.
  */
 import { logger } from "@oh-my-pi/pi-utils";
+import * as AIError from "../error";
 import type { Api, AssistantMessage, Model, StreamOptions } from "../types";
 import { AssistantMessageEventStream } from "./event-stream";
 
@@ -403,7 +402,9 @@ export function guardThinkingLoopStream(
 						provider: model.provider,
 						detail,
 					});
-					controller.abort(new Error(THINKING_LOOP_ERROR_MARKER));
+					controller.abort(
+						AIError.attach(new Error(THINKING_LOOP_ERROR_MARKER), AIError.create(AIError.Flag.ThinkingLoop)),
+					);
 					outer.push({
 						type: "error",
 						reason: "error",
@@ -433,7 +434,9 @@ export function guardThinkingLoopStream(
  * Apply the loop guard around a provider dispatch. For non-guarded models
  * (or when disabled) this is a transparent pass-through. For guarded models it injects a
  * guard abort signal into the provider call so a detected loop tears down the
- * upstream, then wraps the returned stream.
+ * upstream, then wraps the returned stream. The guard only raises the retryable
+ * stall; bounding the re-samples and the final cook pass lives in the
+ * result-awaiting caller.
  */
 export function withGeminiThinkingLoopGuard<
 	O extends { signal?: AbortSignal; loopGuard?: { enabled?: boolean; checkAssistantContent?: boolean } },
@@ -474,6 +477,7 @@ function buildThinkingLoopError(model: Model<Api>, detail: string): AssistantMes
 		// "stream stall" makes the transport/session retry classifiers treat this
 		// as a transient (retryable) failure with no bespoke rule.
 		errorMessage: `${THINKING_LOOP_ERROR_MARKER}: the model repeated near-identical content (${detail}). Treating as a stream stall and retrying.`,
+		errorId: AIError.create(AIError.Flag.ThinkingLoop),
 		timestamp: Date.now(),
 	};
 }

package/src/utils/validation.ts

@@ -26,6 +26,7 @@ import { structuredCloneJSON } from "@oh-my-pi/pi-utils";
 import { type Type, type } from "arktype";
 import type { ZodType } from "zod/v4";
 import type { $ZodIssue as ZodIssue } from "zod/v4/core";
+import * as AIError from "../error";
 import type { Tool, ToolCall } from "../types";
 import { upgradeJsonSchemaTo202012 } from "./schema/draft";
 import {
@@ -1365,7 +1366,7 @@ const MAX_COERCION_PASSES = 5;
 export function validateToolCall(tools: Tool[], toolCall: ToolCall): ToolCall["arguments"] {
 	const tool = tools.find(t => t.name === toolCall.name);
 	if (!tool) {
-		throw new Error(`Tool "${toolCall.name}" not found`);
+		throw new AIError.ToolNotFoundError(toolCall.name);
 	}
 	return validateToolArguments(tool, toolCall);
 }
@@ -1405,7 +1406,7 @@ export function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall[
 			rawJson.length <= maxLen
 				? rawJson
 				: `${rawJson.slice(0, maxLen)}… [truncated ${rawJson.length - maxLen} chars]`;
-		throw new Error(
+		throw new AIError.ValidationError(
 			`Validation failed for tool "${toolCall.name}": Tool call arguments are not valid JSON.\nParse Error: ${parseError}\nRaw JSON:\n${truncatedRawJson}`,
 		);
 	}
@@ -1501,5 +1502,5 @@ export function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall[
 		toolCall.name
 	}":\n${errors}\n\nReceived arguments:\n${JSON.stringify(receivedArgs, null, 2)}`;
 
-	throw new Error(errorMessage);
+	throw new AIError.ValidationError(errorMessage);
 }

package/dist/types/dialect/pi.d.ts

@@ -1,9 +0,0 @@
-import type { DialectDefinition, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types";
-export declare class PiNativeInbandScanner implements InbandScanner {
-    #private;
-    constructor(options?: InbandScannerOptions);
-    feed(text: string): InbandScanEvent[];
-    flush(): InbandScanEvent[];
-}
-declare const definition: DialectDefinition;
-export default definition;

package/dist/types/errors.d.ts

@@ -1,24 +0,0 @@
-/**
- * Structured HTTP errors thrown by provider clients.
- *
- * Downstream classification reads these fields structurally rather than via
- * `instanceof`: `extractHttpStatusFromError` (pi-utils) reads `status`,
- * `getHeadersFromError` (retry-after extraction) reads `headers`, and retry
- * policies such as `isCopilotTransientModelError` read `code`. Per-provider
- * subclasses exist so call sites can narrow with `instanceof` and logs carry
- * a meaningful `error.name`.
- */
-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 endpoint. */
-export declare class ProviderHttpError extends Error {
-    readonly status: number;
-    readonly headers: Headers | undefined;
-    readonly code: string | undefined;
-    constructor(message: string, status: number, options?: ProviderHttpErrorOptions);
-}

package/dist/types/utils/overflow.d.ts

@@ -1,55 +0,0 @@
-import type { AssistantMessage } from "../types";
-/**
- * Check if an assistant message represents a context overflow error.
- *
- * This handles two cases:
- * 1. Error-based overflow: Most providers return stopReason "error" with a
- *    specific error message pattern.
- * 2. Silent overflow: Some providers accept overflow requests and return
- *    successfully. For these, we check if usage.input exceeds the context window.
- *
- * ## Reliability by Provider
- *
- * **Reliable detection (returns error with detectable message):**
- * - Anthropic: "prompt is too long: X tokens > Y maximum"
- * - OpenAI (Completions & Responses): "exceeds the context window"
- * - Google Gemini: "input token count exceeds the maximum"
- * - xAI (Grok): "maximum prompt length is X but request contains Y"
- * - Groq: "reduce the length of the messages"
- * - Cerebras: 400/413 status code (no body)
- * - Mistral: 400/413 status code (no body)
- * - HTTP 413 payload/entity-too-large variants
- * - OpenRouter (all backends): "maximum context length is X tokens"
- * - llama.cpp: "exceeds the available context size"
- * - LM Studio: "greater than the context length"
- * - Kimi For Coding: "exceeded model token limit: X (requested: Y)"
- * - Anthropic 413: "request_too_large" (request body exceeds size limit)
- * - HTTP 413: "Payload Too Large" / "Request Entity Too Large"
- * - Ollama OpenAI-compatible: "prompt filled the context window"
- *
- * **Unreliable detection:**
- * - z.ai: Sometimes accepts overflow silently (detectable via usage.input > contextWindow),
- *   sometimes returns rate limit errors. Pass contextWindow param to detect silent overflow.
- * - Ollama native: Silently truncates input without error. Cannot be detected via this function.
- *   The response will have usage.input < expected, but we don't know the expected value.
- *
- * ## Custom Providers
- *
- * If you've added custom models via settings.json, this function may not detect
- * overflow errors from those providers. To add support:
- *
- * 1. Send a request that exceeds the model's context window
- * 2. Check the errorMessage in the response
- * 3. Create a regex pattern that matches the error
- * 4. The pattern should be added to OVERFLOW_PATTERNS in this file, or
- *    check the errorMessage yourself before calling this function
- *
- * @param message - The assistant message to check
- * @param contextWindow - Optional context window size for detecting silent overflow (z.ai)
- * @returns true if the message indicates a context overflow
- */
-export declare function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean;
-/**
- * Get the overflow patterns for testing purposes.
- */
-export declare function getOverflowPatterns(): RegExp[];

package/src/dialect/pi.md

@@ -1,55 +0,0 @@
-## Format guide
-
-A tool call begins with `§` immediately followed by the function NAME (start each call on its own line). Scalar arguments follow on the same line as `key=value` pairs; a single large or multi-line string argument goes in a verbatim body fenced by `«…»` right after the header.
-
-Scalar-only call (the line ends the call):
-
-```text
-§read path=src/a.ts offset=50 limit=200
-```
-
-Call with a verbatim body — everything between `«` and `»` is taken literally, no quoting or escaping:
-
-```text
-§edit path=src/server/auth.ts«
-*** Begin Patch
-*** Update File: src/server/auth.ts
-@@ class AuthService
--  login(user) {
-+  async login(user, opts) {
-*** End Patch
-»
-```
-
-Argument values:
-
-- Strings are written bare and verbatim (`path=src/a.ts`). Quote with `"…"` only when the value contains spaces or starts with `"`, `[`, or `{` (`i="run the tests"`).
-- Numbers, booleans, and `null` are JSON literals (`offset=50`, `force=true`).
-- Arrays and objects are inline JSON (`paths=["src","test"]`).
-- The body fence holds the call's first long/multi-line string parameter; its key is implied, never written.
-
-Private reasoning goes in a `¤…¤` block before your calls:
-
-```text
-¤
-brief reasoning
-¤
-```
-
-Tool results arrive in `‡‡…‡‡` blocks, read in call order:
-
-```text
-‡‡
-verbatim tool result
-‡‡
-```
-
-## Rules
-
-- `NAME` MUST match a listed function; never wrap calls in JSON or fences.
-- Put each scalar argument once as `key=value`; reserve the `«…»` body for the one dominant string argument (file contents, patches, commands, queries).
-- Body text is verbatim — include no surrounding quotes. If the body itself contains `»`, widen BOTH guillemet fences equally (`««…»»`, `«««…»»»`).
-- Emit parallel calls as consecutive `§…` blocks. NEVER invent call ids; results are positional.
-- Private reasoning goes in a `¤…¤` block before your calls; NEVER put calls inside it, and keep a literal `¤` out of the reasoning text.
-- Read each `‡‡…‡‡` result in call order. NEVER emit a `‡‡` block yourself.
-- Emit the stop sequence ONLY after the call is fully written — NEVER announce a tool then stop (e.g. halting at "Let's run `cargo clippy`" with no `§` call emitted). Write the complete call, THEN the stop sequence, THEN halt.