codex-copilot-dx 0.8.1 → 0.8.3

package/README.md

@@ -147,9 +147,11 @@ ccdx enable-image
 
 The command accepts an HTTPS base URL or a full `/images/generations` endpoint, then asks for an API key without echoing the key. A bare origin such as `https://api.example` expands to `/v1/images/generations`; `https://api.example/v1` expands to the same endpoint. Custom base paths are retained, and existing full endpoints remain unchanged. CCDX uses GET for the corresponding `/models` catalog and POST for image requests; there is no endpoint-search or automatic fallback. It asks for a numeric model selection only when multiple image models are available, then detects either the standard OpenAI Images request format or the supported `input.messages` format for the selected model only. Its single 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. 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 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. Only after enabling, CCDX installs `ccdx-image` guidance under `~/.codex/skills`, with a self-contained Node helper. The concise `SKILL.md` keeps operation selection, safety, and final-image delivery rules; editing details and helper instructions live in references read only for those operations. 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. Built-in skills and unrelated tools are not modified.
 
-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.
+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 only for an already-enabled provider, without repeating API setup. Without `enable-image`, it installs neither this skill nor the MCP registration. Unchanged guidance is not rewritten. The existing adapter can remain running because provider settings are loaded when the tool is invoked.
+
+Existing compatible `ccdx_image` registrations are reused without requiring CCDX's comment markers or resetting user timeouts/tool policies. Missing or damaged markers alone do not block startup. Core GPT configuration is committed independently before optional image maintenance: image configuration conflicts, image-only write failures, or Skill maintenance failures warn without aborting the core service. No new image guidance is installed after failed image configuration. With images disabled or their provider configuration invalid/unreadable, normal startup performs no image configuration maintenance, Skill installation, or image-network probe; explicit `disable-image` owns cleanup. Automatic updates/removal are limited to recognizable CCDX defaults and isolated TOML declarations, never everything between two comments. Ambiguous shared-inline or customized registrations are left intact; `disable-image` still disables the CCDX provider and removes its owned guidance. Invalid TOML/UTF-8 in the shared Codex config or a failed essential core configuration write remains an explicit error rather than a silent success.
 
 Direct MCP generations and edits retain their original inline image content and editing ID, and also save the exact image bytes privately under `~/.local/share/codex-copilot-dx/images`. The result includes ready-to-use image Markdown for Codex's final chat reply, so the image appears as a clickable thumbnail instead of only inside a tool result. Files use unique names and are not overwritten or removed on adapter restart. Asking to show the same image again reuses its existing Markdown, not a new generation or edit. If saving fails, CCDX still returns the generated image content, reports the delivery failure, and does not retry the provider or invent a file path. The bundled helper continues saving once at its existing output location, without a second adapter-side copy. Existing enabled users receive updated, unmodified CCDX-owned guidance on the next CCDX startup; no new setup command is needed.
 
