dsh-packycode-api 1.1.9 → 1.2.0

package/lib/index.js

@@ -2,10 +2,10 @@ import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { homedir, tmpdir } from "node:os";
 import { dirname, isAbsolute, join, posix, resolve, sep, win32 } from "node:path";
 import z from "@deepseek-ai/schemastery";
-import { HarnessError, LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+import { HarnessError, LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, createUserMessage, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { spawn } from "node:child_process";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
-import { mkdtemp, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { credentialKey } from "@deepseek-ai/dsh-credentials";
@@ -184,6 +184,8 @@ const CHANNEL = "/packycode-api";
 const SETTINGS_NAMESPACE = "packycode-api";
 /** Credential record id inside the plugin's own scope. */
 const KEY_RECORD_ID = "keys";
+/** Image credentials never participate in the conversation key ring. */
+const IMAGE_KEY_RECORD_ID = "image-keys";
 /**
 * Model-traffic host. Each model declares the protocol its gateway route
 * actually serves: `cf.api.fan/v1` answers chat/completions and responses,
@@ -270,6 +272,51 @@ function accountHostOrder(hosts) {
 	]);
 }
 //#endregion
+//#region src/secret-redactor.js
+/**
+* Redaction of plugin-owned credentials and ephemeral bridge capabilities.
+* Work on decoded strings where possible; JSON-escaped forms also cover
+* diagnostics containing serialized data. Delta redaction holds only the
+* longest suffix that could still become a secret in the next chunk.
+*/
+const strings = (values) => [...new Set(values.filter((value) => typeof value === "string" && value !== ""))].sort((a, b) => b.length - a.length);
+const variants = (values) => strings(values.flatMap((value) => typeof value === "string" ? [value, JSON.stringify(value).slice(1, -1)] : []));
+function redactSecrets(text, values) {
+	let safe = String(text);
+	for (const secret of variants(values)) safe = safe.split(secret).join("[redacted]");
+	return safe;
+}
+/** Protect secrets fragmented across consecutive decoded text deltas. */
+function createDeltaRedactor(values) {
+	const secrets = variants(values);
+	let pending = "";
+	return {
+		write(text) {
+			const safe = redactSecrets(pending + text, secrets);
+			let held = 0;
+			for (const secret of secrets) {
+				const maximum = Math.min(safe.length, secret.length - 1);
+				for (let length = maximum; length > held; length--) if (safe.endsWith(secret.slice(0, length))) {
+					held = length;
+					break;
+				}
+			}
+			pending = held === 0 ? "" : safe.slice(-held);
+			return held === 0 ? safe : safe.slice(0, -held);
+		},
+		/**
+		* At a block/tool boundary, mask a still-ambiguous prefix so a subsequent
+		* block cannot reconstruct the credential. At end of output it is safe
+		* to flush an incomplete prefix literally; no later delta can complete it.
+		*/
+		flush({ boundary = false } = {}) {
+			const result = boundary && pending !== "" ? "[redacted]" : pending;
+			pending = "";
+			return result;
+		}
+	};
+}
+//#endregion
 //#region src/balance.js
 /**
 * Account and per-key balance.
@@ -376,7 +423,11 @@ async function getJson(url, key, { fetchImpl, timeoutMs, signal }) {
 		throw new Error(error.message, { cause: error });
 	}
 	if (!response.ok) throw new Error(statusMessage(response.status));
-	return response.json();
+	try {
+		return await response.json();
+	} catch {
+		throw new Error("the gateway returned unreadable balance data");
+	}
 }
 async function withFallback(hosts, path, key, options) {
 	const tried = [];
@@ -401,7 +452,7 @@ async function withFallback(hosts, path, key, options) {
 * @param options - key listing, host resolution, and transport knobs.
 * @returns `{ read({force, signal}), invalidate() }`.
 */
-function createBalanceReader({ listKeys, getHosts, fetchImpl = ambientFetch, now = Date.now, ttlMs = DEFAULT_BALANCE_TTL_MS, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = {}) {
+function createBalanceReader({ listKeys, getHosts, fetchImpl = ambientFetch, now = Date.now, ttlMs = DEFAULT_BALANCE_TTL_MS, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, includeAccount = true } = {}) {
 	if (typeof listKeys !== "function") throw new Error("PackyCode balance reader requires listKeys");
 	if (typeof getHosts !== "function") throw new Error("PackyCode balance reader requires getHosts");
 	/** Last successful per-key usage, by key id, and the last account figures. */
@@ -458,17 +509,21 @@ function createBalanceReader({ listKeys, getHosts, fetchImpl = ambientFetch, now
 		signal?.throwIfAborted();
 		const hosts = getHosts();
 		const keys = await listKeys();
+		const secrets = keys.map((entry) => entry.key);
+		const safe = (value) => redactSecrets(value, secrets);
 		for (const id of lastGood.keys()) if (!keys.some((entry) => entry.id === id)) lastGood.delete(id);
 		const entries = [];
 		const usableIds = [];
 		for (const entry of keys) {
 			const base = {
 				id: entry.id,
-				label: entry.label,
+				label: safe(entry.label),
 				disabled: entry.disabled === true
 			};
 			try {
 				const usage = await loadKey(entry, hosts, signal);
+				if (usage.name !== void 0) usage.name = safe(usage.name);
+				if (usage.resetPeriod !== void 0) usage.resetPeriod = safe(usage.resetPeriod);
 				lastGood.set(entry.id, {
 					usage,
 					fetchedAt: now()
@@ -480,7 +535,7 @@ function createBalanceReader({ listKeys, getHosts, fetchImpl = ambientFetch, now
 				usableIds.push(entry.id);
 			} catch (error) {
 				signal?.throwIfAborted();
-				const message = error instanceof Error ? error.message : String(error);
+				const message = safe(error instanceof Error ? error.message : String(error));
 				const previous = lastGood.get(entry.id);
 				entries.push(previous === void 0 ? {
 					...base,
@@ -496,7 +551,7 @@ function createBalanceReader({ listKeys, getHosts, fetchImpl = ambientFetch, now
 			}
 		}
 		let account;
-		try {
+		if (includeAccount) try {
 			account = await loadAccount(keys, hosts, signal, usableIds);
 			lastAccount = {
 				account,
@@ -504,7 +559,7 @@ function createBalanceReader({ listKeys, getHosts, fetchImpl = ambientFetch, now
 			};
 		} catch (error) {
 			signal?.throwIfAborted();
-			const message = error instanceof Error ? error.message : String(error);
+			const message = safe(error instanceof Error ? error.message : String(error));
 			account = lastAccount === void 0 || !keys.some((entry) => entry.id === lastAccount.account.keyId) ? { error: message } : {
 				...lastAccount.account,
 				stale: {
@@ -515,7 +570,7 @@ function createBalanceReader({ listKeys, getHosts, fetchImpl = ambientFetch, now
 		}
 		return {
 			keys: entries,
-			account,
+			...includeAccount ? { account } : {},
 			hosts,
 			fetchedAt: now()
 		};
@@ -2225,51 +2280,6 @@ function withProgramDirOnPath(env, program, platform = process.platform) {
 	};
 }
 //#endregion
-//#region src/secret-redactor.js
-/**
-* Redaction of plugin-owned credentials and ephemeral bridge capabilities.
-* Work on decoded strings where possible; JSON-escaped forms also cover
-* diagnostics containing serialized data. Delta redaction holds only the
-* longest suffix that could still become a secret in the next chunk.
-*/
-const strings = (values) => [...new Set(values.filter((value) => typeof value === "string" && value !== ""))].sort((a, b) => b.length - a.length);
-const variants = (values) => strings(values.flatMap((value) => typeof value === "string" ? [value, JSON.stringify(value).slice(1, -1)] : []));
-function redactSecrets(text, values) {
-	let safe = String(text);
-	for (const secret of variants(values)) safe = safe.split(secret).join("[redacted]");
-	return safe;
-}
-/** Protect secrets fragmented across consecutive decoded text deltas. */
-function createDeltaRedactor(values) {
-	const secrets = variants(values);
-	let pending = "";
-	return {
-		write(text) {
-			const safe = redactSecrets(pending + text, secrets);
-			let held = 0;
-			for (const secret of secrets) {
-				const maximum = Math.min(safe.length, secret.length - 1);
-				for (let length = maximum; length > held; length--) if (safe.endsWith(secret.slice(0, length))) {
-					held = length;
-					break;
-				}
-			}
-			pending = held === 0 ? "" : safe.slice(-held);
-			return held === 0 ? safe : safe.slice(0, -held);
-		},
-		/**
-		* At a block/tool boundary, mask a still-ambiguous prefix so a subsequent
-		* block cannot reconstruct the credential. At end of output it is safe
-		* to flush an incomplete prefix literally; no later delta can complete it.
-		*/
-		flush({ boundary = false } = {}) {
-			const result = boundary && pending !== "" ? "[redacted]" : pending;
-			pending = "";
-			return result;
-		}
-	};
-}
-//#endregion
 //#region src/claude-cli.js
 /**
 * Bridge to the local Claude Code CLI.
@@ -4579,6 +4589,698 @@ function createClaudeCodeTool({ runner, modeCeiling, planActive }) {
 	});
 }
 //#endregion
+//#region src/image-models.js
+/** Images API models are separate from the conversational pi-ai catalog. */
+const DEFAULT_IMAGE_MODEL = "gpt-image-2";
+const IMAGE_MODELS = Object.freeze({
+	"gpt-image-2": Object.freeze([
+		"auto",
+		"low",
+		"medium",
+		"high"
+	]),
+	"gpt-image-2.5-flare": Object.freeze([
+		"auto",
+		"low",
+		"medium",
+		"high",
+		"xhigh",
+		"max"
+	]),
+	"gpt-image-2.5-sunburst": Object.freeze([
+		"auto",
+		"low",
+		"medium",
+		"high",
+		"xhigh",
+		"max"
+	])
+});
+const IMAGE_MODEL_IDS = Object.freeze(Object.keys(IMAGE_MODELS));
+const IMAGE_QUALITIES = Object.freeze([
+	"auto",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max"
+]);
+function validateImageOptions({ model = DEFAULT_IMAGE_MODEL, quality = "auto", size = "auto", background = "auto" } = {}) {
+	if (!IMAGE_MODEL_IDS.includes(model)) throw new Error("PackyCode image model is not supported");
+	if (!IMAGE_MODELS[model].includes(quality)) throw new Error("PackyCode image quality is not supported by the selected model");
+	if (![
+		"auto",
+		"transparent",
+		"opaque"
+	].includes(background)) throw new Error("PackyCode image background is not supported");
+	if (size !== "auto") {
+		const match = typeof size === "string" ? /^(\d{1,4})x(\d{1,4})$/u.exec(size) : null;
+		const width = Number(match?.[1]);
+		const height = Number(match?.[2]);
+		const pixels = width * height;
+		if (match === null || width % 16 !== 0 || height % 16 !== 0 || Math.max(width, height) > 3840 || Math.max(width, height) > Math.min(width, height) * 3 || pixels < 655360 || pixels > 8294400) throw new Error("PackyCode image size must be auto or a supported widthxheight resolution");
+	}
+	return {
+		model,
+		quality,
+		size,
+		background
+	};
+}
+//#endregion
+//#region src/preferences.js
+/**
+* Where the plugin's preferences are read from and written to, on both
+* settings generations DSH has shipped.
+*
+* - DSH 0.1.5 installs a settings *section*: the section hands back a live
+*   source and writes go through `settings.update(namespace, patch)`.
+* - DSH 0.2 has no sections: a preference is a *volatile* Config field of the
+*   plugin's own row, read through a live reference, written through
+*   `settings.update(rowId, patch)`, and announced by `loader/volatile-update`.
+*   Only volatile fields are writable there, so the host overrides stay
+*   read-only while web search and model visibility are editable.
+*
+* @module dsh-packycode-api/preferences
+*/
+/**
+* Mark a preference editable without restarting the plugin. DSH 0.2 stores
+* plugin preferences as volatile Config fields and writes only those, so the
+* schema version that implements `volatile()` is a peer requirement.
+*
+* Name the cause when it is missing instead of letting a bare
+* `schema.volatile is not a function` reach the host log: the Loader creates
+* no fiber for a plugin whose module throws while it is imported, so DSH shows
+* nothing at all — no settings section, no model route, no RPC channel — and
+* the only explanation is that one log line.
+*/
+const live = (schema) => {
+	if (typeof schema?.volatile !== "function") throw new Error("PackyCode needs @deepseek-ai/schemastery ^3.18.4, which implements Schema.volatile(); the copy resolved for this plugin is older. A plugin installed from a registry has no node_modules of its own, so this usually means a stale dependency tree inside the installed package directory (for example <profile>/node_modules/dsh-packycode-api/node_modules, left by an earlier local-path install) is shadowing the DSH installation. Remove that directory, or uninstall the plugin and install it again, then restart DSH.");
+	return schema.volatile();
+};
+/** Read a Config field that may arrive as a volatile reference. */
+const fieldValue = (value) => value !== null && typeof value === "object" && typeof value.get === "function" ? value.get() : value;
+/** A preference target nothing can write to yet. */
+function unwritable(message) {
+	return {
+		writable: false,
+		set: async () => {
+			throw new Error(message);
+		}
+	};
+}
+/**
+* Connect the preferences to the settings service the host provides.
+* @param settingsCtx - the scope the `settings` inject handed over.
+* @param options - the plugin context and Config, the section namespace, the
+*   current source and how to replace it, what to do when the section changes,
+*   and the preference targets this fills in (host overrides, search, models).
+*/
+function connectSettings(settingsCtx, { ctx, Config, namespace, source, setSource, onChange, hostPreference, searchPreference, modelPreference, imagePreference }) {
+	const settings = settingsCtx.settings;
+	if (typeof settings?.installSection === "function") {
+		try {
+			settings.installSection(ctx, namespace, Config, source(), {
+				setSource: (current) => setSource(typeof current === "function" ? () => current() ?? {} : () => current ?? {}),
+				onChange
+			});
+			if (typeof settings.update === "function") {
+				const write = (patch) => settings.update(namespace, patch);
+				const target = {
+					writable: settings.writable !== false,
+					set: write
+				};
+				Object.assign(hostPreference, target);
+				Object.assign(searchPreference, target);
+				Object.assign(modelPreference, target);
+				if (imagePreference !== void 0) Object.assign(imagePreference, target);
+			}
+		} catch (error) {
+			ctx.logger?.warn?.("packycode-api: host overrides unavailable, defaults stand: %s", error.message);
+		}
+		return;
+	}
+	if (typeof settings?.update !== "function") return;
+	const rowId = ctx.fiber?.entry?.options?.id ?? namespace;
+	const target = {
+		writable: settings.writable !== false,
+		set: (patch) => settings.update(rowId, patch)
+	};
+	Object.assign(searchPreference, target);
+	Object.assign(modelPreference, target);
+	if (imagePreference !== void 0) Object.assign(imagePreference, target);
+	if (typeof settings.configure === "function") {
+		const scope = typeof settingsCtx.effect === "function" ? settingsCtx : ctx;
+		try {
+			scope.effect(() => settings.configure({ auto: false }, ctx.fiber), "packycode-api: settings page policy");
+		} catch (error) {
+			ctx.logger?.warn?.("packycode-api: could not hide the generated settings page: %s", error.message);
+		}
+	}
+}
+//#endregion
+//#region src/image-settings.js
+function readImagePreference(value = {}) {
+	const model = fieldValue(value.imageModel);
+	const imageModel = IMAGE_MODEL_IDS.includes(model) ? model : DEFAULT_IMAGE_MODEL;
+	const quality = fieldValue(value.imageQuality);
+	return {
+		imageEnabled: fieldValue(value.imageEnabled) !== false,
+		imageModel,
+		imageQuality: IMAGE_MODELS[imageModel].includes(quality) ? quality : "auto"
+	};
+}
+/** No request is sent by a settings or credential mutation. */
+function createImageController({ ring, balance, readPreference, writePreference, isWritable }) {
+	let mounted;
+	let disposeTool;
+	let generation = 0;
+	let closed = false;
+	const preference = () => readImagePreference(readPreference());
+	const reconcile = async () => {
+		const current = ++generation;
+		const key = await ring.activeKey();
+		if (closed || current !== generation) return;
+		const enabled = preference().imageEnabled && key !== void 0 && mounted !== void 0;
+		if (enabled && disposeTool === void 0) disposeTool = mounted();
+		if (!enabled && disposeTool !== void 0) {
+			disposeTool();
+			disposeTool = void 0;
+		}
+	};
+	const status = async () => ({
+		...preference(),
+		...await ring.list(),
+		writable: isWritable() === true,
+		available: mounted !== void 0,
+		toolRegistered: disposeTool !== void 0,
+		models: IMAGE_MODEL_IDS.map((id) => ({
+			id,
+			qualities: [...IMAGE_MODELS[id]]
+		}))
+	});
+	return {
+		preference,
+		status,
+		invalidateBalance: () => balance?.invalidate(),
+		async readBalance({ force = false, signal } = {}) {
+			if (balance === void 0) throw new Error("PackyCode image balance is unavailable in this runtime");
+			try {
+				const [value, state] = await Promise.all([balance.read({
+					force,
+					signal
+				}), ring.list()]);
+				return {
+					...value,
+					activeId: state.activeId
+				};
+			} catch {
+				throw new Error("PackyCode image balance could not be read");
+			}
+		},
+		reconcile,
+		mount(register) {
+			mounted = register;
+			closed = false;
+			reconcile().catch(() => void 0);
+			return () => {
+				closed = true;
+				generation += 1;
+				mounted = void 0;
+				disposeTool?.();
+				disposeTool = void 0;
+			};
+		},
+		async update(value = {}) {
+			if (isWritable() !== true) throw new Error("PackyCode image settings are not writable in this profile");
+			const patch = {};
+			if (Object.hasOwn(value, "imageEnabled")) {
+				if (typeof value.imageEnabled !== "boolean") throw new Error("PackyCode image switch must be a boolean");
+				patch.imageEnabled = value.imageEnabled;
+			}
+			if (Object.hasOwn(value, "imageModel")) patch.imageModel = value.imageModel;
+			if (Object.hasOwn(value, "imageQuality")) patch.imageQuality = value.imageQuality;
+			const next = {
+				...preference(),
+				...patch
+			};
+			if (patch.imageModel !== void 0 && patch.imageQuality === void 0 && !IMAGE_MODELS[patch.imageModel]?.includes(next.imageQuality)) patch.imageQuality = next.imageQuality = "auto";
+			validateImageOptions({
+				model: next.imageModel,
+				quality: next.imageQuality
+			});
+			try {
+				await writePreference(patch);
+			} catch {
+				throw new Error("PackyCode could not save the image settings");
+			}
+			await reconcile();
+			return status();
+		},
+		async mutate(operation, payload = {}) {
+			const operations = {
+				add: () => ring.add(payload.key, payload.label),
+				remove: () => ring.remove(String(payload.id ?? "")),
+				select: () => ring.select(String(payload.id ?? "")),
+				enable: () => ring.enable(String(payload.id ?? ""))
+			};
+			if (!Object.hasOwn(operations, operation)) throw new Error("Unknown PackyCode image key operation");
+			await operations[operation]();
+			balance?.invalidate();
+			await reconcile();
+			return status();
+		}
+	};
+}
+//#endregion
+//#region src/images.js
+/** Host-only Images API transport and DSH tool. No subscription/LLM key fallback. */
+const IMAGE_TOOL_NAME = "packycode_image_generate";
+const IMAGE_TIMEOUT_MS = 5 * 6e4;
+const MAX_IMAGE_BYTES = 48 * 1024 * 1024;
+const MAX_REFERENCE_IMAGES = 16;
+const ENVELOPE_BYTES = 1024 * 1024;
+const EDIT_MEDIA_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp"
+];
+const SIGNATURE = "89504e470d0a1a0a";
+const ATTACHMENT_ID = /^sha256:[0-9a-f]{64}$/u;
+var ImageRequestError = class extends Error {};
+const nonempty = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+/** Some model calls fill unused object fields with a zero-valued reference. */
+function emptyMaskReference(value) {
+	return value !== null && typeof value === "object" && (value.attachmentId === "" || value.attachmentId === `sha256:${"0".repeat(64)}`) && value.bytes === 0 && value.width === 0 && value.height === 0 && (value.name === void 0 || value.name === "") && (value.originalDimensions === void 0 || value.originalDimensions.width === 0 && value.originalDimensions.height === 0);
+}
+/** A bounded reader applies to both successful payloads and error envelopes. */
+async function readJson(response, maximum, signal) {
+	const length = Number(response.headers.get("content-length"));
+	if (Number.isFinite(length) && length > maximum || response.body === null) {
+		await response.body?.cancel().catch(() => void 0);
+		throw new ImageRequestError("PackyCode image response is unreadable or exceeds the size limit");
+	}
+	const reader = response.body.getReader();
+	const cancel = () => {
+		reader.cancel().catch(() => void 0);
+	};
+	signal.addEventListener("abort", cancel, { once: true });
+	const chunks = [];
+	let total = 0;
+	try {
+		signal.throwIfAborted();
+		while (true) {
+			const { done, value } = await reader.read();
+			signal.throwIfAborted();
+			if (done) break;
+			total += value.byteLength;
+			if (total > maximum) throw new ImageRequestError("PackyCode image response exceeds the size limit");
+			chunks.push(Buffer.from(value));
+		}
+		try {
+			return JSON.parse(Buffer.concat(chunks, total).toString("utf8"));
+		} catch {
+			throw new ImageRequestError("PackyCode returned an unreadable image response");
+		}
+	} finally {
+		signal.removeEventListener("abort", cancel);
+		await reader.cancel().catch(() => void 0);
+		reader.releaseLock();
+	}
+}
+function pngDimensions(data) {
+	const buffer = Buffer.from(data);
+	if (buffer.length < 24 || buffer.subarray(0, 8).toString("hex") !== SIGNATURE || buffer.readUInt32BE(8) !== 13 || buffer.subarray(12, 16).toString("ascii") !== "IHDR") throw new ImageRequestError("PackyCode returned an invalid PNG image");
+	const width = buffer.readUInt32BE(16);
+	const height = buffer.readUInt32BE(20);
+	if (width === 0 || height === 0 || Math.max(width, height) > 3840 || width * height > 8294400) throw new ImageRequestError("PackyCode returned unsupported image dimensions");
+	return {
+		width,
+		height
+	};
+}
+function decodeImagePng(encoded, maximum = MAX_IMAGE_BYTES) {
+	if (typeof encoded !== "string" || encoded.length === 0 || encoded.length > Math.ceil(maximum / 3) * 4 || encoded.length % 4 !== 0) throw new ImageRequestError("PackyCode returned invalid or oversized base64 image data");
+	const padding = encoded.endsWith("==") ? 2 : encoded.endsWith("=") ? 1 : 0;
+	for (let index = 0; index < encoded.length - padding; index += 1) {
+		const code = encoded.charCodeAt(index);
+		if (!(code >= 65 && code <= 90 || code >= 97 && code <= 122 || code >= 48 && code <= 57 || code === 43 || code === 47)) throw new ImageRequestError("PackyCode returned invalid base64 image data");
+	}
+	const data = Buffer.from(encoded, "base64");
+	if (data.length > maximum || data.toString("base64") !== encoded) throw new ImageRequestError("PackyCode returned invalid base64 image data");
+	pngDimensions(data);
+	return data;
+}
+function imageFailure(status, value) {
+	if (value?.error?.code === "moderation_blocked") return "PackyCode image request was blocked by the image safety check; revise the prompt or references";
+	if (status === 401 || status === 403) return "PackyCode image key was rejected; check the separate image key and its model permissions";
+	if (status === 429) return "PackyCode image quota or rate limit is unavailable; check the separate image key";
+	return `PackyCode image request failed (HTTP ${status}); check model, quality, and image key permissions`;
+}
+/** One paid attempt only. Invalid references never turn an edit into a generation. */
+function createPackyCodeImageClient({ resolveKey, getHost, fetchImpl = ambientFetch, timeoutMs = IMAGE_TIMEOUT_MS }) {
+	return { async request(args, { signal, images, mask } = {}) {
+		const options = validateImageOptions(args);
+		const prompt = nonempty(args?.prompt);
+		if (prompt === void 0 || prompt.length > 32e3) throw new ImageRequestError("PackyCode image prompt must contain 1-32000 characters");
+		if (images !== void 0 && (!Array.isArray(images) || images.length === 0 || images.length > MAX_REFERENCE_IMAGES)) throw new ImageRequestError("PackyCode image edits require 1-16 reference images");
+		if (mask !== void 0 && images === void 0) throw new ImageRequestError("PackyCode image mask requires a reference image");
+		const timeout = AbortSignal.timeout(timeoutMs);
+		const requestSignal = signal === void 0 ? timeout : AbortSignal.any([signal, timeout]);
+		let selected;
+		try {
+			selected = await waitForSharedRequest(Promise.resolve().then(resolveKey), requestSignal);
+		} catch {
+			if (signal?.aborted) throw new ImageRequestError("PackyCode image request was cancelled");
+			if (timeout.aborted) throw new ImageRequestError("PackyCode image request timed out");
+			throw new ImageRequestError("PackyCode image credentials could not be read");
+		}
+		if (typeof selected?.key !== "string" || selected.key === "") throw new ImageRequestError("PackyCode images need a separate image key; add one under Settings → PackyCode → Images");
+		const fields = {
+			...options,
+			prompt,
+			n: 1,
+			output_format: "png"
+		};
+		let body;
+		const headers = {
+			authorization: `Bearer ${selected.key}`,
+			accept: "application/json"
+		};
+		if (images === void 0) {
+			headers["content-type"] = "application/json";
+			body = JSON.stringify(fields);
+		} else {
+			body = new FormData();
+			for (const [key, value] of Object.entries(fields)) body.append(key, String(value));
+			for (const [index, image] of images.entries()) {
+				if (!EDIT_MEDIA_TYPES.includes(image?.mediaType) || !(image.data instanceof Uint8Array) || image.data.byteLength === 0 || image.data.byteLength >= 50 * 1024 * 1024) throw new ImageRequestError("PackyCode reference images must be PNG, JPEG or WebP smaller than 50 MB");
+				const extension = image.mediaType === "image/jpeg" ? "jpg" : image.mediaType.split("/")[1];
+				body.append("image[]", new Blob([image.data], { type: image.mediaType }), `reference-${index + 1}.${extension}`);
+			}
+			if (mask !== void 0) {
+				if (mask.mediaType !== "image/png" || !(mask.data instanceof Uint8Array) || mask.data.byteLength >= 4 * 1024 * 1024) throw new ImageRequestError("PackyCode image mask must be a PNG smaller than 4 MB");
+				const dimensions = pngDimensions(mask.data);
+				if (dimensions.width !== images[0].width || dimensions.height !== images[0].height) throw new ImageRequestError("PackyCode image mask must match the first reference image dimensions");
+				body.append("mask", new Blob([mask.data], { type: "image/png" }), "mask.png");
+			}
+		}
+		try {
+			requestSignal.throwIfAborted();
+			const response = await fetchImpl(`${normalizeHost(getHost(), DEFAULT_API_HOST).replace(/\/v1$/u, "")}/v1/images/${images === void 0 ? "generations" : "edits"}`, {
+				method: "POST",
+				redirect: "error",
+				headers,
+				body,
+				signal: requestSignal
+			});
+			if (!response.ok) {
+				const value = await readJson(response, 64 * 1024, requestSignal).catch(() => void 0);
+				requestSignal.throwIfAborted();
+				throw new ImageRequestError(imageFailure(response.status, value));
+			}
+			const value = await readJson(response, Math.ceil(MAX_IMAGE_BYTES / 3) * 4 + ENVELOPE_BYTES, requestSignal);
+			const data = decodeImagePng(value?.data?.[0]?.b64_json);
+			return {
+				data,
+				...pngDimensions(data),
+				requestedModel: options.model,
+				requestedQuality: options.quality,
+				requestedSize: options.size,
+				...IMAGE_MODEL_IDS.includes(value?.model) ? { reportedModel: value.model } : {},
+				...IMAGE_QUALITIES.includes(value?.quality) ? { quality: value.quality } : {}
+			};
+		} catch (error) {
+			if (signal?.aborted) throw new ImageRequestError("PackyCode image request was cancelled");
+			if (timeout.aborted) throw new ImageRequestError("PackyCode image request timed out");
+			if (error instanceof ImageRequestError) throw error;
+			throw new ImageRequestError("PackyCode image connection failed");
+		}
+	} };
+}
+const referenceSchema = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		attachmentId: {
+			type: "string",
+			required: true,
+			description: "Complete sha256:<64 lowercase hex> image reference from the current session or read_image. Never a path or filename."
+		},
+		mediaType: {
+			type: "string",
+			required: true
+		},
+		bytes: {
+			type: "integer",
+			required: true
+		},
+		width: {
+			type: "integer",
+			required: true
+		},
+		height: {
+			type: "integer",
+			required: true
+		},
+		name: { type: "string" },
+		originalDimensions: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				width: {
+					type: "integer",
+					required: true
+				},
+				height: {
+					type: "integer",
+					required: true
+				}
+			}
+		}
+	}
+};
+/** Select only trusted references already present in this tool call's session. */
+async function readReferences(values, attachments, messages, signal) {
+	if (!Array.isArray(values) || values.length === 0 || values.length > MAX_REFERENCE_IMAGES) throw new ImageRequestError("PackyCode image edits require 1-16 reference images");
+	const available = /* @__PURE__ */ new Map();
+	const visit = (content) => {
+		for (const block of content ?? []) {
+			if (block?.type === "image" && ATTACHMENT_ID.test(block.attachment?.attachmentId)) available.set(block.attachment.attachmentId, block.attachment);
+			if (block?.type === "tool-result" && Array.isArray(block.content)) visit(block.content);
+		}
+	};
+	for (const message of messages ?? []) if (Array.isArray(message?.content)) visit(message.content);
+	const ids = values.map((value) => value?.attachmentId);
+	if (ids.some((id) => typeof id !== "string" || !ATTACHMENT_ID.test(id) || !available.has(id))) throw new ImageRequestError("PackyCode image reference is missing from this session; use read_image and copy its complete attachment reference");
+	if (new Set(ids).size !== ids.length) throw new ImageRequestError("PackyCode image references must not contain duplicates");
+	const images = [];
+	let total = 0;
+	for (const id of ids) {
+		signal?.throwIfAborted();
+		let stored;
+		try {
+			stored = await attachments.readImage(available.get(id), signal);
+		} catch {
+			throw new ImageRequestError("PackyCode could not read the selected image attachment");
+		}
+		const { data, ref } = stored;
+		if (!(data instanceof Uint8Array) || !EDIT_MEDIA_TYPES.includes(ref?.mediaType)) throw new ImageRequestError("PackyCode image reference must be PNG, JPEG or WebP");
+		total += data.byteLength;
+		if (total > attachments.imageLimits.maxMessageImageBytes) throw new ImageRequestError("PackyCode image references exceed the DSH image limit");
+		images.push({
+			data,
+			mediaType: ref.mediaType,
+			width: ref.width,
+			height: ref.height
+		});
+	}
+	return images;
+}
+function attachmentProjection(ref) {
+	return Object.fromEntries([
+		"attachmentId",
+		"mediaType",
+		"bytes",
+		"width",
+		"height",
+		"name",
+		"originalDimensions"
+	].filter((key) => ref[key] !== void 0).map((key) => [key, ref[key]]));
+}
+const renderImage = (value) => [{
+	type: "text",
+	text: `PackyCode · ${value.requestedModel} · ${value.width} × ${value.height} · ${value.requestedQuality}\nOriginal PNG on the DSH host: ${value.localPath}`
+}, {
+	type: "image",
+	attachment: value.image
+}];
+function createPackyCodeImageTool({ client, attachments, getPreference, getSessionMessages, imageDirectory, onGenerated }) {
+	return defineTool({
+		name: IMAGE_TOOL_NAME,
+		description: "Generate or edit images through PackyCode using the separately configured image API key. Use only when the user requests image output. This is independent of the conversation model and Codex subscription. For a new image omit referenceImages; for edits include only the intended images from this session or read_image. Never replace an edit with text-only generation, silently change models or downgrade quality. Return the resulting image to the user. Rendering may take several minutes.",
+		parameters: {
+			prompt: {
+				type: "string",
+				required: true,
+				description: "Complete image description or precise editing instructions."
+			},
+			operation: {
+				type: "string",
+				enum: ["generate", "edit"],
+				description: "Use generate for a new image; edit requires 1-16 real referenceImages. If omitted, nonempty references select editing, while an omitted or empty array selects generation."
+			},
+			model: {
+				type: "string",
+				enum: ["settings", ...IMAGE_MODEL_IDS],
+				description: "Use settings (or omit) to follow the PackyCode image setting. Choose an explicit engine only when the user requests one."
+			},
+			quality: {
+				type: "string",
+				enum: ["settings", ...IMAGE_QUALITIES],
+				description: "Use settings (or omit) to follow the user image setting. auto is an explicit API quality, not a request to follow settings. xhigh and max require a 2.5 model; never downgrade automatically."
+			},
+			size: {
+				type: "string",
+				description: "auto or widthxheight, e.g. 1024x1024; both edges multiples of 16, each <=3840, ratio <=3:1, pixels 655360..8294400."
+			},
+			background: {
+				type: "string",
+				enum: [
+					"auto",
+					"opaque",
+					"transparent"
+				]
+			},
+			referenceImages: {
+				type: "array",
+				items: referenceSchema,
+				description: "1-16 complete attachment references for editing. Omit or use [] for a new image. Paths and unrelated images are not accepted; never drop real references after an edit fails."
+			},
+			maskImage: {
+				...referenceSchema,
+				description: "Omit for new images and edits without a mask. Never invent a reference. Optional PNG mask from this session, matching the first reference and under 4 MB; alpha=0 marks the area to edit."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					image: {
+						...referenceSchema,
+						required: true
+					},
+					localPath: {
+						type: "string",
+						required: true
+					},
+					width: {
+						type: "integer",
+						required: true
+					},
+					height: {
+						type: "integer",
+						required: true
+					},
+					requestedModel: {
+						type: "string",
+						required: true
+					},
+					requestedQuality: {
+						type: "string",
+						required: true
+					},
+					requestedSize: {
+						type: "string",
+						required: true
+					},
+					reportedModel: { type: "string" },
+					quality: { type: "string" }
+				}
+			},
+			render: (_args, value) => renderImage(value),
+			presentationMeta: (_args, value) => ({
+				kind: "packycode-image",
+				requestedModel: value.requestedModel,
+				requestedQuality: value.requestedQuality,
+				width: value.width,
+				height: value.height
+			})
+		},
+		timeoutMs: IMAGE_TIMEOUT_MS,
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			const preference = getPreference();
+			if (!preference.imageEnabled) throw new ImageRequestError("PackyCode images are disabled in settings");
+			if (exec?.agent?.id === void 0) throw new ImageRequestError("PackyCode images require a session-owned tool call");
+			const signal = exec.signal;
+			const hasReferences = Array.isArray(args.referenceImages) && args.referenceImages.length > 0;
+			if (args.operation === "generate" && hasReferences) throw new ImageRequestError("PackyCode image generation cannot include reference images; use edit");
+			const editing = args.operation === "edit" || hasReferences;
+			const maskImage = emptyMaskReference(args.maskImage) ? void 0 : args.maskImage;
+			if (maskImage !== void 0 && !editing) throw new ImageRequestError("PackyCode image mask requires referenceImages");
+			let messages;
+			try {
+				messages = editing ? await getSessionMessages(exec.agent.id) : void 0;
+			} catch {
+				throw new ImageRequestError("PackyCode could not read the current session image references");
+			}
+			const images = editing ? await readReferences(args.referenceImages, attachments, messages, signal) : void 0;
+			const masks = maskImage === void 0 ? void 0 : await readReferences([maskImage], attachments, messages, signal);
+			if (!getPreference().imageEnabled) throw new ImageRequestError("PackyCode images are disabled in settings");
+			const result = await client.request({
+				...args,
+				model: args.model === "settings" ? preference.imageModel : args.model ?? preference.imageModel,
+				quality: args.quality === "settings" ? preference.imageQuality : args.quality ?? preference.imageQuality
+			}, {
+				signal,
+				images,
+				mask: masks?.[0]
+			});
+			onGenerated?.();
+			signal?.throwIfAborted();
+			await mkdir(imageDirectory, {
+				recursive: true,
+				mode: 448
+			});
+			const localPath = join(imageDirectory, `${randomUUID()}.png`);
+			let saved = false;
+			try {
+				const file = await open(localPath, "wx", 384);
+				saved = true;
+				try {
+					await file.writeFile(result.data);
+				} finally {
+					await file.close();
+				}
+				const ref = await attachments.saveImage({
+					data: result.data,
+					mediaType: "image/png",
+					name: "packycode-generated.png"
+				});
+				const { data: _data, ...metadata } = result;
+				const value = {
+					...metadata,
+					image: attachmentProjection(ref),
+					localPath
+				};
+				if (exec.parent !== void 0) exec.deferContext(createUserMessage({
+					content: renderImage(value),
+					source: {
+						kind: "plugin",
+						plugin: "packycode-api"
+					}
+				}));
+				return value;
+			} catch {
+				if (saved) await rm(localPath, { force: true }).catch(() => void 0);
+				throw new ImageRequestError("PackyCode could not save the generated image");
+			}
+		}
+	});
+}
+//#endregion
 //#region src/key-chooser.js
 /**
 * Which stored key a request runs with, and what happens when the gateway
@@ -4730,7 +5432,6 @@ function createKeyChooser({ ring, groups, onRotated, logger, waitMs = DEFAULT_GR
 const LEGAL_KEY = /^[\x21-\x7E]+$/u;
 const RECORD_VERSION = 1;
 const MAX_KEYS = 32;
-const RECORD_KEY = typeof credentialKey === "function" ? credentialKey(PLUGIN_ID, KEY_RECORD_ID) : void 0;
 const text$1 = (value) => typeof value === "string" ? value : "";
 /** Validate a pasted key before it is stored; the gateway never sees a bad one from us. */
 function assertApiKey(value) {
@@ -4794,16 +5495,18 @@ function projection(state) {
 }
 var PackyCodeKeyRing = class {
 	#credentials;
-	constructor(credentials) {
-		if (RECORD_KEY === void 0) throw new Error("dsh-packycode-api requires @deepseek-ai/dsh-credentials with credentialKey()");
+	#recordKey;
+	constructor(credentials, { recordId = KEY_RECORD_ID } = {}) {
+		if (typeof credentialKey !== "function") throw new Error("dsh-packycode-api requires @deepseek-ai/dsh-credentials with credentialKey()");
 		if (credentials === null || typeof credentials !== "object" || typeof credentials.readRecord !== "function" || typeof credentials.modifyRecord !== "function") throw new Error("dsh-packycode-api requires the DSH credential record API");
 		this.#credentials = credentials;
+		this.#recordKey = credentialKey(PLUGIN_ID, recordId);
 	}
 	async #read() {
-		return normalizeState(await this.#credentials.readRecord(RECORD_KEY));
+		return normalizeState(await this.#credentials.readRecord(this.#recordKey));
 	}
 	async #write(mutate) {
-		return normalizeState(await this.#credentials.modifyRecord(RECORD_KEY, async (current) => {
+		return normalizeState(await this.#credentials.modifyRecord(this.#recordKey, async (current) => {
 			const updated = await mutate(normalizeState(current));
 			if (updated === void 0) return current;
 			return {
@@ -4953,95 +5656,6 @@ var PackyCodeKeyRing = class {
 	}
 };
 //#endregion
-//#region src/preferences.js
-/**
-* Where the plugin's preferences are read from and written to, on both
-* settings generations DSH has shipped.
-*
-* - DSH 0.1.5 installs a settings *section*: the section hands back a live
-*   source and writes go through `settings.update(namespace, patch)`.
-* - DSH 0.2 has no sections: a preference is a *volatile* Config field of the
-*   plugin's own row, read through a live reference, written through
-*   `settings.update(rowId, patch)`, and announced by `loader/volatile-update`.
-*   Only volatile fields are writable there, so the host overrides stay
-*   read-only while web search and model visibility are editable.
-*
-* @module dsh-packycode-api/preferences
-*/
-/**
-* Mark a preference editable without restarting the plugin. DSH 0.2 stores
-* plugin preferences as volatile Config fields and writes only those, so the
-* schema version that implements `volatile()` is a peer requirement.
-*
-* Name the cause when it is missing instead of letting a bare
-* `schema.volatile is not a function` reach the host log: the Loader creates
-* no fiber for a plugin whose module throws while it is imported, so DSH shows
-* nothing at all — no settings section, no model route, no RPC channel — and
-* the only explanation is that one log line.
-*/
-const live = (schema) => {
-	if (typeof schema?.volatile !== "function") throw new Error("PackyCode needs @deepseek-ai/schemastery ^3.18.4, which implements Schema.volatile(); the copy resolved for this plugin is older. A plugin installed from a registry has no node_modules of its own, so this usually means a stale dependency tree inside the installed package directory (for example <profile>/node_modules/dsh-packycode-api/node_modules, left by an earlier local-path install) is shadowing the DSH installation. Remove that directory, or uninstall the plugin and install it again, then restart DSH.");
-	return schema.volatile();
-};
-/** Read a Config field that may arrive as a volatile reference. */
-const fieldValue = (value) => value !== null && typeof value === "object" && typeof value.get === "function" ? value.get() : value;
-/** A preference target nothing can write to yet. */
-function unwritable(message) {
-	return {
-		writable: false,
-		set: async () => {
-			throw new Error(message);
-		}
-	};
-}
-/**
-* Connect the preferences to the settings service the host provides.
-* @param settingsCtx - the scope the `settings` inject handed over.
-* @param options - the plugin context and Config, the section namespace, the
-*   current source and how to replace it, what to do when the section changes,
-*   and the preference targets this fills in (host overrides, search, models).
-*/
-function connectSettings(settingsCtx, { ctx, Config, namespace, source, setSource, onChange, hostPreference, searchPreference, modelPreference }) {
-	const settings = settingsCtx.settings;
-	if (typeof settings?.installSection === "function") {
-		try {
-			settings.installSection(ctx, namespace, Config, source(), {
-				setSource: (current) => setSource(typeof current === "function" ? () => current() ?? {} : () => current ?? {}),
-				onChange
-			});
-			if (typeof settings.update === "function") {
-				const write = (patch) => settings.update(namespace, patch);
-				const target = {
-					writable: settings.writable !== false,
-					set: write
-				};
-				Object.assign(hostPreference, target);
-				Object.assign(searchPreference, target);
-				Object.assign(modelPreference, target);
-			}
-		} catch (error) {
-			ctx.logger?.warn?.("packycode-api: host overrides unavailable, defaults stand: %s", error.message);
-		}
-		return;
-	}
-	if (typeof settings?.update !== "function") return;
-	const rowId = ctx.fiber?.entry?.options?.id ?? namespace;
-	const target = {
-		writable: settings.writable !== false,
-		set: (patch) => settings.update(rowId, patch)
-	};
-	Object.assign(searchPreference, target);
-	Object.assign(modelPreference, target);
-	if (typeof settings.configure === "function") {
-		const scope = typeof settingsCtx.effect === "function" ? settingsCtx : ctx;
-		try {
-			scope.effect(() => settings.configure({ auto: false }, ctx.fiber), "packycode-api: settings page policy");
-		} catch (error) {
-			ctx.logger?.warn?.("packycode-api: could not hide the generated settings page: %s", error.message);
-		}
-	}
-}
-//#endregion
 //#region src/model-selection.js
 /** Profile preferences for the models advertised in PackyCode's picker. */
 /** Store exclusions so new catalog models are selected by default as well. */
@@ -5831,7 +6445,7 @@ const keyId = (payload) => String(payload?.id ?? "");
 *   web search controller (without one, its endpoints refuse).
 * @returns a handler for `connection.rpc.handle(CHANNEL, handler)`.
 */
-function createPackyCodeRpc({ ring, balance, groups, hosts, preference, claudeCli, pluginManager, search, modelSelection }) {
+function createPackyCodeRpc({ ring, balance, groups, hosts, preference, claudeCli, pluginManager, search, modelSelection, images }) {
 	const need = (service, message) => {
 		if (service === void 0) throw new Error(message);
 		return service;
@@ -5841,6 +6455,7 @@ function createPackyCodeRpc({ ring, balance, groups, hosts, preference, claudeCl
 	const webSearch = () => need(search, "PackyCode web search is unavailable in this runtime");
 	const groupReader = () => need(groups, "PackyCode key groups are unavailable in this runtime");
 	const models = () => need(modelSelection, "PackyCode model selection is unavailable in this runtime");
+	const imageSupport = () => need(images, "PackyCode images are unavailable in this runtime");
 	const status = async () => ({
 		...await ring.list(),
 		hosts: hosts(),
@@ -5889,6 +6504,7 @@ function createPackyCodeRpc({ ring, balance, groups, hosts, preference, claudeCl
 			});
 			balance.invalidate();
 			groups?.invalidate();
+			images?.invalidateBalance?.();
 			return status();
 		},
 		"claude-cli/status": (payload) => cli().status({ force: payload?.force === true }),
@@ -5907,7 +6523,20 @@ function createPackyCodeRpc({ ring, balance, groups, hosts, preference, claudeCl
 			searchBackend: payload?.searchBackend
 		}),
 		"models/status": () => models().status(),
-		"models/update": (payload) => models().update({ selectedIds: payload?.selectedIds })
+		"models/update": (payload) => models().update({ selectedIds: payload?.selectedIds }),
+		"images/status": () => imageSupport().status(),
+		"images/balance": (payload, signal) => imageSupport().readBalance({
+			force: payload?.force === true,
+			signal
+		}),
+		"images/update": (payload) => imageSupport().update(payload),
+		"images/keys/add": (payload) => imageSupport().mutate("add", {
+			key: payload?.key,
+			label: payload?.label
+		}),
+		"images/keys/remove": (payload) => imageSupport().mutate("remove", { id: payload?.id }),
+		"images/keys/select": (payload) => imageSupport().mutate("select", { id: payload?.id }),
+		"images/keys/enable": (payload) => imageSupport().mutate("enable", { id: payload?.id })
 	};
 	return async (endpoint, payload, signal) => {
 		try {
@@ -6842,16 +7471,23 @@ const Config = z.object({
 	/** Which PackyCode model runs a search: `deepseek` or `gpt`. */
 	searchBackend: live(z.union([...SEARCH_BACKENDS]).default(DEFAULT_SEARCH_BACKEND)),
 	/** Only the picker is filtered; an existing session can keep its model. */
-	hiddenModels: live(z.array(z.string()).default([]))
+	hiddenModels: live(z.array(z.string()).default([])),
+	imageEnabled: live(z.boolean().default(true)),
+	imageModel: live(z.union([...IMAGE_MODEL_IDS]).default(DEFAULT_IMAGE_MODEL)),
+	imageQuality: live(z.union([...IMAGE_QUALITIES]).default("auto"))
 });
 function apply(ctx, config) {
 	const ring = new PackyCodeKeyRing(ctx.credentials);
+	const imageRing = new PackyCodeKeyRing(ctx.credentials, { recordId: IMAGE_KEY_RECORD_ID });
 	let source = () => ({
 		apiHost: normalizeHost(config?.apiHost, DEFAULT_API_HOST),
 		statusHost: normalizeHost(config?.statusHost, DEFAULT_STATUS_HOST),
 		searchProvider: fieldValue(config?.searchProvider),
 		searchBackend: fieldValue(config?.searchBackend),
-		hiddenModels: fieldValue(config?.hiddenModels)
+		hiddenModels: fieldValue(config?.hiddenModels),
+		imageEnabled: fieldValue(config?.imageEnabled),
+		imageModel: fieldValue(config?.imageModel),
+		imageQuality: fieldValue(config?.imageQuality)
 	});
 	const hosts = () => {
 		const current = source() ?? {};
@@ -6864,6 +7500,11 @@ function apply(ctx, config) {
 		listKeys: () => ring.secrets(),
 		getHosts: hosts
 	});
+	const imageBalance = createBalanceReader({
+		listKeys: () => imageRing.secrets(),
+		getHosts: hosts,
+		includeAccount: false
+	});
 	/**
 	* Which token groups each key is in, and so which models it can reach.
 	* Nothing reads it at boot: the settings panel asks for it, and a request
@@ -6998,7 +7639,22 @@ function apply(ctx, config) {
 		writable: false,
 		set: void 0
 	};
+	const imagePreference = {
+		writable: false,
+		set: void 0
+	};
 	const dshHome = typeof process.env.DSH_HOME === "string" && process.env.DSH_HOME !== "" ? process.env.DSH_HOME : join(homedir(), ".dsh");
+	const images = createImageController({
+		ring: imageRing,
+		balance: imageBalance,
+		readPreference: () => source() ?? {},
+		writePreference: (patch) => imagePreference.set(patch),
+		isWritable: () => imagePreference.writable === true && typeof imagePreference.set === "function"
+	});
+	const imageClient = createPackyCodeImageClient({
+		resolveKey: () => imageRing.activeKey(),
+		getHost: () => hosts().apiHost
+	});
 	const search = createSearchController({
 		ring,
 		hosts,
@@ -7037,16 +7693,20 @@ function apply(ctx, config) {
 		},
 		onChange: () => {
 			balance.invalidate();
+			imageBalance.invalidate();
 			groups.invalidate();
 			modelSelection.reconcile();
+			images.reconcile().catch(() => void 0);
 			search.reconcile();
 		},
 		hostPreference,
 		searchPreference,
-		modelPreference
+		modelPreference,
+		imagePreference
 	}));
 	ctx.on?.("loader/volatile-update", () => {
 		modelSelection.reconcile();
+		images.reconcile().catch(() => void 0);
 		search.reconcile();
 	});
 	/**
@@ -7069,7 +7729,8 @@ function apply(ctx, config) {
 		claudeCli,
 		pluginManager: createPackyCodePluginManager(),
 		search,
-		modelSelection
+		modelSelection,
+		images
 	});
 	/**
 	* The shipped Connection getter retains its own service context, whose row
@@ -7090,6 +7751,18 @@ function apply(ctx, config) {
 			planActive: (session, agent) => planModeForToolExecution(ctx, session, agent)
 		})), "packycode-api: claude_code tool");
 	});
+	ctx.inject(["tools", "attachments"], (imageCtx) => {
+		const store = imageCtx.attachments;
+		if (typeof store?.saveImage !== "function" || typeof store?.readImage !== "function") return;
+		(typeof imageCtx.effect === "function" ? imageCtx : ctx).effect(() => images.mount(() => imageCtx.tools.register(createPackyCodeImageTool({
+			client: imageClient,
+			attachments: store,
+			getPreference: images.preference,
+			onGenerated: () => imageBalance.invalidate(),
+			getSessionMessages: (id) => ctx.get?.("sessions")?.get?.(id)?.deriveMessages?.() ?? [],
+			imageDirectory: join(dshHome, "packycode-api", "images")
+		}))), "packycode-api: image tool availability");
+	});
 }
 //#endregion
-export { AUTO_CLAUDE_MODE, CHANNEL, CLAUDE_CLI_MODES, CLAUDE_INSTALL_COMMAND, CLAUDE_MISSING_MESSAGE, CLAUDE_NPM_PACKAGE, CLAUDE_TOOL_INSTRUCTIONS, CLI_BACKED_MODEL_IDS, CLI_IMAGE_LIMITS, Config, DEFAULT_API_HOST, DEFAULT_APPEND_SYSTEM_PROMPT, DEFAULT_SEARCH_BACKEND, DEFAULT_STATUS_HOST, DISPLAY_NAME, LEGACY_STATUS_HOSTS, PACKYCODE_AUTO_SEARCH_PROVIDER_ID, PACKYCODE_MODELS, PACKYCODE_MODEL_IDS, PACKYCODE_SEARCH_PROVIDER_ID, PLUGIN_ID, PROVIDER, PackyCodeKeyRing, SEARCH_BACKENDS, SEARCH_BACKEND_MODELS, SEARCH_MODES, SETTINGS_NAMESPACE, TITLE_MODEL_ID, TITLE_MODEL_ROUTES, accountHostOrder, apply, assertApiKey, buildClaudeArgs, buildClaudeEnvironment, buildClaudeInput, buildDelegatedContent, buildSearchRequest, capClaudeMode, catalogCoverage, classifyClientPolicy, classifyGatewayFailure, claudeBinaryCandidates, claudeModeFor, claudeModeForSession, cliSearchInstructions, createBalanceReader, createClaudeCliAdapter, createClaudeCliManager, createClaudeCodeTool, createClaudeRunner, createClaudeSearchBridge, createGroupReader, createKeyChooser, createModelSelectionController, createPackyCodeAutoSearchProvider, createPackyCodeProfile, createPackyCodeProvider, createPackyCodeRpc, createPackyCodeSearchProvider, createProfileSearchComposition, createRouteAdapter, createSearchComposition, createSearchController, delegationInstructions, describeRunKey, explainCliClientPolicyFailure, explainCliGroupFailure, explainClientPolicyFailure, explainNpmFailure, findClaudeBinary, guardKeyRotation, inject, keyNote, locateClaudeBinary, locateNpm, name, normalizeFailureMessage, normalizeHost, npmCandidates, parseBillingSubscription, parseBillingUsage, parseClaudeResult, parseClaudeVersion, parseMessagesSearchResponse, parsePricing, parseResponsesSearchResponse, parseSelectedGroups, parseTokenUsage, pickKeyForModel, planModeForSession, planModeForToolExecution, readClaudeStreamEvents, readHiddenModels, readSearchChoice, renderAuxiliaryPrompt, renderDelegatedPrompt, resolveSpawnCommand, statusHostOrder, summarizeToolUse };
+export { AUTO_CLAUDE_MODE, CHANNEL, CLAUDE_CLI_MODES, CLAUDE_INSTALL_COMMAND, CLAUDE_MISSING_MESSAGE, CLAUDE_NPM_PACKAGE, CLAUDE_TOOL_INSTRUCTIONS, CLI_BACKED_MODEL_IDS, CLI_IMAGE_LIMITS, Config, DEFAULT_API_HOST, DEFAULT_APPEND_SYSTEM_PROMPT, DEFAULT_IMAGE_MODEL, DEFAULT_SEARCH_BACKEND, DEFAULT_STATUS_HOST, DISPLAY_NAME, IMAGE_MODELS, IMAGE_MODEL_IDS, IMAGE_QUALITIES, IMAGE_TIMEOUT_MS, IMAGE_TOOL_NAME, LEGACY_STATUS_HOSTS, MAX_IMAGE_BYTES, PACKYCODE_AUTO_SEARCH_PROVIDER_ID, PACKYCODE_MODELS, PACKYCODE_MODEL_IDS, PACKYCODE_SEARCH_PROVIDER_ID, PLUGIN_ID, PROVIDER, PackyCodeKeyRing, SEARCH_BACKENDS, SEARCH_BACKEND_MODELS, SEARCH_MODES, SETTINGS_NAMESPACE, TITLE_MODEL_ID, TITLE_MODEL_ROUTES, accountHostOrder, apply, assertApiKey, buildClaudeArgs, buildClaudeEnvironment, buildClaudeInput, buildDelegatedContent, buildSearchRequest, capClaudeMode, catalogCoverage, classifyClientPolicy, classifyGatewayFailure, claudeBinaryCandidates, claudeModeFor, claudeModeForSession, cliSearchInstructions, createBalanceReader, createClaudeCliAdapter, createClaudeCliManager, createClaudeCodeTool, createClaudeRunner, createClaudeSearchBridge, createGroupReader, createImageController, createKeyChooser, createModelSelectionController, createPackyCodeAutoSearchProvider, createPackyCodeImageClient, createPackyCodeImageTool, createPackyCodeProfile, createPackyCodeProvider, createPackyCodeRpc, createPackyCodeSearchProvider, createProfileSearchComposition, createRouteAdapter, createSearchComposition, createSearchController, decodeImagePng, delegationInstructions, describeRunKey, explainCliClientPolicyFailure, explainCliGroupFailure, explainClientPolicyFailure, explainNpmFailure, findClaudeBinary, guardKeyRotation, inject, keyNote, locateClaudeBinary, locateNpm, name, normalizeFailureMessage, normalizeHost, npmCandidates, parseBillingSubscription, parseBillingUsage, parseClaudeResult, parseClaudeVersion, parseMessagesSearchResponse, parsePricing, parseResponsesSearchResponse, parseSelectedGroups, parseTokenUsage, pickKeyForModel, planModeForSession, planModeForToolExecution, pngDimensions, readClaudeStreamEvents, readHiddenModels, readImagePreference, readSearchChoice, renderAuxiliaryPrompt, renderDelegatedPrompt, resolveSpawnCommand, statusHostOrder, summarizeToolUse, validateImageOptions };