codex-copilot-dx 0.8.3 → 0.8.5

package/README.md

@@ -18,15 +18,19 @@ The adapter handles response history, encrypted reasoning state, function/custom
 
 ### Fast and Standard modes
 
-Codex can select Standard or Fast without changing CCDX configuration. When the client requests `gpt-5.6-sol` with `service_tier: "priority"`, CCDX uses `gpt-5.6-sol-fast` only when the live Copilot catalog advertises that exact model as enabled, selectable, OpenAI-owned, and Responses-only. Standard mode continues to use `gpt-5.6-sol`; CCDX does not invent Fast availability when the upstream catalog does not provide it.
+Codex can select Standard or Fast without changing CCDX configuration. When the client requests a model with `service_tier: "priority"`, CCDX uses its exact `-fast` model only when the live Copilot catalog advertises that variant as enabled, selectable, OpenAI-owned, and Responses-only. Standard mode continues to use the base model; CCDX does not invent Fast availability when the upstream catalog does not provide it. This retains the established `gpt-5.6-sol` / `gpt-5.6-sol-fast` mapping and applies the same exact-match rule to future models.
 
 Codex Auto-review uses the hidden `codex-auto-review` model ID. CCDX maps it to Copilot's `gpt-5.5` Responses model by default, independently of the interactive Fast/Standard selection, and logs both model IDs when the mapping is used. The review target can be changed interactively without reinstalling or restarting CCDX.
 
 ### GPT-6 model catalog
 
-Codex App requests a versioned, capability-rich model catalog that is different from Copilot's raw model list. CCDX reads the complete catalog bundled with the installed Codex App and preserves every other model entry and capability. It exposes the bundled `gpt-6-astra` entry only when Copilot's available catalog advertises that exact model as enabled, selectable, OpenAI-owned, and Responses-capable.
+Codex App requests a versioned, capability-rich model catalog that is different from Copilot's raw model list. CCDX reads the complete catalog bundled with the installed Codex App and preserves every other model entry and capability. It exposes each managed GPT-6 entry only when Copilot advertises that exact model as enabled, selectable, OpenAI-owned, and Responses-capable.
 
-CCDX exposes the GPT-6 Standard path and removes its unverified speed-tier metadata. It leaves the bundled reasoning-effort options unchanged, including Ultra when supplied by the installed catalog. GPT-5.6 Sol Fast follows the separate rule above. Versioned model discovery matches the bundled catalog to the client's `client_version`, caches it by application binary identity, and reloads it after an App update. If a matching usable catalog cannot be loaded, the versioned models request returns `503`; an unversioned request returns the Copilot-style list.
+When an installed 0.155.x catalog does not yet contain `gpt-6-sol` or `gpt-6-luna`, CCDX derives their client-compatible entries from that catalog's GPT-6 Astra schema and the published OpenAI Codex model definitions at commit `0a2eb4696c26ac33204bcd255721ab30220a4774`. Only those two missing entries are inserted. Their fallback reasoning controls are intersected with Copilot's advertised efforts; every other bundled entry remains byte-for-byte equivalent. A newer client-provided Sol/Luna entry always wins and is preserved.
+
+CCDX exposes GPT-6 Standard paths and removes unverified speed-tier metadata. It leaves bundled reasoning-effort options unchanged, including Ultra when supplied by the installed catalog. Fast follows the exact upstream-variant rule above. Versioned model discovery matches the bundled catalog to the client's `client_version`, caches it by application binary identity, and reloads it after an App update. If a matching usable catalog cannot be loaded, the versioned models request returns `503`; an unversioned request returns the Copilot-style list.
+
+`/v1/models` still attempts live discovery first. With a usable in-process catalog, it limits that upstream wait to 1.5 seconds (or a shorter configured upstream timeout) before falling back to last-known-good data. Without a catalog it retains the regular upstream timeout. Received HTTP `401`/`403` responses remain errors, not cached successes; fallback does not grant inference access. This does not change the explicitly live `ccdx models` command.
 
 ## Prerequisites
 
@@ -78,6 +82,8 @@ Normal startup and reuse of an existing adapter check `~/.codex/config.toml` onc
 
 The two token limits are fixed defaults, not detected model capabilities. Existing custom values are retained. Writes target the listed keys with format-preserving edits and atomic replacement; this is not a general TOML formatter. Quoted keys, quoted table headers, and explicit dotted shell-environment declarations are recognized; inline shell-environment tables are left intact. Startup and image configuration commands validate UTF-8/TOML and verify that unrelated settings retain their values before writing. An unsafe edit leaves the original file unchanged. 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.
 
