codex-copilot-dx 0.7.7 → 0.7.9

package/README.md

@@ -74,6 +74,7 @@ Normal startup and reuse of an existing adapter check `~/.codex/config.toml` onc
 | `model_auto_compact_token_limit` | Add `900000` only when missing | `900000` |
 | `[shell_environment_policy.set]` OpenAI URL/key | Update `OPENAI_BASE_URL` and set `OPENAI_API_KEY="dummy"` when this section is recognized; leave an absent section absent | Create the section and set both keys; set `shell_environment_policy.inherit="core"` |
 | `[features]` `context_management` | Add `true` when missing; preserve explicit values and alternative declarations as described above | `true` |
+| `[mcp_servers.ccdx_image]` | Added in a marked CCDX-owned block only after `ccdx enable-image`; removed by `ccdx disable-image` | Absent by default |
 
 The two token limits are fixed defaults, not detected model capabilities. Existing custom values are retained. Writes target the listed keys with line-based edits and atomic replacement; this is not a general TOML formatter. The shell environment updater recognizes the literal `[shell_environment_policy.set]` header. Use `ccdx doctor config` to inspect parsed values and preview what this writer would do with the current file. No actual change means no file rewrite.
 
@@ -88,6 +89,7 @@ The upgrade intentionally does not delete or rewrite retired Claude or PM Studio
 ## Commands
 
 Run `ccdx <command> --help` for command-specific behavior and side-effect details.
+After startup, CCDX prints a short reminder that `ccdx help` lists all available commands.
 
 ### Live models
 
@@ -135,6 +137,31 @@ All nine animations use the same 20-column colon track and cyan/blue palette. Th
 
 The selected theme is loaded once when a new adapter starts, so changing it does not restart or alter an adapter that is already running. Stop and start CCDX to apply the new theme. `CCDX_TERMINAL_ANIMATION=0` (also `false`, `no`, or `off`) remains the boolean gate that disables terminal animation regardless of the selected theme.
 
+### Optional image generation
+
+Image generation is disabled by default. Configure it interactively only when you want Codex App to receive the local CCDX image tool:
+
+```bash
+ccdx enable-image
+```
+
+The command asks for an HTTPS `/images/generations` endpoint and an API key without echoing the key. It reads the endpoint's `/models` catalog, detects either the standard OpenAI Images request format or the supported `input.messages` format, and asks for a numeric model selection only when multiple image models are available. Its validation request omits the prompt and does not generate an image.
+
+The provider credential is stored in `~/.config/codex-copilot-dx/image-provider.json`, or under `XDG_CONFIG_HOME`, with mode `0600`. The API key is never written to `~/.codex/config.toml`; that file receives only a marked local MCP entry pointing to the running CCDX adapter with a 210-second tool timeout. 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 and reference images.
+
+The enable command verifies the local MCP handshake and generation-tool directory without generating an image. It reports provider configuration separately from local service readiness; it cannot assert that every running Codex task has refreshed its catalog. Codex normally detects changed skills; restart Codex App once if an open task has not refreshed them. Normal CCDX startup installs or updates this guidance for providers already enabled in 0.7.8, without repeating API setup. Unchanged guidance is not rewritten. The existing adapter can remain running because provider settings are loaded when the tool is invoked.
+
+Inspect or disable the optional provider with:
+
+```bash
+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.
+
+Generated image downloads must use public HTTPS addresses, do not follow redirects, are DNS-checked against private and reserved addresses, and are capped at 32 MiB. The local MCP route accepts calls only from the same device and permits at most two concurrent generations. The tool supports new-image generation at `1024x1024`, `1536x1024`, or `1024x1536`; it does not claim image editing or multi-turn image editing support.
+
 ### Update
 
 Choose a source interactively:
@@ -202,7 +229,7 @@ For the complete machine-readable status payload:
 curl -s http://127.0.0.1:2026/_ccdx/status | jq
 ```
 
