@oh-my-pi/pi-ai 18.2.7 → 18.2.8

package/src/embeddings/openai-embeddings.ts

@@ -0,0 +1,141 @@
+import { calculateCost } from "@oh-my-pi/pi-catalog/models";
+import type { Api, FetchImpl, Model, Usage } from "@oh-my-pi/pi-catalog/types";
+import { type } from "@oh-my-pi/omptype";
+import { type ApiKey, withAuth } from "../auth-retry";
+import * as AIError from "../error";
+import type { EmbeddingRequest, EmbeddingResult } from "./types";
+
+export interface EmbeddingOptions {
+	apiKey: ApiKey;
+	fetch?: FetchImpl;
+	signal?: AbortSignal;
+}
+
+/** Non-2xx response from an OpenAI-compatible embeddings endpoint. */
+export class EmbeddingApiError extends AIError.ProviderHttpError {
+	override readonly name = "EmbeddingApiError";
+}
+
+const upstreamResponseSchema = type({
+	data: "object[]",
+	model: "string",
+	"usage?": "object",
+});
+
+interface UpstreamUsage {
+	prompt_tokens?: unknown;
+	total_tokens?: unknown;
+	cost?: unknown;
+}
+
+function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function decodeUsage(model: Model<Api>, raw: unknown): Usage {
+	const upstream = raw && typeof raw === "object" ? (raw as UpstreamUsage) : {};
+	const input = finiteNumber(upstream.prompt_tokens) ?? 0;
+	const totalTokens = finiteNumber(upstream.total_tokens) ?? input;
+	const reportedCost = finiteNumber(upstream.cost);
+	const usage: Usage = {
+		input,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens,
+		...(reportedCost !== undefined && { credits: { cost: reportedCost } }),
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: reportedCost ?? 0 },
+	};
+	if (reportedCost === undefined) calculateCost(model, usage);
+	return usage;
+}
+
+function decodeEmbeddings(data: object[], model: Model<Api>): EmbeddingResult["embeddings"] {
+	return data.map((raw, position) => {
+		const index = Reflect.get(raw, "index");
+		const embedding = Reflect.get(raw, "embedding");
+		if (!Number.isInteger(index) || index < 0) {
+			throw new AIError.ProviderResponseError(
+				`${model.provider}/${model.id} embeddings response has an invalid index at data[${position}]`,
+				{ provider: model.provider, kind: "envelope" },
+			);
+		}
+		if (
+			typeof embedding !== "string" &&
+			(!Array.isArray(embedding) || !embedding.every(value => typeof value === "number" && Number.isFinite(value)))
+		) {
+			throw new AIError.ProviderResponseError(
+				`${model.provider}/${model.id} embeddings response has an invalid vector at data[${position}]`,
+				{ provider: model.provider, kind: "envelope" },
+			);
+		}
+		return { index, embedding };
+	});
+}
+
+async function responseError(response: Response, model: Model<Api>): Promise<EmbeddingApiError> {
+	const text = await response.text();
+	let detail = text;
+	let code: string | undefined;
+	try {
+		const parsed: unknown = JSON.parse(text);
+		if (parsed && typeof parsed === "object" && "error" in parsed) {
+			const error = parsed.error;
+			if (error && typeof error === "object") {
+				const envelope = error as { message?: unknown; code?: unknown; type?: unknown };
+				if (typeof envelope.message === "string") detail = envelope.message;
+				if (typeof envelope.code === "string") code = envelope.code;
+				else if (typeof envelope.type === "string") code = envelope.type;
+			}
+		}
+	} catch {}
+	return new EmbeddingApiError(
+		`${model.provider}/${model.id} embeddings API error (${response.status}): ${detail || response.statusText}`,
+		response.status,
+		{ headers: response.headers, code },
+	);
+}
+
+/** Call an OpenAI/OpenRouter-compatible embeddings endpoint. */
+export async function embedOpenAI(
+	model: Model<Api>,
+	request: EmbeddingRequest,
+	options: EmbeddingOptions,
+): Promise<EmbeddingResult> {
+	const fetchImpl = options.fetch ?? fetch;
+	const body = {
+		model: model.id,
+		input: request.input,
+		encoding_format: request.encodingFormat,
+		...(request.dimensions !== undefined && { dimensions: request.dimensions }),
+		...(request.user !== undefined && { user: request.user }),
+	};
+	const response = await withAuth(
+		options.apiKey,
+		async key => {
+			const attempt = await fetchImpl(`${model.baseUrl.replace(/\/+$/, "")}/embeddings`, {
+				method: "POST",
+				headers: { Authorization: `Bearer ${key}`, Accept: "application/json", "Content-Type": "application/json" },
+				body: JSON.stringify(body),
+				signal: options.signal,
+			});
+			if (!attempt.ok) throw await responseError(attempt, model);
+			return attempt;
+		},
+		{ signal: options.signal },
+	);
+
+	const raw: unknown = await response.json();
+	const parsed = upstreamResponseSchema(raw);
+	if (parsed instanceof type.errors) {
+		throw new AIError.ProviderResponseError(
+			`${model.provider}/${model.id} embeddings response is malformed: ${parsed.summary}`,
+			{ provider: model.provider, kind: "envelope" },
+		);
+	}
+	return {
+		embeddings: decodeEmbeddings(parsed.data, model),
+		model: parsed.model,
+		usage: decodeUsage(model, parsed.usage),
+	};
+}