+Interactive image setup rereads the shared config after prompts and network validation, so unrelated changes made during setup are preserved. It checks the snapshot again before committing and rejects conflicting image declarations. Identical configuration bytes are not replaced; private file permissions may still be corrected. These checks reduce lost-update risks but are not a filesystem-wide transaction with other applications that do not share a lock.
+
 ## Version 0.7.0 migration
 
 CCDX 0.7.0 retires the former Claude App, Claude Code, Anthropic Messages API, isolated Claude account, and PM Studio patch integrations. Their setup, status, restore, profile, and routing commands are no longer supported.
@@ -111,6 +117,20 @@ The selector first queries the running adapter, including its last-known-good mo
 
 The selection is saved in `~/.config/codex-copilot-dx/config.json`, or under `XDG_CONFIG_HOME` when set. Choosing `gpt-5.5` clears the override and restores the package default. A running adapter reads the setting on the next Auto-review request.
 
+### Runtime caches
+
+```bash
+ccdx cache
+ccdx cache --limit 128
+ccdx cache --limit default
+ccdx cache --clean
+ccdx cache --clean --history
+```
+
+`ccdx cache` separates the shared in-memory Responses history from the rebuildable input-image transform cache. The history limit accepts 16–1024 MiB, is saved in the normal CCDX settings file, and applies immediately to a compatible running adapter. `CCDX_RESPONSE_HISTORY_MAX_BYTES` remains the higher-precedence environment override. Lowering the limit below current usage is rejected rather than evicting tasks silently. `ccdx cache -128` is a short alias for `--limit 128`; `-clean` aliases `--clean`.
+
+Plain `--clean` clears only completed image transforms; the next matching request may recompute them. Adding `--history` also invalidates all process-local `previous_response_id` chains and can make a task's next continuation fail, so it requires interactive confirmation or `--yes`. Cleanup waits for active cache users to finish and never deletes Codex transcripts, generated image files, provider credentials, image edit handles, model catalogs, or usage/debug logs. A stopped or older adapter must be restarted before runtime cleanup; a saved limit applies on the next start.
+
 ### Terminal animation
 
 Choose the terminal activity animation interactively:
@@ -147,6 +167,8 @@ ccdx enable-image
 
 The command accepts an HTTPS base URL or a full `/images/generations` endpoint, then asks for an API key without echoing the key. A bare origin such as `https://api.example` expands to `/v1/images/generations`; `https://api.example/v1` expands to the same endpoint. Custom base paths are retained, and existing full endpoints remain unchanged. CCDX uses GET for the corresponding `/models` catalog and POST for image requests; there is no endpoint-search or automatic fallback. It asks for a numeric model selection only when multiple image models are available, then detects either the standard OpenAI Images request format or the supported `input.messages` format for the selected model only. Its single validation request omits the prompt and does not generate an image.
 
+An empty key answer retains the saved key only when the normalized endpoint has the same origin (scheme, host, and port). Changing origins requires explicitly entering a key before any provider request; the old key is never automatically sent to a new origin.
+
 The provider credential is stored in `~/.config/codex-copilot-dx/image-provider.json`, or under `XDG_CONFIG_HOME`, with mode `0600`. The API key is never written to `~/.codex/config.toml`; that file receives only a marked local MCP entry pointing to the running CCDX adapter with a 210-second tool timeout. Only after enabling, CCDX installs `ccdx-image` guidance under `~/.codex/skills`, with a self-contained Node helper. The concise `SKILL.md` keeps operation selection, safety, and final-image delivery rules; editing details and helper instructions live in references read only for those operations. Codex uses the MCP tool directly, including through deferred tool search; an already-open task without that tool can use the helper to call the same local service and display the saved image. Neither route requires Python, an OpenAI SDK, or copying credentials. Built-in skills and unrelated tools are not modified.
 
 The enable command verifies the local MCP handshake and generation-tool directory without generating an image. It reports provider configuration separately from local service readiness; it cannot assert that every running Codex task has refreshed its catalog. Codex normally detects changed skills; restart Codex App once if an open task has not refreshed them. Normal CCDX startup installs or updates this guidance only for an already-enabled provider, without repeating API setup. Without `enable-image`, it installs neither this skill nor the MCP registration. Unchanged guidance is not rewritten. The existing adapter can remain running because provider settings are loaded when the tool is invoked.