-The status endpoint is restricted to the socket's real loopback address even when LAN binding is explicitly enabled. It reports fixed-size request counters, bounded TTFT/TPOT histograms, admission pressure, memory use, response-history size, image queue/cache and adaptive-history state, model-cache counts, and token expiry state. It never retains metric samples or includes prompts, completions, tool arguments, image content, account names, or token values.
+The status endpoint is restricted to the socket's real loopback address even when LAN binding is explicitly enabled. It reports fixed-size request counters, bounded TTFT/TPOT histograms, admission pressure, memory use, response-history size, image queue/cache and adaptive-history state, model-cache counts, token expiry state, and the ten most recent upstream `response.failed` diagnostics retained by the running process. Failure diagnostics include the event type, model, error code/message, response/request IDs when supplied upstream, and retry outcome; long opaque encrypted values are redacted. They are cleared when the adapter restarts. The endpoint never includes prompts, completions, tool arguments, image content, account names, or token values.
 
 `stream_performance.by_route` also reports `request_ttft_ms`, measured from adapter entry to the first observed output delta, including local preparation. The existing `ttft_ms` continues to start at upstream dispatch. Neither timestamp means the client has drained or displayed the output. `preparation_ms` contains bounded histograms for admission (including history reservations), body reading/decompression/JSON parsing, history materialization/compact preparation, image optimization, and request serialization. Each sample measures one operation, including failed operations; retries can add samples. These are diagnostic intervals rather than a complete breakdown of request time: body reading includes internal decoded-body admission waits; authentication, routing, and other preparation are not individually timed. Non-streaming requests contribute preparation samples without inventing a first-token measurement.
 
@@ -232,6 +259,7 @@ Recovery first tries compatible local credentials and starts Device Flow only wh
 - CCDX binds to loopback by default. Non-loopback hosts are rejected unless `CCDX_ALLOW_LAN=1` is set explicitly.
 - Enabling LAN binding exposes a Copilot-backed API to other reachable machines. Provide your own host firewall and network isolation; do not expose the listener to an untrusted network.
 - The GitHub OAuth credential is stored locally at `~/.local/share/copilot-api/github_token`. Short-lived Copilot service tokens remain in process memory and are refreshed as needed.
+- The optional image API credential is stored separately with mode `0600` only after `ccdx enable-image`; it is never placed in Codex configuration or diagnostic output.
 - Runtime status and usage records retain metadata rather than request/response content. Diagnostic logging records status and error messages; it is not a general redaction layer for arbitrary error text. See Debug logging before sharing logs.
 - Request and response bodies are bounded. Queues, history, image work, SSE parsing, retries, and shutdown all have explicit resource or time limits.
 
@@ -319,7 +347,7 @@ When expanded history exceeds Copilot's 50-image request limit, CCDX removes old
 
 For `/v1/responses/compact`, CCDX sends one terminal `compaction_trigger`, validates completed compaction state, and preserves the complete returned window as the canonical next context. Only a validated window becomes a new local history root. Existing older branches remain available until normal history eviction.
 
-Changing the model or transport of a continuation can require removing incompatible encrypted history from the forwarded request. A specific upstream encrypted-state verification failure can also trigger one sanitized retry. CCDX does not decrypt that state locally.
+Changing the model or transport of a continuation can require removing incompatible encrypted history from the forwarded request. A specific upstream encrypted-state verification failure can also trigger one sanitized retry, including when a nominally successful HTTP response ends with `response.failed`. CCDX withholds only the pre-output prelude of an encrypted continuation while evaluating that terminal event; it never retries after visible model output, so it cannot duplicate an already-started answer. Unrelated failures pass through unchanged. CCDX does not decrypt that state locally.
 
 Successful streaming responses are accepted only when the upstream body is SSE and reaches its protocol terminal event. Unexpected EOF becomes a protocol-native stream error, and repeated blank tool-argument deltas are stopped per tool call. Allowlisted rate-limit, retry, model, trace, and upstream request-ID metadata are forwarded; cookies, authorization, body-length, and encoding headers are not.
 

package/bin/cli.mjs

@@ -22,6 +22,7 @@ import { runAuthCommand } from "../src/cli-auth.mjs";
 import { createProfileRuntime } from "../src/profile-runtime.mjs";
 import { createProfileModelRuntime } from "../src/profile-model-runtime.mjs";
 import { createCodexModelCatalog } from "../src/codex-model-catalog.mjs";
+import { readImageProviderConfig } from "../src/image-provider-config.mjs";
 
 const LOCAL_VERSION = localPackageVersion();
 const CLI_NAME = cliCommandName();
