@linxiraos/pi-ai 1.2.0 → 1.3.0

package/src/error/network-cause.ts

@@ -0,0 +1,179 @@
+/**
+ * Local transport diagnosis for a rejected `fetch`.
+ *
+ * Bun and Node describe the same outage with different shapes — Bun throws a
+ * `TypeError` carrying `code: "ETIMEOUT" | "FailedToOpenSocket" |
+ * "ConnectionRefused"`, undici nests an `ENOTFOUND`/`ECONNREFUSED` errno under
+ * `TypeError: fetch failed` (sometimes through an `AggregateError`), and
+ * `fetchWithRetry` may already have flattened the chain into a message-only
+ * `Error`. Both the code and the text are inspected so every one of those
+ * shapes lands in the right bucket.
+ */
+
+/** Transport-level failure families that get their own user-visible wording. */
+export type NetworkFailureKind = "offline" | "unreachable" | "refused" | "tls";
+
+/** What {@link classifyNetworkCause} reports about a rejected `fetch`: the failure family plus the bits its sentence needs. */
+export interface NetworkFailure {
+	kind: NetworkFailureKind;
+	/** Runtime error code when the chain exposed one (`ETIMEOUT`, `FailedToOpenSocket`, …). */
+	code: string | undefined;
+	/** Short parenthetical detail for the user-visible message. */
+	detail: string | undefined;
+	/** Host named by the error text, when it named one. */
+	host: string | undefined;
+}
+
+const MAX_CAUSE_DEPTH = 8;
+const MAX_AGGREGATE_BRANCH = 4;
+const MAX_LINKS = 16;
+const MAX_DETAIL_LENGTH = 120;
+const UNKNOWN_HOST = "the API host";
+
+const OFFLINE_CODE_PATTERN = /^(?:ETIMEOUT|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH)$/i;
+const OFFLINE_TEXT_PATTERN = /\b(?:ETIMEOUT|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH)\b/i;
+const UNREACHABLE_CODE_PATTERN = /^(?:ENOTFOUND|FailedToOpenSocket)$/i;
+const UNREACHABLE_TEXT_PATTERN = /\b(?:ENOTFOUND|FailedToOpenSocket|getaddrinfo)\b/i;
+const REFUSED_CODE_PATTERN = /^(?:ECONNREFUSED|ConnectionRefused)$/i;
+const REFUSED_TEXT_PATTERN = /\bECONNREFUSED\b|\bConnectionRefused\b|\bUnable to connect\b/i;
+const TLS_CODE_PATTERN =
+	/^(?:CERT_|SELF_SIGNED|UNABLE_TO_GET_ISSUER_CERT|UNABLE_TO_VERIFY|DEPTH_ZERO_SELF_SIGNED_CERT|ERR_TLS_CERT)/i;
+const TLS_TEXT_PATTERN =
+	/unable to verify|certificate verif(?:y|ication)|self[- ]signed certificate|\bCERT_[A-Z_]+\b|\bSELF_SIGNED[A-Z_]*\b|\bUNABLE_TO_GET_ISSUER_CERT[A-Z_]*\b|\bUNABLE_TO_VERIFY_LEAF_SIGNATURE\b/i;
+const GETADDRINFO_HOST_PATTERN = /\bgetaddrinfo\s+[A-Z_]+\s+([^\s,)]+)/i;
+const CONNECT_HOST_PATTERN = /\b(?:connect|connection to)\s+[A-Z_]+\s+([^\s,)]+?)(?::\d+)?(?=[\s,)]|$)/i;
+const BARE_HOST_PATTERN = /\b((?:[a-z0-9-]+\.)+[a-z]{2,})\b/i;
+const GETADDRINFO_DETAIL_PATTERN = /\bgetaddrinfo\s+[A-Z_]+/i;
+const ERRNO_DETAIL_PATTERN = /\b(?:ETIMEOUT|ENOTFOUND|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH|FailedToOpenSocket)\b/i;
+const HOST_PATTERNS = [GETADDRINFO_HOST_PATTERN, CONNECT_HOST_PATTERN, BARE_HOST_PATTERN];
+
+interface Link {
+	value: unknown;
+	depth: number;
+}
+
+function kindOf(code: string | undefined, message: string | undefined): NetworkFailureKind | undefined {
+	// TLS first: a certificate failure usually also reads as a failed connect.
+	if (code !== undefined && TLS_CODE_PATTERN.test(code)) return "tls";
+	if (message !== undefined && TLS_TEXT_PATTERN.test(message)) return "tls";
+	if (code !== undefined && REFUSED_CODE_PATTERN.test(code)) return "refused";
+	if (message !== undefined && REFUSED_TEXT_PATTERN.test(message)) return "refused";
+	// Offline before unreachable: `getaddrinfo ETIMEOUT` matches both text patterns.
+	if (code !== undefined && OFFLINE_CODE_PATTERN.test(code)) return "offline";
+	if (message !== undefined && OFFLINE_TEXT_PATTERN.test(message)) return "offline";
+	if (code !== undefined && UNREACHABLE_CODE_PATTERN.test(code)) return "unreachable";
+	if (message !== undefined && UNREACHABLE_TEXT_PATTERN.test(message)) return "unreachable";
+	return undefined;
+}
+
+/** First host named by any message seen so far, most specific pattern first. */
+function hostFromTexts(texts: readonly string[]): string | undefined {
+	for (const pattern of HOST_PATTERNS) {
+		for (const text of texts) {
+			const host = pattern.exec(text)?.[1];
+			if (host) return host;
+		}
+	}
+	return undefined;
+}
+
+function detailOf(kind: NetworkFailureKind, code: string | undefined, message: string | undefined): string | undefined {
+	// The refused template already carries its own wording.
+	if (kind === "refused") return undefined;
+	if (kind === "tls" && code !== undefined) return code;
+	const pattern = kind === "tls" ? TLS_TEXT_PATTERN : GETADDRINFO_DETAIL_PATTERN;
+	const matched = message === undefined ? undefined : pattern.exec(message)?.[0];
+	if (matched !== undefined) return matched.replace(/\s+/g, " ").trim().slice(0, MAX_DETAIL_LENGTH);
+	if (kind === "tls") return undefined;
+	// A DNS/route failure without a `getaddrinfo …` fragment still names its errno; keeping it in
+	// the sentence is what keeps the rendered message matching TRANSIENT_TRANSPORT_PATTERN.
+	return code ?? (message === undefined ? undefined : ERRNO_DETAIL_PATTERN.exec(message)?.[0]);
+}
+
+/**
+ * Walk an error's `cause`/`errors` graph (bounded depth, cycle-safe) and report
+ * the outermost link that describes a local transport failure. Returns
+ * `undefined` for anything else, including HTTP-level provider errors.
+ */
+export function classifyNetworkCause(err: unknown): NetworkFailure | undefined {
+	const seen = new Set<object>();
+	const queue: Link[] = [{ value: err, depth: 0 }];
+	const texts: string[] = [];
+	let links = 0;
+
+	while (links < MAX_LINKS) {
+		const link = queue.shift();
+		if (link === undefined) break;
+		links++;
+		const { value, depth } = link;
+
+		let code: string | undefined;
+		let message: string | undefined;
+		const isObject = typeof value === "object" && value !== null;
+		if (typeof value === "string") {
+			message = value;
+		} else if (isObject) {
+			if (seen.has(value)) continue;
+			seen.add(value);
+			if ("code" in value && typeof value.code === "string") code = value.code;
+			if ("message" in value && typeof value.message === "string") message = value.message;
+		} else {
+			continue;
+		}
+		if (message !== undefined) texts.push(message);
+
+		const kind = kindOf(code, message);
+		if (kind !== undefined) {
+			return { kind, code, detail: detailOf(kind, code, message), host: hostFromTexts(texts) };
+		}
+
+		if (!isObject || depth >= MAX_CAUSE_DEPTH) continue;
+		if ("cause" in value) queue.push({ value: value.cause, depth: depth + 1 });
+		if ("errors" in value && Array.isArray(value.errors)) {
+			for (const nested of value.errors.slice(0, MAX_AGGREGATE_BRANCH)) {
+				queue.push({ value: nested, depth: depth + 1 });
+			}
+		}
+	}
+	return undefined;
+}
+
+/**
+ * User-visible sentence for a network failure, or `undefined` when the error is
+ * not one. `requestUrl` wins over any host parsed out of the error text.
+ */
+export function networkFailureMessage(err: unknown, requestUrl?: string): string | undefined {
+	const failure = classifyNetworkCause(err);
+	if (failure === undefined) return undefined;
+	let urlHost: string | undefined;
+	if (typeof requestUrl === "string" && requestUrl.length > 0) {
+		try {
+			const { host } = new URL(requestUrl);
+			if (host.length > 0) urlHost = host;
+		} catch {
+			urlHost = undefined;
+		}
+	}
+	const host = urlHost ?? failure.host ?? UNKNOWN_HOST;
+	const detail = failure.detail === undefined ? "" : ` (${failure.detail})`;
+	switch (failure.kind) {
+		case "offline":
+			return `No internet connection: couldn't reach ${host}${detail}. Check your network or proxy and try again.`;
+		case "unreachable":
+			return `Couldn't reach ${host}${detail}. Check the URL, your network, or proxy.`;
+		case "refused":
+			return `Couldn't connect to ${host} (connection refused). Check that the server is running and reachable.`;
+		case "tls":
+			return `TLS certificate verification failed for ${host}${detail}. If you're behind a TLS-inspecting proxy, its CA may need to be trusted.`;
+	}
+}
+
+/**
+ * Re-describe a rejected `fetch` with {@link networkFailureMessage}, keeping the
+ * original error as `cause`. Anything that is not a local transport failure is
+ * returned untouched, so provider/HTTP errors keep their identity.
+ */
+export function networkFailureError(err: unknown, requestUrl?: string): unknown {
+	const message = networkFailureMessage(err, requestUrl);
+	return message === undefined ? err : new Error(message, { cause: err });
+}

