codex-copilot-dx 0.6.2 → 0.6.3

package/README.md

@@ -29,11 +29,11 @@ npm install -g codex-copilot-dx@latest
 ccdx
 ```
 
-The shorter `ccdx` command is the primary launcher. The existing `codex-copilot-dx`
-command remains an equivalent compatibility alias. For a one-off run without a
-global install, use `npx codex-copilot-dx@latest`.
-Both installed commands expose the same options and subcommands; help, version,
-doctor, status, and argument-error output use the command name that was invoked.
+`ccdx` is the only documented command and primary launcher. The old
+`codex-copilot-dx` executable remains temporarily as a compatibility shim: it
+prints a deprecation warning and runs `ccdx`, and will be removed in a future
+breaking release. For a one-off run without a global install, use
+`npm exec --yes --package=codex-copilot-dx@latest -- ccdx`.
 Run `ccdx <command> --help` (including `auth login claude --help` and
 `pms status --help`) for command-specific behavior and side-effect details.
 
@@ -49,8 +49,7 @@ starting the adapter, opening device login, reading the local model cache, or
 consuming an inference request. It lists model IDs by provider with their
 advertised API capabilities and reports the live Claude/Anthropic count. A model
 being advertised does not guarantee that a later inference request will avoid
-quota, rate-limit, or policy enforcement. `codex-copilot-dx models` is fully
-equivalent.
+quota, rate-limit, or policy enforcement.
 
 ### Separate GitHub account for Claude
 
@@ -193,7 +192,7 @@ It saves the selection 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 0.5.1+
 adapter reads the setting on the next Auto-review request, so it does not need to
-be restarted. `codex-copilot-dx auto-review-model` is fully equivalent.
+be restarted.
 
 To update the globally installed package, choose a source interactively:
 
@@ -216,8 +215,7 @@ latest commit from `DaleXiao/codex-copilot-dx` `main` and opts in to Git fetchin
 for that command, as required by npm 12. It does not change npm's persistent
 `allow-git` setting. Both paths use npm's global installer without shell
 interpolation. A currently running adapter keeps its loaded version until it is
-stopped and started again. The
-`codex-copilot-dx update` compatibility command behaves identically.
+stopped and started again.
 If a configured npm mirror has not synchronized the current release yet, use
 the GitHub source to install the current `main` revision.
 
@@ -278,15 +276,13 @@ For a read-only summary of the running adapter, use:
 ccdx status
 ```
 
-The compatibility alias supports the same command as
-`codex-copilot-dx status`. For the complete machine-readable payload, query the
-loopback endpoint directly:
+For the complete machine-readable payload, query the loopback endpoint directly:
 
 ```bash
 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 for streaming routes, admission pressure, memory use, response-history size, image queue/cache state, profile model cache counts, PM relay route totals, and token expiry state. It never retains metric samples or includes prompts, completions, tool arguments, image content, account names, or token values. API responses always include a safe `X-Request-Id` for correlation. If the adapter is not running, the CLI prints the exact start-and-retry command. To include the same ID as `request_id` in related terminal and file log lines, start the adapter with:
+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 for streaming routes, admission pressure, memory use, response-history size, image queue/cache and adaptive-history state, profile model cache counts, PM relay route totals, and token expiry state. It never retains metric samples or includes prompts, completions, tool arguments, image content, account names, or token values. API responses always include a safe `X-Request-Id` for correlation. If the adapter is not running, the CLI prints the exact start-and-retry command. To include the same ID as `request_id` in related terminal and file log lines, start the adapter with:
 
 ```bash
 ccdx --show-request-id
@@ -306,7 +302,7 @@ ccdx
 Claude App support is opt-in so the default Codex Desktop and Claude Code setup stays unchanged:
 
 ```bash
-npx codex-copilot-dx@latest start --configure-claude-app
+npm exec --yes --package=codex-copilot-dx@latest -- ccdx start --configure-claude-app
 ```
 
 The previous `--configure-claude-desktop` spelling remains a compatibility
@@ -316,7 +312,7 @@ key is restored or the profile is configured in that run.
 Or set:
 
 ```bash
-CCDX_CONFIGURE_CLAUDE_DESKTOP=1 npx codex-copilot-dx@latest
+CCDX_CONFIGURE_CLAUDE_DESKTOP=1 npm exec --yes --package=codex-copilot-dx@latest -- ccdx
 ```
 
 This writes a local Claude App 3P gateway profile that points to the adapter root URL, such as `http://127.0.0.1:2026`. The profile uses a generated local bearer key unless `CCDX_CLAUDE_DESKTOP_API_KEY` is set. Later starts restore that key only from the active managed profile when its gateway URL matches the adapter. Once that managed profile is active, successful Copilot model refreshes automatically keep its `inferenceModels` list current without changing the gateway key or other profile settings. Restart Claude App after the initial setup. Later model changes require no profile reconfiguration, although a running Claude App may need to be reopened if it has not reloaded the updated profile yet.
