codex-copilot-dx 0.7.6 → 0.7.8

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
 
@@ -125,12 +127,39 @@ The selector is ordered numerically:
 4. Chase
 5. Mirror
 6. Pulse
-7. Braille
+7. Stack — short light trails arrive, accumulate, then leave as one bundle
+8. Relay — fixed nodes receive and pass a short light trail
+9. Split — one incoming light trail divides into two outgoing trails
 
 Enter the corresponding number to select an animation. The Comet row includes a static preview, and after a selection CCDX plays one cycle of the chosen animation as confirmation when terminal animation is enabled. The setting is saved in `~/.config/codex-copilot-dx/config.json`, or under `XDG_CONFIG_HOME` when set.
 
+All nine animations use the same 20-column colon track and cyan/blue palette. They indicate activity, not completion percentage. Braille was removed in 0.7.7. A saved `terminal_animation: "braille"` falls back to Comet without rewriting the settings file; choosing another animation replaces it, and explicitly choosing Comet clears it. Other settings remain intact.
+
 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. Restart Codex App after enabling so it loads the tool. The existing CCDX adapter can remain running because provider settings are loaded when the tool is invoked.
+
+Inspect or disable the optional provider with:
+
+```bash
+ccdx image-status
+ccdx disable-image
+```
+
+`image-status` never prints the API key. Disabling removes the stored provider credential and the CCDX-owned MCP block; restart Codex App to remove the tool from already running tasks. The image endpoint is contacted only by `enable-image` validation and by explicit `generate_image` tool calls. Ordinary Responses, models, authentication, Fast, Auto-review, compaction, and image-input paths remain on their existing routes.
+
+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:
@@ -198,7 +227,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.
 
@@ -228,6 +257,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.
 
@@ -315,7 +345,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,13 +214,18 @@ async function reuseRunningAdapterIfAvailable() {
   if (!running.ok) return false;
 
   console.log(status("ok", `Using existing adapter at ${running.baseUrl}`));
-  ensureCodexConfig(ADAPTER_PORT, { host: ADAPTER_HOST });
+  ensureCodexConfig(ADAPTER_PORT, {
+    host: ADAPTER_HOST,
+    imageProviderEnabled: Boolean(readImageProviderConfig()),
+  });
 
   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;
 }
@@ -274,7 +298,10 @@ try {
   });
 
   // Point Codex App at the adapter.
-  ensureCodexConfig(ADAPTER_PORT, { host: ADAPTER_HOST });
+  ensureCodexConfig(ADAPTER_PORT, {
+    host: ADAPTER_HOST,
+    imageProviderEnabled: Boolean(readImageProviderConfig()),
+  });
 
   // Launch Codex when available.
   await openCodex();
@@ -294,6 +321,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.6",
+  "version": "0.7.8",
   "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,199 @@
+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 {
+  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 });
+  atomicWriteFilePairSync(
+    codexPath,
+    codex.content,
+    providerPath,
+    `${JSON.stringify(normalized, null, 2)}\n`,
+    { mode: 0o600 },
+  );
+  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);
+  if (fs.existsSync(codexPath)) {
+    atomicWriteFilePairSync(codexPath, codex.content, providerPath, null, { mode: 0o600 });
+  } else if (providerExists) {
+    fs.unlinkSync(providerPath);
+  }
+  return { changed: providerExists || codex.changed };
+}
+
+export async function runImageCommand({
+  action,
+  commandName = "ccdx",
+  env = process.env,
+  home = os.homedir(),
+  input = process.stdin,
+  output = process.stdout,
+  prompt,
+  promptSecret,
+  fetchImpl = 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`);
+    return { enabled: true, ...summary };
+  }
+
+  const codexContent = fileContent(codexPath);
+  if (action === "disable") {
+    const result = disableImageProvider({ providerPath, codexPath, codexContent, adapterPort, adapterHost });
+    output.write(`${result.changed ? "Disabled" : "Kept disabled"} image generation.\n`);
+    output.write("Restart Codex App to remove the image tool from active tasks.\n");
+    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`);
+  output.write("Restart Codex App to load the image tool. A running ccdx adapter can remain running.\n");
+  return { enabled: true, ...configSummary(result.config), codexChanged: result.codexChanged };
+}

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, and registers the local CCDX image tool for Codex App.`,
+    "disable-image": `Usage:\n  ${name} disable-image\n\nDisables the local CCDX image tool and removes its stored API credential.`,
+    "image-status": `Usage:\n  ${name} image-status\n\nShows whether the optional image provider is configured without exposing its API key.`,
     "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}`));