package/src/images/codex-format-directive.md

@@ -0,0 +1,3 @@
+{{{prompt}}}
+
+Output format: {{shape}} image, {{#if pixels}}{{width}}x{{height}} pixels{{else}}{{width}}:{{height}} aspect ratio{{/if}}.

package/src/images/google-antigravity.ts

@@ -8,7 +8,7 @@ import { getAntigravityUserAgent } from "@linxiraos/pi-catalog/wire/gemini-heade
 import { readSseJson } from "@linxiraos/pi-utils";
 import { withAuth } from "../auth-retry";
 import * as AIError from "../error";
-import { errorMessage, ImageApiError, usageFromWire } from "./shared";
+import { errorMessage, ImageApiError, usageFromWire, validateImageInput } from "./shared";
 import type { GeneratedImage, ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
 
 const IMAGE_SYSTEM_INSTRUCTION =
@@ -138,6 +138,7 @@ export async function generateAntigravityImage(
 	request: ImageGenerationRequest,
 	options: ImageGenerationOptions,
 ): Promise<ImageGenerationResult> {
+	for (const image of request.inputImages ?? []) validateImageInput(image);
 	const fetchImpl = options.fetch ?? fetch;
 	const response = await withAuth(
 		options.apiKey,

package/src/images/google-generative-ai.ts

@@ -1,7 +1,7 @@
 import type { Model } from "@linxiraos/pi-catalog/types";
 import { withAuth } from "../auth-retry";
 import * as AIError from "../error";
-import { errorMessage, ImageApiError, imageBaseUrl, modelHeaders, usageFromWire } from "./shared";
+import { errorMessage, ImageApiError, imageBaseUrl, modelHeaders, usageFromWire, validateImageInput } from "./shared";
 import type { GeneratedImage, ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
 
 interface GeminiPart {
@@ -20,7 +20,9 @@ export async function generateGoogleImage(
 	options: ImageGenerationOptions,
 ): Promise<ImageGenerationResult> {
 	const fetchImpl = options.fetch ?? fetch;
-	const parts: Array<{ text?: string; inlineData?: GeneratedImage }> = (request.inputImages ?? []).map(image => ({
+	const inputImages = request.inputImages ?? [];
+	for (const image of inputImages) validateImageInput(image);
+	const parts: Array<{ text?: string; inlineData?: GeneratedImage }> = inputImages.map(image => ({
 		inlineData: image,
 	}));
 	parts.push({ text: request.prompt });

package/src/images/openai-hosted.ts

@@ -7,7 +7,7 @@ import {
 	OPENAI_HEADERS,
 	URL_PATHS,
 } from "@linxiraos/pi-catalog/wire/codex";
-import { readSseJson, USER_AGENT } from "@linxiraos/pi-utils";
+import { prompt, readSseJson, USER_AGENT } from "@linxiraos/pi-utils";
 import { withAuth } from "../auth-retry";
 import * as AIError from "../error";
 import { applySessionHeader } from "../providers/inference-headers";
@@ -20,6 +20,7 @@ import {
 	toDataUrl,
 	usageFromWire,
 } from "./shared";
+import codexFormatDirective from "./codex-format-directive.md" with { type: "text" };
 import type { GeneratedImage, ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
 
 const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
@@ -143,6 +144,27 @@ async function parseSse(response: Response, signal?: AbortSignal): Promise<Image
 	return collectResponse(completed?.output?.length ? completed : { ...completed, output: fallbackOutput });
 }
 
+/**
+ * The Codex backend runs its image tool with `size: "auto"`, ignoring the requested `size`, and
+ * shapes the canvas from the prompt alone. Spell the requested shape out so it is honored.
+ */
+function withCodexFormatDirective(request: ImageGenerationRequest): string {
+	const dimensions = request.imageSize?.match(/^(\d+)x(\d+)$/);
+	const ratio = dimensions ? undefined : request.aspectRatio?.match(/^(\d+):(\d+)$/);
+	const match = dimensions ?? ratio;
+	if (!match) return request.prompt;
+	const width = Number(match[1]);
+	const height = Number(match[2]);
+	const shape = width === height ? "square" : width > height ? "landscape" : "portrait";
+	return prompt.render(codexFormatDirective, {
+		prompt: request.prompt,
+		shape,
+		width,
+		height,
+		pixels: dimensions !== undefined,
+	});
+}
+
 export async function generateHostedImage(
 	model: Model,
 	request: ImageGenerationRequest,
@@ -154,7 +176,8 @@ export async function generateHostedImage(
 		throw new AIError.ValidationError(`Hosted image carrier API ${carrier.api} is unsupported`);
 	}
 	const stream = carrier.api === "openai-codex-responses";
-	const content: Array<Record<string, unknown>> = [{ type: "input_text", text: request.prompt }];
+	const inputText = stream ? withCodexFormatDirective(request) : request.prompt;
+	const content: Array<Record<string, unknown>> = [{ type: "input_text", text: inputText }];
 	for (const image of request.inputImages ?? []) {
 		content.push({ type: "input_image", detail: "auto", image_url: toDataUrl(image) });
 	}

package/src/images/openai-images.ts

@@ -8,6 +8,7 @@ import {
 	postMultipart,
 	resolveOpenAIImageSize,
 	toDataUrl,
+	validateImageInput,
 } from "./shared";
 import type { ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
 
@@ -25,21 +26,24 @@ export async function generateOpenAIImage(
 	const fetchImpl = options.fetch ?? fetch;
 	const size = resolveOpenAIImageSize(request.aspectRatio, request.imageSize);
 	const count = request.count ?? 1;
+	const wireModelId = model.requestModelId ?? model.id;
+	// Hand-built image models (SDK callers, tests) may skip `buildModel` and carry no identity.
+	const isGptImage = model.identity?.family === "gpt-image";
 	const isXAI = model.provider === "xai" || model.provider === "xai-oauth";
 	const generationBody = isXAI
 		? {
-				model: model.requestModelId ?? model.id,
+				model: wireModelId,
 				prompt: request.prompt,
 				aspect_ratio: request.aspectRatio ?? "1:1",
 				resolution: resolveXAIResolution(request.imageSize),
 				n: count,
-				response_format: "b64_json",
+				...(isGptImage ? {} : { response_format: "b64_json" }),
 			}
 		: {
-				model: model.requestModelId ?? model.id,
+				model: wireModelId,
 				prompt: request.prompt,
 				n: count,
-				response_format: "b64_json",
+				...(isGptImage ? {} : { response_format: "b64_json" }),
 				...(size ? { size } : {}),
 			};
 	const inputImages = request.inputImages ?? [];
@@ -79,12 +83,13 @@ export async function generateOpenAIImage(
 		try {
 			if (model.provider === "openai") {
 				const form = new FormData();
-				form.set("model", model.requestModelId ?? model.id);
+				form.set("model", wireModelId);
 				form.set("prompt", request.prompt);
 				form.set("n", String(count));
-				form.set("response_format", "b64_json");
+				if (!isGptImage) form.set("response_format", "b64_json");
 				if (size) form.set("size", size);
 				for (const image of inputImages) {
+					validateImageInput(image);
 					form.append("image", new File([Buffer.from(image.data, "base64")], "image", { type: image.mimeType }));
 				}
 				response = await postMultipart({

package/src/images/shared.ts

@@ -1,9 +1,10 @@
 import type { FetchImpl, Model, Usage } from "@linxiraos/pi-catalog/types";
-import { parseImageMetadata, USER_AGENT } from "@linxiraos/pi-utils";
+import { base64ImageDataFailureReason, isRecord, parseImageMetadata, USER_AGENT } from "@linxiraos/pi-utils";
 import type { ApiKey } from "../auth-retry";
 import { withAuth } from "../auth-retry";
 import * as AIError from "../error";
-import type { GeneratedImage } from "./types";
+import type { ImageContent } from "../types";
+import type { GeneratedImage, ImageInput } from "./types";
 
 export class ImageApiError extends AIError.ProviderHttpError {
 	override readonly name = "ImageApiError";
@@ -185,18 +186,91 @@ export function sniffBase64ImageMimeType(base64: string): string | undefined {
 	return parseImageMetadata(Buffer.from(base64.slice(0, 64), "base64"))?.mimeType;
 }
 
-export function toDataUrl(image: GeneratedImage): string {
+/**
+ * Validate provider-bound image input without changing it. Accepts non-empty standard base64
+ * with canonical trailing bits and optional padding, and case-insensitive image MIME syntax
+ * (RFC 6838 restricted names). Does not sniff the MIME type, decode image pixels, or enforce
+ * provider-specific format support; data-URL transports additionally go through `toDataUrl`.
+ *
+ * @throws {AIError.ValidationError} If the base64 data or image MIME type is invalid.
+ */
+export function validateImageInput(image: ImageInput): void {
+	if (!isRecord(image) || typeof image.data !== "string") {
+		throw new AIError.ValidationError("invalid base64 image data");
+	}
+	const reason = base64ImageDataFailureReason(image.data);
+	if (reason) throw new AIError.ValidationError(reason);
+	if (!isImageMimeType(image.mimeType)) throw new AIError.ValidationError("invalid image MIME type");
+}
+
+/**
+ * Encode validated image input as a base64 data URL.
+ *
+ * @throws {AIError.ValidationError} If the input is invalid or its MIME type cannot survive a data URL.
+ */
+export function toDataUrl(image: ImageInput): string {
+	validateImageInput(image);
+	if (!isDataUrlMimeType(image.mimeType)) {
+		throw new AIError.ValidationError("image MIME type containing '#' cannot be sent as a data URL");
+	}
 	return `data:${image.mimeType};base64,${image.data}`;
 }
 
+// RFC 6838 restricted-name.
+const IMAGE_MIME_TYPE = /^image\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}$/i;
+const IMAGE_DETAILS: Record<string, true> = {
+	auto: true,
+	low: true,
+	high: true,
+	original: true,
+};
+
+function isImageMimeType(value: unknown): value is string {
+	return typeof value === "string" && IMAGE_MIME_TYPE.test(value);
+}
+
+/**
+ * Whether a MIME type survives a data URL intact: a raw `#` starts a URL fragment and
+ * data-URL consumers leave a `%23` escape undecoded, so no data-URL transport preserves it.
+ */
+export function isDataUrlMimeType(mimeType: string): boolean {
+	return !mimeType.includes("#");
+}
+
+function isEmbeddedImageShape(image: unknown): image is ImageContent {
+	return (
+		isRecord(image) &&
+		image.type === "image" &&
+		typeof image.data === "string" &&
+		isImageMimeType(image.mimeType) &&
+		isDataUrlMimeType(image.mimeType) &&
+		(image.detail === undefined || (typeof image.detail === "string" && Object.hasOwn(IMAGE_DETAILS, image.detail)))
+	);
+}
+
+/** Whether a value is an embedded image with valid base64 data, MIME type, and detail. */
+export function isEmbeddedImageContent(image: unknown): image is ImageContent {
+	return isEmbeddedImageShape(image) && base64ImageDataFailureReason(image.data) === undefined;
+}
+
+/** Convert one validated embedded image to a lowercase-MIME inline data URL. */
+export function embeddedImageDataUrl(image: unknown): string {
+	if (!isEmbeddedImageShape(image)) {
+		throw new AIError.ValidationError("Judgment images must contain non-empty base64 data and an image MIME type");
+	}
+	return toDataUrl({ data: image.data, mimeType: image.mimeType.toLowerCase() });
+}
+
 export function resolveOpenAIImageSize(aspectRatio?: string, imageSize?: string): string | undefined {
 	if (imageSize) return imageSize;
 	switch (aspectRatio) {
 		case "1:1":
 			return "1024x1024";
+		case "2:3":
 		case "3:4":
 		case "9:16":
 			return "1024x1536";
+		case "3:2":
 		case "4:3":
 		case "16:9":
 			return "1536x1024";

package/src/index.ts

@@ -65,6 +65,7 @@ export * from "./utils/anthropic-auth";
 export * from "./utils/event-stream";
 export * from "./utils/glyph-codec";
 export * from "./utils/openrouter-headers";
+export * from "./utils/narration";
 export * from "./utils/schema";
 export * from "./utils/thinking-loop";
 export * from "./utils/tool-call-loop-guard";

package/src/judgment/chat.ts

@@ -5,6 +5,7 @@
 import { type } from "@linxiraos/pi-omptype";
 import * as AIError from "../error";
 import { retryTransientCompletion } from "../oneshot-retry";
+import { sendsImageInputOnWire } from "../providers/vision-guard";
 import { completeSimple } from "../stream";
 import type { Api, AssistantMessage, Model, SimpleStreamOptions, Tool } from "../types";
 import type { TextBackend, TextCompletion, TextPrompt } from "./text";
@@ -40,19 +41,34 @@ export type ChatTextBackendOptions = Pick<SimpleStreamOptions, "apiKey" | "sessi
 
 /** Chat completions with reasoning disabled, temperature 0, and transient-failure retry. */
 export function chatTextBackend(model: Model<Api>, options: ChatTextBackendOptions): TextBackend {
+	const supportsImages = sendsImageInputOnWire(model);
 	return {
 		api: model.api,
 		provider: model.provider,
 		model: model.id,
+		...(supportsImages ? { supportsImages: true } : {}),
 		parseRetries: 2,
 		async complete(prompt: TextPrompt, judge: JudgeOptions): Promise<TextCompletion> {
+			if (prompt.images?.length && !supportsImages) {
+				throw new AIError.ValidationError(
+					`Chat judgment backend ${model.provider}/${model.id} does not support image inputs`,
+				);
+			}
 			const response = await retryTransientCompletion(
 				() =>
 					completeSimple(
 						model,
 						{
 							systemPrompt: [prompt.system],
-							messages: [{ role: "user", content: prompt.user, timestamp: Date.now() }],
+							messages: [
+								{
+									role: "user",
+									content: prompt.images?.length
+										? [{ type: "text" as const, text: prompt.user }, ...prompt.images]
+										: prompt.user,
+									timestamp: Date.now(),
+								},
+							],
 							tools: prompt.retry ? [SUBMIT_JUDGMENT] : undefined,
 						},
 						{