@@ -237,7 +259,9 @@ 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, 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.
+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. Common credential forms, long opaque encrypted values, and explicitly labelled input/prompt/tool-content echoes are redacted. They are cleared when the adapter restarts. No request/response bodies, credential fields, or account profiles are copied into status. Arbitrary upstream prose cannot be guaranteed free of sensitive content; review diagnostics before sharing them.
+
+`image_mcp` has its own HTTP route counter. After the image handler has been used, `image_generation` separately reports active, succeeded, failed, busy, cancelled, and chat-file delivery-failure counts, including tool errors returned with HTTP 200. A delivery failure can accompany a successful generation; it never causes another generation. Before handler initialization this field is `null`, meaning not observed, not necessarily disabled. Status never initializes that handler, reads its provider credential, installs guidance, or probes the provider. Input-image optimization metrics remain separate. `logging` reports pending records/bytes, queue caps, overflow drops, and write failures for usage and enabled debug-file logging.
 
 `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.
 
@@ -269,7 +293,7 @@ Recovery first tries compatible local credentials and starts Device Flow only wh
 - 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.
+- Request/response bodies, request-admission queues, retained history, image work, SSE buffers, log queues, retries, and shutdown have explicit limits. These component limits are not a single process-wide memory ceiling; completed image files are persistent user artifacts, not an automatically evicted cache.
 
 ## Configuration
 
@@ -316,7 +340,7 @@ Recovery first tries compatible local credentials and starts Device Flow only wh
 | `CCDX_EXISTING_ADAPTER_TIMEOUT_MS` | `500` | Timeout for detecting an already-running local adapter during startup |
 | `CCDX_MODEL_REFRESH_TIMEOUT_MS` | `5000` | Timeout for Copilot model refresh or live Auto-review model lookup |
 | `CCDX_MODEL_REFRESH_INTERVAL_MS` | `7200000` | Periodic model refresh interval; `0` disables periodic refresh, while startup cache/refresh behavior still applies |
-| `CCDX_RESPONSE_HISTORY_MAX_BYTES` | `67108864` | Total in-memory byte budget for locally expanded Responses history |
+| `CCDX_RESPONSE_HISTORY_MAX_BYTES` | `67108864` | Higher-precedence total in-memory byte budget for locally expanded Responses history; `ccdx cache --limit` provides a persistent 16–1024 MiB setting when this is unset |
 | `CCDX_RESPONSE_HISTORY_MAX_ENTRIES` | `4096` | Maximum stored incremental Responses history nodes |
 | `CCDX_USAGE_PATH` | `~/.local/share/codex-copilot-dx/usage.jsonl` | Local JSONL token-usage log |
 | `CCDX_USAGE_MAX_BYTES` | `33554432` | Rotate the usage log at this size and retain one `.1` backup; set to `0` to disable rotation |
@@ -333,9 +357,11 @@ ccdx usage
 
 The summary covers the current log and its single rotated backup, not an unbounded lifetime history. It reports recorded responses and per-model input, cache-read, output, and total token metadata.
 
+Usage writes are asynchronous and batched under the existing cross-process rotation lock. Pending and in-flight records share a 4096-record / 4 MiB ceiling. If either ceiling is reached, new excess records are dropped with a warning and a status counter; inference does not wait or retry. Normal records and per-record rotation boundaries are unchanged. The bounded shutdown flush remains 1.5 seconds; disk failures and shutdown deadlines can prevent persistence, so usage is diagnostic rather than a billing ledger.
+
 ## Debug logging
 
-Set `CCDX_LOG_PATH=1` to mirror terminal logs to `~/.local/share/codex-copilot-dx/debug.log`, or provide a custom path. Add `CCDX_LOG_LEVEL=debug` for upstream attempts, retry causes, status codes, and timings. The adapter does not deliberately dump request/response bodies or authorization headers. The log mirror writes console text verbatim, including diagnostic/error messages that can originate in external components, so review logs before sharing them. `ccdx doctor config` bypasses file logging entirely.
+Set `CCDX_LOG_PATH=1` to mirror terminal logs to `~/.local/share/codex-copilot-dx/debug.log`, or provide a custom path. Add `CCDX_LOG_LEVEL=debug` for upstream attempts, retry causes, status codes, and timings. The adapter does not deliberately dump request/response bodies or authorization headers. File diagnostics redact common credential forms and labelled content echoes, but this cannot identify every secret in arbitrary external prose; review logs before sharing them. File writes are asynchronous and batched with a 4096-record / 2 MiB pending-and-in-flight ceiling. Overflow drops excess file records with one warning and a status counter; terminal output continues. CLI exit paths flush for at most 1.5 seconds. `ccdx doctor config` bypasses file logging entirely.
 
 ## Large histories and images
 
@@ -359,6 +385,8 @@ Changing the model or transport of a continuation can require removing incompati
 
 After the stream handshake succeeds, stream liveness uses the idle timeout rather than the expired handshake deadline. Eligible HTTP-200 failure recovery acquires a bounded preparation budget and history admission before rebuilding its payload, then releases those reservations when the retry opens upstream or fails. Normal streams still release preparation admission after their response headers arrive.
 
+Downstream backpressure waits also observe cancellation and the stream deadline. A client that stops reading cannot retain the pending stream indefinitely after timeout; CCDX closes that connection without retrying its request. Final error-frame delivery has a separate one-second maximum drain wait.
+
 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.
 
 CCDX keeps each native Responses message on its first upstream ID when Copilot changes that ID during streaming. Message deltas, completion events, and cached history stay consistent, addressing this cause of duplicate live messages in Codex App. Tool identities, reasoning/encrypted content, message phases, and speed-tier routing are unchanged by this ID normalization. Stable events retain their original SSE bytes; changed events are rewritten with bounded, backpressured streaming.

package/bin/cli.mjs

@@ -16,13 +16,14 @@ import { cliCommandName, cliHelp, parseAdapterAddressOptions, parseAdapterProbeO
 import { formatAdapterStatus, readAdapterStatus } from "../src/cli-status.mjs";
 import { closeHttpServer } from "../src/shutdown.mjs";
 import { runAutoReviewModelCommand } from "../src/auto-review-model.mjs";
-import { autoReviewModelPreference, terminalAnimationPreference } from "../src/user-settings.mjs";
+import { autoReviewModelPreference, responseHistoryLimitPreference, terminalAnimationPreference } from "../src/user-settings.mjs";
 import { fetchLiveCopilotModels, formatLiveCopilotModels } from "../src/cli-models.mjs";
 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";
+import { setResponseHistoryMaxBytes } from "../src/response-history.mjs";
 
 const LOCAL_VERSION = localPackageVersion();
 const CLI_NAME = cliCommandName();
@@ -80,6 +81,26 @@ if (CLI.command === "usage") {
   });
   process.exit(0);
 }
+if (CLI.command === "cache") {
+  try {
+    const probe = parseAdapterProbeOptions(process.env);
+    const { runCacheCommand } = await import("../src/cli-cache.mjs");
+    await runCacheCommand({
+      action: CLI.action,
+      limitMib: CLI.limitMib,
+      resetLimit: CLI.resetLimit,
+      history: CLI.history,
+      yes: CLI.yes,
+      host: probe.adapterHost,
+      port: probe.adapterPort,
+      timeoutMs: probe.existingAdapterTimeoutMs,
+    });
+    process.exit(0);
+  } catch (e) {
+    console.error(status("err", e.message));
+    process.exit(1);
+  }
+}
 if (CLI.command === "retired") {
   console.error(status("err", `${CLI.integration} integration was retired in ccdx 0.7.0.`));
   if (CLI.integration === "PM Studio") {
@@ -182,6 +203,7 @@ if (CLI.command === "doctor" && CLI.configOnly) {
 let RUNTIME;
 try {
   RUNTIME = parseRuntimeOptions(process.env);
+  setResponseHistoryMaxBytes(responseHistoryLimitPreference().bytes);
 } catch (e) {
   console.error(e.message);
   process.exit(2);
@@ -248,6 +270,7 @@ if (CLI.command === "doctor") {
     online: CLI.online,
     compat: CLI.compat,
   });
+  await LOGGING.cleanup();
   process.exit(checks.some((check) => check.kind === "err") ? 1 : 0);
 }
 
@@ -270,7 +293,10 @@ async function printUpdateNotice() {
 try {
   assertSafeAdapterHost(ADAPTER_HOST, process.env);
   void runInBackground(printUpdateNotice);
-  if (await reuseRunningAdapterIfAvailable()) process.exit(0);
+  if (await reuseRunningAdapterIfAvailable()) {
+    await LOGGING.cleanup();
+    process.exit(0);
+  }
 
   // Ensure GitHub login, using device flow if no token exists.
   await ensureAuth();
@@ -347,7 +373,7 @@ try {
       exitCode = 1;
       console.error(status("err", `Shutdown failed: ${e.message}`));
     } finally {
-      LOGGING.cleanup();
+      await LOGGING.cleanup();
       process.exit(exitCode);
     }
   };
@@ -357,6 +383,6 @@ try {
   console.error(status("err", e.message));
   await closeHttpServer(activeServer, { timeoutMs: RUNTIME.shutdownTimeoutMs }).catch(() => {});
   await flushUsageWrites();
-  LOGGING.cleanup();
+  await LOGGING.cleanup();
   process.exit(1);
 }

package/package.json

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

package/src/adapter.mjs

@@ -17,12 +17,19 @@ 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 {
+  ADAPTER_CACHE_PATH,
+  cacheRuntimeSnapshot,
+  cleanRuntimeCaches,
+  setHistoryCacheLimit,
+} from "./cache-control.mjs";
 import { loadRuntimeConfig, parsePositiveInteger } from "./runtime-config.mjs";
 import {
   createRequestAdmission,
   createRequestAbort,
   httpError,
   logRequestFailure,
+  readJsonBody,
   sendJsonError,
 } from "./http-transport.mjs";
 
@@ -192,7 +199,7 @@ export function createAdapterHandler(options = {}) {
     streamIdleTimeoutMs,
     upstreamTimeoutMs,
   });
-  const dispatch = (req, res, pathname) => {
+  const dispatch = async (req, res, pathname) => {
     if (pathname === "/mcp/image") {
       if (imageMcpHandler) return imageMcpHandler(req, res);
       return import("./image-mcp.mjs").then(({ createImageMcpHandler }) => {
@@ -213,6 +220,7 @@ export function createAdapterHandler(options = {}) {
         admission: acquireRequest,
         imagePressure,
         responseFailures,
+        imageGeneration: imageMcpHandler?.stats?.(),
         modelRegistry: codexModelRegistry,
         codexClient,
         codexModelRegistry,
@@ -226,6 +234,56 @@ export function createAdapterHandler(options = {}) {
       return;
     }
 
+    if (pathname === ADAPTER_CACHE_PATH) {
+      if (!isLoopbackAddress(req.socket?.remoteAddress)) {
+        res.writeHead(403, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Cache control is available only from loopback" }));
+        return;
+      }
+      if (req.method === "GET") {
+        res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+        res.end(JSON.stringify(cacheRuntimeSnapshot()));
+        return;
+      }
+      if (req.method !== "POST") {
+        res.writeHead(405, { "Content-Type": "application/json", Allow: "GET, POST" });
+        res.end(JSON.stringify({ error: "Only GET and POST are supported" }));
+        return;
+      }
+      if (Object.hasOwn(req.headers || {}, "origin")) {
+        res.writeHead(403, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Browser origins are not allowed for cache control" }));
+        return;
+      }
+      const mediaType = String(req.headers?.["content-type"] || "").split(";", 1)[0].trim().toLowerCase();
+      if (mediaType !== "application/json") {
+        res.writeHead(415, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Cache control requires application/json" }));
+        return;
+      }
+      const abort = createRequestAbort(req, res);
+      abort.setTimeout(requestBodyTimeoutMs, "request_body_timeout");
+      try {
+        const body = await readJsonBody(req, {
+          maxBodyBytes: 8 * 1024,
+          maxDecodedBodyBytes: 8 * 1024,
+          signal: abort.signal,
+        });
+        let result;
+        if (body?.action === "set_limit") result = setHistoryCacheLimit(body.max_bytes);
+        else if (body?.action === "clean") result = cleanRuntimeCaches({ history: body.history === true });
+        else throw httpError("Unknown cache action", 400);
+        res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+        res.end(JSON.stringify(result));
+      } catch (error) {
+        if (["ccdx_cache_busy", "ccdx_cache_limit_below_usage"].includes(error?.code)) error.statusCode = 409;
+        sendJsonError(res, error, 400);
+      } finally {
+        abort.cleanup();
+      }
+      return;
+    }
+
     if (req.method === "POST" && pathname === "/v1/responses") {
       return responsesHandler(req, res);
     }
@@ -237,7 +295,12 @@ export function createAdapterHandler(options = {}) {
     if (req.method === "GET" && pathname === "/v1/models") {
       const clientVersion = modelClientVersion(req.url);
       const abort = createRequestAbort(req, res);
-      abort.setTimeout(upstreamTimeoutMs);
+      // Keep live discovery and explicit auth failures authoritative, but do
+      // not make a usable cached picker wait the full inference timeout.
+      const modelTimeoutMs = isValidModelList(codexModelRegistry?.models)
+        ? Math.min(upstreamTimeoutMs, parsePositiveInteger(options.cachedModelsTimeoutMs, 1500))
+        : upstreamTimeoutMs;
+      abort.setTimeout(modelTimeoutMs);
       listModelsFn({ signal: abort.signal })
         .then(async ({ status, body }) => {
           abort.clearTimeout();
@@ -308,7 +371,9 @@ export function createAdapterHandler(options = {}) {
       return;
     }
 
-    const trackRequest = pathname !== ADAPTER_HEALTH_PATH && pathname !== ADAPTER_STATUS_PATH;
+    const trackRequest = pathname !== ADAPTER_HEALTH_PATH
+      && pathname !== ADAPTER_STATUS_PATH
+      && pathname !== ADAPTER_CACHE_PATH;
     const routeName = classifyAdapterRoute(req.method, pathname);
     const complete = trackRequest ? requestMetrics.begin(routeName) : () => {};
     const streamPerformance = trackRequest ? streamPerformanceMetrics.begin(routeName) : null;

package/src/cache-control.mjs

@@ -0,0 +1,59 @@
+import {
+  MIB,
+  RESPONSE_HISTORY_MAX_MIB,
+  RESPONSE_HISTORY_MIN_MIB,
+} from "./cache-limits.mjs";
+import {
+  clearResponseHistory,
+  responseHistoryStats,
+  setResponseHistoryMaxBytes,
+} from "./response-history.mjs";
+import {
+  clearImageOptimizationCache,
+  imageOptimizationStats,
+} from "./image-optimization.mjs";
+
+export const ADAPTER_CACHE_PATH = "/_ccdx/cache";
+
+export function cacheRuntimeSnapshot() {
+  return {
+    response_history: responseHistoryStats(),
+    image_optimization: imageOptimizationStats(),
+  };
+}
+
+export function setHistoryCacheLimit(maxBytes) {
+  const mib = Number(maxBytes) / MIB;
+  if (!Number.isSafeInteger(mib)
+    || mib < RESPONSE_HISTORY_MIN_MIB
+    || mib > RESPONSE_HISTORY_MAX_MIB) {
+    const error = new Error(`History cache limit must be an integer from ${RESPONSE_HISTORY_MIN_MIB} to ${RESPONSE_HISTORY_MAX_MIB} MiB`);
+    error.code = "ccdx_cache_limit_invalid";
+    throw error;
+  }
+  return { changed: setResponseHistoryMaxBytes(maxBytes).previousMaxBytes !== maxBytes, ...cacheRuntimeSnapshot() };
+}
+
+export function cleanRuntimeCaches({ history = false } = {}) {
+  const imageStats = imageOptimizationStats();
+  if (imageStats.active > 0 || imageStats.queued > 0 || imageStats.cache_inflight > 0) {
+    const error = new Error("Image optimization is active; retry cache cleanup after current requests finish");
+    error.code = "ccdx_cache_busy";
+    throw error;
+  }
+  const historyStats = responseHistoryStats();
+  if (history && historyStats.pinnedTrees > 0) {
+    const error = new Error("Response history is active; retry cleanup after current requests finish");
+    error.code = "ccdx_cache_busy";
+    throw error;
+  }
+  const imageOptimization = clearImageOptimizationCache();
+  const responseHistory = history ? clearResponseHistory() : null;
+  return {
+    cleaned: {
+      image_optimization: imageOptimization,
+      ...(responseHistory ? { response_history: responseHistory } : {}),
+    },
+    ...cacheRuntimeSnapshot(),
+  };
+}

package/src/cache-limits.mjs

@@ -0,0 +1,4 @@
+export const RESPONSE_HISTORY_DEFAULT_MIB = 64;
+export const RESPONSE_HISTORY_MIN_MIB = 16;
+export const RESPONSE_HISTORY_MAX_MIB = 1024;
+export const MIB = 1024 * 1024;

package/src/cli-cache.mjs

@@ -0,0 +1,147 @@
+import { createInterface } from "node:readline/promises";
+import os from "node:os";
+import { ADAPTER_CACHE_PATH } from "./cache-control.mjs";
+import { MIB, RESPONSE_HISTORY_DEFAULT_MIB } from "./cache-limits.mjs";
+import { adapterBaseUrl } from "./running-adapter.mjs";
+import {
+  readUserSettings,
+  responseHistoryLimitPreference,
+  writeResponseHistoryLimitMib,
+} from "./user-settings.mjs";
+
+const RESPONSE_HISTORY_MAX_MIB_KEY = "response_history_max_mib";
+
+function mib(bytes) {
+  const value = Number(bytes);
+  return Number.isFinite(value) ? `${(value / MIB).toFixed(value % MIB === 0 ? 0 : 1)} MiB` : "unknown";
+}
+
+async function cacheRequest(baseUrl, { body, fetchImpl, timeoutMs }) {
+  const response = await fetchImpl(`${baseUrl}${ADAPTER_CACHE_PATH}`, {
+    method: body ? "POST" : "GET",
+    headers: { Accept: "application/json", ...(body ? { "Content-Type": "application/json" } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  let payload;
+  try { payload = await response.json(); } catch { payload = null; }
+  if (!response.ok) {
+    const error = new Error(payload?.error || `Cache control returned HTTP ${response.status}`);
+    error.statusCode = response.status;
+    throw error;
+  }
+  return payload;
+}
+
+async function runningSnapshot(baseUrl, options) {
+  try { return { supported: true, data: await cacheRequest(baseUrl, options) }; }
+  catch (error) {
+    if ([404, 405].includes(error?.statusCode)) return { supported: false, error };
+    if (error?.name === "TimeoutError" || error?.cause?.code === "ECONNREFUSED") return { supported: false, offline: true, error };
+    throw error;
+  }
+}
+
+async function confirmHistoryCleanup({ input, output, prompt, yes }) {
+  if (yes) return;
+  if (prompt) {
+    if (!await prompt()) throw new Error("History cache cleanup cancelled");
+    return;
+  }
+  if (!input.isTTY || !output.isTTY) {
+    throw new Error("History cleanup can break task continuation; rerun with --yes to confirm");
+  }
+  const readline = createInterface({ input, output });
+  try {
+    const answer = String(await readline.question(
+      "Clear response history for all tasks? Their next continuation may fail [y/N]: ",
+    )).trim().toLowerCase();
+    if (!["y", "yes"].includes(answer)) throw new Error("History cache cleanup cancelled");
+  } finally { readline.close(); }
+}
+
+function formatStatus(preference, runtime) {
+  const lines = ["ccdx cache", `Configured history limit: ${mib(preference.bytes)} (${preference.source})`];
+  if (!runtime?.supported) {
+    lines.push(runtime?.offline
+      ? "Runtime cache: adapter is not running"
+      : "Runtime cache: restart ccdx to enable cache control");
+    return lines.join("\n");
+  }
+  const history = runtime.data.response_history || {};
+  const images = runtime.data.image_optimization || {};
+  lines.push(
+    `History: ${mib(history.bytes)} / ${mib(history.maxBytes)}, ${history.entries || 0} entries, ${history.evicted || 0} evicted`,
+    `Image transforms: ${mib(images.cache_bytes)} / ${mib(images.cache_max_bytes)}, ${images.cache_entries || 0} entries`,
+  );
+  return lines.join("\n");
+}
+
+export async function runCacheCommand({
+  action = "status",
+  limitMib,
+  resetLimit = false,
+  history = false,
+  yes = false,
+  env = process.env,
+  home = os.homedir(),
+  host = "127.0.0.1",
+  port = 2026,
+  input = process.stdin,
+  output = process.stdout,
+  prompt,
+  fetchImpl = fetch,
+  timeoutMs = 1000,
+} = {}) {
+  const baseUrl = adapterBaseUrl(host, port);
+  const requestOptions = { fetchImpl, timeoutMs };
+  const preference = responseHistoryLimitPreference({ env, home });
+  const runtime = await runningSnapshot(baseUrl, requestOptions);
+  if (action === "status") {
+    const text = formatStatus(preference, runtime);
+    output.write(`${text}\n`);
+    return { preference, runtime };
+  }
+  if (action === "limit") {
+    if (String(env.CCDX_RESPONSE_HISTORY_MAX_BYTES || "").trim()) {
+      throw new Error("CCDX_RESPONSE_HISTORY_MAX_BYTES overrides saved cache settings; unset it before using ccdx cache --limit");
+    }
+    const targetMib = resetLimit ? RESPONSE_HISTORY_DEFAULT_MIB : Number(limitMib);
+    const targetBytes = targetMib * MIB;
+    if (runtime.supported && targetBytes < runtime.data.response_history.bytes) {
+      throw new Error(`History currently uses ${mib(runtime.data.response_history.bytes)}; clean history or choose a larger limit`);
+    }
+    const previous = readUserSettings({ env, home, strict: true });
+    const previousMib = Object.hasOwn(previous, RESPONSE_HISTORY_MAX_MIB_KEY)
+      ? previous[RESPONSE_HISTORY_MAX_MIB_KEY]
+      : null;
+    const saved = writeResponseHistoryLimitMib(resetLimit ? null : targetMib, { env, home });
+    try {
+      if (runtime.supported) {
+        await cacheRequest(baseUrl, { ...requestOptions, body: { action: "set_limit", max_bytes: targetBytes } });
+      }
+    } catch (error) {
+      writeResponseHistoryLimitMib(previousMib, { env, home });
+      throw error;
+    }
+    output.write(`History cache limit: ${targetMib} MiB${runtime.supported ? " (active now)" : " (saved; restart ccdx to apply)"}\n`);
+    return { ...saved, active: runtime.supported };
+  }
+  if (action === "clean") {
+    if (!runtime.supported) throw new Error("Start or restart ccdx before cleaning runtime caches");
+    if (history) await confirmHistoryCleanup({ input, output, prompt, yes });
+    const result = await cacheRequest(baseUrl, {
+      ...requestOptions,
+      body: { action: "clean", history },
+    });
+    const images = result.cleaned.image_optimization;
+    output.write(`Cleared image transform cache: ${images.entries} entries, ${mib(images.bytes)}\n`);
+    if (history) {
+      const cleared = result.cleaned.response_history;
+      output.write(`Cleared response history: ${cleared.entries} entries, ${mib(cleared.bytes)}\n`);
+      output.write("Saved Codex transcripts and generated image files were not deleted.\n");
+    }
+    return result;
+  }
+  throw new Error(`Unknown cache action: ${action}`);
+}

package/src/cli-image.mjs

@@ -3,7 +3,7 @@ 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 { atomicWriteFileIfChangedSync, atomicWriteFilePairSync } from "./atomic-file.mjs";
 import { terminalCell } from "./cli-table.mjs";
 import { computeImageMcpCodexConfig } from "./config.mjs";
 import { probeImageTool } from "./image-readiness.mjs";
@@ -11,6 +11,7 @@ import { updateImageSkill } from "./image-skill.mjs";
 import {
   imageProviderConfigPath,
   inspectImageProvider,
+  normalizeImageEndpoint,
   readImageProviderConfig,
   validateImageProviderConfig,
 } from "./image-provider-config.mjs";
@@ -110,12 +111,15 @@ function enableImageProvider({ providerConfig, providerPath, codexPath, codexCon
   const normalized = validateImageProviderConfig(providerConfig, { filePath: providerPath });
   const skill = updateImageSkill({ enabled: true, codexPath, adapterPort, adapterHost });
   try {
+    if (fileContent(codexPath) !== codexContent) {
+      throw new Error("Codex configuration changed during image setup; retry to preserve the newer settings");
+    }
     atomicWriteFilePairSync(
       codexPath,
       codex.content,
       providerPath,
       `${JSON.stringify(normalized, null, 2)}\n`,
-      { mode: 0o600 },
+      { mode: 0o600, writeFile: atomicWriteFileIfChangedSync },
     );
   } catch (error) {
     skill.rollback();
@@ -134,7 +138,12 @@ function disableImageProvider({ providerPath, codexPath, codexContent, adapterPo
   const skill = updateImageSkill({ enabled: false, codexPath, adapterPort, adapterHost });
   try {
     if (fs.existsSync(codexPath)) {
-      atomicWriteFilePairSync(codexPath, codex.content, providerPath, null, { mode: 0o600 });
+      if (fileContent(codexPath) !== codexContent) {
+        throw new Error("Codex configuration changed during image cleanup; retry to preserve the newer settings");
+      }
+      atomicWriteFilePairSync(codexPath, codex.content, providerPath, null, {
+        mode: 0o600, writeFile: atomicWriteFileIfChangedSync,
+      });
     } else if (providerExists) {
       fs.unlinkSync(providerPath);
     }
@@ -203,10 +212,11 @@ export async function runImageCommand({
   output.write(`${commandName} enable-image\n`);
   output.write("Enter an HTTPS base URL (for example, https://api.example/v1) or a full /images/generations endpoint.\n");
   const endpointAnswer = String(await ask(`API base URL or endpoint${current ? ` [${current.endpoint}]` : ""}: `) || "").trim();
-  const endpoint = endpointAnswer || current?.endpoint;
-  if (!endpoint) throw new Error("Image API base URL or endpoint is required");
-  const keyAnswer = String(await askSecret(`API key${current ? " [Enter to keep current]" : ""}: `) || "").trim();
-  const apiKey = keyAnswer || current?.api_key;
+  if (!endpointAnswer && !current?.endpoint) throw new Error("Image API base URL or endpoint is required");
+  const endpoint = normalizeImageEndpoint(endpointAnswer || current.endpoint);
+  const sameOrigin = current && new URL(endpoint).origin === new URL(current.endpoint).origin;
+  const keyAnswer = String(await askSecret(`API key${sameOrigin ? " [Enter to keep current]" : current ? " [new origin; enter a key]" : ""}: `) || "").trim();
+  const apiKey = keyAnswer || (sameOrigin ? current.api_key : undefined);
   if (!apiKey) throw new Error("Image API key is required");
 
   output.write("Checking image API...\n");
@@ -227,7 +237,9 @@ export async function runImageCommand({
     },
     providerPath,
     codexPath,
-    codexContent,
+    // Prompts and provider validation may take minutes. Merge into the latest
+    // shared file rather than replacing edits made while we were waiting.
+    codexContent: fileContent(codexPath),
     adapterPort,
     adapterHost,
   });