@@ -54,6 +55,24 @@ if (CLI.command === "animation") {
     process.exit(1);
   }
 }
+if (CLI.command === "image") {
+  try {
+    const address = CLI.action === "enable"
+      ? parseAdapterAddressOptions(process.env)
+      : { adapterPort: 2026, adapterHost: "127.0.0.1" };
+    const { runImageCommand } = await import("../src/cli-image.mjs");
+    await runImageCommand({
+      action: CLI.action,
+      commandName: CLI_NAME,
+      adapterPort: address.adapterPort,
+      adapterHost: address.adapterHost,
+    });
+    process.exit(0);
+  } catch (e) {
+    console.error(status("err", e.message));
+    process.exit(1);
+  }
+}
 if (CLI.command === "usage") {
   await printUsageSummary({
     format: CLI.outputFormat || "auto",
@@ -195,17 +214,32 @@ async function reuseRunningAdapterIfAvailable() {
   if (!running.ok) return false;
 
   console.log(status("ok", `Using existing adapter at ${running.baseUrl}`));
-  ensureCodexConfig(ADAPTER_PORT, { host: ADAPTER_HOST });
+  await configureCodexClient();
 
   await openCodex();
   console.log(`
   ${status("ok", "Ready, using the existing ccdx adapter")}
 
   Adapter: ${running.baseUrl}
+
+  Tip: Run ${CLI_NAME} help to view more features and commands.
 `);
   return true;
 }
 
+async function configureCodexClient() {
+  const imageProviderEnabled = Boolean(readImageProviderConfig());
+  ensureCodexConfig(ADAPTER_PORT, { host: ADAPTER_HOST, imageProviderEnabled });
+  if (imageProviderEnabled) {
+    try {
+      const { syncEnabledImageSkill } = await import("../src/cli-image.mjs");
+      syncEnabledImageSkill({ adapterPort: ADAPTER_PORT, adapterHost: ADAPTER_HOST });
+    } catch (error) {
+      console.warn(status("warn", `Image guidance could not be updated: ${error.message}`));
+    }
+  }
+}
+
 if (CLI.command === "doctor") {
   const checks = await runDoctor({
     commandName: CLI_NAME,
@@ -274,7 +308,7 @@ try {
   });
 
   // Point Codex App at the adapter.
-  ensureCodexConfig(ADAPTER_PORT, { host: ADAPTER_HOST });
+  await configureCodexClient();
 
   // Launch Codex when available.
   await openCodex();
@@ -294,6 +328,8 @@ try {
 
   Adapter: ${adapterBaseUrl(ADAPTER_HOST, ADAPTER_PORT)}
 
+  Tip: Run ${CLI_NAME} help to view more features and commands.
+
   Press Ctrl+C to stop.
 `);
 

package/package.json

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

package/src/adapter.mjs

@@ -16,6 +16,7 @@ import { createTerminalActivityIndicator } from "./terminal-activity.mjs";
 import { ADAPTER_HEALTH_PATH, adapterHealthPayload } from "./running-adapter.mjs";
 import { createResponsesCompactHandler, createResponsesHandler } from "./responses-handler.mjs";
 import { createResponsesImagePressureController } from "./responses-image-pressure.mjs";
+import { createResponseFailureDiagnostics } from "./response-failures.mjs";
 import { loadRuntimeConfig, parsePositiveInteger } from "./runtime-config.mjs";
 import {
   createRequestAdmission,
@@ -159,6 +160,8 @@ export function createAdapterHandler(options = {}) {
   const requestMetrics = options.requestMetrics || createRequestMetrics();
   const streamPerformanceMetrics = options.streamPerformanceMetrics || createStreamPerformanceMetrics();
   const imagePressure = options.imagePressure || createResponsesImagePressureController();
+  const responseFailures = options.responseFailures || createResponseFailureDiagnostics();
+  let imageMcpHandler = options.imageMcpHandler || null;
   const responsesHandler = createResponsesHandler({
     acquireRequest,
     autoReviewModelResolver: options.autoReviewModelResolver,
@@ -170,6 +173,7 @@ export function createAdapterHandler(options = {}) {
     openAIModelEnv,
     responsesPayloadOptions: options.responsesPayloadOptions,
     responsesFn,
+    responseFailures,
     requestBodyTimeoutMs,
     streamHandshakeTimeoutMs,
     streamIdleTimeoutMs,
@@ -189,6 +193,13 @@ export function createAdapterHandler(options = {}) {
     upstreamTimeoutMs,
   });
   const dispatch = (req, res, pathname) => {
+    if (pathname === "/mcp/image") {
+      if (imageMcpHandler) return imageMcpHandler(req, res);
+      return import("./image-mcp.mjs").then(({ createImageMcpHandler }) => {
+        imageMcpHandler = createImageMcpHandler();
+        return imageMcpHandler(req, res);
+      });
+    }
     if (req.method === "GET" && pathname === ADAPTER_STATUS_PATH) {
       if (!isLoopbackAddress(req.socket?.remoteAddress)) {
         res.writeHead(403, { "Content-Type": "application/json" });
@@ -201,6 +212,7 @@ export function createAdapterHandler(options = {}) {
         streamPerformance: streamPerformanceMetrics,
         admission: acquireRequest,
         imagePressure,
+        responseFailures,
         modelRegistry: codexModelRegistry,
         codexClient,
         codexModelRegistry,

package/src/cli-image.mjs

@@ -0,0 +1,230 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { createInterface } from "node:readline/promises";
+import { atomicWriteFilePairSync } from "./atomic-file.mjs";
+import { terminalCell } from "./cli-table.mjs";
+import { computeImageMcpCodexConfig } from "./config.mjs";
+import { probeImageTool } from "./image-readiness.mjs";
+import { updateImageSkill } from "./image-skill.mjs";
+import {
+  imageProviderConfigPath,
+  inspectImageProvider,
+  readImageProviderConfig,
+  validateImageProviderConfig,
+} from "./image-provider-config.mjs";
+
+function defaultCodexConfigPath(home) {
+  return path.join(home, ".codex", "config.toml");
+}
+
+async function visibleQuestion(input, output, question) {
+  const prompt = createInterface({ input, output });
+  try { return await prompt.question(question); }
+  finally { prompt.close(); }
+}
+
+export function hiddenQuestion(input, output, question) {
+  if (!input?.isTTY || !output?.isTTY || typeof input.setRawMode !== "function") {
+    return Promise.reject(new Error("Hidden API key input requires an interactive terminal"));
+  }
+  output.write(question);
+  const wasRaw = Boolean(input.isRaw);
+  readline.emitKeypressEvents(input);
+  input.setRawMode(true);
+  input.resume();
+  let value = "";
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      input.off("keypress", onKeypress);
+      input.setRawMode(wasRaw);
+      if (!wasRaw) input.pause();
+      output.write("\n");
+    };
+    const onKeypress = (text, key = {}) => {
+      if (key.ctrl && key.name === "c") {
+        cleanup();
+        reject(new Error("Image provider setup cancelled"));
+        return;
+      }
+      if (key.name === "return" || key.name === "enter") {
+        cleanup();
+        resolve(value);
+        return;
+      }
+      if (key.name === "backspace" || key.name === "delete") {
+        value = value.slice(0, -1);
+        return;
+      }
+      if (!key.ctrl && !key.meta && typeof text === "string" && text >= " " && text !== "\x7f") value += text;
+    };
+    input.on("keypress", onKeypress);
+  });
+}
+
+function fileContent(filePath) {
+  try { return fs.readFileSync(filePath, "utf8"); }
+  catch (error) {
+    if (error?.code === "ENOENT") return "";
+    throw error;
+  }
+}
+
+function chooseModelLines(modelIds, selected) {
+  return modelIds.map((model, index) => `  ${index + 1}. ${terminalCell(model)}${model === selected ? " [current]" : ""}`);
+}
+
+async function chooseModel(modelIds, current, ask, output) {
+  if (modelIds.length === 1) return modelIds[0];
+  const currentIndex = Math.max(0, modelIds.indexOf(current));
+  output.write("Available image models:\n");
+  output.write(`${chooseModelLines(modelIds, current).join("\n")}\n`);
+  while (true) {
+    const answer = String(await ask(`Select [${currentIndex + 1}]: `) || "").trim();
+    if (!answer) return modelIds[currentIndex];
+    const selected = Number(answer) - 1;
+    if (Number.isInteger(selected) && selected >= 0 && selected < modelIds.length) return modelIds[selected];
+    output.write(`Enter a number from 1 to ${modelIds.length}.\n`);
+  }
+}
+
+function configSummary(config) {
+  const endpoint = new URL(config.endpoint);
+  return {
+    endpoint: `${endpoint.origin}${endpoint.pathname}`,
+    model: config.model,
+    protocol: config.protocol,
+  };
+}
+
+function enableImageProvider({ providerConfig, providerPath, codexPath, codexContent, adapterPort, adapterHost }) {
+  const codex = computeImageMcpCodexConfig(codexContent, {
+    enabled: true,
+    adapterPort,
+    adapterHost,
+  });
+  const normalized = validateImageProviderConfig(providerConfig, { filePath: providerPath });
+  const skill = updateImageSkill({ enabled: true, codexPath, adapterPort, adapterHost });
+  try {
+    atomicWriteFilePairSync(
+      codexPath,
+      codex.content,
+      providerPath,
+      `${JSON.stringify(normalized, null, 2)}\n`,
+      { mode: 0o600 },
+    );
+  } catch (error) {
+    skill.rollback();
+    throw error;
+  }
+  return { codexChanged: codex.changed, config: normalized };
+}
+
+function disableImageProvider({ providerPath, codexPath, codexContent, adapterPort, adapterHost }) {
+  const codex = computeImageMcpCodexConfig(codexContent, {
+    enabled: false,
+    adapterPort,
+    adapterHost,
+  });
+  const providerExists = fs.existsSync(providerPath);
+  const skill = updateImageSkill({ enabled: false, codexPath, adapterPort, adapterHost });
+  try {
+    if (fs.existsSync(codexPath)) {
+      atomicWriteFilePairSync(codexPath, codex.content, providerPath, null, { mode: 0o600 });
+    } else if (providerExists) {
+      fs.unlinkSync(providerPath);
+    }
+  } catch (error) {
+    skill.rollback();
+    throw error;
+  }
+  return { changed: providerExists || codex.changed || skill.changed, preservedGuidance: Boolean(skill.preserved) };
+}
+
+export function syncEnabledImageSkill({ home = os.homedir(), codexPath = defaultCodexConfigPath(home), ...options } = {}) {
+  return updateImageSkill({ ...options, enabled: true, codexPath });
+}
+
+function printImageReadiness(readiness, output, commandName) {
+  if (readiness.ready) output.write("Local image service: ready (generation tool verified; no image generated).\n");
+  else output.write(`Local image service: unavailable (${readiness.reason}). Start or restart ${commandName} to use images.\n`);
+}
+
+export async function runImageCommand({
+  action,
+  commandName = "ccdx",
+  env = process.env,
+  home = os.homedir(),
+  input = process.stdin,
+  output = process.stdout,
+  prompt,
+  promptSecret,
+  fetchImpl = fetch,
+  probeFetchImpl = fetch,
+  adapterPort = 2026,
+  adapterHost = "127.0.0.1",
+  codexPath = defaultCodexConfigPath(home),
+} = {}) {
+  const providerPath = imageProviderConfigPath({ env, home });
+  if (action === "status") {
+    const config = readImageProviderConfig({ env, home, strict: true });
+    if (!config) {
+      output.write("Image generation: disabled\n");
+      return { enabled: false };
+    }
+    const summary = configSummary(config);
+    output.write(`Image generation: enabled\nEndpoint: ${terminalCell(summary.endpoint)}\nModel: ${terminalCell(summary.model)}\nProtocol: ${terminalCell(summary.protocol)}\n`);
+    const readiness = await probeImageTool(fileContent(codexPath), { fetchImpl: probeFetchImpl });
+    printImageReadiness(readiness, output, commandName);
+    return { enabled: true, ...summary, readiness };
+  }
+
+  const codexContent = fileContent(codexPath);
+  if (action === "disable") {
+    const result = disableImageProvider({ providerPath, codexPath, codexContent, adapterPort, adapterHost });
+    output.write(`${result.changed ? "Disabled" : "Kept disabled"} image generation.\n`);
+    output.write(result.preservedGuidance
+      ? "Kept user-modified image guidance. Existing image tool calls are now disabled.\n"
+      : "Removed CCDX image guidance. Existing image tool calls are now disabled.\n");
+    return { enabled: false, ...result };
+  }
+  if (action !== "enable") throw new Error(`Unknown image command action: ${action}`);
+  if (!prompt && (!input.isTTY || !output.isTTY)) {
+    throw new Error(`${commandName} enable-image requires an interactive terminal`);
+  }
+
+  const current = readImageProviderConfig({ env, home });
+  const ask = prompt || ((question) => visibleQuestion(input, output, question));
+  const askSecret = promptSecret || ((question) => hiddenQuestion(input, output, question));
+  output.write(`${commandName} enable-image\n`);
+  const endpointAnswer = String(await ask(`API endpoint${current ? ` [${current.endpoint}]` : ""}: `) || "").trim();
+  const endpoint = endpointAnswer || current?.endpoint;
+  if (!endpoint) throw new Error("Image API endpoint is required");
+  const keyAnswer = String(await askSecret(`API key${current ? " [Enter to keep current]" : ""}: `) || "").trim();
+  const apiKey = keyAnswer || current?.api_key;
+  if (!apiKey) throw new Error("Image API key is required");
+
+  output.write("Checking image API...\n");
+  const inspected = await inspectImageProvider({ endpoint, apiKey, fetchImpl });
+  const model = await chooseModel(inspected.modelIds, current?.model, ask, output);
+  const result = enableImageProvider({
+    providerConfig: {
+      endpoint: inspected.endpoint,
+      api_key: apiKey,
+      model,
+      protocol: inspected.protocol,
+    },
+    providerPath,
+    codexPath,
+    codexContent,
+    adapterPort,
+    adapterHost,
+  });
+  output.write(`Enabled image generation with ${terminalCell(model)}.\n`);
+  const readiness = await probeImageTool(fileContent(codexPath), { fetchImpl: probeFetchImpl });
+  printImageReadiness(readiness, output, commandName);
+  output.write("Installed CCDX image guidance for new and existing tasks. Ask Codex to draw an image.\n");
+  output.write("If the open task has not refreshed its skills, restart Codex App once.\n");
+  return { enabled: true, ...configSummary(result.config), codexChanged: result.codexChanged, readiness };
+}

package/src/cli-options.mjs

@@ -21,6 +21,9 @@ const HELP_TOPICS = new Set([
   "models",
   "usage",
   "animation",
+  "enable-image",
+  "disable-image",
+  "image-status",
   "auto-review-model",
   "update",
   "version",
@@ -200,6 +203,12 @@ export function parseCliArgs(args = []) {
     if (rest.length) unexpectedArgs(rest);
     return baseCommand("animation");
   }
+  if (command === "enable-image" || command === "disable-image" || command === "image-status") {
+    if (rest.length) unexpectedArgs(rest);
+    return baseCommand("image", {
+      action: command === "enable-image" ? "enable" : command === "disable-image" ? "disable" : "status",
+    });
+  }
   if (command === "auto-review-model") {
     if (rest.length) unexpectedArgs(rest);
     return baseCommand("auto-review-model");
@@ -293,6 +302,9 @@ function topicHelp(name, topic) {
     models: `Usage:\n  ${name} models [--format table|plain]\n\nPerforms a fresh, read-only Copilot model-directory lookup for the saved account. Interactive terminals use a table by default.`,
     usage: `Usage:\n  ${name} usage [--format table|plain]\n\nSummarizes local token usage metadata without reading prompt or completion content. Interactive terminals use a table by default.`,
     animation: `Usage:\n  ${name} animation\n\nInteractively selects the terminal activity animation used the next time the adapter starts.`,
+    "enable-image": `Usage:\n  ${name} enable-image\n\nInteractively configures an HTTPS image API endpoint and API key, detects its supported image model and protocol, installs CCDX image guidance, and checks the local image tool for Codex App without generating an image.`,
+    "disable-image": `Usage:\n  ${name} disable-image\n\nDisables the local CCDX image tool and removes its stored API credential and unmodified CCDX image guidance.`,
+    "image-status": `Usage:\n  ${name} image-status\n\nShows provider configuration and probes local image-tool readiness without generating an image or exposing its API key.`,
     "auto-review-model": `Usage:\n  ${name} auto-review-model\n\nInteractively selects an advertised Responses model for Codex Auto-review.`,
     update: `Usage:\n  ${name} update [npm|github]\n\nUpdates the global package from the configured npm registry or GitHub main. With no source, an interactive terminal prompts for one.`,
     version: `Usage:\n  ${name} --version`,
@@ -313,6 +325,9 @@ export function cliHelp(commandName = "ccdx", topic = "") {
   ${name} models [--format table|plain]
   ${name} usage [--format table|plain]
   ${name} animation
+  ${name} enable-image
+  ${name} disable-image
+  ${name} image-status
   ${name} auto-review-model
   ${name} update [npm|github]
   ${name} --version
@@ -326,6 +341,9 @@ Commands:
   models             Query a saved account's live Copilot model catalog
   usage              Summarize locally recorded token usage
   animation          Select the terminal activity animation
+  enable-image       Configure and enable the optional image provider
+  disable-image      Disable the image provider and remove its credential
+  image-status       Show the optional image provider status
   auto-review-model  Select the Codex Auto-review Responses model
   update             Update the global package from npm or GitHub
 

package/src/cli-status.mjs

@@ -1,5 +1,6 @@
 import { ADAPTER_STATUS_PATH, adapterBaseUrl } from "./running-adapter.mjs";
 import { status } from "./status.mjs";
+import { terminalCell } from "./cli-table.mjs";
 
 function finiteNumber(value) {
   const number = Number(value);
@@ -135,6 +136,7 @@ export function formatAdapterStatus({ baseUrl, data }, { commandName = "ccdx", c
   const history = data.response_history || {};
   const images = data.image_optimization || {};
   const imageHistory = data.image_history_pressure;
+  const responseFailures = data.response_failures;
   const models = data.models || {};
   const copilot = data.copilot || {};
   const limits = data.limits || {};
@@ -156,6 +158,16 @@ export function formatAdapterStatus({ baseUrl, data }, { commandName = "ccdx", c
   if (imageHistory && typeof imageHistory === "object") {
     lines.push(status("info", `Visual history: ${count(imageHistory.active_recovery_trees)} recovery trees, ${count(imageHistory.adapted_requests)} adapted requests, ${count(imageHistory.historical_images_omitted)} older images omitted, ${count(imageHistory.timeouts_recorded)} timeouts`));
   }
+  if (responseFailures && typeof responseFailures === "object") {
+    lines.push(status("info", `Response failures: ${count(responseFailures.total)} observed, ${count(responseFailures.retried)} compatibility retries`));
+    for (const failure of Array.isArray(responseFailures.recent) ? responseFailures.recent.slice(-3).reverse() : []) {
+      const model = terminalCell(failure.model, { fallback: "unknown" });
+      const code = terminalCell(failure.code, { fallback: "unknown_error" });
+      const message = terminalCell(failure.message, { fallback: "unknown failure" }).slice(0, 160);
+      const retryPolicy = terminalCell(failure.retry_policy, { fallback: "yes" });
+      lines.push(status("warn", `  ${model} ${code}: ${message}${failure.retried ? ` [retried:${retryPolicy}]` : ""}`));
+    }
+  }
   lines.push(status("info", `Models: ${count(models.models)} total; Copilot token ${copilot.token_cached ? `cached (${duration(copilot.token_expires_in_ms)} remaining)` : "not cached"}`));
   if (data.profiles?.codex) {
     lines.push(status("info", `Profile: ${profileSummary("Codex", data.profiles.codex)}`));

package/src/config.mjs

@@ -8,6 +8,9 @@ import { adapterBaseUrl } from "./running-adapter.mjs";
 const CONFIG_PATH = path.join(os.homedir(), ".codex", "config.toml");
 const MODEL_CONTEXT_WINDOW = 1_000_000;
 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";
 
 function isTomlTableHeader(line) {
   const source = line.trimStart();
@@ -105,7 +108,65 @@ function ensureContextManagementDefault(lines) {
   return true;
 }
 
-export function computeUpdatedCodexConfig(content, adapterPort = 2026, adapterHost = "127.0.0.1") {
+function imageMcpHost(adapterHost) {
+  const host = String(adapterHost || "127.0.0.1").trim();
+  if (host === "0.0.0.0") return "127.0.0.1";
+  if (host === "::" || host === "[::]") return "::1";
+  return host;
+}
+
+function removeManagedImageMcp(lines) {
+  const starts = lines.flatMap((line, index) => line === IMAGE_MCP_START ? [index] : []);
+  const ends = lines.flatMap((line, index) => line === IMAGE_MCP_END ? [index] : []);
+  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 hasUnmanagedImageMcp(lines) {
+  return lines.some((line) => line.trim() === `[${IMAGE_MCP_SECTION}]`);
+}
+
+function ensureImageMcp(lines, enabled, adapterPort, adapterHost) {
+  const previous = lines.join("\n");
+  removeManagedImageMcp(lines);
+  if (enabled) {
+    if (hasUnmanagedImageMcp(lines)) {
+      throw new Error(`Codex config already defines [${IMAGE_MCP_SECTION}] outside the CCDX-managed block`);
+    }
+    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}]`,
+      `url = ${JSON.stringify(url)}`,
+      "enabled = true",
+      "tool_timeout_sec = 210",
+      IMAGE_MCP_END,
+    );
+  }
+  return lines.join("\n") !== previous;
+}
+
+export function computeUpdatedCodexConfig(
+  content,
+  adapterPort = 2026,
+  adapterHost = "127.0.0.1",
+  { imageProviderEnabled } = {},
+) {
   const baseUrl = `${adapterBaseUrl(adapterHost, adapterPort)}/v1`;
   const hadTrailingNewline = content.endsWith("\n");
   const lines = content.split("\n");
@@ -131,13 +192,16 @@ export function computeUpdatedCodexConfig(content, adapterPort = 2026, adapterHo
   changed = setTomlKey(lines, "shell_environment_policy.set", "OPENAI_BASE_URL", baseUrl) || changed;
   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;
+  }
 
   return { content: lines.join("\n") + (hadTrailingNewline ? "\n" : ""), changed };
 }
 
-export function initialCodexConfig(adapterPort, adapterHost) {
+export function initialCodexConfig(adapterPort, adapterHost, { imageProviderEnabled = false } = {}) {
   const baseUrl = `${adapterBaseUrl(adapterHost, adapterPort)}/v1`;
-  return `openai_base_url = "${baseUrl}"
+  const base = `openai_base_url = "${baseUrl}"
 model_context_window = ${MODEL_CONTEXT_WINDOW}
 model_auto_compact_token_limit = ${MODEL_AUTO_COMPACT_TOKEN_LIMIT}
 
@@ -151,20 +215,38 @@ OPENAI_API_KEY = "dummy"
 [features]
 context_management = true
 `;
+  return imageProviderEnabled
+    ? computeUpdatedCodexConfig(base, adapterPort, adapterHost, { imageProviderEnabled }).content
+    : base;
+}
+
+export function computeImageMcpCodexConfig(
+  content,
+  { enabled, adapterPort = 2026, adapterHost = "127.0.0.1" } = {},
+) {
+  const hadTrailingNewline = content.endsWith("\n");
+  const lines = content.split("\n");
+  if (hadTrailingNewline) lines.pop();
+  const changed = ensureImageMcp(lines, Boolean(enabled), adapterPort, adapterHost);
+  return { content: lines.join("\n") + (hadTrailingNewline || lines.length ? "\n" : ""), changed };
 }
 
-export function ensureCodexConfig(adapterPort = 2026, { filePath = CONFIG_PATH, host = "127.0.0.1" } = {}) {
+export function ensureCodexConfig(adapterPort = 2026, {
+  filePath = CONFIG_PATH,
+  host = "127.0.0.1",
+  imageProviderEnabled = false,
+} = {}) {
   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));
+    atomicWriteFileIfChangedSync(filePath, initialCodexConfig(adapterPort, host, { imageProviderEnabled }));
     console.log(status("ok", "Created ~/.codex/config.toml"));
     return;
   }
 
   const content = fs.readFileSync(filePath, "utf-8");
-  const updated = computeUpdatedCodexConfig(content, adapterPort, host);
+  const updated = computeUpdatedCodexConfig(content, adapterPort, host, { imageProviderEnabled });
 
   if (!updated.changed) {
     console.log(status("ok", `Codex already points to ${baseUrl}`));