dsh-draw 0.1.0

package/lib/index.js

@@ -0,0 +1,1429 @@
+import { i as statusToView, n as imageToWire, r as probeToWire, t as DRAW_INVOCATIONS } from "./wire-Cc4JZ3jR.js";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import z from "@deepseek-ai/schemastery";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { AttachmentId } from "@deepseek-ai/dsh-attachment";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/config.ts
+/**
+* Plugin configuration for `dsh-draw` and its explicit resolve step.
+* `resolveConfig` re-judges every default and bound so programmatic
+* construction that bypasses Schemastery normalization still fails loud
+* instead of running with hidden defaults (the explicit-resolve contract).
+*
+* @module dsh-draw/config
+*/
+/** Default per-generation HTTP timeout in milliseconds. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 12e4;
+/** Ceiling for one generation call: engines can take minutes per image. */
+const MAX_REQUEST_TIMEOUT_MS = 6e5;
+/** Default prompt length cap (characters). */
+const DEFAULT_MAX_PROMPT_LENGTH = 4e3;
+/** Ceiling on the prompt length cap. */
+const MAX_PROMPT_LENGTH = 32e3;
+/** Ceiling on the per-session generation-call cap. */
+const MAX_GENERATIONS_PER_SESSION = 1e5;
+/** Default per-session image-byte cap (200 MiB). */
+const DEFAULT_MAX_BYTES_PER_SESSION = 209715200;
+/** Ceiling on the per-session image-byte cap (4 GiB). */
+const MAX_BYTES_PER_SESSION = 4294967296;
+/** Default engine cooldown after the failure threshold trips (ms). */
+const DEFAULT_COOLDOWN_MS = 6e4;
+/** Ceiling on the engine cooldown. */
+const MAX_COOLDOWN_MS = 36e5;
+/** The two shipped engine presets: OpenAI Images and Zhipu CogView. */
+const DEFAULT_ENGINES = Object.freeze([Object.freeze({
+	id: "openai",
+	baseUrl: "https://api.openai.com/v1",
+	model: "gpt-image-1",
+	apiKeyRef: "OPENAI_API_KEY",
+	enabled: true,
+	sizeMap: Object.freeze({
+		square: "1024x1024",
+		landscape: "1536x1024",
+		portrait: "1024x1536",
+		auto: "auto"
+	}),
+	qualitySupported: true,
+	styleSupported: true,
+	responseFormat: "b64_json",
+	imageMediaType: "image/png"
+}), Object.freeze({
+	id: "cogview",
+	baseUrl: "https://open.bigmodel.cn/api/paas/v4",
+	model: "cogview-3-flash",
+	apiKeyRef: "ZHIPU_API_KEY",
+	enabled: true,
+	sizeMap: Object.freeze({
+		square: "1024x1024",
+		landscape: "1344x768",
+		portrait: "768x1344",
+		auto: "1024x1024"
+	}),
+	qualitySupported: false,
+	styleSupported: false,
+	responseFormat: "url",
+	imageMediaType: "image/png"
+})]);
+/** Default size map for user-configured engines (the OpenAI vocabulary). */
+const DEFAULT_SIZE_MAP = Object.freeze({
+	square: "1024x1024",
+	landscape: "1536x1024",
+	portrait: "1024x1536",
+	auto: "auto"
+});
+/** Schemastery schema for loader-validated configuration. */
+const Config = z.object({
+	engines: z.array(z.object({
+		id: z.string().min(1).max(64),
+		baseUrl: z.string().min(1).max(2048),
+		model: z.string().min(1).max(128),
+		apiKeyRef: z.string().min(1).max(128),
+		enabled: z.boolean(),
+		sizeMap: z.object({
+			square: z.string().min(1).max(64),
+			landscape: z.string().min(1).max(64),
+			portrait: z.string().min(1).max(64),
+			auto: z.string().min(1).max(64)
+		}),
+		qualitySupported: z.boolean(),
+		styleSupported: z.boolean(),
+		responseFormat: z.union(["b64_json", "url"]),
+		imageMediaType: z.union([
+			"image/png",
+			"image/jpeg",
+			"image/webp",
+			"image/gif"
+		])
+	})).default([...DEFAULT_ENGINES]),
+	defaultEngine: z.string().min(1).max(64).default("openai"),
+	requestTimeoutMs: z.number().min(1e3).max(MAX_REQUEST_TIMEOUT_MS).default(DEFAULT_REQUEST_TIMEOUT_MS),
+	maxImagesPerCall: z.number().min(1).max(10).default(4),
+	maxPromptLength: z.number().min(1).max(MAX_PROMPT_LENGTH).default(DEFAULT_MAX_PROMPT_LENGTH),
+	maxGenerationsPerSession: z.number().min(1).max(MAX_GENERATIONS_PER_SESSION).default(200),
+	maxBytesPerSession: z.number().min(1048576).max(MAX_BYTES_PER_SESSION).default(DEFAULT_MAX_BYTES_PER_SESSION),
+	failureThreshold: z.number().min(1).max(10).default(2),
+	cooldownMs: z.number().min(1e3).max(MAX_COOLDOWN_MS).default(DEFAULT_COOLDOWN_MS)
+});
+const ENGINE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/u;
+/** Credential references are environment-variable names (POSIX identifiers). */
+const API_KEY_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/**
+* Resolve raw config to the runtime policy, re-validating defaults and bounds
+* plus the cross-field facts a per-field schema cannot see (duplicate engine
+* ids, credential-bearing base URLs, an unknown default engine).
+*
+* @param config - raw loader config; `undefined` for a bare row.
+* @returns the frozen resolved config.
+* @throws on any invalid value (fail-loud at load).
+*/
+function resolveConfig(config) {
+	const rawEngines = config?.engines ?? DEFAULT_ENGINES;
+	const engines = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const engine of rawEngines) {
+		const id = typeof engine?.id === "string" ? engine.id : "";
+		if (!ENGINE_ID_PATTERN.test(id)) throw new Error(`dsh-draw: engine id ${JSON.stringify(id)} must match ${ENGINE_ID_PATTERN}`);
+		if (seen.has(id)) throw new Error(`dsh-draw: duplicate engine id ${JSON.stringify(id)}`);
+		seen.add(id);
+		const baseUrl = engine.baseUrl ?? "";
+		let parsed;
+		try {
+			parsed = new URL(baseUrl);
+		} catch {
+			throw new Error(`dsh-draw: engine "${id}" baseUrl ${JSON.stringify(baseUrl)} is not a valid URL`);
+		}
+		if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new Error(`dsh-draw: engine "${id}" baseUrl must use http or https`);
+		if (parsed.username !== "" || parsed.password !== "") throw new Error(`dsh-draw: engine "${id}" baseUrl must not embed credentials — use the apiKeyRef credential reference instead`);
+		const model = typeof engine.model === "string" && engine.model.length > 0 && engine.model.length <= 128 ? engine.model : "";
+		if (model === "") throw new Error(`dsh-draw: engine "${id}" model must be a non-empty string of at most 128 characters`);
+		const apiKeyRef = typeof engine.apiKeyRef === "string" && API_KEY_REF_PATTERN.test(engine.apiKeyRef) ? engine.apiKeyRef : "";
+		if (apiKeyRef === "") throw new Error(`dsh-draw: engine "${id}" apiKeyRef ${JSON.stringify(engine.apiKeyRef)} must be an environment-variable name`);
+		const sizeMap = engine.sizeMap === void 0 ? DEFAULT_SIZE_MAP : engine.sizeMap;
+		for (const key of [
+			"square",
+			"landscape",
+			"portrait",
+			"auto"
+		]) {
+			const value = sizeMap[key];
+			if (typeof value !== "string" || value.length === 0 || value.length > 64) throw new Error(`dsh-draw: engine "${id}" sizeMap.${key} must be a non-empty string of at most 64 characters`);
+		}
+		const enabled = engine.enabled ?? true;
+		if (typeof enabled !== "boolean") throw new TypeError(`dsh-draw: engine "${id}" enabled must be a boolean`);
+		const qualitySupported = engine.qualitySupported ?? false;
+		if (typeof qualitySupported !== "boolean") throw new TypeError(`dsh-draw: engine "${id}" qualitySupported must be a boolean`);
+		const styleSupported = engine.styleSupported ?? false;
+		if (typeof styleSupported !== "boolean") throw new TypeError(`dsh-draw: engine "${id}" styleSupported must be a boolean`);
+		const responseFormat = engine.responseFormat ?? "b64_json";
+		if (responseFormat !== "b64_json" && responseFormat !== "url") throw new Error(`dsh-draw: engine "${id}" responseFormat must be "b64_json" or "url"`);
+		const imageMediaType = engine.imageMediaType ?? "image/png";
+		if (imageMediaType !== "image/png" && imageMediaType !== "image/jpeg" && imageMediaType !== "image/webp" && imageMediaType !== "image/gif") throw new Error(`dsh-draw: engine "${id}" imageMediaType ${JSON.stringify(imageMediaType)} is not a supported raster type`);
+		engines.push({
+			id,
+			baseUrl: baseUrl.replace(/\/+$/u, ""),
+			model,
+			apiKeyRef,
+			enabled,
+			sizeMap: Object.freeze({ ...sizeMap }),
+			qualitySupported,
+			styleSupported,
+			responseFormat,
+			imageMediaType
+		});
+	}
+	if (engines.length === 0) throw new Error("dsh-draw: at least one engine must be configured");
+	const defaultEngine = config?.defaultEngine ?? engines[0].id;
+	if (!seen.has(defaultEngine)) throw new Error(`dsh-draw: defaultEngine ${JSON.stringify(defaultEngine)} does not name a configured engine`);
+	const requestTimeoutMs = config?.requestTimeoutMs ?? 12e4;
+	if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs < 1e3 || requestTimeoutMs > 6e5) throw new Error(`dsh-draw: config.requestTimeoutMs must be a finite number between 1000 and ${MAX_REQUEST_TIMEOUT_MS}`);
+	const maxImagesPerCall = config?.maxImagesPerCall ?? 4;
+	if (!Number.isInteger(maxImagesPerCall) || maxImagesPerCall < 1 || maxImagesPerCall > 10) throw new Error(`dsh-draw: config.maxImagesPerCall must be an integer between 1 and 10`);
+	const maxPromptLength = config?.maxPromptLength ?? 4e3;
+	if (!Number.isInteger(maxPromptLength) || maxPromptLength < 1 || maxPromptLength > 32e3) throw new Error(`dsh-draw: config.maxPromptLength must be an integer between 1 and ${MAX_PROMPT_LENGTH}`);
+	const maxGenerationsPerSession = config?.maxGenerationsPerSession ?? 200;
+	if (!Number.isInteger(maxGenerationsPerSession) || maxGenerationsPerSession < 1 || maxGenerationsPerSession > 1e5) throw new Error(`dsh-draw: config.maxGenerationsPerSession must be an integer between 1 and ${MAX_GENERATIONS_PER_SESSION}`);
+	const maxBytesPerSession = config?.maxBytesPerSession ?? 209715200;
+	if (!Number.isInteger(maxBytesPerSession) || maxBytesPerSession < 1048576 || maxBytesPerSession > 4294967296) throw new Error(`dsh-draw: config.maxBytesPerSession must be an integer between 1048576 and ${MAX_BYTES_PER_SESSION}`);
+	const failureThreshold = config?.failureThreshold ?? 2;
+	if (!Number.isInteger(failureThreshold) || failureThreshold < 1 || failureThreshold > 10) throw new Error(`dsh-draw: config.failureThreshold must be an integer between 1 and 10`);
+	const cooldownMs = config?.cooldownMs ?? 6e4;
+	if (!Number.isInteger(cooldownMs) || cooldownMs < 1e3 || cooldownMs > 36e5) throw new Error(`dsh-draw: config.cooldownMs must be an integer between 1000 and ${MAX_COOLDOWN_MS}`);
+	return Object.freeze({
+		engines: Object.freeze(engines),
+		defaultEngine,
+		requestTimeoutMs,
+		maxImagesPerCall,
+		maxPromptLength,
+		maxGenerationsPerSession,
+		maxBytesPerSession,
+		failureThreshold,
+		cooldownMs
+	});
+}
+/** Engine id by which an engine is addressed, or `undefined` for an unknown id. */
+function engineById(config, id) {
+	return config.engines.find((engine) => engine.id === id);
+}
+//#endregion
+//#region src/session-events.ts
+/**
+* Append one `draw/generated` event to a session.
+*
+* @param session - owning session.
+* @param event - accounting payload.
+* @returns the logged event.
+*/
+function appendDrawGenerated(session, event) {
+	return session.append("draw/generated", event);
+}
+/**
+* Collect the `draw/generated` events of a session in log order. Declaration
+* merging narrows `event.type === 'draw/generated'` to the payload type.
+*
+* @param session - session whose log is scanned.
+* @returns the accounting events.
+*/
+function drawGeneratedEvents(session) {
+	return session.events.filter((event) => event.type === "draw/generated");
+}
+//#endregion
+//#region src/quota.ts
+/**
+* Fold one session's `draw/generated` events into current usage.
+*
+* @param session - session whose log is folded.
+* @returns generation and byte totals.
+*/
+function quotaState(session) {
+	let generations = 0;
+	let bytes = 0;
+	for (const event of drawGeneratedEvents(session)) {
+		generations += 1;
+		bytes += event.data.bytes;
+	}
+	return {
+		generations,
+		bytes
+	};
+}
+/**
+* Check the generation-call axis before any engine is contacted: a session at
+* its cap fails fast without spending engine credits.
+*
+* @param session - owning session.
+* @param limits - configured limits.
+* @returns allowance or denial.
+*/
+function checkQuotaGenerations(session, limits) {
+	const state = quotaState(session);
+	if (state.generations >= limits.maxGenerations) return {
+		allowed: false,
+		reason: "generations",
+		state
+	};
+	return {
+		allowed: true,
+		state
+	};
+}
+/**
+* Check the byte axis after the engine produced images but before anything is
+* stored: the incoming bytes must fit under the cap, otherwise the images are
+* discarded without touching the attachment store.
+*
+* @param session - owning session.
+* @param limits - configured limits.
+* @param incomingBytes - bytes the new images would add.
+* @returns allowance or denial.
+*/
+function checkQuotaBytes(session, limits, incomingBytes) {
+	const state = quotaState(session);
+	if (state.bytes + incomingBytes > limits.maxBytes) return {
+		allowed: false,
+		reason: "bytes",
+		state
+	};
+	return {
+		allowed: true,
+		state
+	};
+}
+//#endregion
+//#region src/translate.ts
+const SIZES = [
+	"square",
+	"landscape",
+	"portrait",
+	"auto"
+];
+const QUALITIES = [
+	"low",
+	"medium",
+	"high",
+	"auto"
+];
+const STYLES = ["natural", "vivid"];
+/**
+* Normalize unvalidated tool args to a {@link StandardImageRequest}; malformed
+* values fall back to defaults. The prompt passes through verbatim — length
+* validation is the drawer's job (an over-long prompt fails the call loudly
+* instead of being silently truncated).
+*
+* @param args - unvalidated tool arguments.
+* @param maxImagesPerCall - configured cap the requested count clamps to.
+* @returns the normalized request.
+*/
+function normalizeRequest(args, maxImagesPerCall) {
+	const record = typeof args === "object" && args !== null ? args : {};
+	const prompt = typeof record["prompt"] === "string" ? record["prompt"] : "";
+	const rawSize = record["size"];
+	const size = typeof rawSize === "string" && SIZES.includes(rawSize) ? rawSize : "square";
+	const rawCount = record["count"];
+	const parsedCount = typeof rawCount === "number" ? Math.trunc(rawCount) : 1;
+	const count = Math.min(Math.max(Number.isFinite(parsedCount) ? parsedCount : 1, 1), maxImagesPerCall);
+	const rawQuality = record["quality"];
+	const quality = typeof rawQuality === "string" && QUALITIES.includes(rawQuality) ? rawQuality : "auto";
+	const rawStyle = record["style"];
+	const style = typeof rawStyle === "string" && STYLES.includes(rawStyle) ? rawStyle : void 0;
+	const rawEngine = record["engine"];
+	const engine = typeof rawEngine === "string" && rawEngine.length > 0 ? rawEngine : void 0;
+	return {
+		prompt,
+		size,
+		count,
+		quality,
+		...style !== void 0 ? { style } : {},
+		...engine !== void 0 ? { engine } : {}
+	};
+}
+/**
+* Translate one standardized request into a concrete engine request.
+*
+* @param engine - resolved engine configuration.
+* @param request - normalized standard request.
+* @returns the engine request fields.
+*/
+function translateRequest(engine, request) {
+	const size = engine.sizeMap[request.size ?? "square"];
+	return {
+		model: engine.model,
+		prompt: request.prompt,
+		size,
+		n: request.count ?? 1,
+		...engine.qualitySupported && request.quality !== "auto" ? { quality: request.quality } : {},
+		...engine.styleSupported && request.style !== void 0 ? { style: request.style } : {},
+		responseFormat: engine.responseFormat
+	};
+}
+//#endregion
+//#region src/drawer.ts
+/**
+* The shared generation path.
+*/
+var Drawer = class {
+	config;
+	router;
+	deps;
+	/**
+	* @param config - resolved plugin configuration.
+	* @param router - the engine router.
+	* @param deps - per-call dependencies (public: the remote service reads them for probes).
+	*/
+	constructor(config, router, deps) {
+		this.config = config;
+		this.router = router;
+		this.deps = deps;
+	}
+	/**
+	* Run one generation end to end: normalize and validate, check quota,
+	* route through the engine chain, commit images to the attachment store,
+	* and append the audit event.
+	*
+	* @param args - unvalidated standard request (tool args or card regenerate args).
+	* @param options - cancellation, session, and source.
+	* @returns the outcome.
+	*/
+	async generate(args, options) {
+		const request = normalizeRequest(args, this.config.maxImagesPerCall);
+		if (request.prompt.trim().length === 0) return {
+			ok: false,
+			reason: "invalid-prompt",
+			message: "image_generate: prompt must be a non-empty string"
+		};
+		if (request.prompt.length > this.config.maxPromptLength) return {
+			ok: false,
+			reason: "invalid-prompt",
+			message: `image_generate: prompt exceeds the configured ${this.config.maxPromptLength}-character cap`
+		};
+		const session = options.session;
+		if (session === void 0) return {
+			ok: false,
+			reason: "no-session",
+			message: "image_generate: no session owns this call — quota accounting and the audit event need a session"
+		};
+		const limits = {
+			maxGenerations: this.config.maxGenerationsPerSession,
+			maxBytes: this.config.maxBytesPerSession
+		};
+		const generationCheck = checkQuotaGenerations(session, limits);
+		if (!generationCheck.allowed) return {
+			ok: false,
+			reason: "quota-generations",
+			message: `image_generate: session generation quota exhausted (${generationCheck.state.generations}/${limits.maxGenerations} calls)`,
+			quota: generationCheck.state
+		};
+		const startedAt = Date.now();
+		const routed = await this.router.generate(request, this.deps.engine, options.signal);
+		if (!routed.ok) return {
+			ok: false,
+			reason: "all-engines-failed",
+			message: `image_generate: no configured engine produced images${routed.attempts.length === 0 ? "" : ` (${routed.attempts.map((attempt) => attempt.engine).join(", ")})`}`,
+			attempts: routed.attempts,
+			quota: generationCheck.state
+		};
+		const attachments = this.deps.attachments?.();
+		if (attachments === void 0) return {
+			ok: false,
+			reason: "attachments-unavailable",
+			message: "image_generate: the attachment store is not composed — images cannot be saved durably",
+			quota: generationCheck.state,
+			attempts: routed.attempts
+		};
+		const totalBytes = routed.images.reduce((sum, image) => sum + image.data.byteLength, 0);
+		const byteCheck = checkQuotaBytes(session, limits, totalBytes);
+		if (!byteCheck.allowed) return {
+			ok: false,
+			reason: "quota-bytes",
+			message: `image_generate: session image-byte quota exhausted (${byteCheck.state.bytes}/${limits.maxBytes} bytes)`,
+			quota: byteCheck.state,
+			attempts: routed.attempts
+		};
+		let refs;
+		try {
+			refs = await this.saveImages(attachments, routed.engine, routed.images, options.signal);
+		} catch (error) {
+			return {
+				ok: false,
+				reason: "attachments-unavailable",
+				message: `image_generate: saving images failed: ${error instanceof Error ? error.message : String(error)}`,
+				quota: generationCheck.state,
+				attempts: routed.attempts
+			};
+		}
+		const images = refs.map((ref) => ({
+			attachmentId: String(ref.attachmentId),
+			mediaType: ref.mediaType,
+			bytes: ref.bytes,
+			width: ref.width,
+			height: ref.height,
+			...ref.name !== void 0 ? { name: ref.name } : {}
+		}));
+		const elapsedMs = Date.now() - startedAt;
+		appendDrawGenerated(session, {
+			engine: routed.engine,
+			model: routed.model,
+			source: options.source,
+			prompt: request.prompt,
+			size: request.size ?? "square",
+			quality: request.quality ?? "auto",
+			count: images.length,
+			bytes: totalBytes,
+			attachmentIds: images.map((image) => image.attachmentId),
+			elapsedMs
+		});
+		const after = checkQuotaGenerations(session, limits);
+		return {
+			ok: true,
+			engine: routed.engine,
+			model: routed.model,
+			size: request.size ?? "square",
+			images,
+			quota: after.state,
+			limits,
+			fallbackUsed: routed.fallbackUsed,
+			elapsedMs,
+			attempts: routed.attempts
+		};
+	}
+	/** Save every produced image to the attachment store; an empty image fails the batch. */
+	async saveImages(attachments, engineId, produced, signal) {
+		const refs = [];
+		for (let index = 0; index < produced.length; index += 1) {
+			signal?.throwIfAborted();
+			const image = produced[index];
+			if (image.data.byteLength === 0) throw new Error(`engine "${engineId}" produced an empty image`);
+			refs.push(await attachments.saveImage({
+				data: image.data,
+				mediaType: image.mediaType,
+				name: `${engineId}-${index + 1}.${image.mediaType === "image/jpeg" ? "jpg" : image.mediaType.slice(6)}`
+			}));
+		}
+		return refs;
+	}
+};
+//#endregion
+//#region src/http.ts
+/**
+* A transport-level failure. `status` is absent for network/timeout failures;
+* `code` routes fallback and cooldown decisions.
+*/
+var HttpError = class extends Error {
+	/** Stable failure code. */
+	code;
+	/** HTTP status when a response existed. */
+	status;
+	/** @param code - stable failure code. @param message - display-safe message. @param options - optional status and cause. */
+	constructor(code, message, options) {
+		super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "HttpError";
+		this.code = code;
+		if (options?.status !== void 0) this.status = options.status;
+	}
+};
+/**
+* Fuse a caller signal with a per-call timeout into one signal and a disposer
+* that clears the timer when the call settles.
+*
+* @param signal - caller signal, or undefined.
+* @param timeoutMs - positive timeout.
+* @returns the fused signal plus its disposer.
+*/
+function fusedSignal(signal, timeoutMs) {
+	if (signal === void 0) {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(new HttpError("timeout", `request exceeded ${timeoutMs} ms`)), timeoutMs);
+		return {
+			signal: controller.signal,
+			dispose: () => clearTimeout(timer)
+		};
+	}
+	if (signal.aborted) return {
+		signal,
+		dispose: () => void 0
+	};
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(new HttpError("timeout", `request exceeded ${timeoutMs} ms`)), timeoutMs);
+	const forward = () => {
+		controller.abort(signal.reason);
+	};
+	signal.addEventListener("abort", forward, { once: true });
+	const dispose = () => {
+		clearTimeout(timer);
+		signal.removeEventListener("abort", forward);
+	};
+	return {
+		signal: controller.signal,
+		dispose
+	};
+}
+/** Map an undici/fetch rejection to an {@link HttpError} by its observable identity. */
+function mapFetchFailure(signal, error) {
+	const reason = signal.reason;
+	if (signal.aborted && reason instanceof HttpError) return reason;
+	if (signal.aborted) return new HttpError("aborted", reason instanceof Error ? reason.message : "request aborted", { cause: error });
+	if (error instanceof Error && error.name === "TimeoutError") return new HttpError("timeout", error.message, { cause: error });
+	return new HttpError("network", error instanceof Error ? error.message : String(error), { cause: error });
+}
+/**
+* The production transport: global `fetch` (undici under Node ≥ 22) with the
+* timeout fused onto the caller signal. The response body is read to bytes;
+* oversized or unreadable bodies surface as `invalid-response`.
+*
+* @param timeoutMs - per-call timeout.
+* @param maxBytes - response byte cap (the engine's image cap plus headroom).
+* @returns a transport ready for the router.
+*/
+function defaultHttpTransport(timeoutMs, maxBytes) {
+	return { async request(request) {
+		const { signal, dispose } = fusedSignal(request.signal, timeoutMs);
+		try {
+			let response;
+			try {
+				response = await fetch(request.url, {
+					method: request.method,
+					...request.headers === void 0 ? {} : { headers: request.headers },
+					...request.body === void 0 ? {} : { body: request.body },
+					signal,
+					redirect: "follow"
+				});
+			} catch (error) {
+				throw mapFetchFailure(signal, error);
+			}
+			let body;
+			try {
+				body = new Uint8Array(await response.arrayBuffer());
+			} catch (error) {
+				throw new HttpError("invalid-response", `failed to read response body: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+			}
+			if (body.byteLength > maxBytes) throw new HttpError("invalid-response", `response body exceeds ${maxBytes} bytes`, { status: response.status });
+			return {
+				status: response.status,
+				body
+			};
+		} finally {
+			dispose();
+		}
+	} };
+}
+/**
+* Decode a standard base64 string to bytes. A malformed string fails loud —
+* a provider change would otherwise silently corrupt an image.
+*
+* @param data - base64 payload without a data: prefix.
+* @returns decoded bytes.
+* @throws when the payload is not valid base64.
+*/
+function decodeBase64(data) {
+	if (data.length === 0) throw new HttpError("invalid-response", "empty base64 image payload");
+	const binary = atob(data);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}
+//#endregion
+//#region src/sanitize.ts
+/**
+* Display sanitization for dsh-draw surfaces. Everything shown to a human —
+* the tool result text, the settings panel snapshot, probe details, engine
+* errors — passes through these pure functions so URL credentials, API keys,
+* bearer tokens, and JWTs never reach a display. Secrets themselves are
+* credential references; this module redacts what can still leak through
+* configured URLs and provider error text.
+*
+* @module dsh-draw/sanitize
+*/
+/** Replacement for every redacted credential value. */
+const REDACTED = "***";
+/** Query/field keys whose values are credentials regardless of their name casing. */
+const CREDENTIAL_KEY = /^(?:access[_-]?token|api[_-]?key|apikey|auth|authorization|client[_-]?secret|key|password|passwd|pwd|secret|sig|signature|token)$/iu;
+/** Credential keys for the unparseable-URL fallback and embedded-text scans. */
+const CREDENTIAL_KEY_SOURCE = "(?:access[_-]?token|api[_-]?key|apikey|auth(?:orization)?|client[_-]?secret|key|passw(?:or)?d|passwd|pwd|secret|sig(?:nature)?|token)";
+/** Whole userinfo before `@` (unparseable URLs only — parsed URLs redact just the password). */
+const USERINFO = /([a-z][a-z0-9+.-]*:\/\/)([^/@\s]+)@/giu;
+/** `?key=value` / `&key=value` credential pairs inside arbitrary text. */
+const QUERY_CREDENTIAL = new RegExp(`([?&](?:[^=&#\\s]*${CREDENTIAL_KEY_SOURCE}[^=&#\\s]*)=)[^&#\\s]*`, "giu");
+/** `#key=value` credential pairs in URL fragments and arbitrary text. */
+const FRAGMENT_CREDENTIAL = new RegExp(`(#[^=&#\\s]*${CREDENTIAL_KEY_SOURCE}[^=&#\\s]*=)[^&#\\s]*`, "giu");
+/** `Authorization: <value>`-style header lines in arbitrary text (quoted value first). */
+const HEADER_CREDENTIAL_QUOTED = new RegExp(`(\\b${CREDENTIAL_KEY_SOURCE}\\s*[:=]\\s*["'])[^"']*(["'])`, "giu");
+/** `Authorization: <value>`-style header lines with unquoted values. */
+const HEADER_CREDENTIAL_BARE = new RegExp(`(\\b${CREDENTIAL_KEY_SOURCE}\\s*[:=]\\s*)[^\\s,;)\\]}]+`, "giu");
+/** Environment-variable-shaped credentials (`GITHUB_TOKEN=…`) in spawn errors. */
+const ENV_VAR_CREDENTIAL = /\b[A-Za-z0-9_]*(?:TOKEN|API[_-]?KEY|SECRET|PASSWORD|PASSWD)[A-Za-z0-9_]*\s*=\s*[^\s,;)\]}]+/gu;
+/** Bearer tokens, including the `Bearer ` keyword and the token itself. */
+const BEARER = /(bearer)\s+[A-Za-z0-9._~+/=-]+/giu;
+/** Quoted JSON-ish `"token": "value"` pairs in arbitrary text. */
+const QUOTED_CREDENTIAL = new RegExp(`(["'](?:access[_-]?token|api[_-]?key|client[_-]?secret|secret|token)["']\\s*[:=]\\s*["'])[^"']*(["'])`, "giu");
+/** Raw JWT bodies, wherever they appear. */
+const JWT = /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/gu;
+/**
+* Redact a URL for display: userinfo password, credential query values, and
+* credential fragment pairs. Query keys are read through `URLSearchParams`,
+* so percent-encoded key names are decoded before matching. Unparseable
+* inputs fall back to pattern redaction (whole userinfo, credential query
+* pairs, credential fragment pairs) instead of throwing.
+*
+* @param url - candidate URL text.
+* @returns display-safe URL text.
+*/
+function sanitizeUrl(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return url.replace(USERINFO, "$1***@").replace(QUERY_CREDENTIAL, `$1***`).replace(FRAGMENT_CREDENTIAL, `$1***`);
+	}
+	if (parsed.password !== "") parsed.password = "***";
+	for (const key of [...parsed.searchParams.keys()]) if (CREDENTIAL_KEY.test(key)) parsed.searchParams.set(key, "***");
+	if (parsed.hash !== "") parsed.hash = parsed.hash.replace(FRAGMENT_CREDENTIAL, `$1***`);
+	return parsed.toString();
+}
+/**
+* Redact credential-shaped fragments from free text: header lines, bearer
+* tokens, raw JWTs, embedded query pairs, and quoted token values.
+*
+* @param text - candidate display text.
+* @returns display-safe text.
+*/
+function sanitizeText(text) {
+	return text.replace(BEARER, `$1 ***`).replace(HEADER_CREDENTIAL_QUOTED, `$1***$2`).replace(HEADER_CREDENTIAL_BARE, `$1***`).replace(ENV_VAR_CREDENTIAL, (value) => {
+		const equals = value.indexOf("=");
+		return equals < 0 ? value : `${value.slice(0, equals)}=***`;
+	}).replace(QUOTED_CREDENTIAL, `$1***$2`).replace(QUERY_CREDENTIAL, `$1***`).replace(FRAGMENT_CREDENTIAL, `$1***`).replace(JWT, "***");
+}
+/**
+* Stringify an arbitrary thrown value safely and redact it for display.
+* Never throws: unrenderable values degrade to a fixed marker.
+*
+* @param error - thrown value from an engine call or probe.
+* @returns display-safe error text.
+*/
+function sanitizeError(error) {
+	let text;
+	try {
+		text = typeof error === "string" ? error : String(error);
+	} catch {
+		text = "<unrenderable error>";
+	}
+	return sanitizeText(text);
+}
+//#endregion
+//#region src/engine.ts
+/**
+* A single engine call failure. `message` is display-safe (never carries the
+* API key); `status` carries the HTTP status when a response existed.
+*/
+var EngineCallError = class extends Error {
+	/** Which stage failed. */
+	phase;
+	/** Stable machine code: `unconfigured`, `auth`, `http`, `parse`. */
+	code;
+	/** HTTP status when a response existed. */
+	status;
+	/** @param phase - failing stage. @param code - stable code. @param message - display-safe message. @param options - optional status and cause. */
+	constructor(phase, code, message, options) {
+		super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "EngineCallError";
+		this.phase = phase;
+		this.code = code;
+		if (options?.status !== void 0) this.status = options.status;
+	}
+};
+/** Timeout for one image URL download (fraction of the request budget). */
+const DOWNLOAD_TIMEOUT_MS = 6e4;
+/**
+* Call one engine for the given translated request.
+*
+* @param engine - resolved engine configuration.
+* @param request - translated request body fields.
+* @param deps - transport and credential resolution.
+* @param signal - caller cancellation.
+* @returns the produced images.
+* @throws {@link EngineCallError} with a phase the router can act on.
+*/
+async function callEngine(engine, request, deps, signal) {
+	const credential = await deps.resolveCredential(engine.apiKeyRef);
+	if (credential === void 0) throw new EngineCallError("credential", "unconfigured", `engine "${engine.id}" has no resolved credential reference ${engine.apiKeyRef}`);
+	const headers = {
+		"content-type": "application/json",
+		authorization: `Bearer ${credential}`
+	};
+	const body = {
+		model: request.model,
+		prompt: request.prompt,
+		size: request.size,
+		n: request.n,
+		...request.quality !== void 0 ? { quality: request.quality } : {},
+		...request.style !== void 0 ? { style: request.style } : {},
+		...request.responseFormat === "b64_json" ? { response_format: request.responseFormat } : {}
+	};
+	const response = await deps.transport.request({
+		method: "POST",
+		url: `${engine.baseUrl}/images/generations`,
+		headers,
+		body: new TextEncoder().encode(JSON.stringify(body)),
+		...signal === void 0 ? {} : { signal }
+	});
+	if (response.status === 401 || response.status === 403) throw new EngineCallError("request", "auth", `engine "${engine.id}" rejected the credential (HTTP ${response.status})`, { status: response.status });
+	if (response.status < 200 || response.status >= 300) throw new EngineCallError("request", "http", `engine "${engine.id}" failed with HTTP ${response.status}`, { status: response.status });
+	let parsed;
+	try {
+		parsed = JSON.parse(new TextDecoder().decode(response.body));
+	} catch (cause) {
+		throw new EngineCallError("parse", "parse", `engine "${engine.id}" returned a non-JSON response`, { cause });
+	}
+	const items = Array.isArray(parsed.data) ? parsed.data : void 0;
+	if (items === void 0) throw new EngineCallError("parse", "parse", `engine "${engine.id}" response has no data array`);
+	const images = [];
+	for (const raw of items) {
+		if (typeof raw !== "object" || raw === null) throw new EngineCallError("parse", "parse", `engine "${engine.id}" returned a malformed image entry`);
+		const item = raw;
+		if (typeof item.b64_json === "string" && item.b64_json.length > 0) {
+			images.push({
+				data: decodeBase64(item.b64_json),
+				mediaType: engine.imageMediaType
+			});
+			continue;
+		}
+		if (typeof item.url === "string" && item.url.length > 0) {
+			images.push({
+				data: await downloadImageUrl(engine, item.url, credential, deps, signal),
+				mediaType: engine.imageMediaType
+			});
+			continue;
+		}
+		throw new EngineCallError("parse", "parse", `engine "${engine.id}" returned an image entry without bytes or a URL`);
+	}
+	if (images.length === 0) throw new EngineCallError("parse", "parse", `engine "${engine.id}" returned no images`);
+	return images;
+}
+/**
+* Download one image URL with the engine's bearer credential. The download is
+* one GET request on the same transport; a non-2xx status is an engine
+* failure, not silent emptiness.
+*/
+async function downloadImageUrl(engine, url, credential, deps, signal) {
+	const { signal: downloadSignal, dispose } = fusedSignal(signal, DOWNLOAD_TIMEOUT_MS);
+	try {
+		const response = await deps.transport.request({
+			method: "GET",
+			url,
+			headers: { authorization: `Bearer ${credential}` },
+			signal: downloadSignal
+		});
+		if (response.status < 200 || response.status >= 300) throw new EngineCallError("request", "http", `engine "${engine.id}" image download failed with HTTP ${response.status}`, { status: response.status });
+		return response.body;
+	} catch (error) {
+		if (error instanceof EngineCallError) throw error;
+		throw new EngineCallError("request", "http", `engine "${engine.id}" image download failed: ${sanitizeError(error)}`, { cause: error });
+	} finally {
+		dispose();
+	}
+}
+//#endregion
+//#region src/router.ts
+/**
+* The engine chain with per-engine health and cooldown. All mutations are
+* synchronous bookkeeping guarded by `generate`'s single-writer path (the
+* tool is not concurrency-safe, so generations serialize).
+*/
+var EngineRouter = class {
+	config;
+	health = /* @__PURE__ */ new Map();
+	now;
+	/**
+	* @param config - resolved plugin configuration (engine order and bounds).
+	* @param options - failure threshold, cooldown, and clock.
+	*/
+	constructor(config, options) {
+		this.config = config;
+		this.now = options.now ?? Date.now;
+		for (const engine of config.engines) this.health.set(engine.id, {
+			consecutiveFailures: 0,
+			cooldownUntil: null,
+			lastError: null,
+			lastStatus: null
+		});
+	}
+	/**
+	* Route one standardized request through the configured chain. The chain
+	* order is the config array order, except an explicit `request.engine`
+	* promotes that engine to the front; every engine is attempted at most
+	* once, and an engine in cooldown or without a resolved credential is
+	* skipped with a recorded attempt.
+	*
+	* @param request - normalized standard request.
+	* @param deps - transport and credential resolution.
+	* @param signal - caller cancellation.
+	* @returns success with images, or the complete failure record.
+	*/
+	async generate(request, deps, signal) {
+		const ordered = this.chainOrder(request.engine);
+		const attempts = [];
+		let tried = 0;
+		for (const engine of ordered) {
+			if (tried > 0) signal?.throwIfAborted();
+			const skip = this.skipReason(engine);
+			if (skip !== void 0) {
+				attempts.push({
+					engine: engine.id,
+					code: skip.code,
+					message: skip.message
+				});
+				continue;
+			}
+			tried += 1;
+			try {
+				const images = await callEngine(engine, this.translate(engine, request), deps, signal);
+				this.recordSuccess(engine.id);
+				attempts.push({
+					engine: engine.id,
+					code: "ok"
+				});
+				return {
+					ok: true,
+					engine: engine.id,
+					model: engine.model,
+					size: request.size ?? "square",
+					images,
+					fallbackUsed: tried > 1,
+					attempts
+				};
+			} catch (error) {
+				const view = this.recordFailure(engine.id, error);
+				attempts.push(view);
+				if (view.phase === "credential" || view.code === "auth" || view.code === "parse") continue;
+				if (signal !== void 0 && signal.aborted) throw signal.reason;
+				continue;
+			}
+		}
+		return {
+			ok: false,
+			attempts
+		};
+	}
+	/** One engine's current health snapshot. */
+	statusOf(engineId) {
+		const health = this.health.get(engineId);
+		if (health === void 0) return void 0;
+		return {
+			engineId,
+			consecutiveFailures: health.consecutiveFailures,
+			cooldownUntil: health.cooldownUntil,
+			lastError: health.lastError,
+			lastStatus: health.lastStatus
+		};
+	}
+	/** Health snapshots for every configured engine in chain order. */
+	statuses() {
+		return this.config.engines.map((engine) => this.statusOf(engine.id)).filter((status) => status !== void 0);
+	}
+	/**
+	* Probe one engine with a cheap authenticated `GET {baseUrl}/models` call.
+	* The probe reports reachability and credential validity without mutating
+	* routing health — it is a settings-panel check, not the router's memory.
+	*
+	* @param engine - engine to probe.
+	* @param deps - transport and credential resolution.
+	* @returns the probe outcome.
+	*/
+	async probe(engine, deps) {
+		const target = sanitizeUrl(`${engine.baseUrl}/models`);
+		const credential = await deps.resolveCredential(engine.apiKeyRef);
+		if (credential === void 0) return {
+			engineId: engine.id,
+			reachable: false,
+			httpStatus: null,
+			target,
+			note: `credential reference ${engine.apiKeyRef} is not configured`,
+			credentialConfigured: false
+		};
+		try {
+			const response = await deps.transport.request({
+				method: "GET",
+				url: `${engine.baseUrl}/models`,
+				headers: { authorization: `Bearer ${credential}` }
+			});
+			if (response.status === 401 || response.status === 403) return {
+				engineId: engine.id,
+				reachable: true,
+				httpStatus: response.status,
+				target,
+				note: `endpoint answered but rejected the credential (HTTP ${response.status})`,
+				credentialConfigured: true
+			};
+			if (response.status === 404 || response.status === 405 || response.status === 501) return {
+				engineId: engine.id,
+				reachable: true,
+				httpStatus: response.status,
+				target,
+				note: `endpoint answered (HTTP ${response.status}); the models listing may be absent but generation can still work`,
+				credentialConfigured: true
+			};
+			if (response.status < 200 || response.status >= 300) return {
+				engineId: engine.id,
+				reachable: true,
+				httpStatus: response.status,
+				target,
+				note: `endpoint answered with HTTP ${response.status}`,
+				credentialConfigured: true
+			};
+			return {
+				engineId: engine.id,
+				reachable: true,
+				httpStatus: response.status,
+				target,
+				note: "endpoint reachable and credential accepted",
+				credentialConfigured: true
+			};
+		} catch (error) {
+			return {
+				engineId: engine.id,
+				reachable: false,
+				httpStatus: null,
+				target,
+				note: sanitizeError(error),
+				credentialConfigured: true
+			};
+		}
+	}
+	/** Chain order: an explicit engine override first, then config order minus the override. */
+	chainOrder(override) {
+		const engines = [...this.config.engines];
+		if (override === void 0 || override === this.config.defaultEngine) {
+			const index = engines.findIndex((engine) => engine.id === this.config.defaultEngine);
+			if (index > 0) {
+				const [preferred] = engines.splice(index, 1);
+				engines.unshift(preferred);
+			}
+			return engines;
+		}
+		const index = engines.findIndex((engine) => engine.id === override);
+		if (index < 0) return engines;
+		const [preferred] = engines.splice(index, 1);
+		engines.unshift(preferred);
+		return engines;
+	}
+	/** Why an engine may not even be attempted: disabled, cooling down. */
+	skipReason(engine) {
+		if (!engine.enabled) return {
+			code: "disabled",
+			message: `engine "${engine.id}" is disabled`
+		};
+		const health = this.health.get(engine.id);
+		const now = this.now();
+		const cooldown = health?.cooldownUntil;
+		if (cooldown !== null && cooldown !== void 0 && cooldown > now) return {
+			code: "cooldown",
+			message: `engine "${engine.id}" is cooling down after repeated failures`
+		};
+	}
+	/** Translate the standard request against one engine (the pure translate step). */
+	translate(engine, request) {
+		return translateRequest(engine, request);
+	}
+	/** Record a success: reset consecutive failures and cooldown. */
+	recordSuccess(engineId) {
+		const health = this.health.get(engineId);
+		if (health === void 0) return;
+		health.consecutiveFailures = 0;
+		health.cooldownUntil = null;
+		health.lastError = null;
+		health.lastStatus = null;
+	}
+	/** Record a failure: bump the counter, trip cooldown at the threshold, and build the attempt view. */
+	recordFailure(engineId, error) {
+		const health = this.health.get(engineId);
+		const engineError = error instanceof EngineCallError ? error : void 0;
+		const phase = engineError?.phase ?? "request";
+		const code = engineError?.code ?? "http";
+		const message = sanitizeText(sanitizeError(error));
+		const status = engineError?.status;
+		if (health !== void 0) {
+			health.consecutiveFailures += 1;
+			health.lastError = message;
+			health.lastStatus = status ?? null;
+			if (health.consecutiveFailures >= this.config.failureThreshold) health.cooldownUntil = this.now() + this.config.cooldownMs;
+		}
+		return {
+			engine: engineId,
+			phase,
+			code,
+			message,
+			...status !== void 0 ? { status } : {}
+		};
+	}
+};
+//#endregion
+//#region src/version.ts
+/**
+* The plugin version, hardcoded beside `package.json` so the release script
+* bumps both and `tests/version.spec.ts` trips when they drift. Served in the
+* `draw/status` snapshot so the settings panel shows which plugin build runs.
+*
+* @module dsh-draw/version
+*/
+/** Plugin version; must equal the `version` field in `package.json`. */
+const PLUGIN_VERSION = "0.1.0";
+//#endregion
+//#region src/service.ts
+/**
+* The `draw` Typert Remote service.
+*/
+var DrawService = class extends TypertRemoteService {
+	/** Per-call bindings (replaced on plugin reload). */
+	options;
+	/**
+	* @param ctx - the mounting context.
+	* @param options - runtime bindings.
+	*/
+	constructor(ctx, options) {
+		super(ctx, "draw");
+		this.options = options;
+	}
+	/** Resolve one engine's credential view for the status snapshot. */
+	async credentialView(reference) {
+		const credentials = this.options.credentials;
+		if (credentials === void 0) return {
+			configured: false,
+			writable: false
+		};
+		try {
+			const info = await credentials.describe(credentialRef(reference));
+			return {
+				configured: info.configured,
+				writable: info.writable,
+				...info.source !== void 0 ? { source: info.source } : {}
+			};
+		} catch {
+			return {
+				configured: false,
+				writable: false
+			};
+		}
+	}
+	/** Read-only panel snapshot: engine chain, health, credential facts, quota. */
+	async status() {
+		const { config, router } = this.options;
+		const engines = [];
+		for (const engine of config.engines) {
+			const status = router.statusOf(engine.id);
+			const view = statusToView(status ?? {
+				engineId: engine.id,
+				consecutiveFailures: 0,
+				cooldownUntil: null,
+				lastError: null,
+				lastStatus: null
+			}, {
+				id: engine.id,
+				model: engine.model,
+				baseUrl: engine.baseUrl,
+				apiKeyRef: engine.apiKeyRef,
+				enabled: engine.enabled,
+				preferred: engine.id === config.defaultEngine
+			}, await this.credentialView(engine.apiKeyRef));
+			engines.push(view);
+		}
+		return {
+			pluginVersion: PLUGIN_VERSION,
+			engines,
+			quota: {
+				maxGenerationsPerSession: config.maxGenerationsPerSession,
+				maxBytesPerSession: config.maxBytesPerSession
+			},
+			requestTimeoutMs: config.requestTimeoutMs,
+			maxImagesPerCall: config.maxImagesPerCall
+		};
+	}
+	/** Probe one engine's connectivity without mutating routing health. */
+	async probe(engineId) {
+		const engine = engineById(this.options.config, engineId);
+		if (engine === void 0) return {
+			engineId,
+			reachable: false,
+			httpStatus: null,
+			target: "",
+			note: `unknown engine "${engineId}"`,
+			credentialConfigured: false
+		};
+		const outcome = await this.options.router.probe(engine, {
+			transport: this.options.drawer.deps.engine.transport,
+			resolveCredential: this.options.drawer.deps.engine.resolveCredential
+		});
+		return probeToWire(outcome);
+	}
+	/** Store one API key under the engine's credential reference (credentials seam). */
+	async setCredential(engineId, value) {
+		const engine = engineById(this.options.config, engineId);
+		if (engine === void 0) throw new TypeError(`unknown engine "${engineId}"`);
+		const credentials = this.options.credentials;
+		if (credentials === void 0) throw new TypeError("the credential service is not composed on this profile");
+		if (typeof value !== "string" || value.length === 0) throw new TypeError("credential value must be a non-empty string");
+		await credentials.set(credentialRef(engine.apiKeyRef), value);
+		return {
+			engineId,
+			reference: engine.apiKeyRef,
+			note: `stored under the ${engine.apiKeyRef} credential reference`
+		};
+	}
+	/** Remove a stored API key for the engine's credential reference. */
+	async unsetCredential(engineId) {
+		const engine = engineById(this.options.config, engineId);
+		if (engine === void 0) throw new TypeError(`unknown engine "${engineId}"`);
+		const credentials = this.options.credentials;
+		if (credentials === void 0) throw new TypeError("the credential service is not composed on this profile");
+		await credentials.unset(credentialRef(engine.apiKeyRef));
+		return {
+			engineId,
+			reference: engine.apiKeyRef,
+			note: `removed from the ${engine.apiKeyRef} credential reference`
+		};
+	}
+	/** Re-run a generation from the result card through the full drawer path. */
+	async regenerate(sessionId, args) {
+		const sessions = this.options.drawer.deps.sessions?.();
+		if (sessions === void 0) throw new TypeError("the session store is not composed on this profile");
+		const session = sessions.get(SessionId(sessionId));
+		if (session === void 0) throw new TypeError(`unknown session "${sessionId}"`);
+		const outcome = await this.options.drawer.generate(args, {
+			session,
+			source: "regenerate"
+		});
+		if (!outcome.ok) throw new TypeError(outcome.message);
+		return projectRegenerate(outcome);
+	}
+};
+/** Project a successful draw onto the regenerate wire shape. */
+function projectRegenerate(outcome) {
+	return {
+		engine: outcome.engine,
+		model: outcome.model,
+		size: outcome.size,
+		images: outcome.images.map(imageToWire),
+		quota: outcome.quota,
+		quotaLimits: outcome.limits,
+		fallbackUsed: outcome.fallbackUsed,
+		elapsedMs: outcome.elapsedMs,
+		attempts: outcome.attempts
+	};
+}
+//#endregion
+//#region src/tool.ts
+/**
+* The `image_generate` tool: the model-facing unified image generation entry.
+* Standard parameters (prompt/size/count/quality/style/engine) flow into the
+* shared drawer path; the canonical value carries the durable attachment
+* references plus quota and routing facts, and the render output embeds the
+* images as attachment content blocks so both text-only surfaces and the web
+* conversation show them.
+*
+* @module dsh-draw/tool
+*/
+/**
+* Build the `image_generate` tool over one drawer.
+*
+* @param drawer - the shared generation path.
+* @param config - resolved config (prompt cap for the description, timeout budget).
+* @returns the tool definition.
+*/
+function imageGenerateTool(drawer, config) {
+	return defineTool({
+		name: "image_generate",
+		description: `Generate 1..${config.maxImagesPerCall} static images from a text prompt through the configured image engines (OpenAI Images, Zhipu CogView, or any OpenAI-compatible endpoint). Standard parameters are translated per engine; a failing engine falls back down the configured chain. Results are saved as durable attachments and count against the per-session quota. Prompt cap: ${config.maxPromptLength} characters.`,
+		parameters: {
+			prompt: {
+				type: "string",
+				description: "Image prompt.",
+				required: true
+			},
+			size: {
+				type: "string",
+				enum: [
+					"square",
+					"landscape",
+					"portrait",
+					"auto"
+				],
+				description: "Composition (default square)."
+			},
+			count: {
+				type: "integer",
+				description: "Number of images (default 1; capped by configuration)."
+			},
+			quality: {
+				type: "string",
+				enum: [
+					"low",
+					"medium",
+					"high",
+					"auto"
+				],
+				description: "Quality tier (default auto; dropped for engines without it)."
+			},
+			style: {
+				type: "string",
+				enum: ["natural", "vivid"],
+				description: "Style preset (dropped for engines without it)."
+			},
+			engine: {
+				type: "string",
+				description: "Engine id override (must name a configured engine; omitted = chain order)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					ok: {
+						type: "boolean",
+						const: true
+					},
+					engine: { type: "string" },
+					model: { type: "string" },
+					size: { type: "string" },
+					images: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								attachmentId: { type: "string" },
+								mediaType: { type: "string" },
+								bytes: { type: "integer" },
+								width: { type: "integer" },
+								height: { type: "integer" },
+								name: { type: "string" }
+							},
+							additionalProperties: false
+						}
+					},
+					quota: {
+						type: "object",
+						properties: {
+							generations: { type: "integer" },
+							bytes: { type: "integer" }
+						},
+						additionalProperties: false
+					},
+					limits: {
+						type: "object",
+						properties: {
+							maxGenerations: { type: "integer" },
+							maxBytes: { type: "integer" }
+						},
+						additionalProperties: false
+					},
+					fallbackUsed: { type: "boolean" },
+					elapsedMs: { type: "integer" },
+					attempts: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								engine: { type: "string" },
+								phase: { oneOf: [{ type: "string" }, { type: "null" }] },
+								code: { type: "string" },
+								message: { oneOf: [{ type: "string" }, { type: "null" }] },
+								status: { oneOf: [{ type: "integer" }, { type: "null" }] }
+							},
+							additionalProperties: false
+						}
+					}
+				},
+				additionalProperties: false
+			},
+			render(_args, value) {
+				const result = value;
+				const lines = [`Generated ${result.images.length} image(s) via ${result.engine} (${result.model}, ${result.size})${result.fallbackUsed ? " after fallback" : ""} in ${result.elapsedMs} ms.`, `Quota: ${result.quota.generations}/${result.limits.maxGenerations} calls, ${result.quota.bytes}/${result.limits.maxBytes} bytes this session.`];
+				for (const attempt of result.attempts) {
+					if (attempt.code === "ok") continue;
+					lines.push(`- ${attempt.engine}: ${attempt.code}${attempt.message === void 0 ? "" : ` (${attempt.message})`}`);
+				}
+				const blocks = [{
+					type: "text",
+					text: lines.join("\n")
+				}];
+				for (const image of result.images) {
+					const attachment = {
+						attachmentId: AttachmentId(image.attachmentId),
+						mediaType: image.mediaType,
+						bytes: image.bytes,
+						width: image.width,
+						height: image.height,
+						...image.name !== void 0 ? { name: image.name } : {}
+					};
+					blocks.push({
+						type: "image",
+						attachment
+					});
+				}
+				return blocks;
+			},
+			presentationMeta(_args, value) {
+				return value;
+			}
+		},
+		timeoutMs: config.requestTimeoutMs,
+		async execute(args, exec) {
+			const outcome = await drawer.generate(args, {
+				session: exec.agent?.session,
+				source: "tool",
+				signal: exec.signal
+			});
+			if (!outcome.ok) throw new Error(outcome.message);
+			return {
+				...outcome,
+				images: [...outcome.images],
+				attempts: [...outcome.attempts]
+			};
+		}
+	});
+}
+//#endregion
+//#region src/index.ts
+const name = "dsh-draw";
+/** Hard services: the tool registry every contribution lands in. */
+const inject = ["tools"];
+/** Response byte ceiling: one engine call may carry several full-size images. */
+const MAX_RESPONSE_BYTES = 67108864;
+/**
+* Mount the plugin: router, drawer, the `image_generate` tool, and the `draw`
+* Remote service. Every registration is an effect on this fiber, so
+* unload/hot-reload removes the tool and the service together.
+*
+* @param ctx - context carrying tools plus the optional attachment/credentials seams.
+* @param config - raw loader config; defaults applied through {@link resolveConfig}.
+*/
+async function apply(ctx, config) {
+	const resolved = resolveConfig(config);
+	const logger = ctx.logger("draw");
+	const transport = ctx.get("dsh-draw/transport") ?? defaultHttpTransport(resolved.requestTimeoutMs, MAX_RESPONSE_BYTES);
+	const router = new EngineRouter(resolved, {
+		failureThreshold: resolved.failureThreshold,
+		cooldownMs: resolved.cooldownMs
+	});
+	const credentials = () => ctx.get("credentials");
+	const drawer = new Drawer(resolved, router, {
+		engine: {
+			transport,
+			resolveCredential: async (reference) => {
+				const service = credentials();
+				if (service === void 0) return void 0;
+				return (await service.resolve(credentialRef(reference)))?.value;
+			}
+		},
+		attachments: () => ctx.get("attachments"),
+		sessions: () => ctx.get("sessions")
+	});
+	ctx.effect(() => ctx.tools.register(imageGenerateTool(drawer, resolved)), "dsh-draw: image_generate tool");
+	await ctx.plugin(DrawService, {
+		config: resolved,
+		router,
+		drawer,
+		credentials: credentials()
+	});
+	logger.info(`image generation enabled: ${resolved.engines.map((engine) => engine.id).join(", ")} (preferred ${resolved.defaultEngine})`);
+}
+//#endregion
+export { Config, DEFAULT_ENGINES, DRAW_INVOCATIONS, DrawService, Drawer, EngineCallError, EngineRouter, HttpError, PLUGIN_VERSION, REDACTED, appendDrawGenerated, apply, callEngine, checkQuotaBytes, checkQuotaGenerations, defaultHttpTransport, drawGeneratedEvents, engineById, fusedSignal, imageGenerateTool, imageToWire, inject, name, normalizeRequest, probeToWire, quotaState, resolveConfig, sanitizeError, sanitizeText, sanitizeUrl, statusToView, translateRequest };