@dickpy/dsh-imagegen 1.1.0 → 1.2.0

package/lib/index.js

@@ -6,6 +6,8 @@ import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
+import { createUserMessage } from "@deepseek-ai/dsh-llm/message";
+import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region src/protocol.ts
 /**
 * Wire contract shared by the host and client halves of dsh-imagegen: the
@@ -15,7 +17,7 @@ import { spawn } from "node:child_process";
 /** Settings namespace this plugin owns (host settings seam + bridge). */
 const IMAGEGEN_SETTINGS_NAMESPACE = "dsh-imagegen";
 /** Published package version shared by the host updater and the client UI. */
-const PLUGIN_VERSION = "1.1.0";
+const PLUGIN_VERSION = "1.2.0";
 /** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
 const SETTINGS_API = {
 	describe: "/api/dsh-imagegen/settings/describe",
@@ -28,6 +30,8 @@ const PROMPT_ENHANCE_API = {
 	models: "/api/dsh-imagegen/prompt-enhance/models",
 	enhance: "/api/dsh-imagegen/prompt-enhance"
 };
+/** Host-mediated candidate discovery for the configured image API. */
+const IMAGE_MODEL_API = { models: "/api/dsh-imagegen/image-models" };
 /** Host-resident generation queue endpoints. */
 const TASK_API = {
 	submit: "/api/dsh-imagegen/tasks/submit",
@@ -78,6 +82,78 @@ const TEMPLATES_API = {
 	image: "/api/dsh-imagegen/templates/image"
 };
 //#endregion
+//#region src/prompt-enhancer.ts
+function endpoint(base, suffix) {
+	return `${base.replace(/\/+$/, "")}${suffix}`;
+}
+function headers(apiKey) {
+	return {
+		"content-type": "application/json",
+		...apiKey.trim() === "" ? {} : { authorization: `Bearer ${apiKey.trim()}` }
+	};
+}
+async function responseJson(response) {
+	const body = await response.json().catch(() => void 0);
+	if (!response.ok || body === void 0 || body === null || typeof body !== "object") {
+		const message = body !== null && typeof body === "object" && typeof body.error?.message === "string" ? body.error.message : `HTTP ${response.status}`;
+		throw new Error(message);
+	}
+	return body;
+}
+/** List candidates exposed by an OpenAI-compatible endpoint. */
+async function listOpenAIModels(config) {
+	if (config.apiUrl.trim() === "") throw new Error("API URL is required");
+	const body = await responseJson(await fetch(endpoint(config.apiUrl, "/models"), { headers: headers(config.apiKey) }));
+	const data = Array.isArray(body.data) ? body.data : [];
+	return [...new Set(data.flatMap((item) => item !== null && typeof item === "object" && typeof item.id === "string" ? [item.id.trim()] : []).filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+/** List chat models exposed by an OpenAI-compatible endpoint. */
+async function listPromptModels(config) {
+	return listOpenAIModels(config);
+}
+/** Expand a concise image request into a production-ready image prompt. */
+async function enhancePrompt(config, prompt) {
+	if (config.apiUrl.trim() === "" || config.model.trim() === "") throw new Error("prompt enhancement model is not configured");
+	const body = await responseJson(await fetch(endpoint(config.apiUrl, "/chat/completions"), {
+		method: "POST",
+		headers: headers(config.apiKey),
+		body: JSON.stringify({
+			model: config.model.trim(),
+			temperature: .7,
+			messages: [{
+				role: "system",
+				content: "You are an expert image-prompt editor. Expand the user request into one vivid, specific image-generation prompt. Preserve intent and language. Add only useful visual detail: subject, composition, lighting, materials, color, camera/style and quality. Return only the finished prompt, with no preface or markdown."
+			}, {
+				role: "user",
+				content: prompt
+			}]
+		})
+	}));
+	const choices = Array.isArray(body.choices) ? body.choices : [];
+	const content = choices[0] !== null && typeof choices[0] === "object" ? choices[0].message?.content : void 0;
+	if (typeof content !== "string" || content.trim() === "") throw new Error("chat model returned an empty prompt");
+	return content.trim();
+}
+//#endregion
+//#region src/image-models.ts
+/**
+* Image-model configuration shared by the host, panel, and Agent tools.
+* `/models` exposes candidates only: the configured list is the explicit
+* allow-list because OpenAI-compatible gateways rarely advertise modalities.
+*/
+const DEFAULT_IMAGE_MODELS = ["gpt-image-2", "grok-imagine-image"];
+/** Normalize user-entered model identifiers and retain a usable legacy default. */
+function normalizeImageModels(value) {
+	const candidates = Array.isArray(value) ? value : [];
+	const unique = /* @__PURE__ */ new Set();
+	for (const candidate of candidates) {
+		if (typeof candidate !== "string") continue;
+		const model = candidate.trim();
+		if (model !== "") unique.add(model);
+	}
+	return unique.size > 0 ? [...unique] : [...DEFAULT_IMAGE_MODELS];
+}
+//#endregion
 //#region src/engine.ts
 /** A generation failure with a user-presentable message. */
 var ImageGenError = class extends Error {
@@ -123,6 +199,30 @@ const OPENAI_SIZE_BY_RATIO = {
 /** Panel ratios that need renaming for a model's vocabulary. Grok documents
 *  20:9 as its ultra-wide ratio, so the panel's 21:9 label is sent as 20:9. */
 const GROK_ASPECT_ALIASES = { "21:9": "20:9" };
+/**
+* One request-scoped timeout that is cleared as soon as its fetch settles.
+* AbortSignal.timeout() cannot be disposed early; using it inside a long-lived
+* task queue leaves an otherwise idle Node process holding every timeout.
+*/
+function requestSignal(source, timeoutMs) {
+	const controller = new AbortController();
+	const abortFromSource = () => {
+		controller.abort(source?.reason);
+	};
+	if (source?.aborted === true) abortFromSource();
+	else source?.addEventListener("abort", abortFromSource, { once: true });
+	const timeout = setTimeout(() => {
+		controller.abort(new DOMException("The operation timed out.", "TimeoutError"));
+	}, timeoutMs);
+	timeout.unref();
+	return {
+		signal: controller.signal,
+		dispose: () => {
+			clearTimeout(timeout);
+			source?.removeEventListener("abort", abortFromSource);
+		}
+	};
+}
 /** Content-type extension hints for URL-fetched images. */
 function mimeOfExtension(path) {
 	const match = /\.([a-z0-9]+)$/i.exec(path);
@@ -207,14 +307,17 @@ async function normalizeItem(item, upstream) {
 			revisedPrompt
 		};
 	}
+	const budget = requestSignal(void 0, IMAGE_FETCH_TIMEOUT_MS);
 	let response;
 	try {
 		response = await fetch(url, {
 			headers: { ...upstream.apiKey === "" ? {} : { authorization: `Bearer ${upstream.apiKey}` } },
-			signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS)
+			signal: budget.signal
 		});
 	} catch (error) {
 		throw new ImageGenError(`failed to fetch the generated image url: ${error instanceof Error ? error.message : String(error)}`);
+	} finally {
+		budget.dispose();
 	}
 	if (!response.ok) throw new ImageGenError(`failed to fetch the generated image url: HTTP ${response.status}`);
 	const buffer = Buffer.from(await response.arrayBuffer());
@@ -273,18 +376,21 @@ async function requestOneImage(baseUrl, upstream, request, params, signal) {
 			...params
 		});
 	}
+	const budget = requestSignal(signal, UPSTREAM_TIMEOUT_MS);
 	let response;
 	try {
 		response = await fetch(`${baseUrl}/images/${request.mode === "edit" ? "edits" : "generations"}`, {
 			method: "POST",
 			headers,
 			body,
-			signal: signal === void 0 ? AbortSignal.timeout(UPSTREAM_TIMEOUT_MS) : AbortSignal.any([signal, AbortSignal.timeout(UPSTREAM_TIMEOUT_MS)])
+			signal: budget.signal
 		});
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		if (/aborter/i.test(message) || /timeout/i.test(message)) throw new ImageGenError("上游接口响应超时（240 秒）", "upstream-timeout");
 		throw new ImageGenError(`无法连接上游接口：${message}`, "upstream-unreachable");
+	} finally {
+		budget.dispose();
 	}
 	let payload;
 	try {
@@ -340,128 +446,6 @@ function extensionOf$2(mime) {
 	}
 }
 //#endregion
-//#region src/prompt-enhancer.ts
-function endpoint(base, suffix) {
-	return `${base.replace(/\/+$/, "")}${suffix}`;
-}
-function headers(apiKey) {
-	return {
-		"content-type": "application/json",
-		...apiKey.trim() === "" ? {} : { authorization: `Bearer ${apiKey.trim()}` }
-	};
-}
-async function responseJson(response) {
-	const body = await response.json().catch(() => void 0);
-	if (!response.ok || body === void 0 || body === null || typeof body !== "object") {
-		const message = body !== null && typeof body === "object" && typeof body.error?.message === "string" ? body.error.message : `HTTP ${response.status}`;
-		throw new Error(message);
-	}
-	return body;
-}
-/** List chat models exposed by an OpenAI-compatible endpoint. */
-async function listPromptModels(config) {
-	if (config.apiUrl.trim() === "") throw new Error("prompt enhancement API URL is required");
-	const body = await responseJson(await fetch(endpoint(config.apiUrl, "/models"), { headers: headers(config.apiKey) }));
-	return (Array.isArray(body.data) ? body.data : []).flatMap((item) => item !== null && typeof item === "object" && typeof item.id === "string" ? [item.id] : []).sort((a, b) => a.localeCompare(b));
-}
-/** Expand a concise image request into a production-ready image prompt. */
-async function enhancePrompt(config, prompt) {
-	if (config.apiUrl.trim() === "" || config.model.trim() === "") throw new Error("prompt enhancement model is not configured");
-	const body = await responseJson(await fetch(endpoint(config.apiUrl, "/chat/completions"), {
-		method: "POST",
-		headers: headers(config.apiKey),
-		body: JSON.stringify({
-			model: config.model.trim(),
-			temperature: .7,
-			messages: [{
-				role: "system",
-				content: "You are an expert image-prompt editor. Expand the user request into one vivid, specific image-generation prompt. Preserve intent and language. Add only useful visual detail: subject, composition, lighting, materials, color, camera/style and quality. Return only the finished prompt, with no preface or markdown."
-			}, {
-				role: "user",
-				content: prompt
-			}]
-		})
-	}));
-	const choices = Array.isArray(body.choices) ? body.choices : [];
-	const content = choices[0] !== null && typeof choices[0] === "object" ? choices[0].message?.content : void 0;
-	if (typeof content !== "string" || content.trim() === "") throw new Error("chat model returned an empty prompt");
-	return content.trim();
-}
-//#endregion
-//#region src/task-queue.ts
-/** In-memory, host-resident image generation queue. */
-var GenerationTaskQueue = class {
-	run;
-	tasks = [];
-	controllers = /* @__PURE__ */ new Map();
-	running = false;
-	constructor(run) {
-		this.run = run;
-	}
-	list() {
-		return this.tasks.map((task) => ({
-			...task,
-			request: { ...task.request },
-			...task.result === void 0 ? {} : { result: task.result }
-		}));
-	}
-	submit(request) {
-		const task = {
-			id: randomUUID(),
-			request: { ...request },
-			status: "queued",
-			createdAt: Date.now()
-		};
-		this.tasks.unshift(task);
-		this.drain();
-		return task;
-	}
-	cancel(id) {
-		const task = this.tasks.find((item) => item.id === id);
-		if (task === void 0 || task.status === "completed" || task.status === "failed" || task.status === "cancelled") return task;
-		task.status = "cancelled";
-		task.finishedAt = Date.now();
-		this.controllers.get(id)?.abort();
-		return task;
-	}
-	retry(id) {
-		const previous = this.tasks.find((item) => item.id === id);
-		return previous === void 0 ? void 0 : this.submit(previous.request);
-	}
-	async drain() {
-		if (this.running) return;
-		this.running = true;
-		try {
-			for (;;) {
-				const task = this.tasks.find((item) => item.status === "queued");
-				if (task === void 0) return;
-				task.status = "running";
-				task.startedAt = Date.now();
-				const controller = new AbortController();
-				this.controllers.set(task.id, controller);
-				try {
-					const result = await this.run(task.request, controller.signal);
-					if (this.tasks.find((item) => item.id === task.id)?.status !== "cancelled") {
-						task.status = "completed";
-						task.result = result;
-						task.finishedAt = Date.now();
-					}
-				} catch (error) {
-					if (this.tasks.find((item) => item.id === task.id)?.status !== "cancelled") {
-						task.status = "failed";
-						task.error = error instanceof Error ? error.message : String(error);
-						task.finishedAt = Date.now();
-					}
-				} finally {
-					this.controllers.delete(task.id);
-				}
-			}
-		} finally {
-			this.running = false;
-		}
-	}
-};
-//#endregion
 //#region src/history-store.ts
 /**
 * Host-persisted generation history: images are stored as individual files
@@ -643,6 +627,146 @@ async function readHistoryImage(file) {
 	}
 }
 //#endregion
+//#region src/task-queue.ts
+/** In-memory, host-resident image generation queue. */
+var GenerationTaskQueue = class {
+	run;
+	tasks = [];
+	controllers = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	running = false;
+	constructor(run) {
+		this.run = run;
+	}
+	list() {
+		return this.tasks.map((task) => this.snapshot(task));
+	}
+	/** Observe queue state changes. Listener failures never disrupt generation. */
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	submit(request) {
+		const task = {
+			id: randomUUID(),
+			request: { ...request },
+			status: "queued",
+			createdAt: Date.now()
+		};
+		this.tasks.unshift(task);
+		this.publish(task);
+		this.drain();
+		return this.snapshot(task);
+	}
+	cancel(id) {
+		const task = this.tasks.find((item) => item.id === id);
+		if (task === void 0 || task.status === "completed" || task.status === "failed" || task.status === "cancelled") return task;
+		task.status = "cancelled";
+		task.finishedAt = Date.now();
+		this.controllers.get(id)?.abort();
+		this.publish(task);
+		return this.snapshot(task);
+	}
+	retry(id) {
+		const previous = this.tasks.find((item) => item.id === id);
+		return previous === void 0 ? void 0 : this.submit(previous.request);
+	}
+	async drain() {
+		if (this.running) return;
+		this.running = true;
+		try {
+			for (;;) {
+				const task = this.tasks.find((item) => item.status === "queued");
+				if (task === void 0) return;
+				task.status = "running";
+				task.startedAt = Date.now();
+				this.publish(task);
+				const controller = new AbortController();
+				this.controllers.set(task.id, controller);
+				try {
+					const result = await this.run(task.request, controller.signal);
+					if (this.tasks.find((item) => item.id === task.id)?.status !== "cancelled") {
+						task.status = "completed";
+						task.result = result;
+						task.finishedAt = Date.now();
+						this.publish(task);
+					}
+				} catch (error) {
+					if (this.tasks.find((item) => item.id === task.id)?.status !== "cancelled") {
+						task.status = "failed";
+						task.error = error instanceof Error ? error.message : String(error);
+						task.finishedAt = Date.now();
+						this.publish(task);
+					}
+				} finally {
+					this.controllers.delete(task.id);
+				}
+			}
+		} finally {
+			this.running = false;
+		}
+	}
+	publish(task) {
+		const snapshot = this.snapshot(task);
+		for (const listener of this.listeners) try {
+			listener(snapshot);
+		} catch {}
+	}
+	snapshot(task) {
+		return {
+			...task,
+			request: { ...task.request },
+			...task.result === void 0 ? {} : { result: task.result }
+		};
+	}
+};
+//#endregion
+//#region src/generation-runtime.ts
+/**
+* Shared host-side generation runtime. Both the browser routes and Agent tools
+* submit to this one queue so persisted history and cancellation semantics stay
+* identical regardless of where a request originated.
+*/
+var ImageGenerationRuntime = class {
+	resolve;
+	history;
+	queue;
+	constructor(resolve, history = { append: appendHistory }) {
+		this.resolve = resolve;
+		this.history = history;
+		this.queue = new GenerationTaskQueue((request, signal) => this.run(request, signal));
+	}
+	async run(request, signal) {
+		const result = await generateImage(this.resolve(), request, { signal });
+		try {
+			const history = await this.history.append({
+				id: randomUUID(),
+				createdAt: Date.now(),
+				mode: request.mode,
+				model: request.model,
+				prompt: request.prompt,
+				size: request.size,
+				quality: request.quality,
+				detail: request.detail,
+				n: request.n,
+				images: result.images,
+				...request.refName === void 0 ? {} : { refName: request.refName }
+			});
+			return {
+				...result,
+				history
+			};
+		} catch (error) {
+			return {
+				...result,
+				historyError: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+};
+//#endregion
 //#region src/gallery-store.ts
 /**
 * Host-persisted gallery (user-curated favorites): mirrors the history store
@@ -1286,7 +1410,7 @@ function parseGenerateRequest(body) {
 	if (prompt === "") return void 0;
 	return {
 		mode: body.mode === "edit" ? "edit" : "text",
-		model: typeof body.model === "string" ? body.model : "gpt-image-2",
+		model: typeof body.model === "string" ? body.model : "",
 		prompt,
 		size: typeof body.size === "string" ? body.size : "auto",
 		quality: typeof body.quality === "string" ? body.quality : "auto",
@@ -1403,34 +1527,19 @@ function makeRoutes(deps) {
 		apiKey: "",
 		model: ""
 	}));
-	const runGeneration = async (request, signal) => {
-		const result = await generateImage(deps.resolve(), request, { signal });
-		try {
-			const entries = await history.append({
-				id: randomUUID(),
-				createdAt: Date.now(),
-				mode: request.mode,
-				model: request.model,
-				prompt: request.prompt,
-				size: request.size,
-				quality: request.quality,
-				detail: request.detail,
-				n: request.n,
-				images: result.images,
-				...request.refName === void 0 ? {} : { refName: request.refName }
-			});
-			return {
-				...result,
-				history: entries
-			};
-		} catch (error) {
-			return {
-				...result,
-				historyError: messageOf(error)
-			};
-		}
+	const resolveImageModels = deps.resolveImageModels ?? (() => normalizeImageModels(void 0));
+	const parseConfiguredRequest = (body) => {
+		const request = parseGenerateRequest(body);
+		if (request === void 0) return void 0;
+		const models = normalizeImageModels(resolveImageModels());
+		const model = request.model.trim() === "" ? models[0] : request.model.trim();
+		if (!models.includes(model)) throw new Error(`image model "${model}" is not configured; choose one of: ${models.join(", ")}`);
+		return {
+			...request,
+			model
+		};
 	};
-	const taskQueue = new GenerationTaskQueue((request, signal) => runGeneration(request, signal));
+	const runtime = deps.runtime ?? new ImageGenerationRuntime(deps.resolve, history);
 	const guard = (req, res, method) => {
 		if (!isLoopbackRequest(req)) {
 			writeJson(res, 403, { error: "forbidden: loopback-only" });
@@ -1443,6 +1552,25 @@ function makeRoutes(deps) {
 		return true;
 	};
 	return [
+		{
+			kind: "exact",
+			path: IMAGE_MODEL_API.models,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						models: await listOpenAIModels(deps.resolve())
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "image-models-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
 		{
 			kind: "exact",
 			path: PROMPT_ENHANCE_API.models,
@@ -1565,7 +1693,17 @@ function makeRoutes(deps) {
 					});
 					return;
 				}
-				const request = parseGenerateRequest(body);
+				let request;
+				try {
+					request = parseConfiguredRequest(body);
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "image-model-not-configured",
+						message: messageOf(error)
+					});
+					return;
+				}
 				if (request === void 0) {
 					writeJson(res, 200, {
 						ok: false,
@@ -1577,7 +1715,7 @@ function makeRoutes(deps) {
 				try {
 					writeJson(res, 200, {
 						ok: true,
-						...await runGeneration(request)
+						...await runtime.run(request)
 					});
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error);
@@ -1595,7 +1733,17 @@ function makeRoutes(deps) {
 			handler: async (req, res) => {
 				if (!guard(req, res, "POST")) return;
 				const body = await readJsonBody(req);
-				const request = body === void 0 ? void 0 : parseGenerateRequest(body);
+				let request;
+				try {
+					request = body === void 0 ? void 0 : parseConfiguredRequest(body);
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "image-model-not-configured",
+						message: messageOf(error)
+					});
+					return;
+				}
 				if (request === void 0) {
 					writeJson(res, 200, {
 						ok: false,
@@ -1606,7 +1754,7 @@ function makeRoutes(deps) {
 				}
 				writeJson(res, 200, {
 					ok: true,
-					task: taskQueue.submit(request)
+					task: runtime.queue.submit(request)
 				});
 			}
 		},
@@ -1617,7 +1765,7 @@ function makeRoutes(deps) {
 				if (!guard(req, res, "POST")) return;
 				writeJson(res, 200, {
 					ok: true,
-					tasks: taskQueue.list()
+					tasks: runtime.queue.list()
 				});
 			}
 		},
@@ -1627,7 +1775,7 @@ function makeRoutes(deps) {
 			handler: async (req, res) => {
 				if (!guard(req, res, "POST")) return;
 				const body = await readJsonBody(req);
-				const task = typeof body?.id === "string" ? taskQueue.cancel(body.id) : void 0;
+				const task = typeof body?.id === "string" ? runtime.queue.cancel(body.id) : void 0;
 				if (task === void 0) {
 					writeJson(res, 200, {
 						ok: false,
@@ -1648,7 +1796,7 @@ function makeRoutes(deps) {
 			handler: async (req, res) => {
 				if (!guard(req, res, "POST")) return;
 				const body = await readJsonBody(req);
-				const task = typeof body?.id === "string" ? taskQueue.retry(body.id) : void 0;
+				const task = typeof body?.id === "string" ? runtime.queue.retry(body.id) : void 0;
 				if (task === void 0) {
 					writeJson(res, 200, {
 						ok: false,
@@ -2097,6 +2245,328 @@ function makeRoutes(deps) {
 	];
 }
 //#endregion
+//#region src/agent-image-tools.ts
+const imageRefSchema = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		attachment_id: {
+			type: "string",
+			required: true
+		},
+		media_type: {
+			type: "string",
+			required: true
+		},
+		bytes: {
+			type: "integer",
+			required: true
+		},
+		width: {
+			type: "integer",
+			required: true
+		},
+		height: {
+			type: "integer",
+			required: true
+		},
+		name: { type: "string" }
+	}
+};
+const taskResultSchema = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		task_id: {
+			type: "string",
+			required: true
+		},
+		status: {
+			type: "string",
+			required: true
+		},
+		message: {
+			type: "string",
+			required: true
+		},
+		error: { type: "string" },
+		images: {
+			type: "array",
+			required: true,
+			items: imageRefSchema
+		}
+	}
+};
+function acceptedMediaType(value) {
+	return value === "image/png" || value === "image/jpeg" || value === "image/webp" || value === "image/gif";
+}
+function projectRef(ref) {
+	return {
+		attachment_id: String(ref.attachmentId),
+		media_type: ref.mediaType,
+		bytes: ref.bytes,
+		width: ref.width,
+		height: ref.height,
+		...ref.name === void 0 ? {} : { name: ref.name }
+	};
+}
+function restoreRef(value) {
+	if (!acceptedMediaType(value.media_type)) throw new ImageGenError("source_image.media_type is not a supported image type", "bad-reference-image");
+	if (!Number.isInteger(value.bytes) || value.bytes < 1 || !Number.isInteger(value.width) || value.width < 1 || !Number.isInteger(value.height) || value.height < 1) throw new ImageGenError("source_image metadata is invalid", "bad-reference-image");
+	return {
+		attachmentId: value.attachment_id,
+		mediaType: value.media_type,
+		bytes: value.bytes,
+		width: value.width,
+		height: value.height,
+		...value.name === void 0 ? {} : { name: value.name }
+	};
+}
+function imageDataUrl(image) {
+	return `data:${image.ref.mediaType};base64,${Buffer.from(image.data).toString("base64")}`;
+}
+function renderTaskResult(value) {
+	return [{
+		type: "text",
+		text: JSON.stringify(value)
+	}, ...value.images.map((image) => ({
+		type: "image",
+		attachment: restoreRef(image)
+	}))];
+}
+/** Register the global Agent tools and unregister them with the plugin lifecycle. */
+function registerAgentImageTools(ctx, runtime, resolve) {
+	const attachmentRefs = /* @__PURE__ */ new Map();
+	const taskSubscriptions = /* @__PURE__ */ new Set();
+	const ensureConfigured = () => {
+		const config = resolve();
+		if (!config.enabled) throw new ImageGenError("AI image generation is disabled. Open Settings > Plugins > AI Image and enable it.", "plugin-disabled");
+		if (!config.allowAgentImageGeneration) throw new ImageGenError("Agent image generation is disabled in Settings > Plugins > AI Image.", "agent-generation-disabled");
+		if (config.apiUrl.trim() === "" || config.apiKey.trim() === "") throw new ImageGenError("Image API credentials are not configured. Open Settings > Plugins > AI Image and fill in API URL and API key.", "image-api-not-configured");
+	};
+	const selectedModel = (requested) => {
+		const models = normalizeImageModels(resolve().imageModels);
+		const model = typeof requested === "string" && requested.trim() !== "" ? requested.trim() : models[0];
+		if (!models.includes(model)) throw new ImageGenError(`Image model "${model}" is not configured. Choose one of: ${models.join(", ")}.`, "image-model-not-configured");
+		return model;
+	};
+	const materializeTaskImages = (task) => {
+		if (task.status !== "completed") return Promise.resolve([]);
+		const existing = attachmentRefs.get(task.id);
+		if (existing !== void 0) return existing;
+		const pending = ctx.attachments.saveImages((task.result?.images ?? []).map((image, index) => toSaveImage(image, task.id, index))).then((refs) => refs.map(projectRef));
+		attachmentRefs.set(task.id, pending);
+		pending.catch(() => {
+			if (attachmentRefs.get(task.id) === pending) attachmentRefs.delete(task.id);
+		});
+		return pending;
+	};
+	const taskResult = async (task) => {
+		const images = await materializeTaskImages(task);
+		return {
+			task_id: task.id,
+			status: task.status,
+			message: task.status === "completed" ? "Generation completed. The images are attached below and can be reused as source_image in edit_image." : task.status === "failed" ? "Generation failed." : task.status === "cancelled" ? "Generation was cancelled." : "Generation is still running. Completion will be delivered to the conversation automatically with image attachments.",
+			...task.error === void 0 ? {} : { error: task.error },
+			images
+		};
+	};
+	const findTask = (id) => {
+		const task = runtime.queue.list().find((candidate) => candidate.id === id);
+		if (task === void 0) throw new ImageGenError(`Image generation task ${id} was not found.`, "task-not-found");
+		return task;
+	};
+	const notifyCompletion = async (agent, task) => {
+		const result = await taskResult(task);
+		const completed = task.status === "completed";
+		const text = completed ? `图像生成任务已完成（${task.id}）。图片已附在这条消息中，可以直接查看、下载或作为后续图生图的参考。` : task.status === "cancelled" ? `图像生成任务已取消（${task.id}）。` : `图像生成任务失败（${task.id}）：${task.error ?? "未知错误"}`;
+		agent.send(createUserMessage({
+			content: [{
+				type: "text",
+				text
+			}, ...completed ? result.images.map((image) => ({
+				type: "image",
+				attachment: restoreRef(image)
+			})) : []],
+			source: { kind: "user" }
+		}), "next-turn", true);
+	};
+	const watchTask = (task, agent) => {
+		if (agent === void 0) return;
+		let dispose;
+		const onChange = (updated) => {
+			if (updated.id !== task.id || !isFinalTask(updated)) return;
+			dispose?.();
+			if (dispose !== void 0) taskSubscriptions.delete(dispose);
+			notifyCompletion(agent, updated).catch(() => {});
+		};
+		dispose = runtime.queue.subscribe(onChange);
+		taskSubscriptions.add(dispose);
+		const current = findTask(task.id);
+		if (isFinalTask(current)) onChange(current);
+	};
+	const disposers = [
+		ctx.tools.register(defineTool({
+			name: "generate_image",
+			description: "Queue a text-to-image generation request. This returns immediately with a task id. When it finishes, the conversation automatically receives a visible image-attachment notification; do not repeatedly poll. Only use models configured for this plugin; omit model to use the first configured image model. Use get_image_generation_task only for an explicit status check or recovery.",
+			parameters: {
+				prompt: {
+					type: "string",
+					required: true,
+					description: "Detailed image-generation prompt."
+				},
+				model: {
+					type: "string",
+					description: "One of the configured image models. Defaults to the first configured model."
+				},
+				size: {
+					type: "string",
+					description: "Aspect ratio such as 1:1, 16:9, 9:16, or auto."
+				},
+				quality: {
+					type: "string",
+					description: "auto, 1k, 2k, or 4k."
+				},
+				count: {
+					type: "integer",
+					description: "Number of images, 1 to 4. Defaults to 1."
+				},
+				detail: {
+					type: "string",
+					description: "Optional provider detail value, for example standard or high."
+				}
+			},
+			output: {
+				schema: taskResultSchema,
+				render: (_args, value) => renderTaskResult(value)
+			},
+			async execute(args, exec) {
+				ensureConfigured();
+				const task = runtime.queue.submit({
+					mode: "text",
+					model: selectedModel(args.model),
+					prompt: args.prompt.trim(),
+					size: args.size ?? "auto",
+					quality: args.quality ?? "auto",
+					n: Math.min(4, Math.max(1, args.count ?? 1)),
+					detail: args.detail ?? ""
+				});
+				watchTask(task, exec.agent);
+				return taskResult(task);
+			}
+		})),
+		ctx.tools.register(defineTool({
+			name: "edit_image",
+			description: "Queue an image-to-image edit. source_image must be an image reference returned by a completed generation notification or get_image_generation_task; pass that entire object unchanged. Only configured image models are allowed; omit model to use the first configured model. Completion is automatically delivered to the conversation with visible image attachments; do not repeatedly poll.",
+			parameters: {
+				prompt: {
+					type: "string",
+					required: true,
+					description: "How to transform the source image."
+				},
+				source_image: {
+					...imageRefSchema,
+					required: true,
+					description: "Image reference returned by get_image_generation_task."
+				},
+				model: {
+					type: "string",
+					description: "One of the configured image models. Defaults to the first configured model."
+				},
+				size: {
+					type: "string",
+					description: "Aspect ratio such as 1:1, 16:9, 9:16, or auto."
+				},
+				quality: {
+					type: "string",
+					description: "auto, 1k, 2k, or 4k."
+				},
+				count: {
+					type: "integer",
+					description: "Number of images, 1 to 4. Defaults to 1."
+				},
+				detail: {
+					type: "string",
+					description: "Optional provider detail value."
+				}
+			},
+			output: {
+				schema: taskResultSchema,
+				render: (_args, value) => renderTaskResult(value)
+			},
+			async execute(args, exec) {
+				ensureConfigured();
+				const reference = await ctx.attachments.readImage(restoreRef(args.source_image), exec.signal);
+				const task = runtime.queue.submit({
+					mode: "edit",
+					model: selectedModel(args.model),
+					prompt: args.prompt.trim(),
+					size: args.size ?? "auto",
+					quality: args.quality ?? "auto",
+					n: Math.min(4, Math.max(1, args.count ?? 1)),
+					detail: args.detail ?? "",
+					image: imageDataUrl(reference),
+					...reference.ref.name === void 0 ? {} : { refName: reference.ref.name }
+				});
+				watchTask(task, exec.agent);
+				return taskResult(task);
+			}
+		})),
+		ctx.tools.register(defineTool({
+			name: "get_image_generation_task",
+			description: "Optionally check an image-generation task status. Completed tasks return image references for edit_image, but the conversation already receives a visible completion notification automatically; do not poll repeatedly.",
+			parameters: { task_id: {
+				type: "string",
+				required: true,
+				description: "Task id returned by generate_image or edit_image."
+			} },
+			output: {
+				schema: taskResultSchema,
+				render: (_args, value) => renderTaskResult(value)
+			},
+			async execute(args) {
+				ensureConfigured();
+				return taskResult(findTask(args.task_id));
+			}
+		})),
+		ctx.tools.register(defineTool({
+			name: "cancel_image_generation_task",
+			description: "Cancel a queued or running image generation task.",
+			parameters: { task_id: {
+				type: "string",
+				required: true,
+				description: "Task id returned by generate_image or edit_image."
+			} },
+			output: {
+				schema: taskResultSchema,
+				render: (_args, value) => renderTaskResult(value)
+			},
+			async execute(args) {
+				ensureConfigured();
+				const task = runtime.queue.cancel(args.task_id);
+				if (task === void 0) throw new ImageGenError(`Image generation task ${args.task_id} was not found.`, "task-not-found");
+				return taskResult(task);
+			}
+		}))
+	];
+	return () => {
+		for (const dispose of taskSubscriptions) dispose();
+		taskSubscriptions.clear();
+		for (const dispose of disposers) dispose();
+	};
+}
+function isFinalTask(task) {
+	return task.status === "completed" || task.status === "failed" || task.status === "cancelled";
+}
+function toSaveImage(image, taskId, index) {
+	const mediaType = acceptedMediaType(image.mime) ? image.mime : "image/png";
+	return {
+		data: Buffer.from(image.b64, "base64"),
+		mediaType,
+		name: `imagegen-${taskId}-${index + 1}.${mediaType === "image/jpeg" ? "jpg" : mediaType.slice(6)}`
+	};
+}
+//#endregion
 //#region src/index.ts
 /** Stable cordis plugin name. */
 const name = "imagegen";
@@ -2107,8 +2577,10 @@ const ImageGenSettingsNamespace = settingsNamespace(IMAGEGEN_SETTINGS_NAMESPACE)
 const Config = z.object({
 	enabled: z.boolean().default(true),
 	announceToAgent: z.boolean().default(true),
+	allowAgentImageGeneration: z.boolean().default(true),
 	apiUrl: z.string().default(""),
 	apiKey: z.string().role("secret").default(""),
+	imageModels: z.array(z.string()).default([...DEFAULT_IMAGE_MODELS]),
 	promptApiUrl: z.string().default(""),
 	promptApiKey: z.string().role("secret").default(""),
 	promptModel: z.string().default("")
@@ -2116,10 +2588,15 @@ const Config = z.object({
 /** Schema defaults, re-read for hand-built contexts (the loader applies them normally). */
 const DEFAULT_ENABLED = true;
 const DEFAULT_ANNOUNCE = true;
+const DEFAULT_ALLOW_AGENT_IMAGE_GENERATION = true;
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 150;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const IMAGEGEN_GUIDANCE = "本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2 / grok-imagine-image），支持文生图（/images/generations）与图生图（/images/edits，上传参考图，grok 模型按官方 JSON image_url 协议发送）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载；可一键把满意的图片加入「画廊」（工作台顶部 文生图 / 图生图 / 画廊 三个标签页，画廊在右侧展示，收藏持久化在本地 ~/.dsh/dsh-imagegen/gallery/）。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：打包 awesome-gpt-image-2 的数百条 gpt-image-2 提示词案例（含中文标题、分类、参考图，可搜索/按分类筛选），参考图经宿主代理按需缓存到本地；用户可一键把模板提示词填入提示词框再生成。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问 vibeui.top。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / grok-imagine-image / 文生图 / 图生图 / 画廊 / 提示词模板」时即指本插件，请据此协作。";
+const IMAGEGEN_GUIDANCE = "本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：对接 OpenAI 兼容图像生成 API，模型由用户在「设置 → 插件 → AI 生图」中检测或手动配置的生图模型列表决定；支持文生图（/images/generations）与图生图（/images/edits，上传参考图，grok-imagine 模型按官方 JSON image_url 协议发送）。API 地址与密钥在 GUI 设置中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。模型只能使用已配置的生图模型；模型出现在 /models 中不等于其网关原生支持生图协议，遇到 Qwen、Gemini 等非 OpenAI 生图协议时应如实说明上游兼容性。可一键把满意的图片加入「画廊」。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：打包 awesome-gpt-image-2 的数百条提示词案例，可搜索、筛选与复用。Agent 可直接调用 `generate_image` 提交文生图，也可用 `edit_image` 图生图；任务后台异步执行，完成后插件会自动唤醒原对话，并以可直接查看和复用的图片附件回贴结果，因此不要反复轮询。仅在用户明确要求进度或需要恢复任务时，才使用 `get_image_generation_task` 查询状态。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问 vibeui.top。用户提到「生图 / 绘画 / 生成图片 / 文生图 / 图生图 / 画廊 / 提示词模板」时即指本插件，请据此协作。";
+/** Add the live allow-list so an Agent can honor a user's model choice. */
+function guidanceFor(imageModels) {
+	return `${IMAGEGEN_GUIDANCE} 当前允许调用的生图模型：${imageModels.join("、")}。用户指定其中某个模型时，工具参数 model 必须使用该精确名称；未指定时使用列表中的第一个。`;
+}
 /**
 * Mount the settings section, routes, and announcement.
 * @param ctx - host plugin context carrying webServer/systemPrompt.
@@ -2132,13 +2609,22 @@ function apply(ctx, config) {
 		return {
 			enabled: value.enabled ?? DEFAULT_ENABLED,
 			announceToAgent: value.announceToAgent ?? DEFAULT_ANNOUNCE,
+			allowAgentImageGeneration: value.allowAgentImageGeneration ?? DEFAULT_ALLOW_AGENT_IMAGE_GENERATION,
 			apiUrl: value.apiUrl ?? "",
 			apiKey: value.apiKey ?? "",
+			imageModels: normalizeImageModels(value.imageModels),
 			promptApiUrl: value.promptApiUrl ?? "",
 			promptApiKey: value.promptApiKey ?? "",
 			promptModel: value.promptModel ?? ""
 		};
 	};
+	const runtime = new ImageGenerationRuntime(() => {
+		const value = resolve();
+		return {
+			apiUrl: value.apiUrl,
+			apiKey: value.apiKey
+		};
+	});
 	ctx.inject(["settings"], (sctx) => {
 		const seam = sctx.get("settings");
 		sctx.effect(() => {
@@ -2158,13 +2644,27 @@ function apply(ctx, config) {
 						apiKey: value.promptApiKey.trim() || value.apiKey,
 						model: value.promptModel
 					};
-				}
+				},
+				resolveImageModels: () => resolve().imageModels,
+				runtime
 			}).map((route) => ctx.webServer.register(route));
 			return () => {
 				for (const dispose of disposers) dispose();
 			};
 		}, "dsh-imagegen: routes");
 	});
+	ctx.inject(["tools", "attachments"], (tctx) => {
+		tctx.effect(() => registerAgentImageTools(tctx, runtime, () => {
+			const value = resolve();
+			return {
+				enabled: value.enabled,
+				allowAgentImageGeneration: value.allowAgentImageGeneration,
+				apiUrl: value.apiUrl,
+				apiKey: value.apiKey,
+				imageModels: value.imageModels
+			};
+		}), "dsh-imagegen: agent image tools");
+	});
 	let disposeSection;
 	const sync = () => {
 		if (disposeSection !== void 0) {
@@ -2176,7 +2676,7 @@ function apply(ctx, config) {
 		disposeSection = ctx.systemPrompt.section({
 			name: "plugin:dsh-imagegen",
 			order: SECTION_ORDER,
-			text: IMAGEGEN_GUIDANCE
+			text: guidanceFor(value.imageModels)
 		});
 	};
 	installSettingsSection(ctx, ImageGenSettingsNamespace, Config, config ?? {}, {
@@ -2189,4 +2689,4 @@ function apply(ctx, config) {
 	sync();
 }
 //#endregion
-export { CURRENT_VERSION, Config, IMAGEGEN_GUIDANCE, ImageGenError, ImageGenSettingsNamespace, appendGallery, apply, checkForUpdate, clearGallery, clearTemplateMemo, clearUpdateCache, compareVersions, generateImage, inject, installUpdate, listGallery, listTemplates, makeRoutes, name, profileFromProcess, readGalleryImage, readTemplateImage, refreshTemplates, removeGallery, updateGalleryTags };
+export { CURRENT_VERSION, Config, IMAGEGEN_GUIDANCE, ImageGenError, ImageGenSettingsNamespace, ImageGenerationRuntime, appendGallery, apply, checkForUpdate, clearGallery, clearTemplateMemo, clearUpdateCache, compareVersions, generateImage, inject, installUpdate, listGallery, listTemplates, makeRoutes, name, profileFromProcess, readGalleryImage, readTemplateImage, refreshTemplates, registerAgentImageTools, removeGallery, updateGalleryTags };