@@ -160,7 +162,7 @@ ccdx image-status
 ccdx disable-image
 ```
 
-`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.
+`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 skill, reference, and helper files; user-modified 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` or `edit_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. DNS resolution and downloading share one deadline and respond to cancellation; a late DNS result cannot start a cancelled download. The local MCP route accepts calls only from the same device and permits at most two concurrent image operations. It requires `application/json` and rejects browser `Origin` headers; native Codex and Node clients do not send an Origin. The tool supports new-image generation at `1024x1024`, `1536x1024`, or `1024x1536`.
 

package/bin/cli.mjs

@@ -229,8 +229,8 @@ async function reuseRunningAdapterIfAvailable() {
 
 async function configureCodexClient() {
   const imageProviderEnabled = Boolean(readImageProviderConfig());
-  ensureCodexConfig(ADAPTER_PORT, { host: ADAPTER_HOST, imageProviderEnabled });
-  if (imageProviderEnabled) {
+  const { imageMcpSkipped } = ensureCodexConfig(ADAPTER_PORT, { host: ADAPTER_HOST, imageProviderEnabled });
+  if (imageProviderEnabled && !imageMcpSkipped) {
     try {
       const { syncEnabledImageSkill } = await import("../src/cli-image.mjs");
       syncEnabledImageSkill({ adapterPort: ADAPTER_PORT, adapterHost: ADAPTER_HOST });

package/package.json

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

package/src/config.mjs

@@ -4,6 +4,7 @@ import os from "node:os";
 import { status } from "./status.mjs";
 import { atomicWriteFileIfChangedSync } from "./atomic-file.mjs";
 import { adapterBaseUrl } from "./running-adapter.mjs";
+import { isLoopbackHost } from "./security.mjs";
 import { codexTomlStatements, configValue, parseCodexToml, validateManagedConfigEdit } from "./config-toml.mjs";
 
 const CONFIG_PATH = path.join(os.homedir(), ".codex", "config.toml");
@@ -12,6 +13,10 @@ const MODEL_AUTO_COMPACT_TOKEN_LIMIT = 900_000;
 const IMAGE_MCP_START = "# ccdx:image-mcp:start";
 const IMAGE_MCP_END = "# ccdx:image-mcp:end";
 const IMAGE_MCP_SECTION = "mcp_servers.ccdx_image";
+const IMAGE_MCP_KEYS = ["enabled", "tool_timeout_sec", "url"];
+
+// Only optional image-configuration conflicts may degrade to core-only startup.
+export class ImageMcpConfigError extends Error {}
 const STARTUP_MANAGED_PATHS = [
   "openai_base_url",
   "model_context_window",
@@ -92,41 +97,98 @@ function imageMcpHost(adapterHost) {
   return host;
 }
 
-function removeManagedImageMcp(lines) {
-  const comments = codexTomlStatements(lines.join("\n")).filter((item) => item.kind === "comment");
-  const starts = comments.filter((item) => lines[item.line] === IMAGE_MCP_START).map((item) => item.line);
-  const ends = comments.filter((item) => lines[item.line] === IMAGE_MCP_END).map((item) => item.line);
-  let start = starts[0] ?? -1;
-  const end = ends[0] ?? -1;
-  if (start === -1 && end === -1) return false;
-  if (starts.length !== 1 || ends.length !== 1 || end < start) {
-    throw new Error("Invalid managed CCDX image MCP block in Codex config");
-  }
-  lines.splice(start, end - start + 1);
-  while (start > 0 && start >= lines.length && lines[start - 1].trim() === "") {
-    lines.splice(start - 1, 1);
-    start -= 1;
-  }
-  while (start < lines.length && lines[start].trim() === "" && start > 0 && lines[start - 1].trim() === "") {
-    lines.splice(start, 1);
-  }
-  return true;
+function imageMcpUrl(value) {
+  if (typeof value !== "string" || /[\s\x00-\x1f\x7f]/.test(value)) return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" && url.pathname === "/mcp/image"
+      && !url.username && !url.password && !url.search && !url.hash ? url : null;
+  } catch { return null; }
+}
+
+function isImageDeclaration(item) {
+  return ["table", "value"].includes(item.kind)
+    && sameKeys(item.keys.slice(0, IMAGE_MANAGED_PATH.length), IMAGE_MANAGED_PATH);
+}
+
+function imageMcpMarkers(content, statements) {
+  return statements.filter((item) => item.kind === "comment"
+    && [IMAGE_MCP_START, IMAGE_MCP_END].includes(item.source.trim())
+    && !content.slice(content.lastIndexOf("\n", item.start - 1) + 1, item.start).trim());
 }
 
-function hasUnmanagedImageMcp(lines) {
-  return configValue(parseCodexToml(lines.join("\n")), IMAGE_MANAGED_PATH) !== undefined;
+function knownImageMcp(section, expectedUrl, previousBaseUrl, statements, markers) {
+  if (!section || Object.keys(section).sort().join(",") !== IMAGE_MCP_KEYS.join(",")
+    || section.enabled !== true || section.tool_timeout_sec !== 210n) return false;
+  const url = imageMcpUrl(section.url);
+  if (!url) return false;
+  if (url.href === new URL(expectedUrl).href) return true;
+  // The core and image URLs were configured together. This survives comment
+  // stripping and allows an adapter address change without guessing a new owner.
+  try {
+    const previous = new URL(previousBaseUrl);
+    if (previous.protocol === "http:" && previous.pathname === "/v1"
+      && !previous.username && !previous.password && !previous.search && !previous.hash
+      && previous.origin === url.origin
+      && (isLoopbackHost(url.hostname) || url.hostname === new URL(expectedUrl).hostname)) return true;
+  } catch {}
+  // Legacy markers are an additional ownership hint, never deletion boundaries.
+  const starts = markers.filter((item) => item.source.trim() === IMAGE_MCP_START);
+  const ends = markers.filter((item) => item.source.trim() === IMAGE_MCP_END);
+  if (starts.length !== 1 || ends.length !== 1 || starts[0].start >= ends[0].start
+    || !(isLoopbackHost(url.hostname) || url.hostname === new URL(expectedUrl).hostname)) return false;
+  const declarations = statements.filter((item) => ["table", "value"].includes(item.kind));
+  return declarations.some(isImageDeclaration)
+    && declarations.filter(isImageDeclaration).every((item) => item.start > starts[0].start && item.end < ends[0].start)
+    && declarations.filter((item) => item.start > starts[0].start && item.start < ends[0].start).every(isImageDeclaration);
 }
 
-function ensureImageMcp(lines, enabled, adapterPort, adapterHost) {
+function removeImageMcpDeclarations(content, statements, markers) {
+  const declarations = statements.filter(isImageDeclaration);
+  // A shared inline parent is not a surgical edit target. Reuse it unchanged or
+  // leave it for the user; never serialize away sibling settings or credentials.
+  if (!declarations.length) return null;
+  const ranges = [...declarations, ...markers].map((item) => {
+    const start = content.lastIndexOf("\n", item.start - 1) + 1;
+    const newline = content.indexOf("\n", item.end);
+    return [start, newline < 0 ? content.length : newline + 1];
+  }).sort((left, right) => right[0] - left[0]);
+  for (const [start, end] of ranges) content = content.slice(0, start) + content.slice(end);
+  return content;
+}
+
+function ensureImageMcp(lines, enabled, adapterPort, adapterHost, previousBaseUrl) {
   const previous = lines.join("\n");
-  removeManagedImageMcp(lines);
+  const config = parseCodexToml(previous);
+  const section = configValue(config, IMAGE_MANAGED_PATH);
+  const url = `${adapterBaseUrl(imageMcpHost(adapterHost), adapterPort)}/mcp/image`;
+  if (section !== undefined) {
+    // Reuse compatible registrations without rewriting comments, formatting,
+    // user tool policies, or timeouts. An explicit disabled flag is preserved.
+    if (enabled && imageMcpUrl(section?.url)?.href === new URL(url).href
+      && [undefined, true].includes(section?.enabled)) return false;
+    const statements = codexTomlStatements(previous);
+    const markers = imageMcpMarkers(previous, statements);
+    if (!knownImageMcp(section, url, previousBaseUrl, statements, markers)) {
+      if (!enabled) return false;
+      throw new ImageMcpConfigError(`Codex config already defines [${IMAGE_MCP_SECTION}] outside the CCDX-managed block; its settings were preserved`);
+    }
+    const removed = removeImageMcpDeclarations(previous, statements, markers);
+    if (removed === null) {
+      if (!enabled) return false;
+      throw new ImageMcpConfigError(`Cannot safely update [${IMAGE_MCP_SECTION}] inside a shared inline table; its settings were preserved`);
+    }
+    lines.splice(0, lines.length, ...removed.split("\n"));
+    while (lines.length && !lines.at(-1).trim()) lines.pop();
+  }
   if (enabled) {
-    if (hasUnmanagedImageMcp(lines)) {
-      throw new Error(`Codex config already defines [${IMAGE_MCP_SECTION}] outside the CCDX-managed block`);
+    const parent = config.mcp_servers;
+    if (parent !== undefined && (typeof parent !== "object" || parent === null || Array.isArray(parent)
+      || codexTomlStatements(previous).some((item) => item.kind === "value" && sameKeys(item.keys, ["mcp_servers"])))) {
+      throw new ImageMcpConfigError("Cannot append the image MCP to an inline or non-table mcp_servers setting; its settings were preserved");
     }
     while (lines.length && lines.at(-1).trim() === "") lines.pop();
     if (lines.length) lines.push("");
-    const url = `${adapterBaseUrl(imageMcpHost(adapterHost), adapterPort)}/mcp/image`;
     lines.push(
       IMAGE_MCP_START,
       `[${IMAGE_MCP_SECTION}]`,
@@ -149,7 +211,6 @@ export function computeUpdatedCodexConfig(
   const baseUrl = `${adapterBaseUrl(adapterHost, adapterPort)}/v1`;
   const hadTrailingNewline = content.endsWith("\n");
   const lines = content.split("\n");
-  if (hadTrailingNewline) lines.pop();
 
   let changed = false;
   const openaiLine = `openai_base_url = "${baseUrl}"`;
@@ -166,10 +227,11 @@ export function computeUpdatedCodexConfig(
   changed = setTomlKey(lines, "shell_environment_policy.set", "OPENAI_API_KEY", "dummy") || changed;
   changed = ensureContextManagementDefault(lines) || changed;
   if (typeof imageProviderEnabled === "boolean") {
-    changed = ensureImageMcp(lines, imageProviderEnabled, adapterPort, adapterHost) || changed;
+    changed = ensureImageMcp(lines, imageProviderEnabled, adapterPort, adapterHost, config.openai_base_url) || changed;
   }
 
-  const updated = lines.join("\n") + (hadTrailingNewline ? "\n" : "");
+  const joined = lines.join("\n");
+  const updated = joined + (hadTrailingNewline && !joined.endsWith("\n") ? "\n" : "");
   validateManagedConfigEdit(config, updated, typeof imageProviderEnabled === "boolean"
     ? [...STARTUP_MANAGED_PATHS, IMAGE_MANAGED_PATH] : STARTUP_MANAGED_PATHS);
   return { content: updated, changed };
@@ -196,20 +258,26 @@ context_management = true
     : base;
 }
 
-export function computeImageMcpCodexConfig(
+function computeImageConfig(
   content,
   { enabled, adapterPort = 2026, adapterHost = "127.0.0.1" } = {},
+  previousBaseUrl,
 ) {
   const config = parseCodexToml(content);
   const hadTrailingNewline = content.endsWith("\n");
   const lines = content.split("\n");
-  if (hadTrailingNewline) lines.pop();
-  const changed = ensureImageMcp(lines, Boolean(enabled), adapterPort, adapterHost);
-  const updated = lines.join("\n") + (hadTrailingNewline || lines.length ? "\n" : "");
+  const changed = ensureImageMcp(lines, Boolean(enabled), adapterPort, adapterHost, previousBaseUrl ?? config.openai_base_url);
+  if (!changed) return { content, changed: false };
+  const joined = lines.join("\n");
+  const updated = joined + ((hadTrailingNewline || lines.length) && !joined.endsWith("\n") ? "\n" : "");
   validateManagedConfigEdit(config, updated, [IMAGE_MANAGED_PATH]);
   return { content: updated, changed };
 }
 
+export function computeImageMcpCodexConfig(content, options = {}) {
+  return computeImageConfig(content, options);
+}
+
 export function ensureCodexConfig(adapterPort = 2026, {
   filePath = CONFIG_PATH,
   host = "127.0.0.1",
@@ -217,26 +285,41 @@ export function ensureCodexConfig(adapterPort = 2026, {
 } = {}) {
   const baseUrl = `${adapterBaseUrl(host, adapterPort)}/v1`;
 
-  if (!fs.existsSync(filePath)) {
-    // Codex config does not exist yet; create the local proxy defaults.
-    atomicWriteFileIfChangedSync(filePath, initialCodexConfig(adapterPort, host, { imageProviderEnabled }));
-    console.log(status("ok", "Created ~/.codex/config.toml"));
-    return;
-  }
-
   let content;
   try {
     content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(filePath));
   } catch (error) {
-    if (error?.code !== "ERR_ENCODING_INVALID_ENCODED_DATA") throw error;
-    throw new Error("Codex configuration is not valid UTF-8 TOML; no configuration changes were written");
+    if (error?.code === "ERR_ENCODING_INVALID_ENCODED_DATA") {
+      throw new Error("Codex configuration is not valid UTF-8 TOML; no configuration changes were written");
+    }
+    if (error?.code !== "ENOENT") throw error;
   }
-  const updated = computeUpdatedCodexConfig(content, adapterPort, host, { imageProviderEnabled });
-
-  if (!updated.changed) {
+  // Commit essential configuration independently. Image-only parse/edit/write
+  // failures must not roll it back or close an otherwise usable GPT adapter.
+  const core = content === undefined
+    ? { content: initialCodexConfig(adapterPort, host), changed: true }
+    : computeUpdatedCodexConfig(content, adapterPort, host);
+  if (!core.changed) {
     console.log(status("ok", `Codex already points to ${baseUrl}`));
-    return;
+  } else {
+    atomicWriteFileIfChangedSync(filePath, core.content);
+    console.log(status("ok", content === undefined ? "Created ~/.codex/config.toml" : `Configured Codex base URL: ${baseUrl}`));
+  }
+  // Disabled means no image maintenance, including no implicit removal of old
+  // or user-owned entries. Explicit disable-image owns the cleanup operation.
+  if (!imageProviderEnabled) return { imageMcpSkipped: false };
+  try {
+    const previousBaseUrl = content === undefined ? undefined : parseCodexToml(content).openai_base_url;
+    const image = computeImageConfig(core.content, { enabled: true, adapterPort, adapterHost: host }, previousBaseUrl);
+    if (image.changed) {
+      if (fs.readFileSync(filePath, "utf8") !== core.content) {
+        throw new ImageMcpConfigError("Codex config changed during image setup; the newer configuration was preserved");
+      }
+      atomicWriteFileIfChangedSync(filePath, image.content);
+    }
+    return { imageMcpSkipped: false };
+  } catch (error) {
+    console.warn(status("warn", `Image MCP setup was skipped: ${error.message}. Core proxy startup will continue.`));
+    return { imageMcpSkipped: true };
   }
-  atomicWriteFileIfChangedSync(filePath, updated.content);
-  console.log(status("ok", `Configured Codex base URL: ${baseUrl}`));
 }

package/src/image-mcp.mjs

@@ -78,7 +78,7 @@ function imageTool() {
   return {
     name: IMAGE_TOOL_NAME,
     title: "Generate image",
-    description: "Generate a new image with the image provider the user enabled in CCDX. Returns image content and saved-image Markdown: include that Markdown in the final chat reply to show a thumbnail. Credentials and generation are handled by CCDX, with no Python or OpenAI SDK setup. Does not edit or take reference images. Do not call just to redisplay an existing result.",
+    description: "Generate a raster image with the user's enabled CCDX provider. Input: text prompt and optional size; no source images. Returns image content, saved-image Markdown for the final chat reply, and an edit ID when supported. For changes to an earlier CCDX image use edit_image; for redisplay reuse its Markdown without a tool call.",
     inputSchema: {
       type: "object",
       properties: {
@@ -108,7 +108,7 @@ function editTool() {
     ...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; include its returned saved-image Markdown in the final chat reply. Source images must still be retained by this running adapter. Does not accept file paths, URLs, masks, or arbitrary uploads. Do not call just to redisplay an existing result.",
+    description: "Edit a retained CCDX image using its exact image_id and a change prompt. Preserves the source and returns a new image, saved-image Markdown for the final chat reply, and a new edit ID when retained. Omit size to preserve source dimensions. Does not accept paths, URLs, masks, or arbitrary uploads. Redisplay requires no tool call.",
     inputSchema: {
       ...tool.inputSchema,
       properties: {
@@ -184,7 +184,7 @@ export function createImageMcpHandler({
         capabilities: { tools: { listChanged: false } },
         serverInfo: { name: "ccdx-image", version: "1" },
         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."} Include the returned saved-image Markdown in the final chat reply to display a thumbnail; tool image content alone does not ensure chat delivery. To show an existing image again, reuse its Markdown without calling generation or editing. 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.`