package/src/embeddings/types.ts

@@ -0,0 +1,14 @@
+import type { Usage } from "@oh-my-pi/pi-catalog/types";
+
+export interface EmbeddingRequest {
+	input: string | string[] | number[] | number[][];
+	dimensions?: number;
+	encodingFormat: "float" | "base64";
+	user?: string;
+}
+
+export interface EmbeddingResult {
+	embeddings: Array<{ index: number; embedding: number[] | string }>;
+	model: string;
+	usage: Usage;
+}

package/src/error/rate-limit.ts

@@ -306,7 +306,7 @@ export function calculateRateLimitBackoffMs(reason: RateLimitReason): number {
 
 /** Detect usage/quota limit errors in error messages (persistent, requires credential switch). */
 const USAGE_LIMIT_PATTERN =
-	/usage.?limit|usage_limit_reached|usage_not_included|limit_reached|quota.?(?:exceeded|reached|insufficient)|额度不足|额度耗尽|resource.?exhausted|exhausted your capacity|quota will reset|insufficient.?(?:balance|quota)|balance.?exhausted|run out of credits|out of credits|spending[- _]?limit|personal-team-blocked|clinepass limit|free limit reached on model|access_terminated_error/i;
+	/usage.?limit|usage_limit_reached|usage_not_included|limit_reached|quota.?(?:exceeded|reached|insufficient)|额度不足|额度耗尽|resource.?exhausted|exhausted your capacity|quota will reset|insufficient.?(?:balance|quota)|balance.?exhausted|run out of credits|out of credits|out of (?:extra )?usage|spending[- _]?limit|personal-team-blocked|clinepass limit|free limit reached on model|access_terminated_error/i;
 
 /**
  * HTTP status codes that, absent richer body classification, represent an

package/src/images/google-antigravity.ts

@@ -0,0 +1,180 @@
+import {
+	ANTIGRAVITY_PRIMARY_ENDPOINT,
+	ANTIGRAVITY_SANDBOX_ENDPOINT,
+	fetchAntigravityImageModel,
+} from "@oh-my-pi/pi-catalog/discovery/antigravity";
+import type { Model } from "@oh-my-pi/pi-catalog/types";
+import { getAntigravityUserAgent } from "@oh-my-pi/pi-catalog/wire/gemini-headers";
+import { readSseJson } from "@oh-my-pi/pi-utils";
+import { withAuth } from "../auth-retry";
+import * as AIError from "../error";
+import { errorMessage, ImageApiError, usageFromWire } from "./shared";
+import type { GeneratedImage, ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
+
+const IMAGE_SYSTEM_INSTRUCTION =
+	"You are an AI image generator. Generate images based on user descriptions. Focus on creating high-quality, visually appealing images that match the user's request.";
+
+interface AntigravityCredentials {
+	accessToken: string;
+	projectId: string;
+}
+
+interface AntigravityTarget {
+	model: string;
+	endpoints: string[];
+}
+
+interface AntigravityChunk {
+	response?: {
+		candidates?: Array<{
+			content?: { parts?: Array<{ text?: string; inlineData?: { data?: string; mimeType?: string } }> };
+		}>;
+		usageMetadata?: { promptTokenCount?: number; candidatesTokenCount?: number };
+	};
+}
+
+export function parseAntigravityCredentials(raw: string): AntigravityCredentials | undefined {
+	try {
+		const parsed = JSON.parse(raw) as { token?: unknown; projectId?: unknown };
+		if (typeof parsed.token === "string" && typeof parsed.projectId === "string") {
+			return { accessToken: parsed.token, projectId: parsed.projectId };
+		}
+	} catch {
+		// Report the same validation error below.
+	}
+	return undefined;
+}
+
+function antigravityEndpoints(model: Model): string[] {
+	const configured = model.baseUrl.replace(/\/+$/, "");
+	return [...new Set([configured, ANTIGRAVITY_PRIMARY_ENDPOINT, ANTIGRAVITY_SANDBOX_ENDPOINT])];
+}
+
+async function resolveTarget(
+	model: Model,
+	credentials: AntigravityCredentials,
+	fetchImpl: ImageGenerationOptions["fetch"],
+	signal?: AbortSignal,
+): Promise<AntigravityTarget> {
+	const endpoints = antigravityEndpoints(model);
+	const advertised = await fetchAntigravityImageModel({
+		token: credentials.accessToken,
+		endpoint: endpoints.length === 1 ? endpoints[0] : undefined,
+		userAgent: getAntigravityUserAgent(),
+		signal,
+		fetcher: fetchImpl,
+	});
+	return advertised
+		? {
+				model: advertised.id,
+				endpoints: [advertised.endpoint, ...endpoints.filter(endpoint => endpoint !== advertised.endpoint)],
+			}
+		: { model: model.requestModelId ?? model.id, endpoints };
+}
+
+function buildRequest(request: ImageGenerationRequest, model: string, projectId: string): Record<string, unknown> {
+	const parts: Array<{ text?: string; inlineData?: GeneratedImage }> = (request.inputImages ?? []).map(image => ({
+		inlineData: image,
+	}));
+	parts.push({ text: request.prompt });
+	const imageConfig =
+		request.aspectRatio || request.imageSize
+			? { aspectRatio: request.aspectRatio, imageSize: request.imageSize }
+			: undefined;
+	return {
+		project: projectId,
+		model,
+		request: {
+			contents: [{ role: "user", parts }],
+			systemInstruction: { parts: [{ text: IMAGE_SYSTEM_INSTRUCTION }] },
+			generationConfig: {
+				responseModalities: ["IMAGE"],
+				...(imageConfig ? { imageConfig } : {}),
+				candidateCount: request.count ?? 1,
+			},
+			safetySettings: [
+				{ category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_ONLY_HIGH" },
+				{ category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" },
+				{ category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold: "BLOCK_ONLY_HIGH" },
+				{ category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_ONLY_HIGH" },
+				{ category: "HARM_CATEGORY_CIVIC_INTEGRITY", threshold: "BLOCK_ONLY_HIGH" },
+			],
+		},
+		requestType: "agent",
+		requestId: `agent-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,
+		userAgent: "antigravity",
+	};
+}
+
+async function parseSse(response: Response, signal?: AbortSignal): Promise<ImageGenerationResult> {
+	if (!response.body) {
+		throw new AIError.ProviderResponseError("Antigravity image response has no body", { kind: "empty-body" });
+	}
+	const images: GeneratedImage[] = [];
+	const texts: string[] = [];
+	let usage = usageFromWire(undefined);
+	for await (const chunk of readSseJson<AntigravityChunk>(response.body, signal)) {
+		for (const candidate of chunk.response?.candidates ?? []) {
+			for (const part of candidate.content?.parts ?? []) {
+				if (part.text) texts.push(part.text);
+				if (part.inlineData?.data && part.inlineData.mimeType) {
+					images.push({ data: part.inlineData.data, mimeType: part.inlineData.mimeType });
+				}
+			}
+		}
+		const metadata = chunk.response?.usageMetadata;
+		if (metadata) {
+			usage = usageFromWire({
+				input_tokens: metadata.promptTokenCount,
+				output_tokens: metadata.candidatesTokenCount,
+			});
+		}
+	}
+	const text = texts.join(" ").trim();
+	return { images, ...(text ? { text } : {}), usage };
+}
+
+export async function generateAntigravityImage(
+	model: Model,
+	request: ImageGenerationRequest,
+	options: ImageGenerationOptions,
+): Promise<ImageGenerationResult> {
+	const fetchImpl = options.fetch ?? fetch;
+	const response = await withAuth(
+		options.apiKey,
+		async rawKey => {
+			const credentials = parseAntigravityCredentials(rawKey);
+			if (!credentials) {
+				throw new AIError.ValidationError("Antigravity image credentials must contain token and projectId");
+			}
+			const target = await resolveTarget(model, credentials, fetchImpl, options.signal);
+			const body = buildRequest(request, target.model, credentials.projectId);
+			let lastError: ImageApiError | undefined;
+			for (let index = 0; index < target.endpoints.length; index++) {
+				const result = await fetchImpl(`${target.endpoints[index]}/v1internal:streamGenerateContent?alt=sse`, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${credentials.accessToken}`,
+						"Content-Type": "application/json",
+						Accept: "text/event-stream",
+						"User-Agent": getAntigravityUserAgent(),
+					},
+					body: JSON.stringify(body),
+					signal: options.signal,
+				});
+				if (result.ok) return result;
+				const text = await result.text();
+				lastError = new ImageApiError(
+					`${model.provider}/${model.id} image request failed (${result.status}): ${errorMessage(text)}`,
+					result.status,
+					{ headers: result.headers },
+				);
+				const retryable = result.status === 429 || result.status >= 500;
+				if (!retryable || index === target.endpoints.length - 1) throw lastError;
+			}
+			throw lastError ?? new AIError.ProviderResponseError("Antigravity image request failed");
+		},
+		{ signal: options.signal },
+	);
+	return parseSse(response, options.signal);
+}

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

@@ -0,0 +1,92 @@
+import type { Model } from "@oh-my-pi/pi-catalog/types";
+import { withAuth } from "../auth-retry";
+import * as AIError from "../error";
+import { errorMessage, ImageApiError, imageBaseUrl, modelHeaders, usageFromWire } from "./shared";
+import type { GeneratedImage, ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
+
+interface GeminiPart {
+	text?: string;
+	inlineData?: { data?: string; mimeType?: string };
+}
+
+interface GeminiResponse {
+	candidates?: Array<{ content?: { parts?: GeminiPart[] } }>;
+	usageMetadata?: { promptTokenCount?: number; candidatesTokenCount?: number; totalTokenCount?: number };
+}
+
+export async function generateGoogleImage(
+	model: Model,
+	request: ImageGenerationRequest,
+	options: ImageGenerationOptions,
+): Promise<ImageGenerationResult> {
+	const fetchImpl = options.fetch ?? fetch;
+	const parts: Array<{ text?: string; inlineData?: GeneratedImage }> = (request.inputImages ?? []).map(image => ({
+		inlineData: image,
+	}));
+	parts.push({ text: request.prompt });
+	const imageConfig =
+		request.aspectRatio || request.imageSize
+			? { aspectRatio: request.aspectRatio, imageSize: request.imageSize }
+			: undefined;
+	const body = {
+		contents: [{ role: "user", parts }],
+		generationConfig: {
+			responseModalities: ["IMAGE"],
+			...(imageConfig ? { imageConfig } : {}),
+			...(request.count ? { candidateCount: request.count } : {}),
+		},
+	};
+	const response = await withAuth(
+		options.apiKey,
+		async key => {
+			const result = await fetchImpl(
+				`${imageBaseUrl(model)}/models/${encodeURIComponent(model.requestModelId ?? model.id)}:generateContent`,
+				{
+					method: "POST",
+					headers: {
+						...(await modelHeaders(model, options.signal)),
+						"Content-Type": "application/json",
+						"x-goog-api-key": key,
+					},
+					body: JSON.stringify(body),
+					signal: options.signal,
+				},
+			);
+			const text = await result.text();
+			if (!result.ok) {
+				throw new ImageApiError(
+					`${model.provider}/${model.id} image request failed (${result.status}): ${errorMessage(text)}`,
+					result.status,
+					{ headers: result.headers },
+				);
+			}
+			try {
+				return JSON.parse(text) as GeminiResponse;
+			} catch (cause) {
+				throw new AIError.ProviderResponseError("Gemini image API returned malformed JSON", {
+					provider: model.provider,
+					kind: "envelope",
+					cause,
+				});
+			}
+		},
+		{ signal: options.signal },
+	);
+	const responseParts = response.candidates?.flatMap(candidate => candidate.content?.parts ?? []) ?? [];
+	const images: GeneratedImage[] = [];
+	const textParts: string[] = [];
+	for (const part of responseParts) {
+		if (part.text) textParts.push(part.text);
+		if (part.inlineData?.data && part.inlineData.mimeType) {
+			images.push({ data: part.inlineData.data, mimeType: part.inlineData.mimeType });
+		}
+	}
+	const text = textParts.join("\n").trim();
+	const wireUsage = response.usageMetadata;
+	const usage = usageFromWire(
+		wireUsage
+			? { input_tokens: wireUsage.promptTokenCount, output_tokens: wireUsage.candidatesTokenCount }
+			: undefined,
+	);
+	return { images, ...(text ? { text } : {}), usage };
+}

package/src/images/index.ts

@@ -0,0 +1,59 @@
+import type { Api, Model } from "@oh-my-pi/pi-catalog/types";
+import * as AIError from "../error";
+import { generateAntigravityImage } from "./google-antigravity";
+import { generateGoogleImage } from "./google-generative-ai";
+import { generateOpenAIImage } from "./openai-images";
+import { generateHostedImage } from "./openai-hosted";
+import { generateOpenRouterImage } from "./openrouter-images";
+import type { ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
+
+export * from "./google-antigravity";
+export * from "./google-generative-ai";
+export * from "./openai-hosted";
+export * from "./openai-images";
+export * from "./openrouter-images";
+export * from "./types";
+
+/** Catalog APIs {@link generateImage} serves; the hosted Responses pair needs an explicit carrier model. */
+export type ImageGenerationApi =
+	| "openai-images"
+	| "openrouter-images"
+	| "google-generative-ai"
+	| "google-gemini-cli"
+	| "openai-responses"
+	| "openai-codex-responses";
+
+/** Whether a catalog API generates images through one of the pi-ai image clients. */
+export function isImageGenerationApi(api: Api): api is ImageGenerationApi {
+	return (
+		api === "openai-images" ||
+		api === "openrouter-images" ||
+		api === "google-generative-ai" ||
+		api === "google-gemini-cli" ||
+		api === "openai-responses" ||
+		api === "openai-codex-responses"
+	);
+}
+
+/** Generate (or edit, when `request.inputImages` is set) images through the transport selected by the model's `api`. */
+export async function generateImage(
+	model: Model<Api>,
+	request: ImageGenerationRequest,
+	options: ImageGenerationOptions,
+): Promise<ImageGenerationResult> {
+	switch (model.api) {
+		case "openai-images":
+			return generateOpenAIImage(model, request, options);
+		case "openrouter-images":
+			return generateOpenRouterImage(model, request, options);
+		case "google-generative-ai":
+			return generateGoogleImage(model, request, options);
+		case "google-gemini-cli":
+			return generateAntigravityImage(model, request, options);
+		case "openai-responses":
+		case "openai-codex-responses":
+			return generateHostedImage(model, request, options);
+		default:
+			throw new AIError.ValidationError(`Image generation does not support model API ${model.api}`);
+	}
+}

package/src/images/openai-hosted.ts

@@ -0,0 +1,185 @@
+import type { Api, Model } from "@oh-my-pi/pi-catalog/types";
+import {
+	applyCodexResidencyHeader,
+	CODEX_BASE_URL,
+	getCodexAccountId,
+	OPENAI_HEADER_VALUES,
+	OPENAI_HEADERS,
+	URL_PATHS,
+} from "@oh-my-pi/pi-catalog/wire/codex";
+import { parseImageMetadata, readSseJson, USER_AGENT } from "@oh-my-pi/pi-utils";
+import { withAuth } from "../auth-retry";
+import * as AIError from "../error";
+import { errorMessage, ImageApiError, modelHeaders, resolveOpenAIImageSize, toDataUrl, usageFromWire } from "./shared";
+import type { GeneratedImage, ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
+
+const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
+const IMAGE_SYSTEM_INSTRUCTION =
+	"You are an AI image generator. Generate images based on user descriptions. Focus on creating high-quality, visually appealing images that match the user's request.";
+
+interface HostedOutput {
+	type: "image_generation_call" | "message";
+	result?: string;
+	content?: Array<{ type?: string; text?: string; refusal?: string }>;
+}
+
+interface HostedResponse {
+	output?: HostedOutput[];
+	usage?: { input_tokens?: number; output_tokens?: number };
+	error?: { message?: string };
+}
+
+interface HostedEvent {
+	type?: string;
+	item?: HostedOutput;
+	response?: HostedResponse;
+	error?: { message?: string };
+	message?: string;
+}
+
+function responsesUrl(model: Model<Api>): string {
+	const fallback =
+		model.api === "openai-codex-responses" || model.provider === "openai-codex"
+			? CODEX_BASE_URL
+			: DEFAULT_OPENAI_BASE_URL;
+	const baseUrl = (model.baseUrl || fallback).replace(/\/+$/, "");
+	if (model.api !== "openai-codex-responses" && model.provider !== "openai-codex") {
+		return `${baseUrl}/responses`;
+	}
+	const baseWithSlash = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+	return new URL(URL_PATHS.RESPONSES.slice(1), baseWithSlash)
+		.toString()
+		.replace(URL_PATHS.RESPONSES, URL_PATHS.CODEX_RESPONSES);
+}
+
+async function headers(
+	carrier: Model<Api>,
+	key: string,
+	sessionId: string | undefined,
+	signal?: AbortSignal,
+): Promise<Headers> {
+	const result = new Headers(await modelHeaders(carrier, signal));
+	result.set("Content-Type", "application/json");
+	result.set("Authorization", `Bearer ${key}`);
+	if (carrier.api === "openai-codex-responses" || carrier.provider === "openai-codex") {
+		const accountId = getCodexAccountId(key);
+		result.delete("x-api-key");
+		if (accountId) result.set(OPENAI_HEADERS.ACCOUNT_ID, accountId);
+		applyCodexResidencyHeader(result, key);
+		result.set(OPENAI_HEADERS.BETA, OPENAI_HEADER_VALUES.BETA_RESPONSES);
+		result.set(OPENAI_HEADERS.ORIGINATOR, OPENAI_HEADER_VALUES.ORIGINATOR_CODEX);
+		result.set("User-Agent", USER_AGENT);
+		if (sessionId) {
+			result.set(OPENAI_HEADERS.CONVERSATION_ID, sessionId);
+			result.set(OPENAI_HEADERS.SESSION_ID, sessionId);
+		}
+	}
+	return result;
+}
+
+function collectResponse(response: HostedResponse): ImageGenerationResult {
+	const images: GeneratedImage[] = [];
+	const texts: string[] = [];
+	for (const output of response.output ?? []) {
+		if (output.type === "image_generation_call" && output.result) {
+			const bytes = Buffer.from(output.result, "base64");
+			images.push({ data: output.result, mimeType: parseImageMetadata(bytes)?.mimeType ?? "image/webp" });
+		}
+		if (output.type === "message") {
+			for (const part of output.content ?? []) {
+				if (part.type === "output_text" && part.text) texts.push(part.text);
+				if (part.type === "refusal" && part.refusal) texts.push(part.refusal);
+			}
+		}
+	}
+	const text = texts.join("\n").trim();
+	return { images, ...(text ? { text } : {}), usage: usageFromWire(response.usage) };
+}
+
+async function parseSse(response: Response, signal?: AbortSignal): Promise<ImageGenerationResult> {
+	if (!response.body) {
+		throw new AIError.ProviderResponseError("OpenAI hosted image response has no body", { kind: "empty-body" });
+	}
+	const fallbackOutput: HostedOutput[] = [];
+	let completed: HostedResponse | undefined;
+	for await (const event of readSseJson<HostedEvent>(response.body, signal)) {
+		if (event.type === "error") {
+			throw new AIError.ProviderResponseError(
+				event.error?.message ?? event.message ?? "OpenAI image request failed",
+			);
+		}
+		if (event.type === "response.failed") {
+			throw new AIError.ProviderResponseError(event.response?.error?.message ?? "OpenAI image request failed");
+		}
+		if (event.type === "response.output_item.done" && event.item) fallbackOutput.push(event.item);
+		if ((event.type === "response.completed" || event.type === "response.done") && event.response) {
+			completed = event.response;
+		}
+	}
+	return collectResponse(completed?.output?.length ? completed : { output: fallbackOutput, usage: completed?.usage });
+}
+
+export async function generateHostedImage(
+	model: Model,
+	request: ImageGenerationRequest,
+	options: ImageGenerationOptions,
+): Promise<ImageGenerationResult> {
+	const carrier = options.carrier;
+	if (!carrier) throw new AIError.ValidationError("Hosted image generation requires an explicit carrier model");
+	if (carrier.api !== "openai-responses" && carrier.api !== "openai-codex-responses") {
+		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 }];
+	for (const image of request.inputImages ?? []) {
+		content.push({ type: "input_image", detail: "auto", image_url: toDataUrl(image) });
+	}
+	const size = resolveOpenAIImageSize(request.aspectRatio, request.imageSize);
+	const tool = {
+		type: "image_generation",
+		action: content.length > 1 ? "edit" : "generate",
+		output_format: "webp",
+		...(size ? { size } : {}),
+		...(model.api === "openai-responses" ? { model: model.requestModelId ?? model.id } : {}),
+	};
+	const body = {
+		model: carrier.requestModelId ?? carrier.id,
+		input: [{ role: "user", content }],
+		tools: [tool],
+		tool_choice: { type: "image_generation" },
+		store: false,
+		...(stream ? { instructions: IMAGE_SYSTEM_INSTRUCTION, stream: true } : {}),
+	};
+	const fetchImpl = options.fetch ?? fetch;
+	return withAuth(
+		options.apiKey,
+		async key => {
+			const response = await fetchImpl(responsesUrl(carrier), {
+				method: "POST",
+				headers: await headers(carrier, key, options.sessionId, options.signal),
+				body: JSON.stringify(body),
+				signal: options.signal,
+			});
+			if (!response.ok) {
+				const text = await response.text();
+				throw new ImageApiError(
+					`OpenAI image request failed (${response.status}): ${errorMessage(text)}`,
+					response.status,
+					{ headers: response.headers },
+				);
+			}
+			if (stream || response.headers.get("content-type")?.includes("text/event-stream")) {
+				return parseSse(response, options.signal);
+			}
+			const value = (await response.json()) as HostedResponse;
+			if (value.error) throw new AIError.ProviderResponseError(value.error.message ?? "OpenAI image request failed");
+			if (!Array.isArray(value.output)) {
+				throw new AIError.ProviderResponseError("OpenAI image request returned a malformed response", {
+					kind: "envelope",
+				});
+			}
+			return collectResponse(value);
+		},
+		{ signal: options.signal },
+	);
+}