@sayknow-cli/coding-agent 0.4.6 → 0.5.0

package/src/tools/image-gen.ts

@@ -1,3 +1,6 @@
+import * as http from "node:http";
+import * as https from "node:https";
+import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
 import { getAntigravityUserAgent, getEnvApiKey, type Model } from "@sayknow-cli/ai";
@@ -23,22 +26,27 @@ import packageJson from "../../package.json" with { type: "json" };
 import { isAuthenticated, type ModelRegistry } from "../config/model-registry";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 import imageGenDescription from "../prompts/tools/image-gen.md" with { type: "text" };
+import { isPrivateOrSpecialAddress, validatePublicHttpUrl } from "../web/insane/url-guard";
 import { resolveReadPath } from "./path-utils";
 
 const DEFAULT_MODEL = "gemini-3-pro-image-preview";
-const DEFAULT_OPENROUTER_MODEL = "google/gemini-3-pro-image-preview";
-const DEFAULT_ANTIGRAVITY_MODEL = "gemini-3-pro-image";
 const IMAGE_TIMEOUT = 3 * 60 * 1000; // 3 minutes
 const MAX_IMAGE_SIZE = 35 * 1024 * 1024;
+const MAX_IMAGE_REDIRECTS = 5;
+const MAX_IMAGE_HEADER_SIZE = 16 * 1024;
+const MAX_IMAGE_ERROR_PREVIEW_SIZE = 8 * 1024;
+const IMAGE_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
 const OPENAI_IMAGE_OUTPUT_FORMAT = "webp";
 const OPENAI_IMAGE_MIME_TYPE = "image/webp";
 
 const ANTIGRAVITY_ENDPOINT = "https://daily-cloudcode-pa.sandbox.googleapis.com";
+const ALIBABA_TOKEN_PLAN_HOST = "https://token-plan.ap-southeast-1.maas.aliyuncs.com";
+const ALIBABA_IMAGE_GENERATION_URL = `${ALIBABA_TOKEN_PLAN_HOST}/api/v1/services/aigc/multimodal-generation/generation`;
 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.";
 
-type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter";
+type ImageProvider = "alibaba" | "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter";
 interface ImageApiKey {
 	provider: ImageProvider;
 	apiKey: string;
@@ -290,6 +298,81 @@ interface AntigravityResponseChunk {
 	};
 }
 