+          ? `CCDX handles the configured image API and credentials; no Python or SDK setup. Embed returned image Markdown in the final reply. Redisplay reuses it without tool calls. Keep each image_id with its own image. Do not automatically retry failed/timed-out requests or switch providers.${supportsImageEditing(config) ? " Use generate_image for new images; edit_image requires the exact retained source ID." : " Use generate_image for new images. Editing is unsupported; do not substitute generation."}`
           : "Image generation is disabled. Enable it with ccdx enable-image before requesting images.",
       });
       return;

package/src/image-skill/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: ccdx-image
+description: Generate raster images with the user's enabled CCDX provider, edit earlier CCDX results, or redisplay their saved images. Not for arbitrary uploaded-image edits, masks, transparent output, or code-native SVG/HTML assets.
+---
+
+# CCDX image generation
+
+Use the user's enabled CCDX provider for supported image requests. Respect an explicitly requested different provider. CCDX supplies credentials and execution; no additional API key, Python, or SDK setup is needed.
+
+## Select the operation
+
+- **Generate:** Call `ccdx_image.generate_image` with a complete prompt. Supported sizes are `1024x1024`, `1536x1024`, and `1024x1536`; the default is square.
+- **Edit:** Read [editing.md](references/editing.md) before calling `ccdx_image.edit_image`. Use the exact source `image_id` from this conversation; never substitute a different image or a fresh generation.
+- **Redisplay:** Reuse the requested image's existing Markdown. Do not call generation or editing tools.
+
+Use the MCP tool directly when callable. Otherwise, if tool search is available, make one targeted search for the relevant `ccdx_image` tool. Only if the MCP tool remains unavailable, read [helper.md](references/helper.md) for the bundled fallback. An explicitly unsupported edit or a failed tool call is not a reason to use the fallback.
+
+## Deliver the result
+
+Embed the returned saved-image Markdown unchanged in the final chat reply to display a clickable thumbnail. Image content in a tool result or a viewer call alone is not final delivery. Do not use a code block or replace the image with a download-only link.
+
+Retain the image's Markdown/path together with its returned `image_id`, when present. Reuse that artifact for later redisplay. If saving failed, distinguish generation success from delivery failure: do not invent a path, claim display succeeded, or generate/edit again to repair delivery.
+
+## Execution boundaries
+
+- Do not automatically retry a failed or timed-out image request, switch providers, or run the helper afterward; the request may already have been processed.
+- Preserve the host's approval policy. A user request to generate an image does not bypass execution permissions.
+- Arbitrary uploaded-image edits, masks, reference-image inputs, and transparent output are outside this integration. Explain the limitation without substituting a different operation. Use another available workflow only when consistent with the user's request.

