codex-copilot-dx 0.7.8 → 0.7.10

package/README.md

@@ -131,7 +131,7 @@ The selector is ordered numerically:
 8. Relay — fixed nodes receive and pass a short light trail
 9. Split — one incoming light trail divides into two outgoing trails
 
-Enter the corresponding number to select an animation. The Comet row includes a static preview, and after a selection CCDX plays one cycle of the chosen animation as confirmation when terminal animation is enabled. The setting is saved in `~/.config/codex-copilot-dx/config.json`, or under `XDG_CONFIG_HOME` when set.
+All nine rows preview their animations together while you enter a number to select one. The live previews keep each theme's original timing and leave the input cursor in place; selection ends them immediately. Small terminals, disabled animation, CI and dumb terminals retain static previews. Resizing or clearing the terminal pauses the live gallery so input stays usable. When the gallery cannot run, CCDX retains the selected animation's one-cycle confirmation when supported. The setting is saved in `~/.config/codex-copilot-dx/config.json`, or under `XDG_CONFIG_HOME` when set.
 
 All nine animations use the same 20-column colon track and cyan/blue palette. They indicate activity, not completion percentage. Braille was removed in 0.7.7. A saved `terminal_animation: "braille"` falls back to Comet without rewriting the settings file; choosing another animation replaces it, and explicitly choosing Comet clears it. Other settings remain intact.
 
@@ -147,7 +147,9 @@ ccdx enable-image
 
 The command asks for an HTTPS `/images/generations` endpoint and an API key without echoing the key. It reads the endpoint's `/models` catalog, detects either the standard OpenAI Images request format or the supported `input.messages` format, and asks for a numeric model selection only when multiple image models are available. Its validation request omits the prompt and does not generate an image.
 
-The provider credential is stored in `~/.config/codex-copilot-dx/image-provider.json`, or under `XDG_CONFIG_HOME`, with mode `0600`. The API key is never written to `~/.codex/config.toml`; that file receives only a marked local MCP entry pointing to the running CCDX adapter with a 210-second tool timeout. Restart Codex App after enabling so it loads the tool. The existing CCDX adapter can remain running because provider settings are loaded when the tool is invoked.
+The provider credential is stored in `~/.config/codex-copilot-dx/image-provider.json`, or under `XDG_CONFIG_HOME`, with mode `0600`. The API key is never written to `~/.codex/config.toml`; that file receives only a marked local MCP entry pointing to the running CCDX adapter with a 210-second tool timeout. Enabling also installs CCDX-owned `ccdx-image` guidance under `~/.codex/skills`, with a self-contained Node helper. Codex uses the MCP tool directly, including through deferred tool search; an already-open task without that tool can use the helper to call the same local service and display the saved image. Neither route requires Python, an OpenAI SDK, or copying credentials. The original built-in imagegen skill remains available for capabilities such as editing uploaded images and other reference-image workflows.
+
+The enable command verifies the local MCP handshake and generation-tool directory without generating an image. It reports provider configuration separately from local service readiness; it cannot assert that every running Codex task has refreshed its catalog. Codex normally detects changed skills; restart Codex App once if an open task has not refreshed them. Normal CCDX startup installs or updates this guidance for providers already enabled in 0.7.8, without repeating API setup. Unchanged guidance is not rewritten. The existing adapter can remain running because provider settings are loaded when the tool is invoked.
 
 Inspect or disable the optional provider with:
 
@@ -156,9 +158,13 @@ ccdx image-status
 ccdx disable-image
 ```
 
-`image-status` never prints the API key. Disabling removes the stored provider credential and the CCDX-owned MCP block; restart Codex App to remove the tool from already running tasks. The image endpoint is contacted only by `enable-image` validation and by explicit `generate_image` tool calls. Ordinary Responses, models, authentication, Fast, Auto-review, compaction, and image-input paths remain on their existing routes.
+`image-status` never prints the API key and performs only a local, non-generating tool-readiness check. Disabling removes the stored provider credential, the CCDX-owned MCP block, and unmodified CCDX image guidance; user-modified skill files are preserved. Cached tool calls then fail closed. The Node helper creates a new file under the task's `output/imagegen` directory by default and reports its absolute path; it never overwrites an existing file or automatically repeats a failed generation. The image endpoint is contacted only by `enable-image` validation and by explicit `generate_image` tool calls. Ordinary Responses, models, authentication, Fast, Auto-review, compaction, and image-input paths remain on their existing routes.
+
+Generated image downloads must use public HTTPS addresses, do not follow redirects, are DNS-checked against private and reserved addresses, and are capped at 32 MiB. The local MCP route accepts calls only from the same device and permits at most two concurrent image operations. The tool supports new-image generation at `1024x1024`, `1536x1024`, or `1024x1536`.
+
+With `qwen-image-3.0-pro` or `qwen-image-3.0` using either supported protocol, CCDX also exposes `edit_image`. Ask Codex to modify a specific CCDX-generated image; it passes that image's returned `image_id` and the edit instruction to the same configured provider. Each edit returns a new image and ID while preserving the original; omitting `size` retains the source's requested dimensions. The Qwen request contains the source image again on every edit, as required by its [single-turn image editing API](https://help.aliyun.com/zh/model-studio/qwen-image-generation-and-editing-api-reference).
 
-Generated image downloads must use public HTTPS addresses, do not follow redirects, are DNS-checked against private and reserved addresses, and are capped at 32 MiB. The local MCP route accepts calls only from the same device and permits at most two concurrent generations. The tool supports new-image generation at `1024x1024`, `1536x1024`, or `1024x1536`; it does not claim image editing or multi-turn image editing support.
+Editing references are opaque IDs bound to the provider configuration, not paths or URLs. Source images up to 10 MiB are kept in a 64 MiB byte-bounded in-memory LRU. IDs expire on eviction, provider/credential changes, or adapter restart; restarting Codex App alone does not clear them. A missing or expired ID fails before upstream dispatch. This feature does not import arbitrary local images or provide masks, transparent output, or an `/images/edits` endpoint. Other providers retain their existing generation behavior. The helper accepts `--image-id` for the same edit operation; its stdout remains the saved absolute file path and stderr reports the new ID. Normal host approvals still apply, and failed edits are never replaced with an automatic new generation.
 
 ### Update
 

package/bin/cli.mjs

@@ -214,10 +214,7 @@ async function reuseRunningAdapterIfAvailable() {
   if (!running.ok) return false;
 
   console.log(status("ok", `Using existing adapter at ${running.baseUrl}`));
-  ensureCodexConfig(ADAPTER_PORT, {
-    host: ADAPTER_HOST,
-    imageProviderEnabled: Boolean(readImageProviderConfig()),
-  });
+  await configureCodexClient();
 
   await openCodex();
   console.log(`
@@ -230,6 +227,19 @@ async function reuseRunningAdapterIfAvailable() {
   return true;
 }
 
