codex-copilot-dx 0.8.4 → 0.8.5

package/README.md

@@ -18,15 +18,17 @@ 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.
 
@@ -115,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:
@@ -324,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 |

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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.8.4",
+  "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 }) => {
@@ -227,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);
     }
@@ -314,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-options.mjs

@@ -20,6 +20,7 @@ const HELP_TOPICS = new Set([
   "status",
   "models",
   "usage",
+  "cache",
   "animation",
   "enable-image",
   "disable-image",
@@ -155,6 +156,37 @@ export function parseCliArgs(args = []) {
     const options = parseOptions(rest, new Map([["--format", "value"]]));
     return baseCommand("usage", outputFormatOption(options["--format"]));
   }
+  if (command === "cache") {
+    let cacheArgs = rest;
+    if (rest.length === 1 && /^-\d+$/.test(rest[0])) {
+      cacheArgs = ["--limit", rest[0].slice(1)];
+    } else if (rest[0] === "-clean") {
+      cacheArgs = ["--clean", ...rest.slice(1)];
+    }
+    const options = parseOptions(cacheArgs, new Map([
+      ["--limit", "value"],
+      ["--clean", "flag"],
+      ["--history", "flag"],
+      ["--yes", "flag"],
+    ]));
+    if (options["--limit"] && options["--clean"]) {
+      throw new Error("Use --limit or --clean in one cache command, not both");
+    }
+    if ((options["--history"] || options["--yes"]) && !options["--clean"]) {
+      throw new Error("--history and --yes require --clean");
+    }
+    const rawLimit = options["--limit"];
+    if (rawLimit && rawLimit !== "default" && !/^\d+$/.test(rawLimit)) {
+      throw new Error(`Cache limit must be an integer MiB value or default: ${rawLimit}`);
+    }
+    return baseCommand("cache", {
+      action: rawLimit ? "limit" : options["--clean"] ? "clean" : "status",
+      limitMib: rawLimit && rawLimit !== "default" ? Number(rawLimit) : undefined,
+      resetLimit: rawLimit === "default",
+      history: Boolean(options["--history"]),
+      yes: Boolean(options["--yes"]),
+    });
+  }
   if (PM_COMMANDS.has(command)) {
     return baseCommand("retired", { integration: "PM Studio" });
   }
@@ -301,6 +333,7 @@ function topicHelp(name, topic) {
     status: `Usage:\n  ${name} status\n\nShows bounded runtime, routing, performance, queue, and cache metrics from a running adapter.`,
     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.`,
+    cache: `Usage:\n  ${name} cache\n  ${name} cache --limit <MiB|default>\n  ${name} cache --clean [--history] [--yes]\n\nShows runtime cache use, saves and applies the shared response-history limit, or clears the rebuildable image-transform cache. --history also clears in-memory response history for all tasks and can make their next continuation fail, so interactive confirmation or --yes is required. Generated image files and saved Codex transcripts are never deleted. Short aliases: -128 sets 128 MiB and -clean equals --clean.`,
     animation: `Usage:\n  ${name} animation\n\nPreviews all terminal activity animations together and selects the theme used the next time the adapter starts.`,
     "enable-image": `Usage:\n  ${name} enable-image\n\nInteractively configures an HTTPS image API endpoint (base URLs are also accepted) 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. A blank key preserves the saved key only for the same origin; a new origin requires explicit key entry. Concurrent unrelated config edits are preserved.`,
     "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.`,
@@ -324,6 +357,7 @@ export function cliHelp(commandName = "ccdx", topic = "") {
   ${name} status
   ${name} models [--format table|plain]
   ${name} usage [--format table|plain]
+  ${name} cache [--limit <MiB|default> | --clean [--history] [--yes]]
   ${name} animation
   ${name} enable-image
   ${name} disable-image
@@ -340,6 +374,7 @@ Commands:
   status             Show runtime routing, performance, queue, and cache health
   models             Query a saved account's live Copilot model catalog
   usage              Summarize locally recorded token usage
+  cache              Inspect, size, or clear bounded runtime caches
   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

package/src/codex-model-catalog.mjs

@@ -4,6 +4,30 @@ import os from "node:os";
 import path from "node:path";
 import { CODEX_GPT6_MODEL } from "./models.mjs";
 
+// Compatibility metadata is derived from OpenAI Codex's public models catalog
+// at commit 0a2eb4696c26ac33204bcd255721ab30220a4774. The installed client's
+// GPT-6 Astra entry supplies its own schema and instructions; these overrides
+// describe only the two new model identities and capability differences.
+const GPT6_COMPATIBILITY_SPECS = new Map([
+  ["gpt-6-sol", Object.freeze({
+    display_name: "GPT-6-Sol",
+    description: "Workhorse model for coding and everyday work.",
+    default_reasoning_level: "medium",
+    shell_type: "shell_command",
+    priority: 2,
+    node_repl_auto_review_required: true,
+  })],
+  ["gpt-6-luna", Object.freeze({
+    display_name: "GPT-6-Luna",
+    description: "Fast and affordable model for easier tasks.",
+    default_reasoning_level: "medium",
+    shell_type: "shell_command",
+    priority: 3,
+    node_repl_auto_review_required: false,
+  })],
+]);
+const MANAGED_GPT6_MODELS = new Set([CODEX_GPT6_MODEL, ...GPT6_COMPATIBILITY_SPECS.keys()]);
+
 export { CODEX_GPT6_MODEL };
 
 export const CODEX_APP_BINARY_PATHS = [
@@ -50,29 +74,81 @@ function isEligibleOpenAIModel(model, id) {
     && supportsResponses(model);
 }
 
-export function isEligibleCopilotGpt6(copilotModels) {
+export function isEligibleCopilotGpt6(copilotModels, id = CODEX_GPT6_MODEL) {
   const data = copilotModelData(copilotModels);
   if (!data) return false;
-  const matches = data.filter((model) => String(model?.id || "").trim() === CODEX_GPT6_MODEL);
-  return matches.length === 1 && isEligibleOpenAIModel(matches[0], CODEX_GPT6_MODEL);
+  const matches = data.filter((model) => String(model?.id || "").trim() === id);
+  return matches.length === 1 && isEligibleOpenAIModel(matches[0], id);
+}
+
+function copilotModel(copilotModels, id) {
+  return copilotModelData(copilotModels)?.find((model) => String(model?.id || "").trim() === id);
+}
+
+function advertisedReasoningEfforts(model) {
+  const values = model?.capabilities?.supports?.reasoning_effort;
+  return new Set(Array.isArray(values) ? values.map((value) => String(value)) : []);
+}
+
+function catalogModelForCopilot(model, copilotModels, { filterReasoning = false } = {}) {
+  const upstream = copilotModel(copilotModels, model.slug);
+  const reasoning = advertisedReasoningEfforts(upstream);
+  const patched = {
+    ...structuredClone(model),
+    visibility: "list",
+    supported_reasoning_levels: filterReasoning && reasoning.size
+      ? model.supported_reasoning_levels.filter(({ effort }) => reasoning.has(effort))
+      : model.supported_reasoning_levels,
+  };
+  // The Codex catalog describes ChatGPT service tiers. Copilot must advertise
+  // an exact fast model before CCDX exposes the corresponding selector.
+  if (!isEligibleCopilotGpt6(copilotModels, `${model.slug}-fast`)) {
+    patched.additional_speed_tiers = [];
+    patched.service_tiers = [];
+    delete patched.default_service_tier;
+  }
+  return patched;
+}
+
+function compatibilityModel(codexCatalog, slug) {
+  const astra = codexCatalog.models.find((model) => model.slug === CODEX_GPT6_MODEL);
+  const spec = GPT6_COMPATIBILITY_SPECS.get(slug);
+  if (!astra || !spec) return null;
+  return {
+    ...structuredClone(astra),
+    ...spec,
+    slug,
+    supports_parallel_tool_calls: true,
+    multi_agent_reasoning_effort: null,
+    supports_experimental_context: false,
+    minimal_client_version: "0.155.0",
+  };
+}
+
+function insertByPriority(models, model) {
+  const priority = Number(model.priority);
+  const index = models.findIndex((candidate) => Number.isFinite(priority)
+    && Number.isFinite(Number(candidate.priority))
+    && Number(candidate.priority) > priority);
+  if (index < 0) models.push(model);
+  else models.splice(index, 0, model);
 }
 
 export function buildCodexModelResponse({ copilotModels, codexCatalog } = {}) {
   if (!copilotModelData(copilotModels) || !codexCatalogIsValid(codexCatalog)) return null;
 
-  const exposeGpt6 = isEligibleCopilotGpt6(copilotModels);
+  const bundledSlugs = new Set(codexCatalog.models.map(({ slug }) => slug));
   const models = codexCatalog.models.map((model) => {
-    if (model.slug !== CODEX_GPT6_MODEL) return model;
-    if (!exposeGpt6) return { ...model, visibility: "hide" };
-    const patched = {
-      ...model,
-      visibility: "list",
-      additional_speed_tiers: [],
-      service_tiers: [],
-    };
-    delete patched.default_service_tier;
-    return patched;
+    if (!MANAGED_GPT6_MODELS.has(model.slug)) return model;
+    if (!isEligibleCopilotGpt6(copilotModels, model.slug)) return { ...model, visibility: "hide" };
+    return catalogModelForCopilot(model, copilotModels);
   });
+  for (const slug of GPT6_COMPATIBILITY_SPECS.keys()) {
+    if (bundledSlugs.has(slug) || !isEligibleCopilotGpt6(copilotModels, slug)) continue;
+    const model = compatibilityModel(codexCatalog, slug);
+    if (!model) continue;
+    insertByPriority(models, catalogModelForCopilot(model, copilotModels, { filterReasoning: true }));
+  }
 
   return { ...copilotModels, object: copilotModels.object || "list", models };
 }

package/src/image-optimization.mjs

@@ -159,6 +159,18 @@ export function imageOptimizationStats() {
   };
 }
 
+export function clearImageOptimizationCache() {
+  const stats = imageOptimizationStats();
+  if (stats.active > 0 || stats.queued > 0 || stats.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 removed = { entries: stats.cache_entries, bytes: stats.cache_bytes };
+  imageResultCache.clear();
+  return removed;
+}
+
 export function resetImageOptimizationCacheForTests() {
   imageResultCache.clear();
 }

package/src/models.mjs

@@ -26,8 +26,8 @@ export function modelIsResponsesOnly(model) {
 
 export function resolveCopilotPriorityTierModel(model, serviceTier, models) {
   const baseModel = String(model || "").trim();
-  if (baseModel !== "gpt-5.6-sol" || serviceTier !== "priority") return null;
-  const fastModelId = "gpt-5.6-sol-fast";
+  if (!baseModel.startsWith("gpt-") || serviceTier !== "priority") return null;
+  const fastModelId = `${baseModel}-fast`;
   const fastModel = copilotModelData(models)
     .find((entry) => String(entry?.id || "").trim() === fastModelId);
   const vendor = String(fastModel?.vendor || fastModel?.owned_by || "").trim().toLowerCase();

package/src/observability.mjs

@@ -167,6 +167,7 @@ export function runtimeStatusPayload({
   const memory = process.memoryUsage();
   const codexRuntime = safeClientRuntimeStatus(codexClient);
   const codexModels = modelRegistryStatus(codexModelRegistry || modelRegistry);
+  const history = responseHistoryStats();
   return {
     ...adapterHealthPayload(),
     uptime_ms: Math.round(process.uptime() * 1000),
@@ -180,7 +181,7 @@ export function runtimeStatusPayload({
     requests: metrics?.snapshot?.() || createRequestMetrics().snapshot(),
     stream_performance: streamPerformance?.snapshot?.() || null,
     admission: admission?.diagnostics?.() || admission?.stats?.() || null,
-    response_history: responseHistoryStats(),
+    response_history: history,
     image_optimization: imageOptimizationStats(),
     image_generation: imageGeneration || null,
     logging: { usage: usageLoggingStats(), debug: debugLoggingStats() },
@@ -196,8 +197,8 @@ export function runtimeStatusPayload({
       max_body_bytes: OBSERVABILITY_RUNTIME_CONFIG.maxBodyBytes,
       max_decoded_body_bytes: OBSERVABILITY_RUNTIME_CONFIG.maxDecodedBodyBytes,
       max_sse_buffer_bytes: OBSERVABILITY_RUNTIME_CONFIG.maxSseBufferBytes,
-      response_history_max_bytes: OBSERVABILITY_RUNTIME_CONFIG.responseHistoryMaxBytes,
-      response_history_max_entries: OBSERVABILITY_RUNTIME_CONFIG.responseHistoryMaxEntries,
+      response_history_max_bytes: history.maxBytes,
+      response_history_max_entries: history.maxEntries,
     },
   };
 }

package/src/response-history.mjs

@@ -203,24 +203,51 @@ function makeRoomFor({ additionalBytes, additionalEntries, protectedRoots }) {
   return true;
 }
 
-export function clearResponseHistoryForTests() {
+export function clearResponseHistory() {
+  if (pinnedTrees.size > 0) {
+    const error = new Error("Response history is active; retry cleanup after current requests finish");
+    error.code = "ccdx_cache_busy";
+    throw error;
+  }
+  const removed = { entries: histories.size, bytes: totalBytes };
   histories.clear();
   childrenById.clear();
   treeLru.clear();
   pinnedTrees.clear();
   evictedIds.clear();
   totalBytes = 0;
+  return removed;
+}
+
+export function clearResponseHistoryForTests() {
+  clearResponseHistory();
   maxBytes = DEFAULT_MAX_BYTES;
   maxEntries = DEFAULT_MAX_ENTRIES;
 }
 
+export function setResponseHistoryMaxBytes(nextMaxBytes) {
+  const parsed = Number(nextMaxBytes);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new TypeError("Response history cache limit must be a positive safe integer");
+  }
+  if (parsed < totalBytes) {
+    const error = new Error(`Response history currently uses ${totalBytes} bytes, above the requested ${parsed}-byte limit`);
+    error.code = "ccdx_cache_limit_below_usage";
+    throw error;
+  }
+  const previousMaxBytes = maxBytes;
+  maxBytes = parsed;
+  return { previousMaxBytes, maxBytes };
+}
+
 export function configureResponseHistoryForTests({ maxBytes: nextMaxBytes, maxEntries: nextMaxEntries } = {}) {
   if (nextMaxBytes !== undefined) maxBytes = parsePositiveInteger(nextMaxBytes, DEFAULT_MAX_BYTES);
   if (nextMaxEntries !== undefined) maxEntries = parsePositiveInteger(nextMaxEntries, DEFAULT_MAX_ENTRIES);
 }
 
 export function responseHistoryStats() {
-  return { entries: histories.size, bytes: totalBytes, evicted: evictedIds.size };
+  return { entries: histories.size, bytes: totalBytes, evicted: evictedIds.size,
+    pinnedTrees: pinnedTrees.size, maxBytes, maxEntries };
 }
 
 export function responseHistoryRootId(responseId) {

package/src/responses-handler.mjs

@@ -89,9 +89,10 @@ function resolveRequestModel(model, openAIModelEnv, autoReviewModelResolver) {
   return resolveOpenAIModel(model, openAIModelEnv, options);
 }
 
-function stripUnsupportedGpt6ServiceTier(body, requestedModel, upstreamModel) {
-  if (requestedModel === CODEX_GPT6_MODEL
+function stripUnsupportedGpt6ServiceTier(body, requestedModel, upstreamModel, priorityTierModel) {
+  if (requestedModel.startsWith("gpt-6-")
     && upstreamModel === requestedModel
+    && !priorityTierModel
     && body.service_tier === "priority") {
     delete body.service_tier;
   }
@@ -263,7 +264,7 @@ export function createResponsesHandler(options) {
         upstreamModel = priorityTierModel;
         delete prepared.body.service_tier;
       }
-      stripUnsupportedGpt6ServiceTier(prepared.body, requestedModel, upstreamModel);
+      stripUnsupportedGpt6ServiceTier(prepared.body, requestedModel, upstreamModel, priorityTierModel);
       if (requestedModel === CODEX_AUTO_REVIEW_MODEL) delete prepared.body.service_tier;
       if (upstreamModel !== requestedModel) prepared.body.model = upstreamModel;
       const upstreamLog = upstreamModel === requestedModel ? "" : ` upstream_model=${upstreamModel}`;
@@ -516,7 +517,7 @@ export function createResponsesCompactHandler(options) {
         upstreamModel = priorityTierModel;
         delete prepared.body.service_tier;
       }
-      stripUnsupportedGpt6ServiceTier(prepared.body, requestedModel, upstreamModel);
+      stripUnsupportedGpt6ServiceTier(prepared.body, requestedModel, upstreamModel, priorityTierModel);
       if (requestedModel === CODEX_AUTO_REVIEW_MODEL) delete prepared.body.service_tier;
       if (upstreamModel !== requestedModel) prepared.body.model = upstreamModel;
       const upstreamLog = upstreamModel === requestedModel ? "" : ` upstream_model=${upstreamModel}`;

package/src/running-adapter.mjs

@@ -3,9 +3,9 @@ import { localPackageVersion } from "./version.mjs";
 
 export const ADAPTER_HEALTH_PATH = "/_ccdx/health";
 export const ADAPTER_STATUS_PATH = "/_ccdx/status";
-export const ADAPTER_PROTOCOL_VERSION = 3;
+export const ADAPTER_PROTOCOL_VERSION = 4;
 export const ADAPTER_VERSION = localPackageVersion();
-export const ADAPTER_CAPABILITIES = Object.freeze([]);
+export const ADAPTER_CAPABILITIES = Object.freeze(["cache-control-v1"]);
 const ADAPTER_INSTANCE_ID = randomUUID();
 
 export function adapterHealthPayload() {

package/src/user-settings.mjs

@@ -3,6 +3,13 @@ import os from "node:os";
 import path from "node:path";
 import { atomicWriteFileIfChangedSync } from "./atomic-file.mjs";
 import { DEFAULT_CODEX_AUTO_REVIEW_MODEL } from "./models.mjs";
+import { loadRuntimeConfig } from "./runtime-config.mjs";
+import {
+  MIB,
+  RESPONSE_HISTORY_DEFAULT_MIB,
+  RESPONSE_HISTORY_MAX_MIB,
+  RESPONSE_HISTORY_MIN_MIB,
+} from "./cache-limits.mjs";
 import {
   DEFAULT_TERMINAL_ANIMATION_THEME,
   isTerminalAnimationTheme,
@@ -11,6 +18,8 @@ import {
 
 const AUTO_REVIEW_MODEL_KEY = "auto_review_model";
 const TERMINAL_ANIMATION_KEY = "terminal_animation";
+const RESPONSE_HISTORY_MAX_MIB_KEY = "response_history_max_mib";
+export { RESPONSE_HISTORY_MAX_MIB, RESPONSE_HISTORY_MIN_MIB };
 
 export function userSettingsPath({ env = process.env, home = os.homedir() } = {}) {
   const xdgConfigHome = String(env.XDG_CONFIG_HOME || "").trim();
@@ -46,6 +55,17 @@ export function readUserSettings({ env = process.env, home = os.homedir(), stric
         delete parsed[TERMINAL_ANIMATION_KEY];
       }
     }
+    if (Object.hasOwn(parsed, RESPONSE_HISTORY_MAX_MIB_KEY)) {
+      const value = parsed[RESPONSE_HISTORY_MAX_MIB_KEY];
+      if (!Number.isSafeInteger(value)
+        || value < RESPONSE_HISTORY_MIN_MIB
+        || value > RESPONSE_HISTORY_MAX_MIB) {
+        if (strict) {
+          throw invalidSettings(filePath, `${RESPONSE_HISTORY_MAX_MIB_KEY} must be an integer from ${RESPONSE_HISTORY_MIN_MIB} to ${RESPONSE_HISTORY_MAX_MIB}`);
+        }
+        delete parsed[RESPONSE_HISTORY_MAX_MIB_KEY];
+      }
+    }
     return parsed;
   } catch (error) {
     if (error?.code === "ENOENT") return {};
@@ -83,6 +103,39 @@ export function terminalAnimationPreference({ env = process.env, home = os.homed
   return { theme: DEFAULT_TERMINAL_ANIMATION_THEME, source: "default" };
 }
 
+export function responseHistoryLimitPreference({ env = process.env, home = os.homedir() } = {}) {
+  const environment = String(env.CCDX_RESPONSE_HISTORY_MAX_BYTES || "").trim();
+  if (environment) {
+    return { bytes: loadRuntimeConfig(env).responseHistoryMaxBytes, source: "environment" };
+  }
+  const settings = readUserSettings({ env, home });
+  const mib = settings[RESPONSE_HISTORY_MAX_MIB_KEY];
+  if (Number.isSafeInteger(mib)) return { bytes: mib * MIB, mib, source: "settings" };
+  return { bytes: RESPONSE_HISTORY_DEFAULT_MIB * MIB, mib: RESPONSE_HISTORY_DEFAULT_MIB, source: "default" };
+}
+
+export function writeResponseHistoryLimitMib(mib, { env = process.env, home = os.homedir() } = {}) {
+  const filePath = userSettingsPath({ env, home });
+  const settings = readUserSettings({ env, home, strict: true });
+  const next = { ...settings };
+  if (mib === null || mib === undefined || mib === "") {
+    if (!Object.hasOwn(next, RESPONSE_HISTORY_MAX_MIB_KEY)) {
+      return { changed: false, filePath, ...responseHistoryLimitPreference({ env, home }) };
+    }
+    delete next[RESPONSE_HISTORY_MAX_MIB_KEY];
+  } else {
+    const parsed = Number(mib);
+    if (!Number.isSafeInteger(parsed)
+      || parsed < RESPONSE_HISTORY_MIN_MIB
+      || parsed > RESPONSE_HISTORY_MAX_MIB) {
+      throw new Error(`History cache limit must be an integer from ${RESPONSE_HISTORY_MIN_MIB} to ${RESPONSE_HISTORY_MAX_MIB} MiB`);
+    }
+    next[RESPONSE_HISTORY_MAX_MIB_KEY] = parsed;
+  }
+  const changed = atomicWriteFileIfChangedSync(filePath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  return { changed, filePath, ...responseHistoryLimitPreference({ env, home }) };
+}
+
 export function writeAutoReviewModel(model, { env = process.env, home = os.homedir() } = {}) {
   const filePath = userSettingsPath({ env, home });
   const settings = readUserSettings({ env, home, strict: true });