codex-copilot-dx 0.7.9 → 0.8.0

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:/, "");
@@ -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) {
@@ -91,6 +113,17 @@ export function createImageMcpHandler({
       writeJson(res, 405, jsonRpcError(null, -32600, "Only POST is supported"));
       return;
     }
+    // This endpoint serves native Codex/Node clients, not browser pages. A
+    // loopback socket alone does not make a browser-supplied Origin trusted.
+    if (Object.hasOwn(req.headers || {}, "origin")) {
+      writeJson(res, 403, jsonRpcError(null, -32001, "Browser origins are not allowed for Image MCP"));
+      return;
+    }
+    const mediaType = String(req.headers?.["content-type"] || "").split(";", 1)[0].trim().toLowerCase();
+    if (mediaType !== "application/json") {
+      writeJson(res, 415, jsonRpcError(null, -32600, "Image MCP requires application/json"));
+      return;
+    }
 
     let request;
     try { request = await readBody(req); }
@@ -109,12 +142,14 @@ 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: configLoader()
-          ? "The user enabled CCDX as their image provider. For new text-to-image requests, call generate_image directly and display the returned image. CCDX handles credentials and the API; no Python, SDK installation, OPENAI_API_KEY, or alternate endpoint is needed. Follow the user's image request; do not retry a failed generation automatically. Editing and reference-image requests require a different capable tool."
+        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;
@@ -125,22 +160,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;
@@ -151,11 +193,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-config.mjs

@@ -170,6 +170,7 @@ export async function inspectImageProvider({
   apiKey,
   fetchImpl = fetch,
   timeoutMs = IMAGE_PROVIDER_TIMEOUT_MS,
+  selectModel,
 } = {}) {
   const normalizedEndpoint = normalizeImageEndpoint(endpoint);
   const normalizedKey = checkedApiKey(apiKey);
@@ -178,11 +179,13 @@ export async function inspectImageProvider({
   if (!models.response.ok) throw new Error(`Image API model lookup failed with HTTP ${models.response.status}`);
   const modelIds = imageModelIds(models.body);
   if (!modelIds.length) throw new Error("Image API model lookup returned no image models");
+  const model = selectModel ? await selectModel([...modelIds]) : modelIds[0];
+  if (!modelIds.includes(model)) throw new Error("Selected image model is not in the provider catalog");
 
   const probe = await fetchJson(normalizedEndpoint, {
     method: "POST",
     headers: { ...headers, "Content-Type": "application/json" },
-    body: JSON.stringify({ model: modelIds[0] }),
+    body: JSON.stringify({ model }),
   }, { fetchImpl, timeoutMs });
   const protocol = detectProtocol(probe.response.status, probe.body);
   if (!protocol) throw new Error("Image API protocol is unsupported or could not be detected safely");

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) {
@@ -152,64 +197,73 @@ export async function downloadPublicImage(urlValue, {
   if (url.protocol !== "https:" || url.username || url.password) {
     throw providerError("Image API returned an unsafe image URL", "ccdx_image_url_unsafe");
   }
-  const addresses = await lookup(url.hostname, { all: true, verbatim: true });
-  if (!Array.isArray(addresses) || !addresses.length || addresses.some(({ address }) => !publicAddress(address))) {
-    throw providerError("Image API returned a non-public image URL", "ccdx_image_url_unsafe");
-  }
   return new Promise((resolve, reject) => {
     let settled = false;
+    let request;
     const finish = (error, value) => {
       if (settled) return;
       settled = true;
+      clearTimeout(timer);
       signal?.removeEventListener("abort", onAbort);
-      if (error) reject(error);
+      if (error) {
+        request?.destroy(error);
+        reject(error);
+      }
       else resolve(value);
     };
-    const request = https.get(url, {
-      headers: { Accept: "image/*,application/octet-stream;q=0.5" },
-      lookup: (_hostname, options, callback) => {
-        if (options?.all) callback(null, addresses);
-        else callback(null, addresses[0].address, addresses[0].family);
-      },
-    }, (response) => {
-      if (response.statusCode < 200 || response.statusCode >= 300) {
-        response.resume();
-        finish(providerError(`Image download failed with HTTP ${response.statusCode}`));
-        return;
-      }
-      const declared = Number(response.headers["content-length"]);
-      if (Number.isFinite(declared) && declared > maxBytes) {
-        response.destroy();
-        finish(providerError("Generated image exceeds the size limit", "ccdx_image_too_large"));
+    const timer = setTimeout(() => finish(providerError("Image download timed out", "ccdx_image_timeout")), timeoutMs);
+    timer.unref?.();
+    const onAbort = () => finish(signal.reason instanceof Error ? signal.reason : providerError("Image request was cancelled"));
+    if (signal?.aborted) { onAbort(); return; }
+    signal?.addEventListener("abort", onAbort, { once: true });
+    // DNS and transfer share one deadline; a late lookup cannot start a cancelled download.
+    Promise.resolve().then(() => settled ? undefined : lookup(url.hostname, { all: true, verbatim: true })).then((addresses) => {
+      if (settled) return;
+      if (!Array.isArray(addresses) || !addresses.length || addresses.some(({ address }) => !publicAddress(address))) {
+        finish(providerError("Image API returned a non-public image URL", "ccdx_image_url_unsafe"));
         return;
       }
-      const chunks = [];
-      let total = 0;
-      response.on("data", (chunk) => {
-        total += chunk.length;
-        if (total > maxBytes) {
+      request = https.get(url, {
+        headers: { Accept: "image/*,application/octet-stream;q=0.5" },
+        lookup: (_hostname, options, callback) => {
+          if (options?.all) callback(null, addresses);
+          else callback(null, addresses[0].address, addresses[0].family);
+        },
+      }, (response) => {
+        response.on("error", (error) => finish(error));
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+          response.resume();
+          finish(providerError(`Image download failed with HTTP ${response.statusCode}`));
+          return;
+        }
+        const declared = Number(response.headers["content-length"]);
+        if (Number.isFinite(declared) && declared > maxBytes) {
           response.destroy();
           finish(providerError("Generated image exceeds the size limit", "ccdx_image_too_large"));
           return;
         }
-        chunks.push(chunk);
+        const chunks = [];
+        let total = 0;
+        response.on("data", (chunk) => {
+          total += chunk.length;
+          if (total > maxBytes) {
+            response.destroy();
+            finish(providerError("Generated image exceeds the size limit", "ccdx_image_too_large"));
+            return;
+          }
+          chunks.push(chunk);
+        });
+        response.on("end", () => finish(null, Buffer.concat(chunks, total)));
       });
-      response.on("end", () => finish(null, Buffer.concat(chunks, total)));
-      response.on("error", (error) => finish(error));
-    });
-    const timer = setTimeout(() => request.destroy(providerError("Image download timed out", "ccdx_image_timeout")), timeoutMs);
-    timer.unref?.();
-    request.on("close", () => clearTimeout(timer));
-    request.on("error", (error) => finish(error));
-    const onAbort = () => request.destroy(signal.reason instanceof Error ? signal.reason : providerError("Image request was cancelled"));
-    if (signal?.aborted) onAbort();
-    else signal?.addEventListener("abort", onAbort, { once: true });
+      request.on("error", (error) => finish(error));
+    }).catch((error) => finish(error));
   });
 }
 
 export async function generateImage(config, {
   prompt,
   size = "1024x1024",
+  image,
 } = {}, {
   fetchImpl = fetch,
   downloadImage = downloadPublicImage,
@@ -218,6 +272,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 +284,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-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

@@ -108,28 +108,32 @@ export function updateImageSkill({
   const endpoint = `${adapterBaseUrl(host, adapterPort)}/mcp/image`;
   const skillBody = `---
 name: ccdx-image
-description: Generate new images from text using the user's configured CCDX image provider. Use for requests to draw, create, or render a new image. Excludes editing existing images, image references, transparent output, and code-native SVG or diagrams.
+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. For new text-to-image requests, use the configured CCDX provider directly.
+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.
 
-Use the ccdx_image server's generate_image tool when available. Supply a complete prompt and one size: 1024x1024 (square), 1536x1024 (landscape), or 1024x1536 (portrait). Display its returned image. No Python, SDK installation, extra API key, or provider discovery is needed.
+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.
 
-If the tool is not directly callable and the host provides tool search, make one targeted search for ccdx_image generate_image and use the tool if it becomes callable. If it is still unavailable, run the bundled Node helper once:
+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
 \`\`\`
 
-Quote the actual prompt safely for the shell. The helper uses the same local CCDX service and prints the saved absolute image path. 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.
+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 a generation fails or times out: the first request may already have consumed a generation. A helper error explicitly saying generation has not started means no generation 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 generation.
+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.
 
-This provider supports text-to-image only. For edits, reference images, transparent output, or explicitly requested other providers, keep the relevant native tools and skills; do not substitute a fresh CCDX generation.
+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`;

package/src/image-tool-client.mjs

@@ -7,22 +7,25 @@ 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 USAGE = "Usage: generate.mjs --prompt <text> [--size 1024x1024|1536x1024|1024x1536] [--out <new-file>]";
+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", "--size", "--out"].includes(option) || option in values) throw new Error(USAGE);
+    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 size = String(values["--size"] || "1024x1024").trim().toLowerCase();
-  if (!IMAGE_SIZES.has(size)) throw new Error("Unsupported image size");
-  return { prompt, size, out: values["--out"] };
+  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) {
@@ -79,6 +82,7 @@ export async function runImageToolClient({
   cwd = process.cwd(),
   fetchImpl = fetch,
   output = process.stdout,
+  metadataOutput = process.stderr,
   signal = AbortSignal.timeout(210_000),
 } = {}) {
   const options = parseImageToolArgs(args);
@@ -114,11 +118,14 @@ export async function runImageToolClient({
     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 generation has not started: ${detail}`), { code: "CCDX_IMAGE_NOT_STARTED" });
+    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: "generate_image", arguments: { prompt: options.prompt, size: options.size } },
+    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));
@@ -137,5 +144,7 @@ export async function runImageToolClient({
   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/responses-handler.mjs

@@ -144,6 +144,42 @@ export function createResponsesHandler(options) {
       activeDeadline = now() + timeoutMs;
       abort.setTimeout(timeoutMs, activeTimeoutReason);
     };
+    const startStream = () => {
+      assertPrepareActive();
+      // Headers completed this phase. Stream liveness is now governed by its
+      // idle timer, not the original handshake deadline.
+      activeDeadline = Number.POSITIVE_INFINITY;
+    };
+    const acquireRetryPreparation = async (reqContext) => {
+      assertPrepareActive();
+      activeDeadline = now() + upstreamTimeoutMs;
+      activeTimeoutReason = "responses_prepare_timeout";
+      abort.setTimeout(upstreamTimeoutMs, activeTimeoutReason);
+      let releaseRetryRequest = () => {};
+      let retrySnapshot = null;
+      const release = () => {
+        retrySnapshot?.release();
+        releaseRetryRequest();
+      };
+      try {
+        releaseRetryRequest = await measureRequestStageAsync("admission", () => acquireRequest(req, { signal: abort.signal }));
+        assertPrepareActive();
+        if (reqContext.historyParentId) {
+          retrySnapshot = measureRequestStage("history", () => acquireResponseHistorySnapshot(reqContext.historyParentId, {
+            assertActive: assertPrepareActive,
+            signal: abort.signal,
+          }));
+          if (retrySnapshot.bytes > 0) {
+            await measureRequestStageAsync("admission", () => releaseRetryRequest.reserveResponseHistory?.(retrySnapshot.bytes, { signal: abort.signal }));
+          }
+        }
+        assertPrepareActive();
+        return { historySnapshot: retrySnapshot, release };
+      } catch (error) {
+        release();
+        throw error;
+      }
+    };
     const applyAdaptiveTimeout = (error) => {
       if (!["responses_prepare_timeout", "stream_handshake_timeout", "upstream_timeout"].includes(abort.reason)) {
         return error;
@@ -251,10 +287,12 @@ export function createResponsesHandler(options) {
       applyCopilotResponsesRequestPolicies(prepared.body);
       if (routePlan.protocol === "openai-responses") {
         const result = await proxyCopilotResponses(prepared, req, res, responsesFn, {
+          acquireRetryPreparation,
           assertPrepareActive,
           signal: abort.signal,
           abort,
           onUpstreamStart: startUpstreamTimeout,
+          onStreamStart: startStream,
           releaseRequest: releaseUpstreamPayload,
           responseFailures,
           streamIdleTimeoutMs,