@@ -392,7 +388,7 @@ Set `CCDX_LOG_PATH=1` to mirror terminal logs to `~/.local/share/codex-copilot-d
 
 ### Image optimization
 
-Long computer-use sessions can accumulate screenshots inside the conversation history. Each screenshot is shipped on later turns, and GitHub Copilot's `/responses` endpoint can reject oversized requests with `408 Request Timeout` while reading the body or `413 Payload Too Large`.
+Long computer-use sessions can accumulate screenshots inside the conversation history. Each screenshot is shipped on later turns, which can increase local preparation time, upstream handshake latency, and the chance of a `413 Payload Too Large` response.
 
 The adapter automatically downsamples embedded screenshots to model-appropriate pixel bounds (with a conservative 2048 px long-edge fallback) and initially re-encodes them as WebP quality 82 before forwarding `/v1/responses`. It never replaces an image with a larger encoding and applies one global concurrency limit across direct, function-tool, and custom-tool output images.
 
@@ -400,6 +396,8 @@ The final serialized UTF-8 request body is measured before forwarding. Above the
 
 Completed image transforms are reused from a byte-bounded process-local LRU cache, and concurrent requests for the same transform share one encode. The cache key includes source content, MIME type, model-aware dimensions, WebP quality, and encoder settings; failures are not cached and request cancellation remains isolated.
 
+Before image encoding, CCDX leaves ordinary visual history byte-for-byte unchanged while it has at most 24 historical images and the expanded body is at most 18 MiB. Above either threshold, the temporary upstream view keeps every current-turn image and at most 16 recent historical images, targeting 16 MiB. If that history tree then times out during local preparation or upstream handshake, the next retry automatically uses an 8-image, 10 MiB recovery window for ten minutes. Two successful requests or a successful compaction clear recovery mode. CCDX never transparently repeats the ambiguous timed-out POST, and no local history is deleted; retrying does not require restarting the service.
+
 When expanded Responses history exceeds Copilot's 50-image request limit, the adapter removes older duplicate image occurrences first, then keeps the 50 most recent images. This applies only to the forwarded request: local history remains complete, current images are preferred over older history, and requests at or below the limit are unchanged.
 
 For `/v1/responses/compact`, the adapter sends one terminal `compaction_trigger` in unary mode, validates that Copilot returned completed compaction state, and rebuilds a replayable snapshot from recent system, developer, user, and assistant messages plus every compaction item. Only a validated snapshot becomes a new local history root. Later turns continue from it without re-expanding pre-compaction history; existing older response branches remain available until normal history eviction.

package/bin/codex-copilot-dx.mjs

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-import "./cli.mjs";
+console.warn("codex-copilot-dx is deprecated; use ccdx instead. The compatibility alias will be removed in a future breaking release.");
+await import("./cli.mjs");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",

package/scripts/benchmark.mjs

@@ -177,6 +177,60 @@ function largeTokenCountProbe(mode) {
   `);
 }
 
+function visualHistoryPressureProbe() {
+  return runProbe(`
+    import { applyResponsesImagePressure } from "./src/responses-image-pressure.mjs";
+
+    const concurrency = 4;
+    const historicalImages = 36;
+    const imageBytes = 256 * 1024;
+    const dataUrls = Array.from({ length: historicalImages }, (_, index) => (
+      \`data:image/png;base64,\${Buffer.alloc(imageBytes, index + 1).toString("base64")}\`
+    ));
+    const contexts = Array.from({ length: concurrency }, (_, requestIndex) => ({
+      historyRootId: \`resp_benchmark_\${requestIndex}\`,
+      currentInputStart: historicalImages,
+      body: {
+        model: "gpt-5.6-sol",
+        stream: true,
+        input: [
+          ...dataUrls.map((imageUrl) => ({
+            type: "message",
+            role: "user",
+            content: [{ type: "input_image", image_url: imageUrl }],
+          })),
+          { type: "message", role: "user", content: "continue" },
+        ],
+      },
+    }));
+    globalThis.gc?.();
+    const before = process.memoryUsage();
+    let peakRss = before.rss;
+    let peakHeap = before.heapUsed;
+    const started = performance.now();
+    const results = await Promise.all(contexts.map(async (context) => {
+      await Promise.resolve();
+      const result = applyResponsesImagePressure(context);
+      const memory = process.memoryUsage();
+      peakRss = Math.max(peakRss, memory.rss);
+      peakHeap = Math.max(peakHeap, memory.heapUsed);
+      return result;
+    }));
+    const mib = (bytes) => +(bytes / 1048576).toFixed(1);
+    process.stdout.write(JSON.stringify({
+      concurrency,
+      historical_images_per_request: historicalImages,
+      elapsed_ms: +(performance.now() - started).toFixed(1),
+      omitted_images: results.map((result) => result.imagesOmitted),
+      retained_historical_images: results.map((result) => result.historicalImages),
+      input_body_mib: results.map((result) => mib(result.initialBodyBytes)),
+      output_body_mib: results.map((result) => mib(result.bodyBytes)),
+      rss_peak_delta_mib: mib(peakRss - before.rss),
+      heap_peak_delta_mib: mib(peakHeap - before.heapUsed),
+    }));
+  `);
+}
+
 const adapterImport = runProbe(`
   const started = performance.now();
   await import("./src/adapter.mjs");
@@ -324,6 +378,7 @@ if (checkMode) {
     largePayloadProbe(30, 1),
     largePayloadProbe(30, 2),
   ];
+  report.visual_history_pressure_36x4 = visualHistoryPressureProbe();
 } else if (process.argv.includes("--large-payload")) {
   report.large_payload_peak = [
     largePayloadProbe(5, 1),
@@ -359,6 +414,12 @@ if (checkMode) {
       failures.push(`request admission exceeded its budget at ${payload.target_request_mib}MiB x${payload.concurrency}`);
     }
   }
+  const visualHistory = report.visual_history_pressure_36x4;
+  if (!visualHistory.omitted_images.every((count) => count === 20)
+    || !visualHistory.retained_historical_images.every((count) => count === 16)
+    || !visualHistory.output_body_mib.every((size, index) => size < visualHistory.input_body_mib[index])) {
+    failures.push("36-image x4 visual history pressure did not preserve the expected 16-image upstream window");
+  }
   if (failures.length) {
     for (const failure of failures) console.error(`[FAIL] ${failure}`);
     process.exitCode = 1;

package/src/adapter.mjs

@@ -17,6 +17,7 @@ import { status } from "./status.mjs";
 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 { loadRuntimeConfig, parsePositiveInteger } from "./runtime-config.mjs";
 import {
   createRequestAdmission,
@@ -138,6 +139,7 @@ export function createAdapterHandler(options = {}) {
   const acquireRequest = options.acquireRequest || createRequestAdmission();
   const requestMetrics = options.requestMetrics || createRequestMetrics();
   const streamPerformanceMetrics = options.streamPerformanceMetrics || createStreamPerformanceMetrics();
+  const imagePressure = options.imagePressure || createResponsesImagePressureController();
   const claudeDesktopModelOptions = () => {
     const modelDefs = claudeModelRegistry?.modelDefs || options.claudeDesktopModelDefs;
     return Array.isArray(modelDefs) ? { modelDefs } : {};
@@ -147,6 +149,7 @@ export function createAdapterHandler(options = {}) {
     autoReviewModelResolver: options.autoReviewModelResolver,
     chatCompletionsFn: codexChatCompletionsFn,
     getCachedModelEndpointsFn,
+    imagePressure,
     openAIModelEnv,
     responsesPayloadOptions: options.responsesPayloadOptions,
     responsesFn,
@@ -157,6 +160,7 @@ export function createAdapterHandler(options = {}) {
   const responsesCompactHandler = createResponsesCompactHandler({
     acquireRequest,
     autoReviewModelResolver: options.autoReviewModelResolver,
+    imagePressure,
     openAIModelEnv,
     responsesCompactFn,
     streamHandshakeTimeoutMs,
@@ -197,6 +201,7 @@ export function createAdapterHandler(options = {}) {
         metrics: requestMetrics,
         streamPerformance: streamPerformanceMetrics,
         admission: acquireRequest,
+        imagePressure,
         modelRegistry: codexModelRegistry,
         codexClient,
         claudeClient,

package/src/cli-options.mjs

@@ -5,7 +5,6 @@ const START_OPTIONS = new Map([
   ["--configure-claude-app", "configure-claude-app"],
   ["--show-request-id", "show-request-id"],
 ]);
-const CLI_COMMANDS = new Set(["ccdx", "codex-copilot-dx"]);
 const PM_COMMANDS = new Set(["pms", "pm-studio"]);
 const HELP_TOPICS = new Set([
   "",
@@ -253,10 +252,8 @@ export function parseAdapterProbeOptions(env = process.env) {
   };
 }
 
-export function cliCommandName(executable = process.argv[1]) {
-  const name = String(executable || "").split(/[\\/]/).pop();
-  if (name === "codex-copilot-dx.mjs") return "codex-copilot-dx";
-  return CLI_COMMANDS.has(name) ? name : "ccdx";
+export function cliCommandName() {
+  return "ccdx";
 }
 
 function topicHelp(name, topic) {
@@ -280,10 +277,9 @@ function topicHelp(name, topic) {
 }
 
 export function cliHelp(commandName = "ccdx", topic = "") {
-  const name = CLI_COMMANDS.has(commandName) ? commandName : "ccdx";
-  const alias = name === "ccdx" ? "codex-copilot-dx" : "ccdx";
+  const name = "ccdx";
   const normalizedTopic = checkedHelpTopic(topic ? topic.split(" ") : []);
-  if (normalizedTopic) return `${topicHelp(name, normalizedTopic)}\n\nEquivalent command: ${alias}`;
+  if (normalizedTopic) return topicHelp(name, normalizedTopic);
   return `Usage:
   ${name} [start] [--configure-claude-app] [--show-request-id]
   ${name} auth status [--online]
@@ -310,7 +306,5 @@ Commands:
   auto-review-model  Select the Codex Auto-review Responses model
   update             Update the global package from npm or GitHub
 
-Run ${name} <command> --help for command details.
-
-Equivalent command: ${alias}`;
+Run ${name} <command> --help for command details.`;
 }

