codex-copilot-dx 0.7.7 → 0.7.9

package/src/image-provider.mjs

@@ -0,0 +1,268 @@
+import dns from "node:dns/promises";
+import https from "node:https";
+import net from "node:net";
+
+export const IMAGE_MAX_BYTES = 32 * 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"]);
+
+function providerError(message, code = "ccdx_image_provider_error") {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function checkedPrompt(value) {
+  const prompt = String(value || "").trim();
+  if (!prompt) throw providerError("Image prompt is required", "ccdx_image_prompt_required");
+  if (prompt.length > 16_000) throw providerError("Image prompt exceeds 16000 characters", "ccdx_image_prompt_too_large");
+  return prompt;
+}
+
+function checkedSize(value) {
+  const size = String(value || "1024x1024").trim().toLowerCase();
+  if (!IMAGE_SIZES.has(size)) {
+    throw providerError(`Image size must be one of: ${[...IMAGE_SIZES].join(", ")}`, "ccdx_image_size_invalid");
+  }
+  return size;
+}
+
+function generationBody(config, prompt, size) {
+  if (config.protocol === "qwen-messages") {
+    return {
+      model: config.model,
+      input: { messages: [{ role: "user", content: [{ text: prompt }] }] },
+      parameters: { n: 1, size: size.replace("x", "*"), watermark: false },
+    };
+  }
+  return { model: config.model, prompt, n: 1, size };
+}
+
+async function boundedJson(response) {
+  const maxBytes = 48 * 1024 * 1024;
+  const declared = Number(response.headers?.get?.("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) throw providerError("Image API response was too large");
+  const reader = response.body?.getReader?.();
+  let text;
+  if (!reader) {
+    text = await response.text();
+    if (Buffer.byteLength(text) > maxBytes) throw providerError("Image API response was too large");
+  } else {
+    const chunks = [];
+    let total = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+          await reader.cancel().catch(() => {});
+          throw providerError("Image API response was too large");
+        }
+        chunks.push(Buffer.from(value.buffer, value.byteOffset, value.byteLength));
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    text = Buffer.concat(chunks, total).toString("utf8");
+  }
+  try { return JSON.parse(text); } catch { throw providerError("Image API returned invalid JSON"); }
+}
+
+function upstreamMessage(body) {
+  return String(body?.message || body?.error?.message || body?.error || "")
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+    .trim()
+    .slice(0, 500);
+}
+
+function imageSource(body) {
+  const standard = body?.data?.[0];
+  if (typeof standard?.b64_json === "string" && standard.b64_json) {
+    return { type: "base64", value: standard.b64_json };
+  }
+  if (typeof standard?.url === "string" && standard.url) return { type: "url", value: standard.url };
+  const contents = body?.output?.choices?.[0]?.message?.content;
+  if (Array.isArray(contents)) {
+    const image = contents.find((part) => typeof part?.image === "string" && part.image);
+    if (image) return { type: "url", value: image.image };
+  }
+  return null;
+}
+
+function imageMetadata(bytes) {
+  if (bytes.length >= 24 && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+    return { mimeType: "image/png", width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+  }
+  if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") {
+    return { mimeType: "image/webp" };
+  }
+  if (bytes.length >= 4 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+    let offset = 2;
+    while (offset + 9 < bytes.length) {
+      if (bytes[offset] !== 0xff) { offset += 1; continue; }
+      const marker = bytes[offset + 1];
+      if (marker === 0xd8 || marker === 0xd9) { offset += 2; continue; }
+      const length = bytes.readUInt16BE(offset + 2);
+      if (length < 2 || offset + 2 + length > bytes.length) break;
+      if ([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf].includes(marker)) {
+        return { mimeType: "image/jpeg", height: bytes.readUInt16BE(offset + 5), width: bytes.readUInt16BE(offset + 7) };
+      }
+      offset += 2 + length;
+    }
+    return { mimeType: "image/jpeg" };
+  }
+  throw providerError("Image API returned an unsupported image format", "ccdx_image_format_unsupported");
+}
+
+function ipv4Public(address) {
+  const parts = address.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false;
+  const [a, b, c] = parts;
+  if (a === 0 || a === 10 || a === 127 || a >= 224) return false;
+  if (a === 100 && b >= 64 && b <= 127) return false;
+  if (a === 169 && b === 254) return false;
+  if (a === 172 && b >= 16 && b <= 31) return false;
+  if (a === 192 && (b === 168 || (b === 0 && [0, 2].includes(c)))) return false;
+  if (a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100))) return false;
+  if (a === 203 && b === 0 && c === 113) return false;
+  return true;
+}
+
+function publicAddress(address) {
+  const family = net.isIP(address);
+  if (family === 4) return ipv4Public(address);
+  if (family !== 6) return false;
+  const lower = address.toLowerCase();
+  if (lower === "::" || lower === "::1" || lower.startsWith("fc") || lower.startsWith("fd")
+    || /^fe[89ab]/.test(lower) || lower.startsWith("ff") || lower.startsWith("2001:db8:")) return false;
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(lower);
+  return mapped ? ipv4Public(mapped[1]) : true;
+}
+
+export async function downloadPublicImage(urlValue, {
+  lookup = dns.lookup,
+  timeoutMs = IMAGE_DOWNLOAD_TIMEOUT_MS,
+  maxBytes = IMAGE_MAX_BYTES,
+  signal,
+} = {}) {
+  let url;
+  try { url = new URL(urlValue); } catch { throw providerError("Image API returned an invalid image URL"); }
+  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;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      if (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"));
+        return;
+      }
+      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("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 });
+  });
+}
+
+export async function generateImage(config, {
+  prompt,
+  size = "1024x1024",
+} = {}, {
+  fetchImpl = fetch,
+  downloadImage = downloadPublicImage,
+  signal,
+  timeoutMs = IMAGE_GENERATION_TIMEOUT_MS,
+} = {}) {
+  const normalizedPrompt = checkedPrompt(prompt);
+  const normalizedSize = checkedSize(size);
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const requestSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  let response;
+  try {
+    response = await fetchImpl(config.endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${config.api_key}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(generationBody(config, normalizedPrompt, normalizedSize)),
+      signal: requestSignal,
+    });
+  } catch (error) {
+    if (requestSignal.aborted) throw providerError("Image generation timed out or was cancelled", "ccdx_image_timeout");
+    throw providerError("Image API could not be reached");
+  }
+  const body = await boundedJson(response);
+  if (!response.ok) {
+    const detail = upstreamMessage(body);
+    throw providerError(`Image API failed with HTTP ${response.status}${detail ? `: ${detail}` : ""}`);
+  }
+  const source = imageSource(body);
+  if (!source) throw providerError("Image API response did not contain an image");
+  let bytes;
+  try {
+    bytes = source.type === "base64"
+      ? Buffer.from(source.value, "base64")
+      : await downloadImage(source.value, { signal: requestSignal, maxBytes: IMAGE_MAX_BYTES });
+  } catch (error) {
+    if (error?.code?.startsWith?.("ccdx_")) throw error;
+    const code = String(error?.cause?.code || error?.code || "").replace(/[^A-Z0-9_-]/gi, "").slice(0, 64);
+    throw providerError(`Generated image could not be downloaded${code ? ` (${code})` : ""}`);
+  }
+  if (!bytes.length || bytes.length > IMAGE_MAX_BYTES) {
+    throw providerError("Generated image is empty or exceeds the size limit", "ccdx_image_too_large");
+  }
+  const metadata = imageMetadata(bytes);
+  return {
+    data: bytes.toString("base64"),
+    mimeType: metadata.mimeType,
+    width: metadata.width,
+    height: metadata.height,
+    model: config.model,
+    size: normalizedSize,
+  };
+}

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-skill.mjs

@@ -0,0 +1,143 @@
+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 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.
+---
+
+# CCDX image generation
+
+The user enabled this provider through ccdx enable-image. For new text-to-image requests, use the configured CCDX provider directly.
+
+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.
+
+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:
+
+\`\`\`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.
+
+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.
+
+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.
+`;
+  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,141 @@
+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 USAGE = "Usage: generate.mjs --prompt <text> [--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 (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"] };
+}
+
+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,
+  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 generation has not started: ${detail}`), { code: "CCDX_IMAGE_NOT_STARTED" });
+  }
+  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 } },
+  }), 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`);
+  return filePath;
+}

package/src/observability.mjs

@@ -154,6 +154,7 @@ export function runtimeStatusPayload({
   streamPerformance,
   admission,
   imagePressure,
+  responseFailures,
   modelRegistry,
   codexClient,
   codexModelRegistry,
@@ -177,6 +178,7 @@ export function runtimeStatusPayload({
     response_history: responseHistoryStats(),
     image_optimization: imageOptimizationStats(),
     image_history_pressure: imagePressure?.snapshot?.() || null,
+    response_failures: responseFailures?.snapshot?.() || null,
     copilot: codexRuntime,
     models: codexModels,
     profiles: {