pi-openai-toolkit 0.17.3 → 0.18.0

package/README.md

@@ -168,7 +168,7 @@ Toolkit does not fall back between routes. See [search configuration](docs/confi
 
 ### Generate an image
 
-Requires a Responses session and may incur provider charges. Enable it with an image model your provider supports:
+Requires an eligible Responses-capable session and may incur provider charges. The local Pi tool sends a separate Images API request to the current provider (`/images/generations` or `/images/edits`; Codex uses `/codex/images/...`) rather than adding an image tool to the conversation request. Enable it with an image model your provider supports:
 
 ```json
 {
@@ -183,7 +183,7 @@ Requires a Responses session and may incur provider charges. Enable it with an i
 }
 ```
 
-Ask Pi to generate an image or edit explicitly supplied local references using `openai_generate_image`. The default model must be in `allowedModels`; image settings are global. See [image configuration](docs/configuration.md#images).
+Ask Pi to generate an image or edit explicitly supplied local references using `openai_generate_image`. The selected image model is sent in the independent request; the active conversation model remains the routing/auth model. Set the tool's optional `model` to another exact `allowedModels` entry, or use `batchSize` (1-10) for concurrent independent variants. Batch calls save canonical artifacts and cannot use a single-file `outputPath`; image settings are global. See [image configuration](docs/configuration.md#images).
 
 ### Review tool calls automatically
 

package/README.zh.md

@@ -168,7 +168,7 @@ Toolkit 不会在路由之间自动回退。后端要求见[搜索配置](docs/c
 
 ### 生成图片
 
-需要 Responses 会话，并可能产生服务商费用。选择服务商支持的生图模型后启用：
+需要符合条件的 Responses-capable 会话，并可能产生服务商费用。Pi 工具会向当前服务商发送独立的 Images API 请求（`/images/generations` 或 `/images/edits`；Codex 使用 `/codex/images/...`），不会把生图 tool 加入普通对话请求。选择服务商支持的生图模型后启用：
 
 ```json
 {
@@ -183,7 +183,7 @@ Toolkit 不会在路由之间自动回退。后端要求见[搜索配置](docs/c
 }
 ```
 
-让 Pi 通过 `openai_generate_image` 生成图片，或编辑明确提供的本地参考图。默认模型必须在 `allowedModels` 中；生图设置全局生效。详见[生图配置](docs/configuration.md#images)。
+让 Pi 通过 `openai_generate_image` 生成图片，或编辑明确提供的本地参考图。选中的生图模型会写入独立请求；当前对话模型仍只负责路由和认证。工具的可选 `model` 必须精确匹配 `allowedModels`，也可以使用 `batchSize`（1-10）并发生成多个独立变体。批量调用会保存 canonical artifacts，不能同时指定单文件 `outputPath`；生图设置全局生效。详见[生图配置](docs/configuration.md#images)。
 
 ### 启用工具调用自动审查
 

package/docs/configuration.md

@@ -104,7 +104,7 @@ There is no v2 search master switch. `local` and `unmanaged` differ in payload c
 
 Image settings are global-only under `defaults.imageGeneration`. `enabled` defaults to `false`. `defaultModel` defaults to `"gpt-image-2.5"`; `allowedModels` defaults to `["gpt-image-2.5"]`.
 
-These are bare output-model IDs, not active-session model keys. Each normalized ID must contain 1-256 characters. The allowed list must remain nonempty after normalization and contain the explicit default. Order has no default-selection meaning. A caller's one-call `model` must be a member; policy and membership are checked before auth, local-reference preparation/upload, and paid dispatch. The active session remains the Responses routing model. Config does not grant permission to upload arbitrary local files or imply that a provider supports a particular image model.
+These are bare output-model IDs, not active-session model keys. Each normalized ID must contain 1-256 characters. The allowed list must remain nonempty after normalization and contain the explicit default. A caller's one-call `model` must be a member; policy and membership are checked before auth, local-reference preparation/upload, and paid dispatch. The active session remains the routing/auth model, while the selected image model is sent in a separate Images API request. Generation uses `/images/generations`; edits use `/images/edits` (Codex uses the corresponding `/codex/images/...` paths). The wrapper never injects a Responses `image_generation` tool. `batchSize` is a tool argument from 1-10; each item is an independent `n: 1` request, partial success preserves saved artifacts, and batch calls cannot use a single-file `outputPath`. Config does not grant permission to upload arbitrary local files or imply that a provider supports a particular image model.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.17.3",
+  "version": "0.18.0",
   "private": false,
   "type": "module",
   "engines": {

package/src/image-generation/client.ts

@@ -1,10 +1,11 @@
 import { buildResponsesRequestHeaders } from "../responses-headers";
-import type { ResponsesRuntime } from "../runtime";
+import { normalizeBaseUrl, type ResponsesRuntime } from "../runtime";
 import {
 	extractProviderErrorMessage,
-	parseImageGenerationResponse,
+	parseImagesApiResponse,
 	type ImageGenerationRequestBody,
 } from "./protocol";
+import type { PreparedReferenceImage } from "./types";
 import {
 	IMAGE_REQUEST_TIMEOUT_MS,
 	MAX_IMAGE_ERROR_BYTES,
@@ -39,8 +40,62 @@ export type ImageGenerationFetch = (
 	init?: RequestInit,
 ) => Promise<Response>;
 
-function buildRequestHeaders(runtime: ResponsesRuntime): Headers {
-	return buildResponsesRequestHeaders(runtime, { accept: "application/json" });
+function buildRequestHeaders(runtime: ResponsesRuntime, contentType: string | null = "application/json"): Headers {
+	return buildResponsesRequestHeaders(runtime, { accept: "application/json", contentType });
+}
+
+function buildImagesEndpoint(runtime: ResponsesRuntime, action: ImageGenerationRequestBody["action"]): string {
+	const baseUrl = normalizeBaseUrl(runtime.baseUrl);
+	if (!baseUrl) throw new Error("Image generation requires a provider base URL.");
+	if (baseUrl.endsWith("/responses") || baseUrl.endsWith("/codex/responses")) {
+		throw new Error("Image generation requires the provider base URL, not a resolved Responses URL.");
+	}
+	const suffix = runtime.api === "openai-codex-responses" ? "codex/images" : "images";
+	const baseAlreadyIncludesCodex = runtime.api === "openai-codex-responses" && baseUrl.endsWith("/codex");
+	return `${baseUrl}/${baseAlreadyIncludesCodex ? "images" : suffix}/${action === "edit" ? "edits" : "generations"}`;
+}
+
+function dataUrl(reference: PreparedReferenceImage): string {
+	return `data:${reference.mimeType};base64,${reference.bytes.toString("base64")}`;
+}
+
+function jsonRequestBody(runtime: ResponsesRuntime, body: ImageGenerationRequestBody): Record<string, unknown> {
+	const common = {
+		model: body.model,
+		prompt: body.prompt,
+		n: body.n,
+		size: body.size,
+		quality: body.quality,
+	};
+	if (body.action === "edit") {
+		return {
+			...common,
+			images: body.references.map((reference) => ({ image_url: dataUrl(reference) })),
+		};
+	}
+	return runtime.api === "openai-codex-responses"
+		? common
+		: { ...common, output_format: "png", response_format: "b64_json" };
+}
+
+function multipartRequestBody(body: ImageGenerationRequestBody): FormData {
+	const form = new FormData();
+	form.append("model", body.model);
+	form.append("prompt", body.prompt);
+	form.append("n", String(body.n));
+	form.append("size", body.size);
+	form.append("quality", body.quality);
+	form.append("output_format", "png");
+	form.append("response_format", "b64_json");
+	for (const [index, reference] of body.references.entries()) {
+		const extension = reference.mimeType === "image/jpeg" ? "jpg" : reference.mimeType.slice("image/".length);
+		form.append(
+			"image",
+			new Blob([new Uint8Array(reference.bytes)], { type: reference.mimeType }),
+			`reference-${index + 1}.${extension}`,
+		);
+	}
+	return form;
 }
 
 async function readBoundedBody(
@@ -141,12 +196,16 @@ export async function requestGeneratedImage(args: {
 		? AbortSignal.any([args.signal, timeoutSignal])
 		: timeoutSignal;
 
+	const multipart = args.body.action === "edit" && args.runtime.api === "openai-responses";
+	const transportBody: BodyInit = multipart
+		? multipartRequestBody(args.body)
+		: JSON.stringify(jsonRequestBody(args.runtime, args.body));
 	let response: Response;
 	try {
-		response = await fetchFn(args.runtime.responsesUrl, {
+		response = await fetchFn(buildImagesEndpoint(args.runtime, args.body.action), {
 			method: "POST",
-			headers: buildRequestHeaders(args.runtime),
-			body: JSON.stringify(args.body),
+			headers: buildRequestHeaders(args.runtime, multipart ? null : "application/json"),
+			body: transportBody,
 			signal,
 		});
 	} catch (error) {
@@ -230,7 +289,7 @@ export async function requestGeneratedImage(args: {
 		};
 	}
 
-	const parsed = parseImageGenerationResponse(payload);
+	const parsed = parseImagesApiResponse(payload);
 	if (!parsed.ok) {
 		return {
 			ok: false,
@@ -244,5 +303,8 @@ export async function requestGeneratedImage(args: {
 
 export const _clientTest = {
 	buildRequestHeaders,
+	buildImagesEndpoint,
+	jsonRequestBody,
+	multipartRequestBody,
 	readBoundedBody,
 };

package/src/image-generation/eligibility.ts

@@ -2,9 +2,9 @@ import type { ImageGenerationConfig } from "../types";
 import { IMAGE_GENERATION_CAPABLE_APIS, type ImageGenerationModel } from "./types";
 
 /**
- * The hosted `image_generation` tool is a capability of the Responses API rather than of a
- * specific model, so support is decided by API alone. `enabled` is the single opt-in switch
- * and defaults to off because every successful provider request may incur a charge.
+ * The independent Images API is exposed only for Responses-capable runtimes rather than for a
+ * specific conversation model. `enabled` is the single opt-in switch and defaults to off because
+ * every successful provider request may incur a charge.
  */
 export function isImageGenerationEnabledForModel(
 	model: ImageGenerationModel | undefined,

package/src/image-generation/extension.ts

@@ -9,13 +9,14 @@ import {
 	IMAGE_GENERATION_QUALITIES,
 	IMAGE_GENERATION_SIZES,
 	IMAGE_GENERATION_TOOL_NAME,
+	MAX_IMAGE_BATCH_SIZE,
 	MAX_IMAGE_MODEL_ID_CHARS,
 	MAX_IMAGE_PATH_CHARS,
 	MAX_IMAGE_PROMPT_CHARS,
 	MAX_REFERENCE_IMAGE_COUNT,
 	ImageGenerationError,
 	sanitizeImageDiagnostic,
-	type ImageGenerationDetails,
+	type ImageGenerationToolDetails,
 } from "./types";
 
 const registeredApis = new WeakSet<object>();
@@ -82,6 +83,18 @@ const GenerateImageParameters = Type.Object(
 				},
 			),
 		),
+		batchSize: Type.Optional(
+			Type.Union(
+				[
+					Type.Null(),
+					Type.Integer({ minimum: 1, maximum: MAX_IMAGE_BATCH_SIZE }),
+				],
+				{
+					description:
+						"Run this many independent image requests concurrently (1-10). Batch requests use generated artifacts and cannot set outputPath.",
+				},
+			),
+		),
 	},
 	{ additionalProperties: false },
 );
@@ -111,12 +124,12 @@ export function registerImageGenerationExtension(
 	if (registeredApis.has(pi)) return;
 	registeredApis.add(pi);
 
-	pi.registerTool<typeof GenerateImageParameters, ImageGenerationDetails, Record<string, never>>({
+	pi.registerTool<typeof GenerateImageParameters, ImageGenerationToolDetails, Record<string, never>>({
 		name: IMAGE_GENERATION_TOOL_NAME,
 		label: "OpenAI Generate Image",
 		description:
-			"Generate a PNG image, or edit from one to five user-approved local reference images, through the current Responses-capable model and a configured hosted image_generation model. This is a paid provider operation.",
-		promptSnippet: "Generate or edit PNG images through the current Responses-capable model and a configured imageGeneration.allowedModels entry.",
+			"Generate PNG images, or edit from one to five user-approved local reference images, through an independent Images API request using a configured image model. This is a paid provider operation; batchSize runs independent requests concurrently.",
+		promptSnippet: "Generate or edit PNG images through an independent Images API request and a configured imageGeneration.allowedModels entry.",
 		promptGuidelines: [
 			"Use openai_generate_image when the user explicitly asks to create, draw, render, or edit a raster image and the active model speaks a Responses API.",
 			"Do not call openai_generate_image speculatively: it consumes the user's provider or gateway image quota.",
@@ -124,6 +137,7 @@ export function registerImageGenerationExtension(
 			"Set referenceImagePaths to null unless the user explicitly identified local files; never invent paths or placeholder strings, and remember upload requires user approval.",
 			"Set outputPath to null unless the user explicitly asks for a destination; never invent a destination or placeholder string, and otherwise use the default Pi agent artifact.",
 			"Set model to null unless the user named an image model configured in imageGeneration.allowedModels; never invent or guess a model id, and remember an unlisted model fails before the paid request.",
+			"Use batchSize only when the user asks for multiple variants; each batch item is an independent paid request, and batchSize cannot be combined with outputPath.",
 			"Do not substitute Python, browser automation, shell scripts, or unrelated image tools for an eligible image request.",
 		],
 		parameters: GenerateImageParameters,

package/src/image-generation/protocol.ts

@@ -4,6 +4,7 @@ import {
 	IMAGE_GENERATION_QUALITIES,
 	IMAGE_GENERATION_SIZES,
 	MAX_GENERATED_IMAGE_BYTES,
+	MAX_IMAGE_BATCH_SIZE,
 	MAX_IMAGE_DIAGNOSTIC_CHARS,
 	MAX_IMAGE_DIMENSION,
 	MAX_IMAGE_IDENTIFIER_CHARS,
@@ -26,26 +27,13 @@ const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/
 const DATA_URL_PATTERN = /^data:image\/[a-z0-9.+-]+;base64,(.*)$/is;
 
 export type ImageGenerationRequestBody = {
+	action: NormalizedGenerateImageParams["action"];
 	model: string;
-	store: false;
-	stream: false;
-	parallel_tool_calls: false;
-	input: Array<{
-		role: "user";
-		content: Array<
-			| { type: "input_text"; text: string }
-			| { type: "input_image"; image_url: string; detail: "auto" }
-		>;
-	}>;
-	tools: Array<{
-		type: "image_generation";
-		model: string;
-		action: "generate" | "edit";
-		size: NormalizedGenerateImageParams["size"];
-		quality: NormalizedGenerateImageParams["quality"];
-		output_format: "png";
-	}>;
-	tool_choice: { type: "image_generation" };
+	prompt: string;
+	n: 1;
+	size: NormalizedGenerateImageParams["size"];
+	quality: NormalizedGenerateImageParams["quality"];
+	references: readonly PreparedReferenceImage[];
 };
 
 export type ParsedImageResponseResult =
@@ -137,6 +125,22 @@ function normalizeRequestedModel(value: unknown): string | undefined {
 	return trimmed;
 }
 
+function normalizeBatchSize(value: unknown): number {
+	if (value === null || value === undefined) return 1;
+	if (
+		typeof value !== "number" ||
+		!Number.isInteger(value) ||
+		value < 1 ||
+		value > MAX_IMAGE_BATCH_SIZE
+	) {
+		throw new ImageGenerationError(
+			"invalid-parameters",
+			`batchSize must be an integer from 1 to ${MAX_IMAGE_BATCH_SIZE}.`,
+		);
+	}
+	return value;
+}
+
 /**
  * Configured model ids are only trusted as far as the shared bounds: unusable entries are
  * dropped, and an empty or malformed list falls back to the shipped default model.
@@ -153,7 +157,7 @@ function usableImageModels(models: readonly string[] | undefined): string[] {
 }
 
 /**
- * Resolve the nested `image_generation` model for one call. An omitted request selects the
+ * Resolve the independent Images API model for one call. An omitted request selects the
  * explicit default when supplied (v2), or the first configured model for legacy callers.
  * An explicit request must match a configured id exactly before any paid dispatch.
  */
@@ -213,6 +217,13 @@ export function normalizeGenerateImageParams(
 
 	const referenceImagePaths = normalizePathList(params.referenceImagePaths);
 	const outputPath = normalizeOutputPath(params.outputPath);
+	const batchSize = normalizeBatchSize(params.batchSize);
+	if (batchSize > 1 && outputPath !== undefined) {
+		throw new ImageGenerationError(
+			"invalid-parameters",
+			"outputPath cannot be used when batchSize is greater than 1; use the generated artifacts instead.",
+		);
+	}
 
 	return {
 		prompt,
@@ -221,12 +232,12 @@ export function normalizeGenerateImageParams(
 		size,
 		quality,
 		model: normalizeRequestedModel(params.model),
+		batchSize,
 		action: referenceImagePaths.length > 0 ? "edit" : "generate",
 	};
 }
 
 export function buildImageGenerationRequest(args: {
-	routingModel: string;
 	imageModel: string;
 	params: NormalizedGenerateImageParams;
 	references: readonly PreparedReferenceImage[];
@@ -238,34 +249,14 @@ export function buildImageGenerationRequest(args: {
 			"A configured image generation model is required.",
 		);
 	}
-	const content: ImageGenerationRequestBody["input"][number]["content"] = [
-		{ type: "input_text", text: args.params.prompt },
-	];
-	for (const reference of args.references) {
-		content.push({
-			type: "input_image",
-			image_url: `data:${reference.mimeType};base64,${reference.bytes.toString("base64")}`,
-			detail: "auto",
-		});
-	}
-
 	return {
-		model: args.routingModel,
-		store: false,
-		stream: false,
-		parallel_tool_calls: false,
-		input: [{ role: "user", content }],
-		tools: [
-			{
-				type: "image_generation",
-				model: imageModel,
-				action: args.params.action,
-				size: args.params.size,
-				quality: args.params.quality,
-				output_format: "png",
-			},
-		],
-		tool_choice: { type: "image_generation" },
+		action: args.params.action,
+		model: imageModel,
+		prompt: args.params.prompt,
+		n: 1,
+		size: args.params.size,
+		quality: args.params.quality,
+		references: args.references,
 	};
 }
 
@@ -390,7 +381,7 @@ export function extractProviderErrorMessage(value: unknown, fallback: string): s
 	return fallback;
 }
 
-export function parseImageGenerationResponse(value: unknown): ParsedImageResponseResult {
+export function parseImagesApiResponse(value: unknown): ParsedImageResponseResult {
 	if (!isRecord(value)) {
 		return {
 			ok: false,
@@ -398,75 +389,47 @@ export function parseImageGenerationResponse(value: unknown): ParsedImageRespons
 			errorMessage: "Image generation returned a non-object response.",
 		};
 	}
-
-	if (value.status !== "completed") {
-		return {
-			ok: false,
-			reason: "request-rejected",
-			errorMessage: extractProviderErrorMessage(
-				value,
-				`Image generation did not complete (status: ${String(value.status ?? "unknown")}).`,
-			),
-		};
-	}
-	if (!Array.isArray(value.output)) {
+	if (!Array.isArray(value.data)) {
 		return {
 			ok: false,
 			reason: "malformed-response",
-			errorMessage: "Image generation response did not contain an output array.",
+			errorMessage: "Image generation response did not contain a data array.",
 		};
 	}
-
-	const calls = new Map<string, { result: string; revisedPrompt?: string }>();
-	for (let index = 0; index < value.output.length; index += 1) {
-		const item = value.output[index];
-		if (!isRecord(item) || item.type !== "image_generation_call") continue;
-		if (item.status !== "completed") continue;
-		const result = typeof item.result === "string"
-			? item.result
-			: typeof item.b64_json === "string"
-				? item.b64_json
-				: undefined;
-		if (!result?.trim()) continue;
-		const id = normalizedOptionalString(item.id, MAX_IMAGE_IDENTIFIER_CHARS) ?? `image_generation_${index}`;
-		const revisedPrompt = normalizedOptionalString(item.revised_prompt, MAX_IMAGE_DIAGNOSTIC_CHARS);
-		const existing = calls.get(id);
-		if (existing && existing.result !== result) {
-			return {
-				ok: false,
-				reason: "malformed-response",
-				errorMessage: "Image generation returned conflicting results for one image call.",
-			};
-		}
-		calls.set(id, { result, revisedPrompt: revisedPrompt ?? existing?.revisedPrompt });
-	}
-
-	if (calls.size === 0) {
+	if (value.data.length === 0) {
 		return {
 			ok: false,
 			reason: "no-image",
 			errorMessage: "Image generation completed without a usable image result.",
 		};
 	}
-	if (calls.size !== 1) {
+	if (value.data.length !== 1) {
 		return {
 			ok: false,
 			reason: "malformed-response",
-			errorMessage: "Image generation returned more than one image result for a single-image request.",
+			errorMessage: "Image generation returned more than one image for a single request.",
 		};
 	}
 
-	const [imageCallId, call] = [...calls.entries()][0]!;
-	const decoded = decodeGeneratedPng(call.result);
+	const item = value.data[0];
+	if (!isRecord(item) || typeof item.b64_json !== "string" || !item.b64_json.trim()) {
+		return {
+			ok: false,
+			reason: "no-image",
+			errorMessage: "Image generation response did not contain base64 image data.",
+		};
+	}
+	const decoded = decodeGeneratedPng(item.b64_json);
 	if (!decoded.ok) return decoded;
 
 	return {
 		ok: true,
 		image: {
 			bytes: decoded.bytes,
-			imageCallId,
+			imageCallId:
+				normalizedOptionalString(item.id, MAX_IMAGE_IDENTIFIER_CHARS) ?? "image_generation_0",
 			responseId: normalizedOptionalString(value.id, MAX_IMAGE_IDENTIFIER_CHARS),
-			revisedPrompt: call.revisedPrompt,
+			revisedPrompt: normalizedOptionalString(item.revised_prompt, MAX_IMAGE_DIAGNOSTIC_CHARS),
 			width: decoded.width,
 			height: decoded.height,
 		},

package/src/image-generation/render.ts

@@ -21,7 +21,7 @@ import {
 	MAX_GENERATED_IMAGE_BYTES,
 	isImageGenerationDetails,
 	type GenerateImageParams,
-	type ImageGenerationDetails,
+	type ImageGenerationToolDetails,
 } from "./types";
 
 export type ImageGenerationRenderState = Record<string, never>;
@@ -54,7 +54,7 @@ function isPathInsideOrEqual(root: string, candidate: string): boolean {
 	return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
 }
 
-function resultText(result: AgentToolResult<ImageGenerationDetails>): string {
+function resultText(result: AgentToolResult<ImageGenerationToolDetails>): string {
 	return result.content
 		.filter((block): block is { type: "text"; text: string } => block.type === "text")
 		.map((block) => block.text)
@@ -148,7 +148,7 @@ function textOnly(args: {
 export function createImageGenerationResultRenderer(
 	deps: ImageRendererDependencies = DEFAULT_RENDER_DEPS,
 ): (
-	result: AgentToolResult<ImageGenerationDetails>,
+	result: AgentToolResult<ImageGenerationToolDetails>,
 	options: ToolRenderResultOptions,
 	theme: Theme,
 	context: ImageGenerationRenderContext,

package/src/image-generation/service.ts

@@ -1,255 +1,356 @@
-import { getAgentDir, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { assertConfigValid, loadToolkitConfig, resolveToolkitConfig } from "../config";
-import { notifyConfigIssues } from "../config/notifications";
-import { resolveResponsesEnvironment } from "../runtime";
-import {
-	copyImageToExplicitPath,
-	prepareExplicitOutputPath,
-	saveCanonicalImage,
-} from "./artifacts";
-import { requestGeneratedImage } from "./client";
-import { isImageGenerationEnabledForModel } from "./eligibility";
-import {
-	buildImageGenerationRequest,
-	normalizeGenerateImageParams,
-	selectImageGenerationModel,
-} from "./protocol";
-import {
-	clearPreparedReferences,
-	prepareReferenceImages,
-} from "./references";
-import {
-	IMAGE_GENERATION_CAPABLE_APIS,
-	IMAGE_GENERATION_MIME_TYPE,
-	ImageGenerationError,
-	sanitizeImageDiagnostic,
-	type GenerateImageParams,
-	type ImageGenerationExecutionResult,
-	type ImageGenerationFailureCode,
-	type ParsedGeneratedImage,
-} from "./types";
-
-export type ImageGenerationServiceDependencies = {
-	loadConfig: typeof loadToolkitConfig;
-	resolveRuntime: typeof resolveResponsesEnvironment;
-	getAgentDir: typeof getAgentDir;
-	prepareOutput: typeof prepareExplicitOutputPath;
-	prepareReferences: typeof prepareReferenceImages;
-	requestImage: typeof requestGeneratedImage;
-	saveCanonical: typeof saveCanonicalImage;
-	copyExplicit: typeof copyImageToExplicitPath;
-	clearReferences: typeof clearPreparedReferences;
-};
-
-const DEFAULT_SERVICE_DEPS: ImageGenerationServiceDependencies = {
-	loadConfig: loadToolkitConfig,
-	resolveRuntime: resolveResponsesEnvironment,
-	getAgentDir,
-	prepareOutput: prepareExplicitOutputPath,
-	prepareReferences: prepareReferenceImages,
-	requestImage: requestGeneratedImage,
-	saveCanonical: saveCanonicalImage,
-	copyExplicit: copyImageToExplicitPath,
-	clearReferences: clearPreparedReferences,
-};
-
-function runtimeFailure(
-	reason: string,
-	errorMessage?: string,
-): ImageGenerationError {
-	switch (reason) {
-		case "disabled":
-			return new ImageGenerationError("disabled", "Image generation is disabled.");
-		case "unsupported-api":
-		case "missing-model":
-			return new ImageGenerationError(
-				"unsupported-model",
-				"Image generation is unavailable for the current model.",
-			);
-		case "missing-api-key":
-		case "auth-resolution-failed":
-			return new ImageGenerationError(
-				"authentication",
-				sanitizeImageDiagnostic(
-					errorMessage,
-					"Unable to resolve authentication for image generation with the current model.",
-				),
-			);
-		default:
-			return new ImageGenerationError(
-				"missing-runtime",
-				"Unable to resolve the current model's Responses endpoint for image generation.",
-			);
-	}
-}
-
-function throwIfAborted(signal: AbortSignal | undefined): void {
-	if (signal?.aborted) {
-		throw new ImageGenerationError("aborted", "Image generation was cancelled.");
-	}
-}
-
-function clientFailureCode(reason: string): ImageGenerationFailureCode {
-	switch (reason) {
-		case "aborted":
-		case "timeout":
-		case "authentication":
-		case "rate-limit":
-		case "request-rejected":
-		case "backend-unavailable":
-		case "network":
-		case "oversized-response":
-		case "malformed-response":
-		case "no-image":
-			return reason;
-		default:
-			return "network";
-	}
-}
-
-function formatResultText(args: {
-	artifactPath: string;
-	outputPath?: string;
-	warning?: string;
-	edited: boolean;
-	width: number;
-	height: number;
-}): string {
-	const lines = [
-		`${args.edited ? "Edited" : "Generated"} PNG image (${args.width}x${args.height}).`,
-		`Artifact: ${args.artifactPath}`,
-	];
-	if (args.outputPath) lines.push(`Copied to: ${args.outputPath}`);
-	if (args.warning) lines.push(`Warning: ${args.warning}`);
-	return lines.join("\n");
-}
-
-export function createImageGenerationExecutor(
-	deps: ImageGenerationServiceDependencies = DEFAULT_SERVICE_DEPS,
-): (args: {
-	params: GenerateImageParams;
-	toolCallId: string;
-	signal?: AbortSignal;
-	ctx: ExtensionContext;
-}) => Promise<ImageGenerationExecutionResult> {
-	return async (args) => {
-		const params = normalizeGenerateImageParams(args.params);
-		throwIfAborted(args.signal);
-		const resolved = resolveToolkitConfig(deps.loadConfig(), args.ctx.model);
-		notifyConfigIssues(args.ctx, resolved);
-		assertConfigValid(resolved, "imageGeneration", "compatibility");
-		const { config } = resolved;
-		if (!isImageGenerationEnabledForModel(args.ctx.model, config.imageGeneration)) {
-			throw new ImageGenerationError(
-				"unsupported-model",
-				"Image generation is not enabled for the current provider/model-id.",
-			);
-		}
-
-		const imageModel = selectImageGenerationModel({
-			requestedModel: params.model,
-			configuredModels: resolved.policy.imageGeneration.allowedModels,
-			defaultModel: resolved.policy.imageGeneration.defaultModel,
-		});
-
-		const runtimeResolution = await deps.resolveRuntime(args.ctx, {
-			enabled: config.imageGeneration.enabled,
-			responsesApis: IMAGE_GENERATION_CAPABLE_APIS,
-			...(resolved.format === "v2" ? { codexGatewayModels: resolved.gatewayModelKeys } : {}),
-		});
-		if (!runtimeResolution.ok) {
-			throw runtimeFailure(runtimeResolution.reason, runtimeResolution.errorMessage);
-		}
-
-		const agentDir = deps.getAgentDir();
-		const explicitOutput = await deps.prepareOutput({
-			rawPath: params.outputPath,
-			agentDir,
-			ctx: args.ctx,
-			signal: args.signal,
-		});
-
-		const references = await deps.prepareReferences({
-			paths: params.referenceImagePaths,
-			ctx: args.ctx,
-			signal: args.signal,
-		});
-		let generated: ParsedGeneratedImage | undefined;
-		try {
-			throwIfAborted(args.signal);
-			const body = buildImageGenerationRequest({
-				routingModel: runtimeResolution.runtime.model,
-				imageModel,
-				params,
-				references,
-			});
-			const response = await deps.requestImage({
-				runtime: runtimeResolution.runtime,
-				body,
-				signal: args.signal,
-			});
-			if (!response.ok) {
-				throw new ImageGenerationError(
-					clientFailureCode(response.reason),
-					response.errorMessage,
-				);
-			}
-			generated = response.image;
-
-			const artifactPath = await deps.saveCanonical({
-				bytes: generated.bytes,
-				agentDir,
-				sessionId: args.ctx.sessionManager.getSessionId(),
-				imageCallId: generated.imageCallId || args.toolCallId,
-			});
-
-			let outputPath: string | undefined;
-			let warning: string | undefined;
-			if (explicitOutput) {
-				try {
-					await deps.copyExplicit({ bytes: generated.bytes, plan: explicitOutput });
-					outputPath = explicitOutput.path;
-				} catch (error) {
-					warning = sanitizeImageDiagnostic(
-						error instanceof Error ? error.message : error,
-						`The generated image was saved to the canonical artifact, but copying to ${explicitOutput.path} failed.`,
-					);
-				}
-			}
-
-			const edited = references.length > 0;
-			const details = {
-				artifactPath,
-				...(outputPath ? { outputPath } : {}),
-				routingModel: `${runtimeResolution.runtime.provider}/${runtimeResolution.runtime.model}`,
-				imageModel,
-				imageCallId: generated.imageCallId,
-				...(generated.responseId ? { responseId: generated.responseId } : {}),
-				mimeType: IMAGE_GENERATION_MIME_TYPE,
-				byteCount: generated.bytes.length,
-				width: generated.width,
-				height: generated.height,
-				edited,
-				referenceCount: references.length,
-				...(generated.revisedPrompt ? { revisedPrompt: generated.revisedPrompt } : {}),
-				...(warning ? { warning } : {}),
-			};
-			return {
-				details,
-				text: formatResultText({
-					artifactPath,
-					outputPath,
-					warning,
-					edited,
-					width: generated.width,
-					height: generated.height,
-				}),
-			};
-		} finally {
-			deps.clearReferences(references);
-			generated?.bytes.fill(0);
-		}
-	};
-}
-
-export const executeImageGeneration = createImageGenerationExecutor();
+import { getAgentDir, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { assertConfigValid, loadToolkitConfig, resolveToolkitConfig } from "../config";
+import { notifyConfigIssues } from "../config/notifications";
+import { resolveResponsesEnvironment } from "../runtime";
+import {
+	copyImageToExplicitPath,
+	prepareExplicitOutputPath,
+	saveCanonicalImage,
+	type ExplicitOutputPlan,
+} from "./artifacts";
+import { requestGeneratedImage } from "./client";
+import { isImageGenerationEnabledForModel } from "./eligibility";
+import {
+	buildImageGenerationRequest,
+	normalizeGenerateImageParams,
+	selectImageGenerationModel,
+} from "./protocol";
+import {
+	clearPreparedReferences,
+	prepareReferenceImages,
+} from "./references";
+import {
+	IMAGE_GENERATION_CAPABLE_APIS,
+	IMAGE_GENERATION_MIME_TYPE,
+	MAX_IMAGE_IDENTIFIER_CHARS,
+	ImageGenerationError,
+	sanitizeImageDiagnostic,
+	type GenerateImageParams,
+	type ImageGenerationBatchDetails,
+	type ImageGenerationExecutionResult,
+	type ImageGenerationFailureCode,
+	type ImageGenerationDetails,
+	type ParsedGeneratedImage,
+} from "./types";
+
+export type ImageGenerationServiceDependencies = {
+	loadConfig: typeof loadToolkitConfig;
+	resolveRuntime: typeof resolveResponsesEnvironment;
+	getAgentDir: typeof getAgentDir;
+	prepareOutput: typeof prepareExplicitOutputPath;
+	prepareReferences: typeof prepareReferenceImages;
+	requestImage: typeof requestGeneratedImage;
+	saveCanonical: typeof saveCanonicalImage;
+	copyExplicit: typeof copyImageToExplicitPath;
+	clearReferences: typeof clearPreparedReferences;
+};
+
+const DEFAULT_SERVICE_DEPS: ImageGenerationServiceDependencies = {
+	loadConfig: loadToolkitConfig,
+	resolveRuntime: resolveResponsesEnvironment,
+	getAgentDir,
+	prepareOutput: prepareExplicitOutputPath,
+	prepareReferences: prepareReferenceImages,
+	requestImage: requestGeneratedImage,
+	saveCanonical: saveCanonicalImage,
+	copyExplicit: copyImageToExplicitPath,
+	clearReferences: clearPreparedReferences,
+};
+
+function runtimeFailure(
+	reason: string,
+	errorMessage?: string,
+): ImageGenerationError {
+	switch (reason) {
+		case "disabled":
+			return new ImageGenerationError("disabled", "Image generation is disabled.");
+		case "unsupported-api":
+		case "missing-model":
+			return new ImageGenerationError(
+				"unsupported-model",
+				"Image generation is unavailable for the current model.",
+			);
+		case "missing-api-key":
+		case "auth-resolution-failed":
+			return new ImageGenerationError(
+				"authentication",
+				sanitizeImageDiagnostic(
+					errorMessage,
+					"Unable to resolve authentication for image generation with the current model.",
+				),
+			);
+		default:
+			return new ImageGenerationError(
+				"missing-runtime",
+				"Unable to resolve the current model's Images endpoint for image generation.",
+			);
+	}
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) {
+		throw new ImageGenerationError("aborted", "Image generation was cancelled.");
+	}
+}
+
+function clientFailureCode(reason: string): ImageGenerationFailureCode {
+	switch (reason) {
+		case "aborted":
+		case "timeout":
+		case "authentication":
+		case "rate-limit":
+		case "request-rejected":
+		case "backend-unavailable":
+		case "network":
+		case "oversized-response":
+		case "malformed-response":
+		case "no-image":
+			return reason;
+		default:
+			return "network";
+	}
+}
+
+function asImageGenerationError(value: unknown): ImageGenerationError {
+	if (value instanceof ImageGenerationError) {
+		return new ImageGenerationError(
+			value.code,
+			sanitizeImageDiagnostic(value.message, "Image generation failed."),
+		);
+	}
+	return new ImageGenerationError(
+		"network",
+		sanitizeImageDiagnostic(value instanceof Error ? value.message : value, "Image generation failed."),
+	);
+}
+
+function formatResultText(args: {
+	artifactPath: string;
+	outputPath?: string;
+	warning?: string;
+	edited: boolean;
+	width: number;
+	height: number;
+}): string {
+	const lines = [
+		`${args.edited ? "Edited" : "Generated"} PNG image (${args.width}x${args.height}).`,
+		`Artifact: ${args.artifactPath}`,
+	];
+	if (args.outputPath) lines.push(`Copied to: ${args.outputPath}`);
+	if (args.warning) lines.push(`Warning: ${args.warning}`);
+	return lines.join("\n");
+}
+
+function formatBatchResultText(details: ImageGenerationBatchDetails): string {
+	const lines = [`Generated ${details.succeededCount}/${details.requestedCount} PNG images.`];
+	const failedIndexes = new Set((details.failures ?? []).map((failure) => failure.index));
+	let imageIndex = 0;
+	for (let batchIndex = 0; batchIndex < details.requestedCount; batchIndex += 1) {
+		if (failedIndexes.has(batchIndex)) continue;
+		const image = details.images[imageIndex++];
+		if (image) lines.push(`Image ${batchIndex + 1}: ${image.artifactPath}`);
+	}
+	for (const failure of details.failures ?? []) {
+		lines.push(`Image ${failure.index + 1} failed: ${failure.message}`);
+	}
+	return lines.join("\n");
+}
+
+function batchImageCallId(imageCallId: string, batchIndex: number, batchSize: number): string {
+	if (batchSize === 1) return imageCallId;
+	const suffix = `-batch-${batchIndex + 1}`;
+	return `${imageCallId.slice(0, Math.max(1, MAX_IMAGE_IDENTIFIER_CHARS - suffix.length))}${suffix}`;
+}
+
+async function persistGeneratedImage(args: {
+	generated: ParsedGeneratedImage;
+	params: ReturnType<typeof normalizeGenerateImageParams>;
+	batchIndex: number;
+	toolCallId: string;
+	batchSize: number;
+	imageModel: string;
+	routingModel: string;
+	agentDir: string;
+	sessionId: string;
+	referencesCount: number;
+	explicitOutput?: ExplicitOutputPlan;
+	deps: ImageGenerationServiceDependencies;
+}): Promise<ImageGenerationDetails> {
+	const imageCallId = batchImageCallId(args.generated.imageCallId || args.toolCallId, args.batchIndex, args.batchSize);
+	try {
+		const artifactPath = await args.deps.saveCanonical({
+			bytes: args.generated.bytes,
+			agentDir: args.agentDir,
+			sessionId: args.sessionId,
+			imageCallId,
+		});
+
+		let outputPath: string | undefined;
+		let warning: string | undefined;
+		if (args.explicitOutput) {
+			try {
+				await args.deps.copyExplicit({ bytes: args.generated.bytes, plan: args.explicitOutput });
+				outputPath = args.explicitOutput.path;
+			} catch (error) {
+				warning = sanitizeImageDiagnostic(
+					error instanceof Error ? error.message : error,
+					`The generated image was saved to the canonical artifact, but copying to ${args.explicitOutput.path} failed.`,
+				);
+			}
+		}
+
+		return {
+			artifactPath,
+			...(outputPath ? { outputPath } : {}),
+			routingModel: args.routingModel,
+			imageModel: args.imageModel,
+			imageCallId,
+			...(args.generated.responseId ? { responseId: args.generated.responseId } : {}),
+			mimeType: IMAGE_GENERATION_MIME_TYPE,
+			byteCount: args.generated.bytes.length,
+			width: args.generated.width,
+			height: args.generated.height,
+			edited: args.params.action === "edit",
+			referenceCount: args.referencesCount,
+			...(args.generated.revisedPrompt ? { revisedPrompt: args.generated.revisedPrompt } : {}),
+			...(warning ? { warning } : {}),
+		};
+	} finally {
+		args.generated.bytes.fill(0);
+	}
+}
+
+export function createImageGenerationExecutor(
+	deps: ImageGenerationServiceDependencies = DEFAULT_SERVICE_DEPS,
+): (args: {
+	params: GenerateImageParams;
+	toolCallId: string;
+	signal?: AbortSignal;
+	ctx: ExtensionContext;
+}) => Promise<ImageGenerationExecutionResult> {
+	return async (args) => {
+		const params = normalizeGenerateImageParams(args.params);
+		throwIfAborted(args.signal);
+		const resolved = resolveToolkitConfig(deps.loadConfig(), args.ctx.model);
+		notifyConfigIssues(args.ctx, resolved);
+		assertConfigValid(resolved, "imageGeneration", "compatibility");
+		const { config } = resolved;
+		if (!isImageGenerationEnabledForModel(args.ctx.model, config.imageGeneration)) {
+			throw new ImageGenerationError(
+				"unsupported-model",
+				"Image generation is not enabled for the current provider/model-id.",
+			);
+		}
+
+		const imageModel = selectImageGenerationModel({
+			requestedModel: params.model,
+			configuredModels: resolved.policy.imageGeneration.allowedModels,
+			defaultModel: resolved.policy.imageGeneration.defaultModel,
+		});
+
+		const runtimeResolution = await deps.resolveRuntime(args.ctx, {
+			enabled: config.imageGeneration.enabled,
+			responsesApis: IMAGE_GENERATION_CAPABLE_APIS,
+			...(resolved.format === "v2" ? { codexGatewayModels: resolved.gatewayModelKeys } : {}),
+		});
+		if (!runtimeResolution.ok) {
+			throw runtimeFailure(runtimeResolution.reason, runtimeResolution.errorMessage);
+		}
+
+		const agentDir = deps.getAgentDir();
+		const explicitOutput = await deps.prepareOutput({
+			rawPath: params.outputPath,
+			agentDir,
+			ctx: args.ctx,
+			signal: args.signal,
+		});
+
+		const references = await deps.prepareReferences({
+			paths: params.referenceImagePaths,
+			ctx: args.ctx,
+			signal: args.signal,
+		});
+		try {
+			const jobs = Array.from({ length: params.batchSize }, (_, batchIndex) =>
+				(async () => {
+					throwIfAborted(args.signal);
+					const body = buildImageGenerationRequest({
+						imageModel,
+						params,
+						references,
+					});
+					const response = await deps.requestImage({
+						runtime: runtimeResolution.runtime,
+						body,
+						signal: args.signal,
+					});
+					if (!response.ok) {
+						throw new ImageGenerationError(
+							clientFailureCode(response.reason),
+							sanitizeImageDiagnostic(response.errorMessage, "Image generation request failed."),
+						);
+					}
+					return persistGeneratedImage({
+						generated: response.image,
+						params,
+						batchIndex,
+						toolCallId: args.toolCallId,
+						batchSize: params.batchSize,
+						imageModel,
+						routingModel: `${runtimeResolution.runtime.provider}/${runtimeResolution.runtime.model}`,
+						agentDir,
+						sessionId: args.ctx.sessionManager.getSessionId(),
+						referencesCount: references.length,
+						explicitOutput,
+						deps,
+					});
+				})(),
+			);
+			const settled = await Promise.allSettled(jobs);
+			const images: ImageGenerationDetails[] = [];
+			const failures: ImageGenerationBatchDetails["failures"] = [];
+			for (const [index, result] of settled.entries()) {
+				if (result.status === "fulfilled") {
+					images.push(result.value);
+				} else {
+					const error = asImageGenerationError(result.reason);
+					failures.push({ index, code: error.code, message: error.message });
+				}
+			}
+
+			if (images.length === 0) {
+				const firstFailure = settled.find((result) => result.status === "rejected");
+				throw asImageGenerationError(firstFailure && firstFailure.status === "rejected" ? firstFailure.reason : "Image generation failed.");
+			}
+
+			if (params.batchSize === 1) {
+				const details = images[0]!;
+				return {
+					details,
+					text: formatResultText({
+						artifactPath: details.artifactPath,
+						outputPath: details.outputPath,
+						warning: details.warning,
+						edited: details.edited,
+						width: details.width,
+						height: details.height,
+					}),
+				};
+			}
+
+			const batchDetails: ImageGenerationBatchDetails = {
+				batch: true,
+				requestedCount: params.batchSize,
+				succeededCount: images.length,
+				failedCount: failures.length,
+				images,
+				...(failures.length > 0 ? { failures } : {}),
+			};
+			return { details: batchDetails, text: formatBatchResultText(batchDetails) };
+		} finally {
+			deps.clearReferences(references);
+		}
+	};
+}
+
+export const executeImageGeneration = createImageGenerationExecutor();

package/src/image-generation/types.ts

@@ -23,8 +23,9 @@ export const IMAGE_REQUEST_TIMEOUT_MS = 5 * 60 * 1000;
 export const MAX_IMAGE_PATH_CHARS = 4096;
 export const MAX_IMAGE_DIAGNOSTIC_CHARS = 4096;
 export const MAX_IMAGE_IDENTIFIER_CHARS = 256;
-/** Upper bound for a configured or requested `image_generation` model id. */
+/** Upper bound for a configured or requested Images API model id. */
 export const MAX_IMAGE_MODEL_ID_CHARS = 256;
+export const MAX_IMAGE_BATCH_SIZE = 10;
 export const MAX_IMAGE_DIMENSION = 100_000;
 
 export type ImageGenerationCapableApi = (typeof IMAGE_GENERATION_CAPABLE_APIS)[number];
@@ -45,8 +46,10 @@ export type GenerateImageParams = {
 	outputPath?: string | null;
 	size?: ImageGenerationSize;
 	quality?: ImageGenerationQuality;
-	/** Optional bare image model id that must exist in `imageGeneration.models`. */
+	/** Optional bare image model id that must exist in the configured image model allowlist. */
 	model?: string | null;
+	/** Number of independent image requests to run concurrently. */
+	batchSize?: number | null;
 };
 
 export type NormalizedGenerateImageParams = {
@@ -56,6 +59,7 @@ export type NormalizedGenerateImageParams = {
 	size: ImageGenerationSize;
 	quality: ImageGenerationQuality;
 	action: ImageGenerationAction;
+	batchSize: number;
 	/** Trimmed requested model id, or undefined when the caller omitted it. */
 	model?: string;
 };
@@ -92,8 +96,25 @@ export type ImageGenerationDetails = {
 	warning?: string;
 };
 
+export type ImageGenerationBatchFailure = {
+	index: number;
+	code: ImageGenerationFailureCode;
+	message: string;
+};
+
+export type ImageGenerationBatchDetails = {
+	batch: true;
+	requestedCount: number;
+	succeededCount: number;
+	failedCount: number;
+	images: ImageGenerationDetails[];
+	failures?: ImageGenerationBatchFailure[];
+};
+
+export type ImageGenerationToolDetails = ImageGenerationDetails | ImageGenerationBatchDetails;
+
 export type ImageGenerationExecutionResult = {
-	details: ImageGenerationDetails;
+	details: ImageGenerationToolDetails;
 	text: string;
 };
 
@@ -120,6 +141,35 @@ export type ImageGenerationFailureCode =
 	| "no-image"
 	| "artifact-write-failed";
 
+function isImageGenerationFailureCode(value: unknown): value is ImageGenerationFailureCode {
+	switch (value) {
+		case "aborted":
+		case "timeout":
+		case "disabled":
+		case "unsupported-model":
+		case "missing-runtime":
+		case "invalid-parameters":
+		case "reference-input-invalid":
+		case "reference-upload-approval-required":
+		case "reference-upload-declined":
+		case "output-path-invalid":
+		case "output-path-approval-required":
+		case "output-path-declined":
+		case "authentication":
+		case "rate-limit":
+		case "request-rejected":
+		case "backend-unavailable":
+		case "network":
+		case "oversized-response":
+		case "malformed-response":
+		case "no-image":
+		case "artifact-write-failed":
+			return true;
+		default:
+			return false;
+	}
+}
+
 export class ImageGenerationError extends Error {
 	readonly code: ImageGenerationFailureCode;
 
@@ -170,6 +220,47 @@ export function isImageGenerationDetails(value: unknown): value is ImageGenerati
 	);
 }
 
+function isBoundedIndex(value: unknown, maximum: number): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 && value < maximum;
+}
+
+export function isImageGenerationBatchDetails(value: unknown): value is ImageGenerationBatchDetails {
+	if (!isRecord(value) || value.batch !== true) return false;
+	if (
+		typeof value.requestedCount !== "number" ||
+		!Number.isInteger(value.requestedCount) ||
+		value.requestedCount < 2 ||
+		value.requestedCount > MAX_IMAGE_BATCH_SIZE ||
+		typeof value.succeededCount !== "number" ||
+		!Number.isInteger(value.succeededCount) ||
+		value.succeededCount < 1 ||
+		value.succeededCount > value.requestedCount ||
+		typeof value.failedCount !== "number" ||
+		!Number.isInteger(value.failedCount) ||
+		value.failedCount !== value.requestedCount - value.succeededCount ||
+		!Array.isArray(value.images) ||
+		value.images.length !== value.succeededCount ||
+		!value.images.every(isImageGenerationDetails)
+	) {
+		return false;
+	}
+	if (value.failedCount === 0) return value.failures === undefined;
+	if (!Array.isArray(value.failures) || value.failures.length !== value.failedCount) return false;
+	const requestedCount = value.requestedCount;
+	const indexes = new Set<number>();
+	return value.failures.every((failure) => {
+		if (!isRecord(failure) || !isBoundedIndex(failure.index, requestedCount)) return false;
+		if (!isImageGenerationFailureCode(failure.code) || !isBoundedString(failure.message, MAX_IMAGE_DIAGNOSTIC_CHARS)) return false;
+		if (indexes.has(failure.index)) return false;
+		indexes.add(failure.index);
+		return true;
+	});
+}
+
+export function isImageGenerationToolDetails(value: unknown): value is ImageGenerationToolDetails {
+	return isImageGenerationDetails(value) || isImageGenerationBatchDetails(value);
+}
+
 export function sanitizeImageDiagnostic(value: unknown, fallback: string): string {
 	if (typeof value !== "string") return fallback;
 	const normalized = value

package/src/responses-headers.ts

@@ -107,7 +107,8 @@ export function clampCodexSessionId(sessionId: string | undefined): string | und
 
 export type ResponsesHeaderOptions = {
 	accept: string;
-	contentType?: string;
+	/** `null` omits content-type so a multipart FormData body can set its boundary. */
+	contentType?: string | null;
 	/** Conversation identity for Codex cache-affinity headers; clamped to 64 chars here. */
 	sessionId?: string;
 };
@@ -121,7 +122,11 @@ export function buildResponsesRequestHeaders(
 		runtime.codexAffinity ? filterCodexGatewayHeaders(mergedHeaders) : mergedHeaders,
 	);
 	headers.set("accept", options.accept);
-	headers.set("content-type", options.contentType ?? "application/json");
+	if (options.contentType === null) {
+		headers.delete("content-type");
+	} else {
+		headers.set("content-type", options.contentType ?? "application/json");
+	}
 	if (!headers.has("authorization")) {
 		headers.set("authorization", `Bearer ${runtime.apiKey}`);
 	}

package/src/types.ts

@@ -151,9 +151,9 @@ export type WebSearchConfig = {
 export type ImageGenerationConfig = {
 	enabled: boolean;
 	/**
-	 * Bare `image_generation` tool model ids this toolkit may send, without a `provider/` prefix.
-	 * The first entry is the default; `openai_generate_image`'s optional `model` argument may
-	 * select any other entry in this order-preserving list.
+	 * Bare Images API model ids this toolkit may send, without a `provider/` prefix.
+	 * The first legacy entry is the default; `openai_generate_image`'s optional `model` argument
+	 * may select any other entry in this order-preserving list.
 	 */
 	models: string[];
 };