package/src/cli-status.mjs

@@ -149,6 +149,7 @@ export function formatAdapterStatus({ baseUrl, data }, { commandName = "ccdx", c
   const admission = data.admission || {};
   const history = data.response_history || {};
   const images = data.image_optimization || {};
+  const imageHistory = data.image_history_pressure;
   const models = data.models || {};
   const copilot = data.copilot || {};
   const limits = data.limits || {};
@@ -166,8 +167,11 @@ export function formatAdapterStatus({ baseUrl, data }, { commandName = "ccdx", c
     status("info", `Memory: RSS ${mebibytes(processStats.rss_bytes)}, heap ${mebibytes(processStats.heap_used_bytes)}`),
     status("info", `History: ${mebibytes(history.bytes)} / ${mebibytes(limits.response_history_max_bytes)}, ${count(history.entries)} entries, ${count(history.evicted)} evicted`),
     status("info", `Image cache: ${count(images.cache_entries)} entries, ${cacheHitRate(images)} hits, ${mebibytes(images.cache_bytes)} / ${mebibytes(images.cache_max_bytes)}`),
-    status("info", `Models: ${count(models.models)} total, ${count(models.claude_models)} Claude; Copilot token ${copilot.token_cached ? `cached (${duration(copilot.token_expires_in_ms)} remaining)` : "not cached"}`),
   ];
+  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`));
+  }
+  lines.push(status("info", `Models: ${count(models.models)} total, ${count(models.claude_models)} Claude; Copilot token ${copilot.token_cached ? `cached (${duration(copilot.token_expires_in_ms)} remaining)` : "not cached"}`));
   if (data.profiles?.codex || data.profiles?.claude) {
     lines.push(status("info", `Profiles: ${profileSummary("Codex", data.profiles?.codex)}; ${profileSummary("Claude", data.profiles?.claude)}`));
   }

package/src/copilot-client.mjs

@@ -85,6 +85,7 @@ export function createCopilotClientRuntime({
     fetchImpl,
     retryOptions,
     bodyText,
+    onUpstreamStart,
   } = {}) {
     const token = await tokenSession.getToken({ signal });
     const upstreamReq = chatReq.stream === true ? withChatStreamUsage(chatReq) : chatReq;
@@ -99,6 +100,7 @@ export function createCopilotClientRuntime({
       vision: computeVision(messages),
     });
     headers["Content-Length"] = String(Buffer.byteLength(serializedBody));
+    onUpstreamStart?.();
     if (upstreamReq.stream === true) markUpstreamStarted();
     return fetchCopilotUpstream(`${tokenSession.getApiBase()}/chat/completions`, {
       method: "POST",
@@ -152,6 +154,7 @@ export function createCopilotClientRuntime({
     fetchImpl,
     retryOptions,
     currentInputStart = 0,
+    onUpstreamStart,
     payloadPrepared = false,
     payloadOptions = {},
   } = {}) {
@@ -175,6 +178,7 @@ export function createCopilotClientRuntime({
     headers["Content-Length"] = String(bodyBytes);
     headers.Accept = reqBody.stream ? "text/event-stream" : "application/json";
     try {
+      onUpstreamStart?.();
       if (reqBody.stream === true) markUpstreamStarted();
       return await fetchCopilotUpstream(`${tokenSession.getApiBase()}${responsesEndpointPath()}`, {
         method: "POST",
@@ -183,6 +187,7 @@ export function createCopilotClientRuntime({
         signal,
       }, { fetchImpl, ...retryOptions });
     } catch (error) {
+      if (signal?.aborted) throw abortError(signal);
       const cause = error?.cause;
       const causeText = cause ? ` (${[cause.code, cause.message].filter(Boolean).join(": ")})` : "";
       throw new Error(`Copilot responses fetch failed: ${error.message}${causeText}`);

package/src/http-transport.mjs

@@ -327,7 +327,7 @@ export function isAbortLikeError(err) {
 }
 
 export function abortErrorStatusCode(reason) {
-  if (["upstream_timeout", "stream_handshake_timeout", "stream_idle_timeout"].includes(reason)) return 504;
+  if (["responses_prepare_timeout", "upstream_timeout", "stream_handshake_timeout", "stream_idle_timeout"].includes(reason)) return 504;
   if (reason === "client_aborted" || reason === "client_closed") return 499;
   return 502;
 }

package/src/observability.mjs

@@ -154,6 +154,7 @@ export function runtimeStatusPayload({
   metrics,
   streamPerformance,
   admission,
+  imagePressure,
   modelRegistry,
   codexClient,
   claudeClient,
@@ -186,6 +187,7 @@ export function runtimeStatusPayload({
     admission: admission?.diagnostics?.() || admission?.stats?.() || null,
     response_history: responseHistoryStats(),
     image_optimization: imageOptimizationStats(),
+    image_history_pressure: imagePressure?.snapshot?.() || null,
     copilot: codexRuntime,
     models: codexModels,
     profiles: {

package/src/response-history.mjs

@@ -174,6 +174,10 @@ export function responseHistoryStats() {
   return { entries: histories.size, bytes: totalBytes, evicted: evictedIds.size };
 }
 
+export function responseHistoryRootId(responseId) {
+  return histories.get(responseId)?.rootId || null;
+}
+
 export function materializeResponseHistory(responseId) {
   const chain = [];
   const seen = new Set();

package/src/responses-bridge.mjs

@@ -149,24 +149,29 @@ export async function forwardToChat(chatReq, emitEvent, onDone, onError, options
   try {
     const chatCompletionsFn = options.chatCompletionsFn || chatCompletions;
     try {
-      resp = await chatCompletionsFn(upstreamReq, { signal: options.signal, bodyText });
+      options.onUpstreamStart?.();
+      resp = await chatCompletionsFn(upstreamReq, {
+        signal: options.signal,
+        bodyText,
+        onUpstreamStart: options.onUpstreamStart,
+      });
     } finally {
       options.releaseRequest?.();
     }
   } catch (e) {
     const statusCode = isAbortLikeError(e) ? abortErrorStatusCode(options.abort?.reason) : 502;
     await onError(statusCode, e.message);
-    return;
+    return false;
   }
   if (!resp.ok) {
     await onError(resp.status, await resp.text(), undefined, resp);
-    return;
+    return false;
   }
   try {
     await requireUpstreamEventStream(resp);
   } catch (error) {
     await onError(error.statusCode, error.message, error);
-    return;
+    return false;
   }
   options.onUpstreamResponse?.(resp);
   options.abort?.setTimeout(options.streamIdleTimeoutMs, "stream_idle_timeout");
@@ -279,7 +284,7 @@ export async function forwardToChat(chatReq, emitEvent, onDone, onError, options
     })) {
       if (!line.startsWith("data: ")) continue;
       const data = line.slice(6).trim();
-      if (data === "[DONE]") { await emitCompleted(); onDone(); return; }
+      if (data === "[DONE]") { await emitCompleted(); onDone(); return true; }
       let parsed;
       try {
         parsed = JSON.parse(data);
@@ -331,8 +336,9 @@ export async function forwardToChat(chatReq, emitEvent, onDone, onError, options
   } catch (e) {
     const statusCode = isAbortLikeError(e) ? abortErrorStatusCode(options.abort?.reason) : (e?.statusCode || 502);
     await onError(statusCode, e?.message || "upstream stream error", e);
-    return;
+    return false;
   }
   const error = incompleteUpstreamStream("[DONE]");
   await onError(error.statusCode, error.message, error);
+  return false;
 }

package/src/responses-byte-budget.mjs

@@ -159,12 +159,14 @@ function recordBytesAfterDrop(record, state, partIndex) {
   return state.baseBytes + remainingElementBytes + remainingCount - 1;
 }
 
-function selectImageDrops(refs, bodyBytes, targetBytes) {
+function selectImageDrops(refs, bodyBytes, targetBytes, maxHistoricalImages = Number.POSITIVE_INFINITY) {
   const candidates = orderedHistoricalImageCandidates(refs);
   const selected = new Set();
   const byRecord = new Map();
   let projectedBytes = bodyBytes;
+  let historicalImages = refs.reduce((count, ref) => count + (ref.historical ? 1 : 0), 0);
   for (const index of candidates) {
+    if (projectedBytes <= targetBytes && historicalImages <= maxHistoricalImages) break;
     const ref = refs[index];
     let state = byRecord.get(ref.record);
     if (!state) {
@@ -173,7 +175,7 @@ function selectImageDrops(refs, bodyBytes, targetBytes) {
     }
     const afterBytes = recordBytesAfterDrop(ref.record, state, ref.partIndex);
     const savings = state.currentBytes - afterBytes;
-    if (savings <= 0) continue;
+    if (savings <= 0 && historicalImages <= maxHistoricalImages) continue;
     state.currentBytes = afterBytes;
     if (ref.record.kind !== "top-level") {
       state.remainingCount -= 1;
@@ -181,9 +183,9 @@ function selectImageDrops(refs, bodyBytes, targetBytes) {
     }
     selected.add(index);
     projectedBytes -= savings;
-    if (projectedBytes <= targetBytes) break;
+    historicalImages -= 1;
   }
-  return selected;
+  return { selected, historicalImages, projectedBytes };
 }
 
 function applyImageDrops(records, refs, selected) {
@@ -253,7 +255,7 @@ export function trimResponsesHistoryToByteBudget(reqBody, {
   while (bodyBytes > limit) {
     const { records, refs } = collectResponseImages(inputItems, currentInputStart);
     if (!refs.length) break;
-    const selected = selectImageDrops(refs, bodyBytes, limit);
+    const { selected } = selectImageDrops(refs, bodyBytes, limit);
     if (!selected.size) break;
     applyImageDrops(records, refs, selected);
     imagesOmitted += selected.size;
@@ -278,6 +280,62 @@ export function trimResponsesHistoryToByteBudget(reqBody, {
   };
 }
 
+export function responsesHistoricalImageStats(inputItems, currentInputStart = 0) {
+  const items = Array.isArray(inputItems) ? inputItems : [];
+  const { refs } = collectResponseImages(items, currentInputStart);
+  const historicalImages = refs.reduce((count, ref) => count + (ref.historical ? 1 : 0), 0);
+  return {
+    totalImages: refs.length,
+    historicalImages,
+    currentImages: refs.length - historicalImages,
+  };
+}
+
+export function trimResponsesHistoricalImages(reqBody, {
+  currentInputStart = 0,
+  maxHistoricalImages = Number.POSITIVE_INFINITY,
+  targetBytes = Number.POSITIVE_INFINITY,
+  initialBodyText,
+  initialBodyBytes,
+} = {}) {
+  let bodyText = initialBodyText ?? JSON.stringify(reqBody);
+  let bodyBytes = initialBodyBytes ?? Buffer.byteLength(bodyText);
+  const byteLimit = Number.isFinite(targetBytes) && targetBytes > 0
+    ? Math.floor(targetBytes)
+    : Number.POSITIVE_INFINITY;
+  const imageLimit = Number.isFinite(maxHistoricalImages) && maxHistoricalImages >= 0
+    ? Math.floor(maxHistoricalImages)
+    : Number.POSITIVE_INFINITY;
+  const inputItems = Array.isArray(reqBody?.input) ? reqBody.input : [];
+  let imagesOmitted = 0;
+
+  while (true) {
+    const { records, refs } = collectResponseImages(inputItems, currentInputStart);
+    const historicalImages = refs.reduce((count, ref) => count + (ref.historical ? 1 : 0), 0);
+    if (bodyBytes <= byteLimit && historicalImages <= imageLimit) break;
+    if (!historicalImages) break;
+    const { selected } = selectImageDrops(refs, bodyBytes, byteLimit, imageLimit);
+    if (!selected.size) break;
+    applyImageDrops(records, refs, selected);
+    imagesOmitted += selected.size;
+    ({ bodyText, bodyBytes } = bodyPayload(reqBody));
+  }
+
+  const stats = responsesHistoricalImageStats(inputItems, currentInputStart);
+  return {
+    bodyText,
+    bodyBytes,
+    targetBytes: byteLimit,
+    maxHistoricalImages: imageLimit,
+    historicalImages: stats.historicalImages,
+    currentImages: stats.currentImages,
+    imagesOmitted,
+    overBudget: bodyBytes > byteLimit,
+    overImageBudget: stats.historicalImages > imageLimit,
+    adapted: imagesOmitted > 0,
+  };
+}
+
 export function enforceResponsesPayloadByteBudget(reqBody, payload) {
   let finalized = payload;
   if (payload?.overBudget) {

package/src/responses-handler.mjs

@@ -79,6 +79,7 @@ export function createResponsesHandler(options) {
     autoReviewModelResolver,
     chatCompletionsFn,
     getCachedModelEndpointsFn = getCachedModelEndpoints,
+    imagePressure,
     openAIModelEnv,
     responsesPayloadOptions,
     responsesFn,
@@ -90,14 +91,42 @@ export function createResponsesHandler(options) {
   return async function handleResponses(req, res) {
     const abort = createRequestAbort(req, res);
     let releaseRequest = () => {};
+    let prepared = null;
+    let imagePressureResult = null;
+    let parsed = null;
+    const startUpstreamTimeout = () => abort.setTimeout(
+      parsed?.stream ? streamHandshakeTimeoutMs : upstreamTimeoutMs,
+      parsed?.stream ? "stream_handshake_timeout" : "upstream_timeout",
+    );
+    const applyAdaptiveTimeout = (error) => {
+      if (!["responses_prepare_timeout", "stream_handshake_timeout", "upstream_timeout"].includes(abort.reason)) {
+        return error;
+      }
+      const activated = imagePressure?.markTimeout?.(prepared?.historyRootId, {
+        eligible: imagePressureResult?.pressureEligible === true,
+      });
+      if (!activated) return error;
+      const message = "Responses timed out while processing a large visual history. Retry the request; ccdx will keep fewer earlier images automatically. Restart is not required.";
+      error.statusCode = 504;
+      error.jsonBody = {
+        error: {
+          message,
+          type: "timeout_error",
+          code: "ccdx_visual_history_timeout",
+          retryable: true,
+        },
+      };
+      return error;
+    };
     try {
       releaseRequest = await acquireRequest(req, { signal: abort.signal });
-      const parsed = await readJsonBody(req);
-      abort.setTimeout(
-        parsed.stream ? streamHandshakeTimeoutMs : upstreamTimeoutMs,
-        parsed.stream ? "stream_handshake_timeout" : "upstream_timeout",
-      );
-      const prepared = prepareResponsesRequest(parsed, { mutate: true });
+      parsed = await readJsonBody(req);
+      abort.setTimeout(upstreamTimeoutMs, "responses_prepare_timeout");
+      prepared = prepareResponsesRequest(parsed, { mutate: true });
+      imagePressureResult = imagePressure?.apply?.(prepared) || null;
+      if (imagePressureResult?.adapted) {
+        console.warn(status("warn", `responses visual history mode=${imagePressureResult.mode} historical_images=${imagePressureResult.initialHistoricalImages}->${imagePressureResult.historicalImages} omitted=${imagePressureResult.imagesOmitted} bytes=${imagePressureResult.initialBodyBytes}->${imagePressureResult.bodyBytes}`));
+      }
       prepared.surface = "responses";
       const model = parsed.model || "unknown";
       const { requestedModel, upstreamModel } = resolveRequestModel(model, openAIModelEnv, autoReviewModelResolver);
@@ -110,12 +139,14 @@ export function createResponsesHandler(options) {
         || (usesCustomTools && cachedModelSupportsResponses(upstreamModel, getCachedModelEndpointsFn));
       if (usesCustomTools && !useNativeResponses) throw unsupportedCustomToolsError(upstreamModel);
       if (useNativeResponses) {
-        await proxyCopilotResponses(prepared, req, res, responsesFn, {
+        const result = await proxyCopilotResponses(prepared, req, res, responsesFn, {
           signal: abort.signal,
           abort,
+          onUpstreamStart: startUpstreamTimeout,
           releaseRequest,
           streamIdleTimeoutMs,
         });
+        if (result?.successful) imagePressure?.markSuccess?.(prepared.historyRootId);
       } else {
         const chatPayload = await prepareResponsesChatPayload(prepared, {
           payloadOptions: responsesPayloadOptions,
@@ -125,7 +156,7 @@ export function createResponsesHandler(options) {
         const { chatReq, bodyText } = chatPayload;
         if (parsed.stream) {
           let streamResponseHeaders = null;
-          await forwardToChat(chatReq, async (event, data) => {
+          const successful = await forwardToChat(chatReq, async (event, data) => {
             if (!res.headersSent) res.writeHead(200, {
               ...streamResponseHeaders,
               "Cache-Control": "no-cache",
@@ -142,7 +173,7 @@ export function createResponsesHandler(options) {
                 sendUpstreamError(res, upstreamResponse, errMsg);
                 return;
               }
-              const responseError = error || Object.assign(new Error(errMsg), { statusCode });
+              const responseError = applyAdaptiveTimeout(error || Object.assign(new Error(errMsg), { statusCode }));
               sendJsonError(res, responseError, statusCode || 500);
               return;
             }
@@ -150,6 +181,7 @@ export function createResponsesHandler(options) {
           }, {
             signal: abort.signal,
             abort,
+            onUpstreamStart: startUpstreamTimeout,
             streamIdleTimeoutMs,
             chatCompletionsFn,
             releaseRequest,
@@ -160,9 +192,15 @@ export function createResponsesHandler(options) {
               });
             },
           });
+          if (successful) imagePressure?.markSuccess?.(prepared.historyRootId);
         } else {
           try {
-            const upstream = await chatCompletionsFn(chatReq, { signal: abort.signal, bodyText });
+            startUpstreamTimeout();
+            const upstream = await chatCompletionsFn(chatReq, {
+              signal: abort.signal,
+              bodyText,
+              onUpstreamStart: startUpstreamTimeout,
+            });
             releaseRequest();
             const data = await upstream.text();
             if (!upstream.ok) {
@@ -171,20 +209,23 @@ export function createResponsesHandler(options) {
             }
             const response = chatToResponses(JSON.parse(data), model);
             rememberResponseHistory(prepared, response);
+            imagePressure?.markSuccess?.(prepared.historyRootId);
             recordResponsesUsage({ surface: prepared.surface, mode: "json", model, response, event: response });
             res.writeHead(200, safeUpstreamResponseHeaders(upstream.headers, {
               contentType: "application/json",
             }));
             res.end(JSON.stringify(response));
           } catch (error) {
-            logRequestFailure("Responses", error, abort);
-            sendJsonError(res, error, 502);
+            const responseError = applyAdaptiveTimeout(error);
+            logRequestFailure("Responses", responseError, abort);
+            sendJsonError(res, responseError, 502);
           }
         }
       }
     } catch (error) {
-      logRequestFailure("Responses", error, abort);
-      sendJsonError(res, error, 502);
+      const responseError = applyAdaptiveTimeout(error);
+      logRequestFailure("Responses", responseError, abort);
+      sendJsonError(res, responseError, 502);
     } finally {
       releaseRequest();
       abort.cleanup();
@@ -196,6 +237,7 @@ export function createResponsesCompactHandler(options) {
   const {
     acquireRequest,
     autoReviewModelResolver,
+    imagePressure,
     openAIModelEnv,
     responsesCompactFn,
     upstreamTimeoutMs,
@@ -207,7 +249,7 @@ export function createResponsesCompactHandler(options) {
     try {
       releaseRequest = await acquireRequest(req, { signal: abort.signal });
       const parsed = await readJsonBody(req);
-      abort.setTimeout(upstreamTimeoutMs, "upstream_timeout");
+      abort.setTimeout(upstreamTimeoutMs, "responses_prepare_timeout");
       const prepared = prepareResponsesCompactionRequest(
         prepareResponsesRequest(parsed, { mutate: true }),
       );
@@ -217,11 +259,13 @@ export function createResponsesCompactHandler(options) {
       if (upstreamModel !== requestedModel) prepared.body.model = upstreamModel;
       const upstreamLog = upstreamModel === requestedModel ? "" : ` upstream_model=${upstreamModel}`;
       console.log(status("info", `responses compact model=${requestedModel}${upstreamLog} stream=false`));
-      await proxyCopilotResponses(prepared, req, res, responsesCompactFn, {
+      const result = await proxyCopilotResponses(prepared, req, res, responsesCompactFn, {
         signal: abort.signal,
         abort,
+        onUpstreamStart: () => abort.setTimeout(upstreamTimeoutMs, "upstream_timeout"),
         releaseRequest,
       });
+      if (result?.compacted) imagePressure?.clear?.(prepared.historyRootId);
     } catch (error) {
       logRequestFailure("Responses compact", error, abort);
       sendJsonError(res, error, 502);

package/src/responses-image-pressure.mjs

@@ -0,0 +1,163 @@
+import {
+  responsesHistoricalImageStats,
+  trimResponsesHistoricalImages,
+} from "./responses-byte-budget.mjs";
+
+const MIB = 1024 * 1024;
+
+export const DEFAULT_RESPONSES_IMAGE_PRESSURE_POLICY = Object.freeze({
+  triggerHistoricalImages: 24,
+  triggerBodyBytes: 18 * MIB,
+  pressureHistoricalImages: 16,
+  pressureBodyBytes: 16 * MIB,
+  recoveryHistoricalImages: 8,
+  recoveryBodyBytes: 10 * MIB,
+});
+
+function normalizedPolicy(policy = {}) {
+  return { ...DEFAULT_RESPONSES_IMAGE_PRESSURE_POLICY, ...policy };
+}
+
+function bodyPayload(body) {
+  const bodyText = JSON.stringify(body);
+  return { bodyText, bodyBytes: Buffer.byteLength(bodyText) };
+}
+
+export function applyResponsesImagePressure(reqContext, {
+  mode = "normal",
+  policy: policyOverrides,
+} = {}) {
+  const policy = normalizedPolicy(policyOverrides);
+  const body = reqContext?.body;
+  const currentInputStart = Number.isFinite(reqContext?.currentInputStart)
+    ? reqContext.currentInputStart
+    : 0;
+  const initial = bodyPayload(body);
+  const initialImages = responsesHistoricalImageStats(body?.input, currentInputStart);
+  const pressureEligible = initialImages.historicalImages > 0 && (
+    initialImages.historicalImages > policy.triggerHistoricalImages
+      || initial.bodyBytes > policy.triggerBodyBytes
+  );
+  const recovery = mode === "recovery";
+  const maxHistoricalImages = recovery
+    ? policy.recoveryHistoricalImages
+    : policy.pressureHistoricalImages;
+  const targetBytes = recovery ? policy.recoveryBodyBytes : policy.pressureBodyBytes;
+  const shouldAdapt = initialImages.historicalImages > 0 && (recovery
+    ? initialImages.historicalImages > maxHistoricalImages || initial.bodyBytes > targetBytes
+    : pressureEligible);
+
+  if (!shouldAdapt) {
+    return {
+      mode: "normal",
+      pressureEligible,
+      adapted: false,
+      imagesOmitted: 0,
+      initialBodyBytes: initial.bodyBytes,
+      bodyBytes: initial.bodyBytes,
+      initialHistoricalImages: initialImages.historicalImages,
+      historicalImages: initialImages.historicalImages,
+      currentImages: initialImages.currentImages,
+      overBudget: false,
+      overImageBudget: false,
+    };
+  }
+
+  const trimmed = trimResponsesHistoricalImages(body, {
+    currentInputStart,
+    maxHistoricalImages,
+    targetBytes,
+    initialBodyText: initial.bodyText,
+    initialBodyBytes: initial.bodyBytes,
+  });
+  return {
+    mode: recovery ? "recovery" : "pressure",
+    pressureEligible: pressureEligible || recovery,
+    initialBodyBytes: initial.bodyBytes,
+    initialHistoricalImages: initialImages.historicalImages,
+    ...trimmed,
+  };
+}
+
+export function createResponsesImagePressureController({
+  now = Date.now,
+  maxEntries = 256,
+  recoveryTtlMs = 10 * 60 * 1000,
+  successesToClear = 2,
+  policy: policyOverrides,
+} = {}) {
+  const policy = normalizedPolicy(policyOverrides);
+  const recovery = new Map();
+  const counters = {
+    adaptedRequests: 0,
+    imagesOmitted: 0,
+    recoveryActivations: 0,
+    timeoutsRecorded: 0,
+  };
+
+  const prune = () => {
+    const timestamp = now();
+    for (const [rootId, state] of recovery) {
+      if (state.expiresAt <= timestamp) recovery.delete(rootId);
+    }
+    while (recovery.size > maxEntries) recovery.delete(recovery.keys().next().value);
+  };
+
+  const modeFor = (rootId) => {
+    prune();
+    return rootId && recovery.has(rootId) ? "recovery" : "normal";
+  };
+
+  return Object.freeze({
+    apply(reqContext) {
+      const result = applyResponsesImagePressure(reqContext, {
+        mode: modeFor(reqContext?.historyRootId),
+        policy,
+      });
+      if (result.adapted) {
+        counters.adaptedRequests += 1;
+        counters.imagesOmitted += result.imagesOmitted;
+      }
+      return result;
+    },
+    markTimeout(rootId, { eligible = false } = {}) {
+      if (!rootId || !eligible) return false;
+      prune();
+      const existing = recovery.get(rootId);
+      recovery.delete(rootId);
+      recovery.set(rootId, { expiresAt: now() + recoveryTtlMs, successes: 0 });
+      counters.timeoutsRecorded += 1;
+      if (!existing) counters.recoveryActivations += 1;
+      prune();
+      return true;
+    },
+    markSuccess(rootId) {
+      if (!rootId) return false;
+      prune();
+      const state = recovery.get(rootId);
+      if (!state) return false;
+      state.successes += 1;
+      if (state.successes >= successesToClear) {
+        recovery.delete(rootId);
+        return true;
+      }
+      return false;
+    },
+    clear(rootId) {
+      return rootId ? recovery.delete(rootId) : false;
+    },
+    snapshot() {
+      prune();
+      return {
+        active_recovery_trees: recovery.size,
+        adapted_requests: counters.adaptedRequests,
+        historical_images_omitted: counters.imagesOmitted,
+        recovery_activations: counters.recoveryActivations,
+        timeouts_recorded: counters.timeoutsRecorded,
+        recovery_ttl_ms: recoveryTtlMs,
+        pressure_image_limit: policy.pressureHistoricalImages,
+        recovery_image_limit: policy.recoveryHistoricalImages,
+      };
+    },
+  });
+}

package/src/responses-proxy.mjs

@@ -126,7 +126,7 @@ export async function proxyCopilotResponses(reqContext, req, res, upstream = cop
   reqContext = opened.reqContext;
   if (errorText !== undefined) {
     sendUpstreamError(res, resp, errorText);
-    return;
+    return { successful: false, compacted: false };
   }
 
   if (reqContext.body.stream) {
@@ -158,7 +158,7 @@ export async function proxyCopilotResponses(reqContext, req, res, upstream = cop
           if (!streamState.sawTerminal) throw incompleteUpstreamStream("a terminal Responses event");
           storeCompletedResponse(reqContext, streamState.completed);
           res.end();
-          return;
+          return { successful: Boolean(streamState.completed), compacted: false };
         }
         options.abort?.setTimeout(options.streamIdleTimeoutMs, "stream_idle_timeout");
         buffer += decoder.decode(value, { stream: true });
@@ -170,12 +170,13 @@ export async function proxyCopilotResponses(reqContext, req, res, upstream = cop
         if (streamState.sawTerminal) {
           storeCompletedResponse(reqContext, streamState.completed);
           res.end();
-          return;
+          return { successful: Boolean(streamState.completed), compacted: false };
         }
       }
     } catch (e) {
       logRequestFailure("Responses", e, options.abort);
       await endStreamWithError(res, "responses", e, options.abort);
+      return { successful: false, compacted: false };
     } finally {
       await reader.cancel().catch(() => {});
       reader.releaseLock();
@@ -199,7 +200,7 @@ export async function proxyCopilotResponses(reqContext, req, res, upstream = cop
         contentType: "application/json",
       }));
       res.end(JSON.stringify(response));
-      return;
+      return { successful: true, compacted: true };
     }
     res.writeHead(resp.status, safeUpstreamResponseHeaders(resp.headers, {
       contentType: "application/json",
@@ -216,7 +217,9 @@ export async function proxyCopilotResponses(reqContext, req, res, upstream = cop
           response,
           event: response,
         });
+        return { successful: true, compacted: false };
       } catch {}
     }
+    return { successful: false, compacted: false };
   }
 }

package/src/responses-request.mjs

@@ -1,7 +1,11 @@
 import { responses as copilotResponses } from "./copilot.mjs";
 import { httpError } from "./http-transport.mjs";
 import { debugLog } from "./log.mjs";
-import { materializeResponseHistory, rememberResponseHistoryNode } from "./response-history.mjs";
+import {
+  materializeResponseHistory,
+  rememberResponseHistoryNode,
+  responseHistoryRootId,
+} from "./response-history.mjs";
 import { enforceResponsesImageLimit } from "./responses-image-limit.mjs";
 import { status } from "./status.mjs";
 
@@ -157,6 +161,7 @@ export async function openCopilotResponse(reqContext, upstream = copilotResponse
     const resp = await upstream(reqContext.body, {
       signal: options.signal,
       currentInputStart: reqContext.currentInputStart,
+      onUpstreamStart: options.onUpstreamStart,
       payloadPrepared,
     });
     payloadPrepared = true;
@@ -198,9 +203,11 @@ export function prepareResponsesRequest(reqBody, { mutate = false } = {}) {
   );
   const previousId = body.previous_response_id;
   let historyItems = [];
+  let historyRootId = null;
 
   if (previousId !== undefined && previousId !== null) {
     historyItems = materializeResponseHistory(previousId);
+    historyRootId = responseHistoryRootId(previousId);
     body.input = [...historyItems, ...currentInputItems];
   } else {
     body.input = currentInputItems;
@@ -232,6 +239,7 @@ export function prepareResponsesRequest(reqBody, { mutate = false } = {}) {
     inputItems: body.input,
     currentInputStart: retainedCurrentInputStart < 0 ? body.input.length : retainedCurrentInputStart,
     historyParentId: previousId ?? null,
+    historyRootId,
     historyInputItems,
     takeHistoryOwnership: mutate,
   };