+async function configureCodexClient() {
+  const imageProviderEnabled = Boolean(readImageProviderConfig());
+  ensureCodexConfig(ADAPTER_PORT, { host: ADAPTER_HOST, imageProviderEnabled });
+  if (imageProviderEnabled) {
+    try {
+      const { syncEnabledImageSkill } = await import("../src/cli-image.mjs");
+      syncEnabledImageSkill({ adapterPort: ADAPTER_PORT, adapterHost: ADAPTER_HOST });
+    } catch (error) {
+      console.warn(status("warn", `Image guidance could not be updated: ${error.message}`));
+    }
+  }
+}
+
 if (CLI.command === "doctor") {
   const checks = await runDoctor({
     commandName: CLI_NAME,
@@ -298,10 +308,7 @@ try {
   });
 
   // Point Codex App at the adapter.
-  ensureCodexConfig(ADAPTER_PORT, {
-    host: ADAPTER_HOST,
-    imageProviderEnabled: Boolean(readImageProviderConfig()),
-  });
+  await configureCodexClient();
 
   // Launch Codex when available.
   await openCodex();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "description": "Use Codex App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",

package/src/adapter.mjs

@@ -196,7 +196,7 @@ export function createAdapterHandler(options = {}) {
     if (pathname === "/mcp/image") {
       if (imageMcpHandler) return imageMcpHandler(req, res);
       return import("./image-mcp.mjs").then(({ createImageMcpHandler }) => {
-        imageMcpHandler = createImageMcpHandler();
+        imageMcpHandler ||= createImageMcpHandler();
         return imageMcpHandler(req, res);
       });
     }

package/src/cli-animation.mjs

@@ -6,6 +6,7 @@ import {
   renderTerminalAnimationFrame,
   TERMINAL_ANIMATION_THEMES,
 } from "./terminal-animation.mjs";
+import { startTerminalAnimationGallery } from "./terminal-animation-gallery.mjs";
 import {
   readUserSettings,
   terminalAnimationPreference,
@@ -34,6 +35,7 @@ export async function runAnimationCommand({
   output = process.stdout,
   prompt,
   preview = playTerminalAnimationPreview,
+  gallery = startTerminalAnimationGallery,
 } = {}) {
   if (!prompt && (!input.isTTY || !output.isTTY)) {
     throw new Error(`${commandName} animation requires an interactive terminal`);
@@ -45,24 +47,49 @@ export async function runAnimationCommand({
 
   output.write(`${commandName} animation\n`);
   output.write(`Current: ${TERMINAL_ANIMATION_THEMES[currentIndex].label} (${current.source})\n\n`);
+  const labels = TERMINAL_ANIMATION_THEMES.map((theme, index) => `  ${index + 1}. ${theme.label}${markers(theme, current.theme)}`);
+  const prefixWidth = Math.max(...labels.map((label) => label.length)) + 2;
   TERMINAL_ANIMATION_THEMES.forEach((theme, index) => {
-    const staticPreview = theme.id === DEFAULT_TERMINAL_ANIMATION_THEME
-      ? `  ${renderTerminalAnimationFrame(theme.id, 10)}`
-      : "";
-    output.write(`  ${index + 1}. ${theme.label}${markers(theme, current.theme)}${staticPreview}\n`);
+    output.write(`${labels[index].padEnd(prefixWidth)}${renderTerminalAnimationFrame(theme.id, theme.startFrame)}\n`);
   });
 
   let readline;
+  const abort = new AbortController();
   const ask = prompt || (async (question) => {
-    readline ||= createInterface({ input, output });
-    return readline.question(question);
+    if (!readline) {
+      readline = createInterface({ input, output });
+      readline.once("SIGINT", () => abort.abort());
+      readline.once("close", () => abort.abort());
+    }
+    return readline.question(question, { signal: abort.signal });
   });
 
   let selectedTheme = current.theme;
   let keepCurrent = false;
+  let livePreviewed = false;
+  let rowsBelow = 0;
+  let activeGallery;
+  let layoutChanged = false;
+  const stopForLayoutChange = () => {
+    layoutChanged = true;
+    activeGallery?.stop();
+  };
+  const onKeypress = (_text, key) => {
+    if ((key?.ctrl && key.name === "l") || (readline?.getCursorPos().rows ?? 0) > 0) stopForLayoutChange();
+  };
+  output.on?.("resize", stopForLayoutChange);
+  input.on?.("keypress", onKeypress);
   try {
     while (true) {
-      const answer = String(await ask(`Select [${currentIndex + 1}], or q to cancel: `) || "").trim();
+      activeGallery = layoutChanged ? { enabled: false, stop() {} }
+        : gallery({ output, env, prefixWidth, rowsBelow, getInputRows: () => readline?.getCursorPos().rows ?? 0 });
+      livePreviewed ||= activeGallery.enabled;
+      let answer;
+      try {
+        answer = String(await ask(`Select [${currentIndex + 1}], or q to cancel: `) || "").trim();
+      } finally {
+        activeGallery.stop();
+      }
       if (answer.toLowerCase() === "q") {
         output.write("No changes made.\n");
         return { changed: false, cancelled: true, theme: current.theme };
@@ -79,8 +106,16 @@ export async function runAnimationCommand({
         break;
       }
       output.write(`Enter a number from 1 to ${TERMINAL_ANIMATION_THEMES.length}, or q to cancel.\n`);
+      rowsBelow += 2;
     }
+  } catch (error) {
+    if (!abort.signal.aborted) throw error;
+    output.write("\nNo changes made.\n");
+    return { changed: false, cancelled: true, theme: current.theme };
   } finally {
+    activeGallery?.stop();
+    output.off?.("resize", stopForLayoutChange);
+    input.off?.("keypress", onKeypress);
     readline?.close();
   }
 
@@ -88,7 +123,7 @@ export async function runAnimationCommand({
     ? { changed: false, theme: current.theme }
     : writeTerminalAnimationTheme(selectedTheme, { env, home });
   const disabledValue = disabledEnvironmentValue(env);
-  if (!disabledValue) {
+  if (!disabledValue && !livePreviewed) {
     try {
       await preview(selectedTheme, { output });
     } catch {

package/src/cli-image.mjs

@@ -6,6 +6,8 @@ import { createInterface } from "node:readline/promises";
 import { atomicWriteFilePairSync } from "./atomic-file.mjs";
 import { terminalCell } from "./cli-table.mjs";
 import { computeImageMcpCodexConfig } from "./config.mjs";
+import { probeImageTool } from "./image-readiness.mjs";
+import { updateImageSkill } from "./image-skill.mjs";
 import {
   imageProviderConfigPath,
   inspectImageProvider,
@@ -103,13 +105,19 @@ function enableImageProvider({ providerConfig, providerPath, codexPath, codexCon
     adapterHost,
   });
   const normalized = validateImageProviderConfig(providerConfig, { filePath: providerPath });
-  atomicWriteFilePairSync(
-    codexPath,
-    codex.content,
-    providerPath,
-    `${JSON.stringify(normalized, null, 2)}\n`,
-    { mode: 0o600 },
-  );
+  const skill = updateImageSkill({ enabled: true, codexPath, adapterPort, adapterHost });
+  try {
+    atomicWriteFilePairSync(
+      codexPath,
+      codex.content,
+      providerPath,
+      `${JSON.stringify(normalized, null, 2)}\n`,
+      { mode: 0o600 },
+    );
+  } catch (error) {
+    skill.rollback();
+    throw error;
+  }
   return { codexChanged: codex.changed, config: normalized };
 }
 
@@ -120,12 +128,27 @@ function disableImageProvider({ providerPath, codexPath, codexContent, adapterPo
     adapterHost,
   });
   const providerExists = fs.existsSync(providerPath);
-  if (fs.existsSync(codexPath)) {
-    atomicWriteFilePairSync(codexPath, codex.content, providerPath, null, { mode: 0o600 });
-  } else if (providerExists) {
-    fs.unlinkSync(providerPath);
+  const skill = updateImageSkill({ enabled: false, codexPath, adapterPort, adapterHost });
+  try {
+    if (fs.existsSync(codexPath)) {
+      atomicWriteFilePairSync(codexPath, codex.content, providerPath, null, { mode: 0o600 });
+    } else if (providerExists) {
+      fs.unlinkSync(providerPath);
+    }
+  } catch (error) {
+    skill.rollback();
+    throw error;
   }
-  return { changed: providerExists || codex.changed };
+  return { changed: providerExists || codex.changed || skill.changed, preservedGuidance: Boolean(skill.preserved) };
+}
+
+export function syncEnabledImageSkill({ home = os.homedir(), codexPath = defaultCodexConfigPath(home), ...options } = {}) {
+  return updateImageSkill({ ...options, enabled: true, codexPath });
+}
+
+function printImageReadiness(readiness, output, commandName) {
+  if (readiness.ready) output.write("Local image service: ready (generation tool verified; no image generated).\n");
+  else output.write(`Local image service: unavailable (${readiness.reason}). Start or restart ${commandName} to use images.\n`);
 }
 
 export async function runImageCommand({
@@ -138,6 +161,7 @@ export async function runImageCommand({
   prompt,
   promptSecret,
   fetchImpl = fetch,
+  probeFetchImpl = fetch,
   adapterPort = 2026,
   adapterHost = "127.0.0.1",
   codexPath = defaultCodexConfigPath(home),
@@ -151,14 +175,18 @@ export async function runImageCommand({
     }
     const summary = configSummary(config);
     output.write(`Image generation: enabled\nEndpoint: ${terminalCell(summary.endpoint)}\nModel: ${terminalCell(summary.model)}\nProtocol: ${terminalCell(summary.protocol)}\n`);
-    return { enabled: true, ...summary };
+    const readiness = await probeImageTool(fileContent(codexPath), { fetchImpl: probeFetchImpl });
+    printImageReadiness(readiness, output, commandName);
+    return { enabled: true, ...summary, readiness };
   }
 
   const codexContent = fileContent(codexPath);
   if (action === "disable") {
     const result = disableImageProvider({ providerPath, codexPath, codexContent, adapterPort, adapterHost });
     output.write(`${result.changed ? "Disabled" : "Kept disabled"} image generation.\n`);
-    output.write("Restart Codex App to remove the image tool from active tasks.\n");
+    output.write(result.preservedGuidance
+      ? "Kept user-modified image guidance. Existing image tool calls are now disabled.\n"
+      : "Removed CCDX image guidance. Existing image tool calls are now disabled.\n");
     return { enabled: false, ...result };
   }
   if (action !== "enable") throw new Error(`Unknown image command action: ${action}`);
@@ -194,6 +222,9 @@ export async function runImageCommand({
     adapterHost,
   });
   output.write(`Enabled image generation with ${terminalCell(model)}.\n`);
-  output.write("Restart Codex App to load the image tool. A running ccdx adapter can remain running.\n");
-  return { enabled: true, ...configSummary(result.config), codexChanged: result.codexChanged };
+  const readiness = await probeImageTool(fileContent(codexPath), { fetchImpl: probeFetchImpl });
+  printImageReadiness(readiness, output, commandName);
+  output.write("Installed CCDX image guidance for new and existing tasks. Ask Codex to draw an image.\n");
+  output.write("If the open task has not refreshed its skills, restart Codex App once.\n");
+  return { enabled: true, ...configSummary(result.config), codexChanged: result.codexChanged, readiness };
 }

package/src/cli-options.mjs

@@ -301,10 +301,10 @@ function topicHelp(name, topic) {
     status: `Usage:\n  ${name} status\n\nShows bounded runtime, routing, performance, queue, and cache metrics from a running adapter.`,
     models: `Usage:\n  ${name} models [--format table|plain]\n\nPerforms a fresh, read-only Copilot model-directory lookup for the saved account. Interactive terminals use a table by default.`,
     usage: `Usage:\n  ${name} usage [--format table|plain]\n\nSummarizes local token usage metadata without reading prompt or completion content. Interactive terminals use a table by default.`,
-    animation: `Usage:\n  ${name} animation\n\nInteractively selects the terminal activity animation used the next time the adapter starts.`,
-    "enable-image": `Usage:\n  ${name} enable-image\n\nInteractively configures an HTTPS image API endpoint and API key, detects its supported image model and protocol, and registers the local CCDX image tool for Codex App.`,
-    "disable-image": `Usage:\n  ${name} disable-image\n\nDisables the local CCDX image tool and removes its stored API credential.`,
-    "image-status": `Usage:\n  ${name} image-status\n\nShows whether the optional image provider is configured without exposing its API key.`,
+    animation: `Usage:\n  ${name} animation\n\nPreviews all terminal activity animations together and selects the theme used the next time the adapter starts.`,
+    "enable-image": `Usage:\n  ${name} enable-image\n\nInteractively configures an HTTPS image API endpoint and API key, detects its supported image model and protocol, installs CCDX image guidance, and checks the local image tool for Codex App without generating an image.`,
+    "disable-image": `Usage:\n  ${name} disable-image\n\nDisables the local CCDX image tool and removes its stored API credential and unmodified CCDX image guidance.`,
+    "image-status": `Usage:\n  ${name} image-status\n\nShows provider configuration and probes local image-tool readiness without generating an image or exposing its API key.`,
     "auto-review-model": `Usage:\n  ${name} auto-review-model\n\nInteractively selects an advertised Responses model for Codex Auto-review.`,
     update: `Usage:\n  ${name} update [npm|github]\n\nUpdates the global package from the configured npm registry or GitHub main. With no source, an interactive terminal prompts for one.`,
     version: `Usage:\n  ${name} --version`,

package/src/image-mcp.mjs

@@ -1,11 +1,13 @@
 import { isLoopbackAddress } from "./observability.mjs";
-import { generateImage } from "./image-provider.mjs";
+import { generateImage, supportsImageEditing } from "./image-provider.mjs";
 import { readImageProviderConfig } from "./image-provider-config.mjs";
+import { createImageReferenceStore } from "./image-references.mjs";
 
 const MCP_PROTOCOL_VERSION = "2025-06-18";
 const MCP_PROTOCOL_VERSIONS = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);
 const MCP_MAX_BODY_BYTES = 256 * 1024;
 const IMAGE_TOOL_NAME = "generate_image";
+const EDIT_TOOL_NAME = "edit_image";
 
 function sameHostSocket(socket) {
   const remote = String(socket?.remoteAddress || "").replace(/^::ffff:/, "");
@@ -42,7 +44,7 @@ function imageTool() {
   return {
     name: IMAGE_TOOL_NAME,
     title: "Generate image",
-    description: "Generate a new image from a detailed text prompt. Use this when the user asks to create, draw, render, or generate an image. This tool does not edit an existing image.",
+    description: "Generate a new image with the image provider the user enabled in CCDX. Call directly for text-to-image requests; returns the image inline. Credentials and generation are handled by CCDX, with no Python or OpenAI SDK setup. Does not edit or take reference images.",
     inputSchema: {
       type: "object",
       properties: {
@@ -66,6 +68,25 @@ function imageTool() {
   };
 }
 
+function editTool() {
+  const tool = imageTool();
+  return {
+    ...tool,
+    name: EDIT_TOOL_NAME,
+    title: "Edit image",
+    description: "Edit a previously generated CCDX image using its exact image_id and a change instruction. Preserve the source and return a new image with a new ID for further edits. Source images must still be retained by this running adapter. Does not accept file paths, URLs, masks, or arbitrary uploads.",
+    inputSchema: {
+      ...tool.inputSchema,
+      properties: {
+        image_id: { type: "string", description: "The image_id returned in the result of the specific CCDX image to edit." },
+        prompt: { type: "string", description: "Describe the requested changes and what to preserve from the source image." },
+        size: { type: "string", enum: [...tool.inputSchema.properties.size.enum], description: "Optional output dimensions; defaults to the source image's requested size." },
+      },
+      required: ["image_id", "prompt"],
+    },
+  };
+}
+
 function safeToolError(error, apiKey) {
   if (typeof error?.message === "string" && error.message) {
     let message = error.message.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
@@ -79,6 +100,7 @@ export function createImageMcpHandler({
   configLoader = () => readImageProviderConfig(),
   generateImageFn = generateImage,
   maxConcurrent = 2,
+  imageReferences = createImageReferenceStore(),
 } = {}) {
   let active = 0;
   return async function imageMcpHandler(req, res) {
@@ -109,11 +131,15 @@ export function createImageMcpHandler({
     const reply = (result) => writeJson(res, 200, { jsonrpc: "2.0", id: request.id, result });
     if (request.method === "initialize") {
       const requestedVersion = String(request.params?.protocolVersion || "");
+      const config = configLoader();
+      if (!config) imageReferences.clear();
       reply({
         protocolVersion: MCP_PROTOCOL_VERSIONS.has(requestedVersion) ? requestedVersion : MCP_PROTOCOL_VERSION,
         capabilities: { tools: { listChanged: false } },
         serverInfo: { name: "ccdx-image", version: "1" },
-        instructions: "Use generate_image only when the user asks to create a new image.",
+        instructions: config
+          ? `The user enabled CCDX as their image provider. Call generate_image for new images.${supportsImageEditing(config) ? " For changes to a CCDX image, call edit_image with that image's returned image_id. Keep each returned ID with its image; there is no global last image." : " Editing is not supported by this configured provider."} Display the returned image. CCDX handles credentials and the API; no Python, SDK installation, extra API key or alternate endpoint is needed. Do not automatically retry failed generations or edits.`
+          : "Image generation is disabled. Enable it with ccdx enable-image before requesting images.",
       });
       return;
     }
@@ -123,22 +149,29 @@ export function createImageMcpHandler({
     }
     if (request.method === "tools/list") {
       const config = configLoader();
-      reply({ tools: config ? [imageTool()] : [] });
+      if (!config) imageReferences.clear();
+      reply({ tools: config ? [imageTool(), ...(supportsImageEditing(config) ? [editTool()] : [])] : [] });
       return;
     }
     if (request.method !== "tools/call") {
       writeJson(res, 200, jsonRpcError(request.id, -32601, "Method not found"));
       return;
     }
-    if (request.params?.name !== IMAGE_TOOL_NAME) {
+    if (![IMAGE_TOOL_NAME, EDIT_TOOL_NAME].includes(request.params?.name)) {
       writeJson(res, 200, jsonRpcError(request.id, -32602, "Unknown image tool"));
       return;
     }
     const config = configLoader();
     if (!config) {
+      imageReferences.clear();
       reply({ content: [{ type: "text", text: "Image generation is disabled. Run ccdx enable-image first." }], isError: true });
       return;
     }
+    const editing = request.params.name === EDIT_TOOL_NAME;
+    if (editing && !supportsImageEditing(config)) {
+      reply({ content: [{ type: "text", text: "The configured image provider does not support CCDX editing. No edit was submitted." }], isError: true });
+      return;
+    }
     if (active >= maxConcurrent) {
       reply({ content: [{ type: "text", text: "Image generation is busy. Try again after the current request finishes." }], isError: true });
       return;
@@ -149,11 +182,24 @@ export function createImageMcpHandler({
     req.once?.("aborted", cancel);
     res.once?.("close", cancel);
     try {
-      const image = await generateImageFn(config, request.params?.arguments || {}, { signal: abort.signal });
+      const args = request.params?.arguments || {};
+      // Only an explicit retained handle can add source pixels to a request.
+      const source = editing ? imageReferences.resolve(config, args.image_id) : null;
+      const parameters = { prompt: args.prompt, size: args.size ?? source?.size ?? "1024x1024" };
+      if (source) parameters.image = source.image;
+      const image = await generateImageFn(config, parameters, { signal: abort.signal });
+      let imageId = null;
+      if (supportsImageEditing(config)) {
+        try { imageId = imageReferences.remember(config, { ...image, size: parameters.size }); } catch {}
+      }
+      const note = imageId ? ` Image ID: ${imageId}. Use this ID for further edits while retained by this adapter.`
+        : supportsImageEditing(config) ? " The image is available, but an editing reference could not be retained." : "";
       reply({
+        // Codex prioritizes structuredContent over image blocks. Keep IDs in metadata/text.
+        ...(imageId ? { _meta: { "ccdx/image_id": imageId } } : {}),
         content: [
           { type: "image", data: image.data, mimeType: image.mimeType },
-          { type: "text", text: `Generated ${image.width || ""}${image.width && image.height ? "×" : ""}${image.height || image.size} image with ${image.model}.` },
+          { type: "text", text: `${editing ? "Edited" : "Generated"} ${image.width || ""}${image.width && image.height ? "×" : ""}${image.height || image.size} image with ${image.model}.${note}` },
         ],
       });
     } catch (error) {

package/src/image-provider.mjs

@@ -3,6 +3,7 @@ import https from "node:https";
 import net from "node:net";
 
 export const IMAGE_MAX_BYTES = 32 * 1024 * 1024;
+export const IMAGE_INPUT_MAX_BYTES = 10 * 1024 * 1024;
 export const IMAGE_GENERATION_TIMEOUT_MS = 180_000;
 export const IMAGE_DOWNLOAD_TIMEOUT_MS = 60_000;
 export const IMAGE_SIZES = new Set(["1024x1024", "1536x1024", "1024x1536"]);
@@ -28,15 +29,59 @@ function checkedSize(value) {
   return size;
 }
 
-function generationBody(config, prompt, size) {
+export function supportsImageEditing(config) {
+  return ["qwen-image-3.0-pro", "qwen-image-3.0"].includes(config?.model)
+    && ["qwen-messages", "openai-images"].includes(config?.protocol);
+}
+
+function checkedImage(config, value) {
+  if (value === undefined) return undefined;
+  if (!supportsImageEditing(config)) {
+    throw providerError("Image editing is not supported by the configured provider", "ccdx_image_edit_unsupported");
+  }
+  if (typeof value !== "string") {
+    throw providerError("Source image must be a PNG, JPEG, or WebP base64 data URI", "ccdx_image_input_invalid");
+  }
+  if (value.length > 4 * Math.ceil(IMAGE_INPUT_MAX_BYTES / 3) + 32) {
+    throw providerError("Source image exceeds the 10 MiB size limit", "ccdx_image_input_too_large");
+  }
+  const match = /^data:(image\/(?:png|jpeg|webp));base64,/.exec(value);
+  if (!match) {
+    throw providerError("Source image must be a PNG, JPEG, or WebP base64 data URI", "ccdx_image_input_invalid");
+  }
+  const encoded = value.slice(match[0].length);
+  if (encoded.length > 4 * Math.ceil(IMAGE_INPUT_MAX_BYTES / 3)) {
+    throw providerError("Source image exceeds the 10 MiB size limit", "ccdx_image_input_too_large");
+  }
+  if (!encoded || encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) {
+    throw providerError("Source image contains invalid base64 data", "ccdx_image_input_invalid");
+  }
+  const bytes = Buffer.from(encoded, "base64");
+  if (bytes.length > IMAGE_INPUT_MAX_BYTES) {
+    throw providerError("Source image exceeds the 10 MiB size limit", "ccdx_image_input_too_large");
+  }
+  if (bytes.toString("base64") !== encoded) {
+    throw providerError("Source image contains non-canonical base64 data", "ccdx_image_input_invalid");
+  }
+  let metadata;
+  try { metadata = imageMetadata(bytes); } catch {
+    throw providerError("Source image has an unsupported image format", "ccdx_image_input_invalid");
+  }
+  if (metadata.mimeType !== match[1]) {
+    throw providerError("Source image format does not match its data URI", "ccdx_image_input_invalid");
+  }
+  return value;
+}
+
+function generationBody(config, prompt, size, image) {
   if (config.protocol === "qwen-messages") {
     return {
       model: config.model,
-      input: { messages: [{ role: "user", content: [{ text: prompt }] }] },
+      input: { messages: [{ role: "user", content: [...(image ? [{ image }] : []), { text: prompt }] }] },
       parameters: { n: 1, size: size.replace("x", "*"), watermark: false },
     };
   }
-  return { model: config.model, prompt, n: 1, size };
+  return { model: config.model, prompt, n: 1, size, ...(image ? { image } : {}) };
 }
 
 async function boundedJson(response) {
@@ -210,6 +255,7 @@ export async function downloadPublicImage(urlValue, {
 export async function generateImage(config, {
   prompt,
   size = "1024x1024",
+  image,
 } = {}, {
   fetchImpl = fetch,
   downloadImage = downloadPublicImage,
@@ -218,6 +264,7 @@ export async function generateImage(config, {
 } = {}) {
   const normalizedPrompt = checkedPrompt(prompt);
   const normalizedSize = checkedSize(size);
+  const normalizedImage = checkedImage(config, image);
   const timeout = AbortSignal.timeout(timeoutMs);
   const requestSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
   let response;
@@ -229,7 +276,7 @@ export async function generateImage(config, {
         "Content-Type": "application/json",
         Accept: "application/json",
       },
-      body: JSON.stringify(generationBody(config, normalizedPrompt, normalizedSize)),
+      body: JSON.stringify(generationBody(config, normalizedPrompt, normalizedSize, normalizedImage)),
       signal: requestSignal,
     });
   } catch (error) {

package/src/image-readiness.mjs

@@ -0,0 +1,55 @@
+import os from "node:os";
+import { parse } from "smol-toml";
+import { readBoundedResponseText } from "./http-transport.mjs";
+
+export async function probeImageTool(codexContent, { fetchImpl = fetch, timeoutMs = 1500 } = {}) {
+  let server;
+  let url;
+  try {
+    server = parse(codexContent).mcp_servers?.ccdx_image;
+    if (!server || server.enabled === false) return { ready: false, reason: "not_configured" };
+    url = new URL(server.url);
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    const local = ["localhost", "127.0.0.1", "::1", ...Object.values(os.networkInterfaces())
+      .flat().filter(Boolean).map((entry) => entry.address)];
+    if (url.protocol !== "http:" || !local.includes(host) || url.username || url.password
+      || url.pathname !== "/mcp/image" || url.search || url.hash) {
+      return { ready: false, reason: "invalid_local_endpoint" };
+    }
+  } catch {
+    return { ready: false, reason: "invalid_config" };
+  }
+  const signal = AbortSignal.timeout(timeoutMs);
+  const headers = { "Content-Type": "application/json", Accept: "application/json, text/event-stream" };
+  async function rpc(id, method, params) {
+    const response = await fetchImpl(url.href, {
+      method: "POST", headers, signal, redirect: "error",
+      body: JSON.stringify({ jsonrpc: "2.0", ...(id === undefined ? {} : { id }), method, params }),
+    });
+    if (!response.ok) {
+      await response.body?.cancel?.().catch(() => {});
+      throw new Error(`HTTP ${response.status}`);
+    }
+    if (id === undefined) {
+      await response.body?.cancel?.().catch(() => {});
+      return;
+    }
+    const text = await readBoundedResponseText(response, { maxBytes: 64 * 1024, signal, label: "Image tool catalog" });
+    const message = JSON.parse(text);
+    if (message.jsonrpc !== "2.0" || message.id !== id || message.error) throw new Error("invalid MCP response");
+    return message.result;
+  }
+  try {
+    const initialized = await rpc(1, "initialize", {
+      protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "ccdx-image-status", version: "1" },
+    });
+    if (initialized?.serverInfo?.name !== "ccdx-image") return { ready: false, reason: "unexpected_server" };
+    await rpc(undefined, "notifications/initialized", {});
+    const result = await rpc(2, "tools/list", {});
+    return result?.tools?.some((tool) => tool.name === "generate_image")
+      ? { ready: true }
+      : { ready: false, reason: "tool_unavailable" };
+  } catch (error) {
+    return { ready: false, reason: signal.aborted ? "timeout" : /^HTTP \d+$/.test(error.message) ? error.message : "unreachable" };
+  }
+}

package/src/image-references.mjs

@@ -0,0 +1,41 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createByteLruCache } from "./bounded-result-cache.mjs";
+import { IMAGE_INPUT_MAX_BYTES } from "./image-provider.mjs";
+
+const IMAGE_ID = /^ccdx_img_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function providerScope(config) {
+  return createHash("sha256").update(JSON.stringify([
+    config.endpoint, config.model, config.protocol, config.api_key,
+  ])).digest("hex");
+}
+
+export function createImageReferenceStore({ maxBytes = 64 * 1024 * 1024 } = {}) {
+  const cache = createByteLruCache({ maxBytes });
+  return {
+    remember(config, image) {
+      if (!["image/png", "image/jpeg", "image/webp"].includes(image?.mimeType)
+        || typeof image?.data !== "string" || !image.data
+        || image.data.length > Math.ceil(IMAGE_INPUT_MAX_BYTES / 3) * 4
+        || Buffer.byteLength(image.data, "base64") > IMAGE_INPUT_MAX_BYTES) return null;
+      const imageId = `ccdx_img_${randomUUID()}`;
+      const retained = cache.set(`${providerScope(config)}:${imageId}`, JSON.stringify({
+        image: `data:${image.mimeType};base64,${image.data}`,
+        size: image.size,
+      }));
+      return retained ? imageId : null;
+    },
+    resolve(config, imageId) {
+      if (typeof imageId !== "string" || !IMAGE_ID.test(imageId)) {
+        throw new Error("Provide the exact image_id returned by CCDX for the image to edit.");
+      }
+      const value = cache.get(`${providerScope(config)}:${imageId}`);
+      if (value === undefined) {
+        throw new Error("This image reference is unavailable: the adapter restarted, the image was evicted, or the provider changed. No edit was submitted.");
+      }
+      return JSON.parse(value);
+    },
+    clear() { cache.clear(); },
+    stats() { return cache.stats(); },
+  };
+}

package/src/image-skill.mjs

@@ -0,0 +1,147 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { atomicWriteFilePairSync, atomicWriteFileSync } from "./atomic-file.mjs";
+import { adapterBaseUrl } from "./running-adapter.mjs";
+
+const SKILL_MARKER = /<!-- ccdx:image-skill:([a-f0-9]{64}) -->\n/;
+const HELPER_MARKER = /^\/\/ ccdx:image-helper:([a-f0-9]{64})\n/;
+
+function digest(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function quote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function conflict(message) {
+  return Object.assign(new Error(message), { code: "CCDX_IMAGE_SKILL_CONFLICT" });
+}
+
+function directoryCheck(directory) {
+  try {
+    if (!fs.lstatSync(directory).isDirectory()) throw conflict(`CCDX image skill path is not a regular directory: ${directory}`);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+function ownedSnapshot(filePath, marker, preserveUnowned = false) {
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile()) throw conflict(`Refusing to replace an unowned CCDX image skill path: ${filePath}`);
+    const content = fs.readFileSync(filePath, "utf8");
+    const match = marker.exec(content);
+    if (!match || digest(content.replace(marker, "")) !== match[1]) {
+      throw conflict(`Preserving an existing or modified image skill file: ${filePath}`);
+    }
+    return { content, mode: stat.mode & 0o777 };
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    if (preserveUnowned && error?.code === "CCDX_IMAGE_SKILL_CONFLICT") return { unowned: true };
+    throw error;
+  }
+}
+
+function removeFile(filePath) {
+  try { fs.unlinkSync(filePath); }
+  catch (error) { if (error?.code !== "ENOENT") throw error; }
+}
+
+function removeEmptyDirectories(skillDirectory) {
+  for (const directory of [path.join(skillDirectory, "scripts"), skillDirectory]) {
+    try { fs.rmdirSync(directory); }
+    catch (error) { if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error?.code)) throw error; }
+  }
+}
+
+export function updateImageSkill({
+  enabled,
+  codexPath,
+  adapterPort = 2026,
+  adapterHost = "127.0.0.1",
+  nodePath = process.execPath,
+} = {}) {
+  const skillDirectory = path.join(path.dirname(codexPath), "skills", "ccdx-image");
+  const skillPath = path.join(skillDirectory, "SKILL.md");
+  const helperPath = path.join(skillDirectory, "scripts", "generate.mjs");
+  try {
+    directoryCheck(skillDirectory);
+    directoryCheck(path.dirname(helperPath));
+  } catch (error) {
+    if (!enabled && error?.code === "CCDX_IMAGE_SKILL_CONFLICT") {
+      return { changed: false, preserved: true, skillPath, rollback: () => {} };
+    }
+    throw error;
+  }
+  const previousSkill = ownedSnapshot(skillPath, SKILL_MARKER, !enabled);
+  const previousHelper = ownedSnapshot(helperPath, HELPER_MARKER, !enabled);
+  const touched = [];
+  let rolledBack = false;
+  const rollback = () => {
+    if (rolledBack) return;
+    for (const [filePath, snapshot] of touched) {
+      if (snapshot) atomicWriteFileSync(filePath, snapshot.content, { mode: snapshot.mode, preserveMode: false });
+      else removeFile(filePath);
+    }
+    removeEmptyDirectories(skillDirectory);
+    rolledBack = true;
+  };
+  if (!enabled) {
+    const preserved = Boolean(previousSkill?.unowned || previousHelper?.unowned);
+    if (!previousSkill?.content && !previousHelper?.content) return { changed: false, preserved, skillPath, rollback: () => {} };
+    try {
+      for (const [filePath, snapshot] of [[skillPath, previousSkill], [helperPath, previousHelper]]) {
+        if (!snapshot?.content) continue;
+        touched.push([filePath, snapshot]);
+        removeFile(filePath);
+      }
+      removeEmptyDirectories(skillDirectory);
+    } catch (error) {
+      rollback();
+      throw error;
+    }
+    return { changed: true, preserved, skillPath, rollback };
+  }
+  const host = ["0.0.0.0", "::", "[::]"].includes(adapterHost) ? (adapterHost === "0.0.0.0" ? "127.0.0.1" : "::1") : adapterHost;
+  const endpoint = `${adapterBaseUrl(host, adapterPort)}/mcp/image`;
+  const skillBody = `---
+name: ccdx-image
+description: Generate images from text and edit previously generated CCDX images using the user's configured provider. Use for drawing a new image or modifying a CCDX result identified in the conversation. Excludes arbitrary image uploads, masks, transparent output, and code-native SVG or diagrams.
+---
+
+# CCDX image generation
+
+The user enabled this provider through ccdx enable-image. Use the configured CCDX provider directly for text-to-image requests and supported edits of its previous results.
+
+For a new image, use the ccdx_image server's generate_image tool. Supply a complete prompt and one size: 1024x1024 (square), 1536x1024 (landscape), or 1024x1536 (portrait). Display its returned image and retain the returned image_id in the conversation for later edits. No Python, SDK installation, extra API key, or provider discovery is needed.
+
+For an edit, use edit_image with the image_id of the specific CCDX result the user wants to change and a prompt describing the changes and what to preserve. Omit size to keep the source dimensions unless the user requests another size. Select the ID from this conversation; never assume a global last image or substitute a different result. Each edit returns a new image and image_id and preserves the source. IDs belong to the running CCDX process and can expire after cache eviction or restart. If the source ID is missing or expired, explain that the original image is unavailable for this edit. The provider must support edit_image; an unsupported edit is not permission to generate a replacement.
+
+If the desired tool is not directly callable and the host provides tool search, make one targeted search for ccdx_image generate_image or ccdx_image edit_image as appropriate and use that tool if it becomes callable. If it is still unavailable, run the bundled Node helper once. To generate:
+
+\`\`\`sh
+${quote(nodePath)} ${quote(helperPath)} --prompt 'A complete image prompt' --size 1024x1024
+\`\`\`
+
+To edit, add --image-id with the exact source ID returned earlier and supply the editing prompt. Omit --size to preserve the source dimensions. This sends one edit_image call to the same service.
+
+Quote the actual prompt safely for the shell. The helper uses the same local CCDX service and prints only the saved absolute image path to stdout; stderr reports CCDX image_id for subsequent edits. An optional --out argument selects a new output file; existing files are never overwritten. Inspect and display the saved image with the available image viewer or an absolute-path Markdown image, and retain its new ID.
+
+The helper needs loopback HTTP access. If the task reports restricted network access, use the execution tool's normal permission-request mechanism for this exact command before running it; localhost is also restricted. Keep the host's approval policy unchanged.
+
+Only use the helper when the MCP tool is absent, not after generation or editing fails or times out: the first request may already have consumed a generation or edit. A helper error explicitly saying generation or editing has not started means no image request was submitted; resolve its stated local connection or permission issue before trying again. Otherwise report the failure once without switching providers, installing dependencies, or repeating the image request.
+
+For arbitrary uploaded images, reference-image workflows, masks, transparent output, or explicitly requested other providers, keep the relevant native tools and skills; do not substitute a fresh CCDX generation.
+`;
+  const skillContent = skillBody.replace("# CCDX image generation", `<!-- ccdx:image-skill:${digest(skillBody)} -->\n# CCDX image generation`);
+  const helperBody = `${fs.readFileSync(new URL("./image-tool-client.mjs", import.meta.url), "utf8")}\ntry {\n  await runImageToolClient({ endpoint: ${JSON.stringify(endpoint)} });\n} catch (error) {\n  console.error(String(error?.message || "Image generation failed").replace(/[\\u0000-\\u001f\\u007f-\\u009f]/g, " ").slice(0, 1000));\n  process.exitCode = 1;\n}\n`;
+  const helperContent = `// ccdx:image-helper:${digest(helperBody)}\n${helperBody}`;
+  if (previousSkill?.content === skillContent && previousHelper?.content === helperContent) {
+    return { changed: false, skillPath, rollback: () => {} };
+  }
+  atomicWriteFilePairSync(helperPath, helperContent, skillPath, skillContent, { mode: 0o600 });
+  touched.push([helperPath, previousHelper], [skillPath, previousSkill]);
+  return { changed: true, skillPath, rollback };
+}

package/src/image-tool-client.mjs

@@ -0,0 +1,150 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+const IMAGE_SIZES = new Set(["1024x1024", "1536x1024", "1024x1536"]);
+const IMAGE_EXTENSIONS = new Map([["image/png", ".png"], ["image/jpeg", ".jpg"], ["image/webp", ".webp"]]);
+const MAX_IMAGE_BYTES = 32 * 1024 * 1024;
+const MAX_RESPONSE_BYTES = 48 * 1024 * 1024;
+const IMAGE_ID = /^ccdx_img_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const USAGE = "Usage: generate.mjs --prompt <text> [--image-id <previous-CCDX-image-id>] [--size 1024x1024|1536x1024|1024x1536] [--out <new-file>]";
+
+export function parseImageToolArgs(args = []) {
+  if (args.length === 1 && ["--help", "-h"].includes(args[0])) return { help: true };
+  const values = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const option = args[index];
+    if (!["--prompt", "--image-id", "--size", "--out"].includes(option) || option in values) throw new Error(USAGE);
+    if (typeof args[index + 1] !== "string" || !args[index + 1].trim()) throw new Error(`Missing value for ${option}`);
+    values[option] = args[index + 1];
+  }
+  const prompt = String(values["--prompt"] || "").trim();
+  if (!prompt || prompt.length > 16_000) throw new Error("Image prompt must contain 1 to 16000 characters");
+  const imageId = values["--image-id"]?.trim();
+  if (imageId !== undefined && !IMAGE_ID.test(imageId)) throw new Error("Invalid CCDX image ID");
+  const size = values["--size"] ? values["--size"].trim().toLowerCase() : (imageId ? undefined : "1024x1024");
+  if (size !== undefined && !IMAGE_SIZES.has(size)) throw new Error("Unsupported image size");
+  return { prompt, size, out: values["--out"], imageId };
+}
+
+function localImageEndpoint(value) {
+  const endpoint = new URL(value);
+  const host = endpoint.hostname.replace(/^\[|\]$/g, "");
+  const localAddresses = Object.values(os.networkInterfaces()).flat().filter(Boolean).map(({ address }) => address);
+  const local = host === "localhost" || host === "::1" || /^127\.\d+\.\d+\.\d+$/.test(host) || localAddresses.includes(host);
+  if (!local || endpoint.protocol !== "http:" || endpoint.username || endpoint.password
+    || endpoint.pathname !== "/mcp/image" || endpoint.search || endpoint.hash) {
+    throw new Error("The CCDX image helper requires the configured local /mcp/image endpoint");
+  }
+  return endpoint.href;
+}
+
+function cleanError(value) {
+  return String(value || "Image generation failed").replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, 1000);
+}
+
+async function readRpcResponse(response, expectedId) {
+  if (!response.ok) throw new Error(`CCDX image service returned HTTP ${response.status}`);
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+    await response.body?.cancel();
+    throw new Error("CCDX image response exceeds the size limit");
+  }
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of response.body) {
+    bytes += chunk.byteLength;
+    if (bytes > MAX_RESPONSE_BYTES) throw new Error("CCDX image response exceeds the size limit");
+    chunks.push(Buffer.from(chunk));
+  }
+  let body;
+  try { body = JSON.parse(Buffer.concat(chunks, bytes).toString("utf8")); }
+  catch { throw new Error("CCDX image service returned invalid JSON"); }
+  if (body?.jsonrpc !== "2.0" || body.id !== expectedId) throw new Error("CCDX image service returned an invalid JSON-RPC response");
+  if (body.error) throw new Error(cleanError(body.error.message));
+  if (!body.result || typeof body.result !== "object") throw new Error("CCDX image service returned no result");
+  return body.result;
+}
+
+function assertNewOutput(filePath) {
+  try {
+    fs.lstatSync(filePath);
+    throw new Error(`Image output already exists: ${filePath}`);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+export async function runImageToolClient({
+  endpoint,
+  args = process.argv.slice(2),
+  cwd = process.cwd(),
+  fetchImpl = fetch,
+  output = process.stdout,
+  metadataOutput = process.stderr,
+  signal = AbortSignal.timeout(210_000),
+} = {}) {
+  const options = parseImageToolArgs(args);
+  if (options.help) {
+    output.write(`${USAGE}\n`);
+    return null;
+  }
+  const url = localImageEndpoint(endpoint);
+  const requestedOutput = options.out ? path.resolve(cwd, options.out) : null;
+  if (requestedOutput) assertNewOutput(requestedOutput);
+  const directory = requestedOutput ? path.dirname(requestedOutput) : path.resolve(cwd, "output", "imagegen");
+  fs.mkdirSync(directory, { recursive: true });
+  fs.accessSync(directory, fs.constants.W_OK);
+  const headers = { "Content-Type": "application/json", Accept: "application/json, text/event-stream" };
+  const post = (body) => fetchImpl(url, {
+    method: "POST", headers, body: JSON.stringify(body), redirect: "error", signal,
+  });
+  try {
+    const initialized = await post({
+      jsonrpc: "2.0", id: 1, method: "initialize",
+      params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "ccdx-image-helper", version: "1" } },
+    });
+    const sessionId = initialized.headers.get("mcp-session-id");
+    const server = await readRpcResponse(initialized, 1);
+    if (server.serverInfo?.name !== "ccdx-image") throw new Error("The configured local service is not CCDX image generation");
+    headers["MCP-Protocol-Version"] = server.protocolVersion || "2025-06-18";
+    if (sessionId) headers["Mcp-Session-Id"] = sessionId;
+    const notified = await post({ jsonrpc: "2.0", method: "notifications/initialized" });
+    await notified.body?.cancel();
+    if (!notified.ok) throw new Error(`CCDX image initialization returned HTTP ${notified.status}`);
+  } catch (error) {
+    const code = error.cause?.code || error.code;
+    const detail = ["EPERM", "EACCES"].includes(code)
+      ? "Local network access was denied. Request normal execution permission for this helper command."
+      : cleanError(error.message);
+    throw Object.assign(new Error(`Image ${options.imageId ? "editing" : "generation"} has not started: ${detail}`), { code: "CCDX_IMAGE_NOT_STARTED" });
+  }
+  const argumentsValue = { prompt: options.prompt };
+  if (options.size !== undefined) argumentsValue.size = options.size;
+  if (options.imageId) argumentsValue.image_id = options.imageId;
+  const result = await readRpcResponse(await post({
+    jsonrpc: "2.0", id: 2, method: "tools/call",
+    params: { name: options.imageId ? "edit_image" : "generate_image", arguments: argumentsValue },
+  }), 2);
+  if (result.isError) {
+    throw new Error(cleanError(result.content?.find((part) => part.type === "text")?.text));
+  }
+  const image = result.content?.find((part) => part.type === "image");
+  const extension = IMAGE_EXTENSIONS.get(image?.mimeType);
+  if (!extension || typeof image.data !== "string" || !image.data
+    || image.data.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4
+    || !/^[A-Za-z0-9+/]+={0,2}$/.test(image.data)) {
+    throw new Error("CCDX image service returned an invalid image");
+  }
+  const bytes = Buffer.from(image.data, "base64");
+  if (!bytes.length || bytes.length > MAX_IMAGE_BYTES || bytes.toString("base64") !== image.data) {
+    throw new Error("CCDX image service returned an invalid image");
+  }
+  const filePath = requestedOutput || path.join(directory, `image-${randomUUID()}${extension}`);
+  fs.writeFileSync(filePath, bytes, { flag: "wx", mode: 0o600 });
+  output.write(`${filePath}\n`);
+  const imageId = result._meta?.["ccdx/image_id"];
+  if (typeof imageId === "string" && IMAGE_ID.test(imageId)) metadataOutput.write(`CCDX image_id: ${imageId}\n`);
+  return filePath;
+}

package/src/terminal-animation-gallery.mjs

@@ -0,0 +1,85 @@
+import {
+  TERMINAL_ANIMATION_THEMES,
+  TERMINAL_ANIMATION_TRACK_WIDTH,
+  getTerminalAnimationFrameDelay,
+  renderTerminalAnimationFrame,
+} from "./terminal-animation.mjs";
+
+const ESC = "\u001b";
+const TICK_MS = 32;
+
+export function startTerminalAnimationGallery({
+  output,
+  env = process.env,
+  prefixWidth,
+  rowsBelow = 0,
+  getInputRows = () => 0,
+  timers = { setTimeout, clearTimeout },
+  now = () => performance.now(),
+} = {}) {
+  const columns = Number(output?.columns);
+  const rows = Number(output?.rows);
+  const disabled = /^(0|false|no|off)$/i.test(String(env.CCDX_TERMINAL_ANIMATION || "").trim());
+  const ci = String(env.CI || "").trim();
+  if (output?.isTTY !== true || disabled || (ci && !/^(0|false|no|off)$/i.test(ci))
+    || String(env.TERM || "").toLowerCase() === "dumb" || !Number.isFinite(columns) || !Number.isFinite(rows)
+    || columns <= prefixWidth + TERMINAL_ANIMATION_TRACK_WIDTH + 2
+    || rows < TERMINAL_ANIMATION_THEMES.length + rowsBelow + 2) {
+    return { enabled: false, stop() {} };
+  }
+
+  const timelines = TERMINAL_ANIMATION_THEMES.map((theme) => {
+    let duration = 0;
+    const frames = Array.from({ length: theme.frameCount }, (_, offset) => {
+      const frame = theme.startFrame + offset;
+      duration += getTerminalAnimationFrameDelay(theme.id, frame);
+      return { frame, until: duration };
+    });
+    return { theme, frames, duration: duration + theme.loopPauseMs, lastFrame: theme.startFrame };
+  });
+  const startedAt = now();
+  let timer;
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer !== undefined) timers.clearTimeout(timer);
+    output.off?.("resize", stop);
+    output.off?.("error", stop);
+    output.off?.("close", stop);
+  };
+  const draw = () => {
+    timer = undefined;
+    if (stopped) return;
+    try {
+      const inputRows = getInputRows();
+      // Once input scrolls the menu out of view its old row anchors are no longer safe.
+      if (!Number.isSafeInteger(inputRows) || inputRows < 0
+        || Number(output.rows) < timelines.length + rowsBelow + inputRows + 2) {
+        stop();
+        return;
+      }
+      const elapsed = now() - startedAt;
+      let update = "";
+      timelines.forEach((timeline, index) => {
+        const position = elapsed % timeline.duration;
+        const frame = timeline.frames.find(({ until }) => position < until)?.frame ?? null;
+        if (frame === timeline.lastFrame) return;
+        timeline.lastFrame = frame;
+        const track = frame === null ? `[${" ".repeat(TERMINAL_ANIMATION_TRACK_WIDTH)}]`
+          : renderTerminalAnimationFrame(timeline.theme.id, frame);
+        const up = timelines.length - index + rowsBelow + inputRows;
+        update += `${ESC}7${ESC}[${up}A${ESC}[${prefixWidth + 1}G${track}${ESC}8`;
+      });
+      if (update && output.write(update) === false) { stop(); return; }
+      timer = timers.setTimeout(draw, TICK_MS);
+      timer?.unref?.();
+    } catch { stop(); }
+  };
+  output.on?.("resize", stop);
+  output.on?.("error", stop);
+  output.on?.("close", stop);
+  timer = timers.setTimeout(draw, TICK_MS);
+  timer?.unref?.();
+  return { enabled: true, stop };
+}