package/src/image-skill/references/editing.md

@@ -0,0 +1,15 @@
+# Edit a CCDX result
+
+## Select the source
+
+Use the specific image's returned `image_id` from this conversation, not a global last image. Resolve an ambiguous source before submitting the edit.
+
+A file path is not an edit ID. Handles can expire after cache eviction, provider changes, or adapter restart while saved files remain viewable. For missing or expired handles, explain that this source is unavailable for editing; do not replace it.
+
+## Submit and deliver
+
+Call `ccdx_image.edit_image` with the exact ID and a prompt specifying changes and what to preserve. Omit `size` to preserve source dimensions unless another supported size was requested.
+
+An explicitly unsupported edit must stop. Only an unavailable MCP tool may use [helper.md](helper.md), not a failed or timed-out edit.
+
+Each edit preserves the source. Keep the new image/ID mapping alongside the original, and apply `SKILL.md`'s final-image delivery rules.

package/src/image-skill/references/helper.md

@@ -0,0 +1,27 @@
+# MCP-unavailable fallback
+
+Use only when MCP is unavailable, never after a failed, timed-out, or unsupported image operation. The helper calls the same local CCDX service at most once per execution.
+
+## Invoke
+
+Generate:
+
+```sh
+{{NODE}} {{HELPER}} --prompt 'A complete image prompt' --size 1024x1024
+```
+
+Edit an identified CCDX result:
+
+```sh
+{{NODE}} {{HELPER}} --image-id 'EXACT_SOURCE_IMAGE_ID' --prompt 'Requested changes and what to preserve'
+```
+
+For edits, follow [editing.md](editing.md); omitting `--size` preserves source dimensions. Replace the examples and quote actual arguments safely. Optional `--out` selects a new file; existing files are never overwritten.
+
+Loopback HTTP can be restricted. If networking is restricted, request normal execution permission for this exact command before running it. Keep the host's approval policy unchanged.
+
+## Interpret the result
+
+- **Success:** stdout is the saved absolute path; stderr includes `CCDX image_id` when retained. Embed an absolute-path Markdown image in the final reply and retain its ID.
+- **Explicitly not started:** No image operation was submitted. Resolve the reported connection/permission issue before another attempt.
+- **Other failure or timeout:** Dispatch may have completed. Report without retrying, switching providers, or installing dependencies. Saving/display failure must not trigger regeneration.