+interface AlibabaImageContentPart {
+	type?: string;
+	text?: string;
+	image?: string;
+}
+
+interface AlibabaImageResponse {
+	code?: string;
+	message?: string;
+	output?: {
+		choices?: Array<{ message?: { content?: AlibabaImageContentPart[] } }>;
+	};
+}
+
+/** Map the tool's image_size values onto wan2.7's 1K/2K size classes. */
+export function resolveAlibabaImageSize(imageSize: string | undefined): string | undefined {
+	switch (imageSize) {
+		case "1024x1024":
+			return "1K";
+		case "1536x1024":
+		case "1024x1536":
+			return "2K";
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Build the Bailian multimodal-generation request body for wan2.7 image
+ * generation/editing. Input images ride along as data URLs; generation-only
+ * calls send just the prompt text. The sync endpoint returns OSS URLs inline.
+ */
+export function buildAlibabaImageRequest(
+	model: string,
+	promptText: string,
+	inputImages: InlineImageData[],
+	imageSize: string | undefined,
+): {
+	model: string;
+	input: { messages: Array<{ role: "user"; content: Array<{ text: string } | { image: string }> }> };
+	parameters: { n: number; watermark: boolean; size?: string };
+} {
+	const content: Array<{ text: string } | { image: string }> = [];
+	for (const image of inputImages) {
+		content.push({ image: toDataUrl(image) });
+	}
+	content.push({ text: promptText });
+	const size = resolveAlibabaImageSize(imageSize);
+	return {
+		model,
+		input: { messages: [{ role: "user", content }] },
+		parameters: { n: 1, watermark: false, ...(size ? { size } : {}) },
+	};
+}
+
+/** Collect OSS image URLs and any text parts from a Bailian image response. */
+export function collectAlibabaImageResult(response: AlibabaImageResponse): {
+	imageUrls: string[];
+	responseText?: string;
+} {
+	const imageUrls: string[] = [];
+	const textParts: string[] = [];
+	for (const choice of response.output?.choices ?? []) {
+		for (const part of choice.message?.content ?? []) {
+			if (part.image) {
+				imageUrls.push(part.image);
+			} else if (part.text) {
+				textParts.push(part.text);
+			}
+		}
+	}
+	const responseText = textParts.join("\n").trim();
+	return { imageUrls, responseText: responseText.length > 0 ? responseText : undefined };
+}
+
 interface ImageGenToolDetails {
 	provider: ImageProvider;
 	model: string;
@@ -327,6 +410,160 @@ function toDataUrl(image: InlineImageData): string {
 	return `data:${image.mimeType};base64,${image.data}`;
 }
 
+function withAbortSignal<T>(operation: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+	if (!signal) return operation;
+	if (signal.aborted) return Promise.reject(signal.reason);
+	const deferred = Promise.withResolvers<T>();
+	const abort = () => deferred.reject(signal.reason);
+	signal.addEventListener("abort", abort, { once: true });
+	operation.then(deferred.resolve, deferred.reject).finally(() => signal.removeEventListener("abort", abort));
+	return deferred.promise;
+}
+
+function normalizePeerAddress(address: string): string {
+	const normalized = address.toLowerCase();
+	return normalized.startsWith("::ffff:") ? normalized.slice(7) : normalized;
+}
+
+function normalizeUrlHostname(hostname: string): string {
+	return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
+
+function responseHeaderByteLength(response: http.IncomingMessage): number {
+	let bytes = Buffer.byteLength(
+		`HTTP/${response.httpVersion} ${response.statusCode ?? ""}${response.statusMessage ? ` ${response.statusMessage}` : ""}\r\n`,
+	);
+	for (let index = 0; index < response.rawHeaders.length; index += 2) {
+		bytes += Buffer.byteLength(`${response.rawHeaders[index] ?? ""}: ${response.rawHeaders[index + 1] ?? ""}\r\n`);
+	}
+	return bytes + Buffer.byteLength("\r\n");
+}
+
+async function validateImageUrl(rawUrl: string, signal: AbortSignal | undefined) {
+	return withAbortSignal(validatePublicHttpUrl(rawUrl), signal);
+}
+
+function openImageResponse(
+	url: URL,
+	addresses: string[],
+	signal: AbortSignal | undefined,
+): Promise<http.IncomingMessage> {
+	const hostname = normalizeUrlHostname(url.hostname);
+	const approved = addresses.map(address => ({ address, family: net.isIP(address) }));
+	const approvedPeers = new Set(approved.map(record => normalizePeerAddress(record.address)));
+	const lookup: net.LookupFunction = (requestedHostname, options, callback) => {
+		const requestedFamily = options.family === "IPv4" ? 4 : options.family === "IPv6" ? 6 : (options.family ?? 0);
+		const matching = approved.filter(record => requestedFamily === 0 || record.family === requestedFamily);
+		if (normalizeUrlHostname(requestedHostname) !== hostname || matching.length === 0) {
+			const error = Object.assign(new Error("No approved address for image host"), { code: "ENOTFOUND" });
+			callback(error, options.all ? [] : "", 0);
+			return;
+		}
+		if (options.all) callback(null, matching);
+		else callback(null, matching[0].address, matching[0].family);
+	};
+	const deferred = Promise.withResolvers<http.IncomingMessage>();
+	const options: https.RequestOptions = {
+		protocol: url.protocol,
+		hostname,
+		port: url.port || undefined,
+		path: `${url.pathname}${url.search}`,
+		method: "GET",
+		headers: { Accept: "image/*", "Accept-Encoding": "identity", Connection: "close", Host: url.host },
+		agent: false,
+		insecureHTTPParser: false,
+		lookup,
+		maxHeaderSize: MAX_IMAGE_HEADER_SIZE,
+		signal,
+		...(url.protocol === "https:"
+			? { rejectUnauthorized: true, servername: net.isIP(hostname) === 0 ? hostname : undefined }
+			: {}),
+	};
+	const requestFn = url.protocol === "https:" ? https.request : http.request;
+	const request = requestFn(options, response => {
+		if (responseHeaderByteLength(response) > MAX_IMAGE_HEADER_SIZE) {
+			response.destroy();
+			deferred.reject(new Error("Image response headers exceed the maximum size of 16 KiB"));
+			return;
+		}
+		const peer = response.socket.remoteAddress;
+		if (peer && (isPrivateOrSpecialAddress(peer) || !approvedPeers.has(normalizePeerAddress(peer)))) {
+			response.destroy();
+			deferred.reject(new Error("Refusing image response from an unapproved connected peer"));
+			return;
+		}
+		deferred.resolve(response);
+	});
+	request.once("error", deferred.reject);
+	const abort = () => {
+		request.destroy(signal?.reason);
+		deferred.reject(signal?.reason);
+	};
+	if (signal?.aborted) abort();
+	else signal?.addEventListener("abort", abort, { once: true });
+	request.once("close", () => signal?.removeEventListener("abort", abort));
+	request.end();
+	return deferred.promise;
+}
+
+function validateImageResponseFraming(response: http.IncomingMessage): void {
+	const rawContentLengths: string[] = [];
+	let hasTransferEncoding = false;
+	for (let index = 0; index < response.rawHeaders.length; index += 2) {
+		const name = response.rawHeaders[index]?.toLowerCase();
+		if (name === "content-length") rawContentLengths.push(response.rawHeaders[index + 1] ?? "");
+		if (name === "transfer-encoding") hasTransferEncoding = true;
+	}
+	if (rawContentLengths.length > 1 || (rawContentLengths.length > 0 && hasTransferEncoding)) {
+		response.destroy();
+		throw new Error("Image response has ambiguous framing");
+	}
+	const contentLength = response.headers["content-length"];
+	if (contentLength === undefined) return;
+	const declaredBytes = typeof contentLength === "string" && /^\d+$/.test(contentLength) ? Number(contentLength) : NaN;
+	if (!Number.isSafeInteger(declaredBytes)) {
+		response.destroy();
+		throw new Error("Image response has an invalid Content-Length");
+	}
+	if (declaredBytes > MAX_IMAGE_SIZE) {
+		response.destroy();
+		throw new Error("Image response exceeds the maximum size of 35 MiB");
+	}
+}
+
+async function readImageResponse(
+	response: http.IncomingMessage,
+	maxBytes: number,
+	signal: AbortSignal | undefined,
+): Promise<Buffer> {
+	const abort = () => response.destroy(signal?.reason);
+	if (signal?.aborted) {
+		abort();
+		throw signal.reason;
+	}
+	signal?.addEventListener("abort", abort, { once: true });
+	const chunks: Buffer[] = [];
+	let receivedBytes = 0;
+	try {
+		for await (const chunk of response) {
+			const bytes = Buffer.from(chunk);
+			receivedBytes += bytes.byteLength;
+			if (receivedBytes > maxBytes) {
+				response.destroy();
+				throw new Error(
+					maxBytes === MAX_IMAGE_SIZE
+						? "Image response exceeds the maximum size of 35 MiB"
+						: "Image download error response exceeded the preview limit",
+				);
+			}
+			chunks.push(bytes);
+		}
+		return Buffer.concat(chunks, receivedBytes);
+	} finally {
+		signal?.removeEventListener("abort", abort);
+	}
+}
+
 async function loadImageFromUrl(imageUrl: string, signal?: AbortSignal): Promise<InlineImageData> {
 	if (imageUrl.startsWith("data:")) {
 		const normalized = normalizeDataUrl(imageUrl.trim());
@@ -339,17 +576,40 @@ async function loadImageFromUrl(imageUrl: string, signal?: AbortSignal): Promise
 		return { data: normalized.data, mimeType: normalized.mimeType };
 	}
 
-	const response = await fetch(imageUrl, { signal });
-	if (!response.ok) {
-		const rawText = await response.text();
-		throw new Error(`Image download failed (${response.status}): ${rawText}`);
-	}
-	const contentType = response.headers.get("content-type")?.split(";")[0];
-	if (!contentType?.startsWith("image/")) {
-		throw new Error(`Unsupported image type from URL: ${imageUrl}`);
+	let currentUrl = imageUrl;
+	for (let redirectCount = 0; ; redirectCount++) {
+		const guard = await validateImageUrl(currentUrl, signal);
+		if (!guard.ok) {
+			throw new Error(`Refusing image URL: target URL is not public HTTP(S): ${guard.reason}`);
+		}
+		const response = await openImageResponse(guard.url, guard.addresses, signal);
+		const status = response.statusCode ?? 0;
+		if (IMAGE_REDIRECT_STATUSES.has(status)) {
+			if (redirectCount >= MAX_IMAGE_REDIRECTS) {
+				response.destroy();
+				throw new Error("Too many redirects downloading image");
+			}
+			const location = response.headers.location;
+			response.destroy();
+			if (!location) throw new Error("Image redirect is missing a Location header");
+			currentUrl = new URL(location, guard.url).toString();
+			continue;
+		}
+		validateImageResponseFraming(response);
+		if (status < 200 || status >= 300) {
+			const preview = (await readImageResponse(response, MAX_IMAGE_ERROR_PREVIEW_SIZE, signal)).toString("utf8");
+			throw new Error(`Image download failed (${status}): ${preview}`);
+		}
+		const rawContentType = response.headers["content-type"];
+		const contentType =
+			typeof rawContentType === "string" ? rawContentType.split(";", 1)[0]?.trim().toLowerCase() : undefined;
+		if (!contentType?.startsWith("image/")) {
+			response.destroy();
+			throw new Error("Image response is missing a supported image Content-Type");
+		}
+		const buffer = await readImageResponse(response, MAX_IMAGE_SIZE, signal);
+		return { data: buffer.toBase64(), mimeType: contentType };
 	}
-	const buffer = await response.bytes();
-	return { data: buffer.toBase64(), mimeType: contentType };
 }
 
 function collectOpenRouterResponseText(message: OpenRouterMessage | undefined): string | undefined {
@@ -399,6 +659,50 @@ export function setPreferredImageProvider(provider: ImageProvider | "auto"): voi
 	preferredImageProvider = provider;
 }
 
+/** Provider → default image model mapping for auto-binding */
+export const IMAGE_PROVIDER_DEFAULTS: Record<string, string> = {
+	openai: "gpt-image-2",
+	alibaba: "wan2.7-image",
+	"openai-codex": "gpt-image-2",
+	antigravity: "gemini-3-pro-image",
+	gemini: "gemini-3-pro-image-preview",
+	openrouter: "google/gemini-3-pro-image-preview",
+};
+
+/** Resolved image generation configuration from settings */
+export interface ImageProviderConfig {
+	provider: ImageProvider | "auto" | "custom";
+	model: string | null;
+	customUrl?: string;
+	customKey?: string;
+	customKeyEnv?: string;
+}
+
+/** Module-level configured image model state (set from settings at session init) */
+let configuredImageConfig: ImageProviderConfig | null = null;
+
+/** Set the configured image provider + model from settings */
+export function setConfiguredImageModel(config: ImageProviderConfig | null): void {
+	configuredImageConfig = config;
+	// Keep preferredImageProvider in sync for backward compat
+	if (config && config.provider !== "auto" && config.provider !== "custom") {
+		preferredImageProvider = config.provider;
+	} else if (!config || config.provider === "auto") {
+		preferredImageProvider = "auto";
+	}
+}
+
+/** Get the current configured image model (for UI display) */
+export function getConfiguredImageModel(): ImageProviderConfig | null {
+	return configuredImageConfig;
+}
+
+/** Resolve the effective image model for a configured provider */
+export function resolveImageModel(provider: string, modelOverride: string | null): string {
+	if (modelOverride) return modelOverride;
+	return IMAGE_PROVIDER_DEFAULTS[provider] ?? DEFAULT_MODEL;
+}
+
 interface ParsedAntigravityCredentials {
 	accessToken: string;
 	projectId?: string;
@@ -420,6 +724,22 @@ function parseAntigravityCredentials(raw: string): ParsedAntigravityCredentials
 	return rawToken.length > 0 ? { accessToken: rawToken } : null;
 }
 
+function createCustomImageModel(baseUrl: string, id: string): Model<"openai-responses"> {
+	return {
+		id,
+		name: id,
+		api: "openai-responses",
+		provider: "openai",
+		baseUrl: baseUrl.replace(/\/+$/, ""),
+		reasoning: false,
+		input: ["text"],
+		output: ["text", "image"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128_000,
+		maxTokens: 16_384,
+	};
+}
+
 async function findAntigravityCredentials(
 	modelRegistry: ModelRegistry,
 	sessionId?: string,
@@ -462,12 +782,64 @@ async function findOpenAIHostedImageCredentials(
 	};
 }
 
+async function findAlibabaImageCredentials(
+	modelRegistry: ModelRegistry | undefined,
+	sessionId?: string,
+): Promise<ImageApiKey | null> {
+	const envKey = getEnvApiKey("alibaba-token-plan");
+	if (envKey) return { provider: "alibaba", apiKey: envKey };
+	if (!modelRegistry) return null;
+	const apiKey = await modelRegistry.getApiKeyForProvider("alibaba-token-plan", sessionId);
+	if (!isAuthenticated(apiKey)) return null;
+	return { provider: "alibaba", apiKey };
+}
+
 async function findImageApiKey(
 	modelRegistry?: ModelRegistry,
 	activeModel?: Model,
 	sessionId?: string,
 ): Promise<ImageApiKey | null> {
-	// If a specific provider is preferred, try it first.
+	// Config-driven routing: if an explicit provider+model is configured, use it.
+	if (configuredImageConfig && configuredImageConfig.provider !== "auto") {
+		const config = configuredImageConfig;
+		if (config.provider === "custom") {
+			const baseUrl = config.customUrl?.trim();
+			const apiKey = config.customKey ?? (config.customKeyEnv ? Bun.env[config.customKeyEnv] : undefined);
+			if (baseUrl && apiKey) {
+				return {
+					provider: "openai",
+					apiKey,
+					model: createCustomImageModel(baseUrl, config.model ?? IMAGE_PROVIDER_DEFAULTS.openai),
+				};
+			}
+			return null;
+		}
+		// For configured providers, resolve credentials through the existing paths.
+		if (config.provider === "openai" || config.provider === "openai-codex") {
+			const openAI = await findOpenAIHostedImageCredentials(modelRegistry, activeModel, sessionId);
+			if (openAI) return openAI;
+			return null;
+		}
+		if (config.provider === "antigravity") {
+			if (!modelRegistry) return null;
+			return await findAntigravityCredentials(modelRegistry, sessionId);
+		}
+		if (config.provider === "gemini") {
+			const geminiKey = getEnvApiKey("google");
+			if (geminiKey) return { provider: "gemini", apiKey: geminiKey };
+			const googleKey = $env.GOOGLE_API_KEY;
+			return googleKey ? { provider: "gemini", apiKey: googleKey } : null;
+		}
+		if (config.provider === "openrouter") {
+			const openRouterKey = getEnvApiKey("openrouter");
+			return openRouterKey ? { provider: "openrouter", apiKey: openRouterKey } : null;
+		}
+		if (config.provider === "alibaba") {
+			return await findAlibabaImageCredentials(modelRegistry, sessionId);
+		}
+	}
+
+	// If a specific provider is preferred (legacy path), try it first.
 	if (preferredImageProvider === "openai") {
 		const openAI = await findOpenAIHostedImageCredentials(modelRegistry, activeModel, sessionId);
 		if (openAI) return openAI;
@@ -483,9 +855,11 @@ async function findImageApiKey(
 	} else if (preferredImageProvider === "openrouter") {
 		const openRouterKey = getEnvApiKey("openrouter");
 		return openRouterKey ? { provider: "openrouter", apiKey: openRouterKey } : null;
+	} else if (preferredImageProvider === "alibaba") {
+		return await findAlibabaImageCredentials(modelRegistry, sessionId);
 	}
 
-	// Auto-detect: GPT hosted image generation, then Antigravity, OpenRouter, Gemini.
+	// Auto-detect: GPT hosted image generation, then Antigravity, OpenRouter, Gemini, Alibaba.
 	const openAI = await findOpenAIHostedImageCredentials(modelRegistry, activeModel, sessionId);
 	if (openAI) return openAI;
 
@@ -503,6 +877,9 @@ async function findImageApiKey(
 	const googleKey = $env.GOOGLE_API_KEY;
 	if (googleKey) return { provider: "gemini", apiKey: googleKey };
 
+	const alibaba = await findAlibabaImageCredentials(modelRegistry, sessionId);
+	if (alibaba) return alibaba;
+
 	return null;
 }
 
@@ -939,19 +1316,23 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 			const apiKey = await findImageApiKey(ctx.modelRegistry, ctx.model, sessionId);
 			if (!apiKey) {
 				throw new Error(
-					"No image API credentials found. Use a GPT Responses/Codex model with OpenAI credentials, login with google-antigravity, or set OPENROUTER_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY.",
+					"No image API credentials found. Use a GPT Responses/Codex model with OpenAI credentials, login with google-antigravity, or set OPENROUTER_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, or ALIBABA_TOKEN_PLAN_API_KEY.",
 				);
 			}
 
 			const provider = apiKey.provider;
 			const model =
-				provider === "openai" || provider === "openai-codex"
-					? (apiKey.model?.id ?? "gpt")
-					: provider === "antigravity"
-						? DEFAULT_ANTIGRAVITY_MODEL
-						: provider === "openrouter"
-							? DEFAULT_OPENROUTER_MODEL
-							: DEFAULT_MODEL;
+				configuredImageConfig && configuredImageConfig.provider !== "auto" && configuredImageConfig.model
+					? configuredImageConfig.model
+					: provider === "openai" || provider === "openai-codex"
+						? (apiKey.model?.id ?? resolveImageModel(provider, null))
+						: provider === "antigravity"
+							? resolveImageModel("antigravity", null)
+							: provider === "alibaba"
+								? resolveImageModel("alibaba", null)
+								: provider === "openrouter"
+									? resolveImageModel("openrouter", null)
+									: resolveImageModel("gemini", null);
 			const resolvedModel = provider === "openrouter" ? resolveOpenRouterModel(model) : model;
 			const cwd = ctx.sessionManager.getCwd();
 
@@ -1169,6 +1550,78 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 				};
 			}
 
+			if (provider === "alibaba") {
+				const requestBody = buildAlibabaImageRequest(
+					model,
+					assemblePrompt(params),
+					resolvedImages,
+					params.image_size,
+				);
+
+				const response = await fetch(ALIBABA_IMAGE_GENERATION_URL, {
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						Authorization: `Bearer ${apiKey.apiKey}`,
+					},
+					body: JSON.stringify(requestBody),
+					signal: requestSignal,
+				});
+
+				const rawText = await response.text();
+				if (!response.ok) {
+					let message = rawText;
+					try {
+						const parsed = JSON.parse(rawText) as { message?: string; error?: { message?: string } };
+						message = parsed.error?.message ?? parsed.message ?? message;
+					} catch {
+						// Keep raw text.
+					}
+					throw new Error(`Alibaba image request failed (${response.status}): ${message}`);
+				}
+
+				const data = JSON.parse(rawText) as AlibabaImageResponse;
+				if (data.code) {
+					throw new Error(`Alibaba image request failed: ${data.code}: ${data.message ?? ""}`.trim());
+				}
+
+				const { imageUrls, responseText } = collectAlibabaImageResult(data);
+				// Result URLs are short-lived OSS-signed URLs (24h); download immediately.
+				const inlineImages: InlineImageData[] = [];
+				for (const imageUrl of imageUrls) {
+					inlineImages.push(await loadImageFromUrl(imageUrl, requestSignal));
+				}
+
+				if (inlineImages.length === 0) {
+					const messageText = responseText ? `\n\n${responseText}` : "";
+					return {
+						content: [{ type: "text", text: `No image data returned.${messageText}` }],
+						details: {
+							provider,
+							model,
+							imageCount: 0,
+							imagePaths: [],
+							images: [],
+							responseText,
+						},
+					};
+				}
+
+				const imagePaths = await saveImagesToTemp(inlineImages);
+
+				return {
+					content: [{ type: "text", text: buildResponseSummary(provider, model, imagePaths, responseText) }],
+					details: {
+						provider,
+						model,
+						imageCount: inlineImages.length,
+						imagePaths,
+						images: inlineImages,
+						responseText,
+					},
+				};
+			}
+
 			const parts = [] as Array<{ text?: string; inlineData?: InlineImageData }>;
 			for (const image of resolvedImages) {
 				parts.push({ inlineData: image });

package/src/tools/index.ts

@@ -137,6 +137,8 @@ export interface AskAnswerRequest {
 	options: string[];
 	interaction: "selector" | "custom_editor" | "clarification_editor";
 	controls: readonly AskRemoteControl[];
+	/** Optional zero-based recommendation into the authoritative raw options. */
+	recommendedIndex?: number;
 }
 
 export type AskRemoteInteraction =
@@ -232,6 +234,8 @@ export interface ToolSession {
 	 *  its terminal-phase chain guard. Returns the raw phase string or undefined
 	 *  when no active skill (or accessor) is available. */
 	getActiveSkillPhase?: () => string | undefined;
+	/** Restrict provider-facing deep-interview ask metadata to the active workflow stage. */
+	getDeepInterviewAskStage?: () => "topology" | "post-topology" | undefined;
 	/** Pre-loaded prompt templates */
 	promptTemplates?: PromptTemplate[];
 	/** Whether LSP integrations are enabled */
@@ -271,9 +275,11 @@ export interface ToolSession {
 	/** Agent identity used for IRC routing. Returns the registry id (e.g. "0-Main", "0-AuthLoader"). */
 	getAgentId?: () => string | null;
 	/** Look up a registered tool by name (used by the eval js backend's tool bridge). */
+	getToolByName?: (name: string) => AgentTool | undefined;
+	/** Look up a registered tool with the session's execution guards applied. */
+	getToolForExecution?: (name: string) => AgentTool | undefined;
 	/** Purge undelivered queued custom messages matching the predicate. Returns counts. */
 	purgeQueuedCustomMessages?: (predicate: (message: CustomMessage) => boolean) => PurgeQueuedCustomMessagesResult;
-	getToolByName?: (name: string) => AgentTool | undefined;
 	/** Agent registry for IRC routing across live sessions. */
 	agentRegistry?: AgentRegistry;
 	/** Optional restricted bash command prefixes for read-only role agents and constrained modes. */