@axhub/acp 0.1.0

package/dist/tools/image-generation/service.mjs

@@ -0,0 +1,978 @@
+import crypto from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const IMAGE_GENERATION_MCP_NAME = "acp-ui-image-generation";
+export const IMAGE_GENERATION_TOOL_NAME = "generate_image";
+export const IMAGE_GENERATION_TOOL_ID = "image-generation";
+
+const TOOL_DIR = path.dirname(fileURLToPath(import.meta.url));
+const INDEX_FILE = "index.json";
+const CONVERSATION_STORE_PATH = path.join(
+	".axhub",
+	"sessions",
+	"conversations.json",
+);
+const DEFAULT_CONFIG = {
+	provider: "openai",
+	baseUrl: "https://api.openai.com/v1",
+	apiKey: "",
+	model: "",
+	outputDir: ".axhub/sessions/image-generation",
+	maxInputBytes: 10 * 1024 * 1024,
+	maxOutputBytes: 50 * 1024 * 1024,
+	downloadTimeoutMs: 30_000,
+	requestTimeoutMs: 180_000,
+	allowSavePath: true,
+	savePathBaseDir: ".",
+	savePathPattern: "",
+	preservePrompt: true,
+};
+const PROMPT_REWRITE_GUARD_PREFIX =
+	"Use the following text as the complete prompt. Do not rewrite it:";
+const SUPPORTED_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/webp"]);
+
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function createId() {
+	return crypto.randomBytes(16).toString("hex");
+}
+
+function nowIso() {
+	return new Date().toISOString();
+}
+
+function normalizeWorkspacePath(workspacePath) {
+	const fallback = path.resolve(/* turbopackIgnore: true */ process.cwd());
+	const raw =
+		typeof workspacePath === "string" && workspacePath.trim()
+			? workspacePath.trim()
+			: fallback;
+	const resolved = path.resolve(/* turbopackIgnore: true */ raw);
+	try {
+		return fsSync.statSync(/* turbopackIgnore: true */ resolved).isDirectory()
+			? resolved
+			: fallback;
+	} catch {
+		return fallback;
+	}
+}
+
+function readJsonFile(filePath) {
+	if (!fsSync.existsSync(/* turbopackIgnore: true */ filePath)) return null;
+	return JSON.parse(
+		fsSync.readFileSync(/* turbopackIgnore: true */ filePath, "utf8"),
+	);
+}
+
+function stringValue(value, fallback) {
+	return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+function booleanValue(value, fallback) {
+	return typeof value === "boolean" ? value : fallback;
+}
+
+function numberValue(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0
+		? value
+		: fallback;
+}
+
+function mergeConfig(base, raw) {
+	if (!isRecord(raw)) return base;
+	return {
+		...base,
+		provider: stringValue(raw.provider, base.provider),
+		baseUrl: stringValue(raw.baseUrl, base.baseUrl).replace(/\/+$/, ""),
+		apiKey: stringValue(raw.apiKey, base.apiKey),
+		model: stringValue(raw.model, base.model),
+		outputDir: stringValue(raw.outputDir, base.outputDir),
+		maxInputBytes: numberValue(raw.maxInputBytes, base.maxInputBytes),
+		maxOutputBytes: numberValue(raw.maxOutputBytes, base.maxOutputBytes),
+		downloadTimeoutMs: numberValue(
+			raw.downloadTimeoutMs,
+			base.downloadTimeoutMs,
+		),
+		requestTimeoutMs: numberValue(raw.requestTimeoutMs, base.requestTimeoutMs),
+		allowSavePath: booleanValue(raw.allowSavePath, base.allowSavePath),
+		savePathBaseDir: stringValue(raw.savePathBaseDir, base.savePathBaseDir),
+		savePathPattern: stringValue(raw.savePathPattern, base.savePathPattern),
+		preservePrompt: booleanValue(raw.preservePrompt, base.preservePrompt),
+	};
+}
+
+function normalizeRuntimeSettings(value) {
+	if (!isRecord(value)) return null;
+	return {
+		...(typeof value.baseUrl === "string" && value.baseUrl.trim()
+			? { baseUrl: value.baseUrl.trim().replace(/\/+$/, "") }
+			: {}),
+		...(typeof value.apiKey === "string" && value.apiKey.trim()
+			? { apiKey: value.apiKey.trim() }
+			: {}),
+		...(typeof value.model === "string" && value.model.trim()
+			? { model: value.model.trim() }
+			: {}),
+		...(typeof value.savePathPattern === "string" &&
+		value.savePathPattern.trim()
+			? { savePathPattern: value.savePathPattern.trim() }
+			: {}),
+		...(typeof value.preservePrompt === "boolean"
+			? { preservePrompt: value.preservePrompt }
+			: {}),
+	};
+}
+
+function getConversationStorePath(workspacePath) {
+	const overridePath = process.env.ACP_UI_CONVERSATION_STORE;
+	if (overridePath)
+		return path.resolve(/* turbopackIgnore: true */ overridePath);
+	return path.join(
+		/* turbopackIgnore: true */ normalizeWorkspacePath(workspacePath),
+		CONVERSATION_STORE_PATH,
+	);
+}
+
+function readThreadRuntimeSettings({ workspacePath, threadId }) {
+	const normalizedThreadId =
+		typeof threadId === "string" && threadId.trim() ? threadId.trim() : null;
+	if (!normalizedThreadId) return null;
+	try {
+		const store = readJsonFile(getConversationStorePath(workspacePath));
+		const conversations = Array.isArray(store?.conversations)
+			? store.conversations
+			: [];
+		const conversation = conversations.find(
+			(entry) =>
+				isRecord(entry) &&
+				entry.threadId === normalizedThreadId &&
+				entry.status !== "deleted",
+		);
+		const builtinToolSettings = conversation?.builtinToolSettings;
+		return normalizeRuntimeSettings(
+			builtinToolSettings?.[IMAGE_GENERATION_TOOL_ID] ??
+				builtinToolSettings?.imageGeneration,
+		);
+	} catch {
+		return null;
+	}
+}
+
+function resolveOutputDir(outputDir, workspacePath) {
+	if (path.isAbsolute(outputDir)) return outputDir;
+	return path.resolve(
+		/* turbopackIgnore: true */ normalizeWorkspacePath(workspacePath),
+		outputDir,
+	);
+}
+
+function resolveSavePathBaseDir(savePathBaseDir, workspacePath) {
+	const workspace = normalizeWorkspacePath(workspacePath);
+	if (path.isAbsolute(savePathBaseDir)) return savePathBaseDir;
+	return path.resolve(/* turbopackIgnore: true */ workspace, savePathBaseDir);
+}
+
+export function getImageGenerationToolDir() {
+	return TOOL_DIR;
+}
+
+export function loadImageGenerationConfig(options = {}) {
+	const exampleConfig = readJsonFile(
+		path.join(TOOL_DIR, "config.example.json"),
+	);
+	const localConfig = readJsonFile(path.join(TOOL_DIR, "config.local.json"));
+	const threadRuntimeSettings = readThreadRuntimeSettings({
+		workspacePath: options.workspacePath,
+		threadId: options.threadId,
+	});
+	const runtimeSettings = normalizeRuntimeSettings(options.runtimeSettings);
+	const merged = mergeConfig(
+		mergeConfig(
+			mergeConfig(mergeConfig(DEFAULT_CONFIG, exampleConfig), localConfig),
+			threadRuntimeSettings,
+		),
+		runtimeSettings,
+	);
+	return {
+		...merged,
+		outputDir: resolveOutputDir(merged.outputDir, options.workspacePath),
+		savePathBaseDir: resolveSavePathBaseDir(
+			merged.savePathBaseDir,
+			options.workspacePath,
+		),
+	};
+}
+
+function mimeToExtension(mimeType) {
+	if (mimeType === "image/jpeg") return "jpg";
+	if (mimeType === "image/webp") return "webp";
+	return "png";
+}
+
+function normalizeSavePathPattern(value) {
+	if (typeof value !== "string") return null;
+	const pattern = value.trim().replace(/\\/g, "/");
+	if (!pattern || pattern.startsWith("/") || pattern.includes("\0"))
+		return null;
+	if (pattern.split("/").some((segment) => segment === "..")) return null;
+	if (!pattern.includes("<index>") && !pattern.includes("{index}")) return null;
+	if (!path.basename(pattern)) return null;
+	return pattern;
+}
+
+function savePathFromPattern({ pattern, index, mimeType, params }) {
+	const normalizedPattern = normalizeSavePathPattern(pattern);
+	if (!normalizedPattern) return null;
+	const extension = mimeToExtension(
+		mimeType || mimeFromOutputFormat(params?.outputFormat),
+	);
+	return normalizedPattern
+		.replace(/<index>/g, String(index))
+		.replace(/\{index\}/g, String(index))
+		.replace(/<ext>/g, extension)
+		.replace(/\{ext\}/g, extension);
+}
+
+function availableSavePathFromPattern({
+	pattern,
+	mimeType,
+	params,
+	config,
+	workspacePath,
+}) {
+	for (let index = 1; index <= 999; index += 1) {
+		const savePath = savePathFromPattern({ pattern, index, mimeType, params });
+		if (!savePath) return null;
+		const resolved = resolveValidatedSavePath({
+			savePath,
+			config,
+			workspacePath,
+		});
+		if (
+			resolved &&
+			!fsSync.existsSync(/* turbopackIgnore: true */ resolved.absolutePath)
+		)
+			return savePath;
+	}
+	throw new Error("No available image savePathPattern slot.");
+}
+
+function sniffMime(buffer, fallback) {
+	if (
+		buffer.length >= 8 &&
+		buffer[0] === 0x89 &&
+		buffer[1] === 0x50 &&
+		buffer[2] === 0x4e &&
+		buffer[3] === 0x47
+	) {
+		return "image/png";
+	}
+	if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8) {
+		return "image/jpeg";
+	}
+	if (
+		buffer.length >= 12 &&
+		buffer.subarray(0, 4).toString("ascii") === "RIFF" &&
+		buffer.subarray(8, 12).toString("ascii") === "WEBP"
+	) {
+		return "image/webp";
+	}
+	return fallback ?? "application/octet-stream";
+}
+
+function assertSupportedImage(buffer, mimeType, maxBytes) {
+	if (buffer.byteLength > maxBytes) {
+		throw new Error(
+			`Input image is too large (${buffer.byteLength} bytes, max ${maxBytes}).`,
+		);
+	}
+	if (!SUPPORTED_MIME_TYPES.has(mimeType)) {
+		throw new Error(`Unsupported input image MIME type: ${mimeType}.`);
+	}
+}
+
+function isPathInside(parent, candidate) {
+	const relative = path.relative(parent, candidate);
+	return (
+		Boolean(relative) &&
+		!relative.startsWith("..") &&
+		!path.isAbsolute(relative)
+	);
+}
+
+function isPathInsideOrEqual(parent, candidate) {
+	const relative = path.relative(parent, candidate);
+	return (
+		relative === "" ||
+		(!relative.startsWith("..") && !path.isAbsolute(relative))
+	);
+}
+
+function normalizeSavePath(savePath) {
+	if (typeof savePath !== "string") return null;
+	const normalized = savePath.trim().replace(/\\/g, "/");
+	return normalized || null;
+}
+
+function resolveValidatedSavePath({ savePath, config, workspacePath }) {
+	const normalized = normalizeSavePath(savePath);
+	if (!normalized) return null;
+	if (!config.allowSavePath) {
+		throw new Error("Custom image savePath is disabled in config.");
+	}
+	if (path.isAbsolute(normalized)) {
+		throw new Error("Image savePath must be relative to the workspace.");
+	}
+	if (normalized.split("/").some((part) => part === "..")) {
+		throw new Error("Image savePath cannot contain '..' path segments.");
+	}
+	if (normalized.endsWith("/")) {
+		throw new Error("Image savePath must include a file name.");
+	}
+
+	const workspace = normalizeWorkspacePath(workspacePath);
+	const baseDir = path.resolve(config.savePathBaseDir);
+	const absolutePath = path.resolve(baseDir, normalized);
+	if (!isPathInsideOrEqual(workspace, baseDir)) {
+		throw new Error(
+			"Configured image savePathBaseDir is outside the workspace.",
+		);
+	}
+	if (!isPathInsideOrEqual(workspace, absolutePath)) {
+		throw new Error("Image savePath must resolve inside the workspace.");
+	}
+	if (!isPathInsideOrEqual(baseDir, absolutePath)) {
+		throw new Error("Image savePath must resolve inside savePathBaseDir.");
+	}
+
+	return {
+		relativePath: path.relative(workspace, absolutePath).replace(/\\/g, "/"),
+		absolutePath,
+	};
+}
+
+function fileNameFromSavePath(savePath, fallback) {
+	if (!savePath) return fallback;
+	const baseName = path.basename(savePath);
+	return baseName && baseName !== "." ? baseName : fallback;
+}
+
+function parseDataUrl(value) {
+	const match = /^data:([^;,]+);base64,([\s\S]+)$/.exec(value);
+	if (!match) throw new Error("Invalid data URL image input.");
+	return {
+		mimeType: match[1].toLowerCase(),
+		buffer: Buffer.from(match[2], "base64"),
+	};
+}
+
+async function loadPathImage(source, config, workspacePath) {
+	const imagePath = path.resolve(
+		/* turbopackIgnore: true */ workspacePath,
+		source.value,
+	);
+	const outputPath = path.resolve(/* turbopackIgnore: true */ config.outputDir);
+	if (
+		!isPathInside(workspacePath, imagePath) &&
+		!isPathInside(outputPath, imagePath)
+	) {
+		throw new Error(
+			`Input image path is outside the workspace and image-generation output directory: ${source.value}`,
+		);
+	}
+	const buffer = await fs.readFile(imagePath);
+	const mimeType = sniffMime(buffer, source.mimeType);
+	assertSupportedImage(buffer, mimeType, config.maxInputBytes);
+	return {
+		buffer,
+		mimeType,
+		filename:
+			source.filename ||
+			path.basename(imagePath) ||
+			`input.${mimeToExtension(mimeType)}`,
+	};
+}
+
+async function loadUrlImage(source, config) {
+	const url = new URL(source.value);
+	if (url.protocol !== "http:" && url.protocol !== "https:") {
+		throw new Error("Only http(s) image URLs are supported.");
+	}
+	const response = await fetch(url, {
+		signal: AbortSignal.timeout(config.downloadTimeoutMs),
+	});
+	if (!response.ok) {
+		throw new Error(`Failed to download image URL: ${response.status}.`);
+	}
+	const buffer = Buffer.from(await response.arrayBuffer());
+	const mimeType = sniffMime(
+		buffer,
+		response.headers.get("content-type")?.split(";")[0] ?? source.mimeType,
+	);
+	assertSupportedImage(buffer, mimeType, config.maxInputBytes);
+	return {
+		buffer,
+		mimeType,
+		filename:
+			source.filename ||
+			path.basename(url.pathname) ||
+			`input.${mimeToExtension(mimeType)}`,
+	};
+}
+
+async function loadInlineImage(source, config) {
+	const parsed =
+		source.type === "data_url"
+			? parseDataUrl(source.value)
+			: {
+					mimeType: source.mimeType ?? "application/octet-stream",
+					buffer: Buffer.from(source.value, "base64"),
+				};
+	const mimeType = sniffMime(parsed.buffer, parsed.mimeType);
+	assertSupportedImage(parsed.buffer, mimeType, config.maxInputBytes);
+	return {
+		buffer: parsed.buffer,
+		mimeType,
+		filename: source.filename || `input.${mimeToExtension(mimeType)}`,
+	};
+}
+
+function normalizeParams(input, config) {
+	return {
+		model: input.model || config.model,
+		...(typeof input.size === "string" && input.size.trim()
+			? { size: input.size.trim() }
+			: {}),
+		...(typeof input.quality === "string" && input.quality.trim()
+			? { quality: input.quality.trim() }
+			: {}),
+		...(typeof input.outputFormat === "string" && input.outputFormat.trim()
+			? { outputFormat: input.outputFormat.trim() }
+			: {}),
+		...(typeof input.background === "string" && input.background.trim()
+			? { background: input.background.trim() }
+			: {}),
+	};
+}
+
+function appendFormParams(formData, params, prompt) {
+	formData.set("model", params.model);
+	formData.set("prompt", prompt);
+	formData.set("n", "1");
+	if (params.size) formData.set("size", params.size);
+	if (params.quality) formData.set("quality", params.quality);
+	if (params.outputFormat) formData.set("output_format", params.outputFormat);
+	if (params.background) formData.set("background", params.background);
+}
+
+function buildImageApiPrompt(prompt, config) {
+	const normalizedPrompt = String(prompt ?? "");
+	if (!config.preservePrompt) return normalizedPrompt;
+	if (normalizedPrompt.startsWith(PROMPT_REWRITE_GUARD_PREFIX)) {
+		return normalizedPrompt;
+	}
+	return `${PROMPT_REWRITE_GUARD_PREFIX}\n${normalizedPrompt}`;
+}
+
+function mimeFromOutputFormat(outputFormat) {
+	if (outputFormat === "jpeg") return "image/jpeg";
+	if (outputFormat === "webp") return "image/webp";
+	return "image/png";
+}
+
+function summarizeRawResponse(value) {
+	if (!isRecord(value)) return undefined;
+	const data = Array.isArray(value.data)
+		? value.data.map((item) => {
+				if (!isRecord(item)) return item;
+				return {
+					...item,
+					b64_json:
+						typeof item.b64_json === "string" ? "[base64]" : item.b64_json,
+				};
+			})
+		: undefined;
+	return {
+		...(typeof value.id === "string" ? { id: value.id } : {}),
+		...(typeof value.created === "number" ? { created: value.created } : {}),
+		...(data ? { data } : {}),
+	};
+}
+
+async function fetchImageUrl(url, config) {
+	const response = await fetch(url, {
+		signal: AbortSignal.timeout(config.downloadTimeoutMs),
+	});
+	if (!response.ok) throw new Error("Failed to fetch generated image URL.");
+	const buffer = Buffer.from(await response.arrayBuffer());
+	const mimeType = sniffMime(
+		buffer,
+		response.headers.get("content-type")?.split(";")[0] ?? undefined,
+	);
+	return { buffer, mimeType };
+}
+
+async function requestImageApi({ config, input, params, inputImages }) {
+	const endpoint =
+		inputImages.length > 0
+			? `${config.baseUrl}/images/edits`
+			: `${config.baseUrl}/images/generations`;
+	const headers = new Headers({
+		Authorization: `Bearer ${config.apiKey}`,
+	});
+	const prompt = buildImageApiPrompt(input.prompt, config);
+	let body;
+
+	if (inputImages.length > 0) {
+		const formData = new FormData();
+		appendFormParams(formData, params, prompt);
+		for (const image of inputImages) {
+			formData.append(
+				"image[]",
+				new Blob([new Uint8Array(image.buffer)], { type: image.mimeType }),
+				image.filename,
+			);
+		}
+		body = formData;
+	} else {
+		headers.set("content-type", "application/json");
+		body = JSON.stringify({
+			model: params.model,
+			prompt,
+			n: 1,
+			...(params.size ? { size: params.size } : {}),
+			...(params.quality ? { quality: params.quality } : {}),
+			...(params.outputFormat ? { output_format: params.outputFormat } : {}),
+			...(params.background ? { background: params.background } : {}),
+		});
+	}
+
+	const response = await fetch(endpoint, {
+		method: "POST",
+		headers,
+		body,
+		signal: AbortSignal.timeout(config.requestTimeoutMs),
+	});
+	const responseText = await response.text();
+	let payload = null;
+	try {
+		payload = responseText ? JSON.parse(responseText) : null;
+	} catch {
+		payload = responseText;
+	}
+	if (!response.ok) {
+		const message =
+			isRecord(payload) && isRecord(payload.error)
+				? JSON.stringify(payload.error)
+				: responseText || `${response.status} ${response.statusText}`;
+		throw new Error(`Image API request failed: ${message}`);
+	}
+	return payload;
+}
+
+async function readIndex(outputDir) {
+	try {
+		const raw = await fs.readFile(
+			/* turbopackIgnore: true */ path.join(outputDir, INDEX_FILE),
+			"utf8",
+		);
+		const parsed = JSON.parse(raw);
+		return {
+			images: isRecord(parsed?.images) ? parsed.images : {},
+			records: Array.isArray(parsed?.records) ? parsed.records : [],
+		};
+	} catch (error) {
+		if (error.code === "ENOENT") return { images: {}, records: [] };
+		throw error;
+	}
+}
+
+async function writeIndex(outputDir, index) {
+	await fs.mkdir(/* turbopackIgnore: true */ outputDir, { recursive: true });
+	const tempPath = path.join(outputDir, `${INDEX_FILE}.tmp`);
+	await fs.writeFile(
+		/* turbopackIgnore: true */ tempPath,
+		JSON.stringify(index, null, 2),
+		"utf8",
+	);
+	await fs.rename(
+		/* turbopackIgnore: true */ tempPath,
+		/* turbopackIgnore: true */ path.join(outputDir, INDEX_FILE),
+	);
+}
+
+function storedImageUrl(id, workspacePath) {
+	const params = new URLSearchParams();
+	if (workspacePath) params.set("workspacePath", workspacePath);
+	const query = params.toString();
+	return `/api/tools/image-generation/files/${id}${query ? `?${query}` : ""}`;
+}
+
+function localImageUrl(filePath) {
+	const params = new URLSearchParams({ path: filePath });
+	return `/api/local-files/image?${params.toString()}`;
+}
+
+function hydrateImage(image, workspacePath) {
+	if (!isRecord(image) || typeof image.id !== "string") return null;
+	if (
+		typeof image.savedPath === "string" &&
+		typeof image.absolutePath === "string"
+	) {
+		return {
+			...image,
+			url: localImageUrl(image.absolutePath),
+		};
+	}
+	return {
+		...image,
+		url: storedImageUrl(image.id, workspacePath),
+	};
+}
+
+function hydrateRecord(record, fallbackWorkspacePath) {
+	if (!isRecord(record) || typeof record.id !== "string") return null;
+	const workspacePath =
+		typeof record.workspacePath === "string" && record.workspacePath.trim()
+			? record.workspacePath
+			: fallbackWorkspacePath;
+	return {
+		...record,
+		threadId: typeof record.threadId === "string" ? record.threadId : null,
+		workspacePath,
+		images: Array.isArray(record.images)
+			? record.images
+					.map((image) => hydrateImage(image, workspacePath))
+					.filter(Boolean)
+			: [],
+	};
+}
+
+export async function saveGeneratedImage({
+	config,
+	data,
+	mimeType,
+	revisedPrompt,
+	actualParams,
+	width,
+	height,
+	workspacePath,
+	savePath,
+}) {
+	if (data.byteLength > config.maxOutputBytes) {
+		throw new Error(
+			`Generated image is too large (${data.byteLength} bytes, max ${config.maxOutputBytes}).`,
+		);
+	}
+	const resolvedSavePath = resolveValidatedSavePath({
+		savePath,
+		config,
+		workspacePath,
+	});
+	await fs.mkdir(/* turbopackIgnore: true */ config.outputDir, {
+		recursive: true,
+	});
+	const id = createId();
+	const fileName = `${id}.${mimeToExtension(mimeType)}`;
+	const absolutePath =
+		resolvedSavePath?.absolutePath ?? path.join(config.outputDir, fileName);
+	if (resolvedSavePath) {
+		await fs.mkdir(
+			/* turbopackIgnore: true */ path.dirname(resolvedSavePath.absolutePath),
+			{
+				recursive: true,
+			},
+		);
+		await fs.writeFile(
+			/* turbopackIgnore: true */ resolvedSavePath.absolutePath,
+			data,
+			{ flag: "wx" },
+		);
+	} else {
+		await fs.writeFile(/* turbopackIgnore: true */ absolutePath, data);
+	}
+
+	const image = {
+		id,
+		fileName: fileNameFromSavePath(resolvedSavePath?.relativePath, fileName),
+		mimeType,
+		sizeBytes: data.byteLength,
+		url: resolvedSavePath
+			? localImageUrl(resolvedSavePath.absolutePath)
+			: storedImageUrl(id, workspacePath),
+		...(resolvedSavePath ? { savedPath: resolvedSavePath.relativePath } : {}),
+		...(width ? { width } : {}),
+		...(height ? { height } : {}),
+		...(revisedPrompt ? { revisedPrompt } : {}),
+		...(actualParams ? { actualParams } : {}),
+	};
+	const index = await readIndex(config.outputDir);
+	index.images[id] = {
+		...image,
+		createdAt: nowIso(),
+		absolutePath,
+	};
+	await writeIndex(config.outputDir, index);
+	return image;
+}
+
+async function saveImageGenerationRecord(config, record) {
+	const index = await readIndex(config.outputDir);
+	index.records = [
+		record,
+		...index.records.filter((entry) => entry?.id !== record.id),
+	];
+	await writeIndex(config.outputDir, index);
+	return record;
+}
+
+function outputToRecord({ output, id, workspacePath, threadId, source }) {
+	const timestamp = nowIso();
+	return {
+		id,
+		requestId: output.requestId,
+		threadId: threadId || null,
+		workspacePath,
+		source,
+		status: output.status,
+		provider: output.provider,
+		prompt: output.prompt,
+		...(output.revisedPrompt ? { revisedPrompt: output.revisedPrompt } : {}),
+		requestedParams: output.requestedParams,
+		actualParams: output.actualParams,
+		images: output.images,
+		durationMs: output.durationMs,
+		...(output.error ? { error: output.error } : {}),
+		createdAt: timestamp,
+		updatedAt: timestamp,
+	};
+}
+
+function failedOutput({ recordId, config, input, params, startedAt, error }) {
+	const message = error instanceof Error ? error.message : String(error);
+	return {
+		status: "failed",
+		recordId,
+		requestId: `img_error_${Date.now().toString(36)}`,
+		provider: config?.provider ?? "unknown",
+		prompt: typeof input?.prompt === "string" ? input.prompt : "",
+		requestedParams: params ?? {},
+		actualParams: {},
+		images: [],
+		durationMs: Date.now() - startedAt,
+		error: message,
+	};
+}
+
+function normalizeSource(value) {
+	return value === "mcp" ? "mcp" : "api";
+}
+
+async function generateImageOrThrow({ input, config, workspacePath }) {
+	if (
+		!isRecord(input) ||
+		typeof input.prompt !== "string" ||
+		!input.prompt.trim()
+	) {
+		throw new Error("Image generation prompt is required.");
+	}
+	if (!config.apiKey) {
+		throw new Error(
+			'Image generation API key is missing. Pass builtinToolSettings["image-generation"].apiKey or configure tools/image-generation/config.local.json.',
+		);
+	}
+	if (!config.model) {
+		throw new Error(
+			'Image generation model is missing. Pass builtinToolSettings["image-generation"].model or configure tools/image-generation/config.local.json.',
+		);
+	}
+
+	const params = normalizeParams(input, config);
+	const inputImages = await Promise.all(
+		(input.images ?? []).map((source) =>
+			source.type === "path"
+				? loadPathImage(source, config, workspacePath)
+				: source.type === "url"
+					? loadUrlImage(source, config)
+					: loadInlineImage(source, config),
+		),
+	);
+	const payload = await requestImageApi({ config, input, params, inputImages });
+	const items =
+		isRecord(payload) && Array.isArray(payload.data) ? payload.data : [];
+	let image = null;
+	for (const item of items) {
+		if (!isRecord(item)) continue;
+		const revisedPrompt =
+			typeof item.revised_prompt === "string" ? item.revised_prompt : undefined;
+		let buffer = null;
+		let mimeType = mimeFromOutputFormat(params.outputFormat);
+		if (typeof item.b64_json === "string") {
+			buffer = Buffer.from(item.b64_json, "base64");
+			mimeType = sniffMime(buffer, mimeType);
+		} else if (typeof item.url === "string") {
+			const fetched = await fetchImageUrl(item.url, config);
+			buffer = fetched.buffer;
+			mimeType = fetched.mimeType;
+		}
+		if (!buffer) continue;
+		const savePath =
+			typeof input.savePath === "string" && input.savePath.trim()
+				? input.savePath
+				: availableSavePathFromPattern({
+						pattern: config.savePathPattern,
+						mimeType,
+						params,
+						config,
+						workspacePath,
+					});
+		image = await saveGeneratedImage({
+			config,
+			data: buffer,
+			mimeType,
+			revisedPrompt,
+			actualParams: params,
+			workspacePath,
+			savePath,
+		});
+		break;
+	}
+
+	if (!image) {
+		throw new Error("Image API response did not include any images.");
+	}
+
+	return { image, params, payload };
+}
+
+export async function generateImage(input, options = {}) {
+	const workspacePath = normalizeWorkspacePath(options.workspacePath);
+	const threadId =
+		typeof options.threadId === "string" && options.threadId.trim()
+			? options.threadId.trim()
+			: null;
+	const source = normalizeSource(options.source);
+	const recordId = createId();
+	const startedAt = Date.now();
+	const config = loadImageGenerationConfig({
+		workspacePath,
+		threadId,
+		runtimeSettings: options.runtimeSettings,
+	});
+	let params = null;
+
+	try {
+		if (isRecord(input)) params = normalizeParams(input, config);
+		const result = await generateImageOrThrow({ input, config, workspacePath });
+		params = result.params;
+		const revisedPrompt = result.image.revisedPrompt;
+		const output = {
+			status: "completed",
+			recordId,
+			requestId:
+				isRecord(result.payload) && typeof result.payload.id === "string"
+					? result.payload.id
+					: `img_${Date.now().toString(36)}`,
+			provider: config.provider,
+			prompt: input.prompt,
+			...(revisedPrompt ? { revisedPrompt } : {}),
+			requestedParams: params,
+			actualParams: params,
+			images: [result.image],
+			durationMs: Date.now() - startedAt,
+			rawResponseSummary: summarizeRawResponse(result.payload),
+		};
+		const record = outputToRecord({
+			output,
+			id: recordId,
+			workspacePath,
+			threadId,
+			source,
+		});
+		await saveImageGenerationRecord(config, record);
+		return output;
+	} catch (error) {
+		const output = failedOutput({
+			recordId,
+			config,
+			input,
+			params,
+			startedAt,
+			error,
+		});
+		const record = outputToRecord({
+			output,
+			id: recordId,
+			workspacePath,
+			threadId,
+			source,
+		});
+		await saveImageGenerationRecord(config, record);
+		return output;
+	}
+}
+
+export async function listImageGenerationRecords(options = {}) {
+	const workspacePath = normalizeWorkspacePath(options.workspacePath);
+	const config = loadImageGenerationConfig({ workspacePath });
+	const threadId =
+		typeof options.threadId === "string" && options.threadId.trim()
+			? options.threadId.trim()
+			: null;
+	const limit = Number.isFinite(options.limit)
+		? Math.max(1, Math.floor(options.limit))
+		: 20;
+	const index = await readIndex(config.outputDir);
+	return index.records
+		.map((record) => hydrateRecord(record, workspacePath))
+		.filter(Boolean)
+		.filter((record) => !threadId || record.threadId === threadId)
+		.sort((left, right) =>
+			String(right.updatedAt ?? right.createdAt ?? "").localeCompare(
+				String(left.updatedAt ?? left.createdAt ?? ""),
+			),
+		)
+		.slice(0, limit);
+}
+
+export async function getStoredImage(options, id) {
+	const workspacePath = normalizeWorkspacePath(options?.workspacePath);
+	if (!/^[a-f0-9]{32}$/.test(id)) return null;
+	const config = loadImageGenerationConfig({ workspacePath });
+	const index = await readIndex(config.outputDir);
+	const image = index.images[id];
+	if (!image) return null;
+	const absolutePath =
+		typeof image.absolutePath === "string"
+			? image.absolutePath
+			: path.join(config.outputDir, image.fileName);
+	const resolvedOutputDir = path.resolve(config.outputDir);
+	const resolvedPath = path.resolve(absolutePath);
+	if (typeof image.savedPath === "string") {
+		const workspace = normalizeWorkspacePath(workspacePath);
+		if (!isPathInsideOrEqual(workspace, resolvedPath)) {
+			return null;
+		}
+		return {
+			...image,
+			url: localImageUrl(resolvedPath),
+			absolutePath: resolvedPath,
+		};
+	}
+	if (
+		resolvedPath !== resolvedOutputDir &&
+		!resolvedPath.startsWith(`${resolvedOutputDir}${path.sep}`)
+	) {
+		return null;
+	}
+	return {
+		...image,
+		url: storedImageUrl(id, workspacePath),
+		absolutePath: resolvedPath,
+	};
+}