package/src/image-skill.mjs

@@ -6,6 +6,8 @@ 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/;
+const REFERENCE_MARKER = /^<!-- ccdx:image-reference:([a-f0-9]{64}) -->\n/;
+const REFERENCE_FILES = ["editing.md", "helper.md"];
 
 function digest(content) {
   return createHash("sha256").update(content).digest("hex");
@@ -50,7 +52,7 @@ function removeFile(filePath) {
 }
 
 function removeEmptyDirectories(skillDirectory) {
-  for (const directory of [path.join(skillDirectory, "scripts"), skillDirectory]) {
+  for (const directory of [path.join(skillDirectory, "scripts"), path.join(skillDirectory, "references"), skillDirectory]) {
     try { fs.rmdirSync(directory); }
     catch (error) { if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error?.code)) throw error; }
   }
@@ -66,9 +68,11 @@ export function updateImageSkill({
   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");
+  const references = REFERENCE_FILES.map((name) => ({ name, filePath: path.join(skillDirectory, "references", name) }));
   try {
     directoryCheck(skillDirectory);
     directoryCheck(path.dirname(helperPath));
+    directoryCheck(path.join(skillDirectory, "references"));
   } catch (error) {
     if (!enabled && error?.code === "CCDX_IMAGE_SKILL_CONFLICT") {
       return { changed: false, preserved: true, skillPath, rollback: () => {} };
@@ -77,6 +81,8 @@ export function updateImageSkill({
   }
   const previousSkill = ownedSnapshot(skillPath, SKILL_MARKER, !enabled);
   const previousHelper = ownedSnapshot(helperPath, HELPER_MARKER, !enabled);
+  for (const reference of references) reference.previous = ownedSnapshot(reference.filePath, REFERENCE_MARKER, !enabled);
+  const snapshots = [[skillPath, previousSkill], [helperPath, previousHelper], ...references.map(({ filePath, previous }) => [filePath, previous])];
   const touched = [];
   let rolledBack = false;
   const rollback = () => {
@@ -89,10 +95,10 @@ export function updateImageSkill({
     rolledBack = true;
   };
   if (!enabled) {
-    const preserved = Boolean(previousSkill?.unowned || previousHelper?.unowned);
-    if (!previousSkill?.content && !previousHelper?.content) return { changed: false, preserved, skillPath, rollback: () => {} };
+    const preserved = snapshots.some(([, snapshot]) => snapshot?.unowned);
+    if (!snapshots.some(([, snapshot]) => snapshot?.content)) return { changed: false, preserved, skillPath, rollback: () => {} };
     try {
-      for (const [filePath, snapshot] of [[skillPath, previousSkill], [helperPath, previousHelper]]) {
+      for (const [filePath, snapshot] of snapshots) {
         if (!snapshot?.content) continue;
         touched.push([filePath, snapshot]);
         removeFile(filePath);
@@ -106,44 +112,31 @@ export function updateImageSkill({
   }
   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.
-
-The tool returns ready-to-use saved-image Markdown in its text result. Include that exact Markdown in your final chat reply so the user sees a clickable thumbnail, alongside any image content you forward. Tool output or saying "generated" is not delivery. Do not put the image Markdown inside a code block or replace it with a download-only link. Keep its image path and image_id together. If the user asks "where is the image", "show it again", or "图呢", embed the same returned Markdown again; do not generate or edit another image just to display it. If the tool reports that saving failed, do not invent a path or claim the image was displayed, and do not submit another image request to fix delivery.
-
-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. Include an absolute-path Markdown image for that saved file in the final chat reply, and retain its new ID. A viewer call alone does not replace the final thumbnail.
-
-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 skillBody = fs.readFileSync(new URL("./image-skill/SKILL.md", import.meta.url), "utf8");
+  for (const reference of references) {
+    const body = fs.readFileSync(new URL(`./image-skill/references/${reference.name}`, import.meta.url), "utf8")
+      .replaceAll("{{NODE}}", () => quote(nodePath)).replaceAll("{{HELPER}}", () => quote(helperPath));
+    reference.content = `<!-- ccdx:image-reference:${digest(body)} -->\n${body}`;
+  }
   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) {
+  if (previousSkill?.content === skillContent && previousHelper?.content === helperContent
+    && references.every(({ previous, content }) => previous?.content === content)) {
     return { changed: false, skillPath, rollback: () => {} };
   }
-  atomicWriteFilePairSync(helperPath, helperContent, skillPath, skillContent, { mode: 0o600 });
-  touched.push([helperPath, previousHelper], [skillPath, previousSkill]);
+  try {
+    // Install conditional resources before publishing the skill entrypoint.
+    for (const { filePath, previous, content } of references) {
+      if (previous?.content === content) continue;
+      touched.push([filePath, previous]);
+      atomicWriteFileSync(filePath, content, { mode: 0o600, preserveMode: false });
+    }
+    atomicWriteFilePairSync(helperPath, helperContent, skillPath, skillContent, { mode: 0o600 });
+    touched.push([helperPath, previousHelper], [skillPath, previousSkill]);
+  } catch (error) {
+    rollback();
+    throw error;
+  }
   return { changed: true, skillPath, rollback };
 }