codex-copilot-dx 0.6.2 → 0.6.4

package/src/http-transport.mjs

@@ -47,6 +47,83 @@ function admissionAbortError(signal) {
   return error;
 }
 
+function createSupplementalAdmission({ maxWeight, maxQueued, waitTimeoutMs, label }) {
+  const queue = [];
+  let activeWeight = 0;
+  let activeRequests = 0;
+
+  const activate = (entry) => {
+    entry.cleanup();
+    activeWeight += entry.weight;
+    activeRequests += 1;
+    let released = false;
+    entry.resolve(() => {
+      if (released) return;
+      released = true;
+      activeWeight = Math.max(0, activeWeight - entry.weight);
+      activeRequests = Math.max(0, activeRequests - 1);
+      drain();
+    });
+  };
+
+  const drain = () => {
+    for (let index = 0; index < queue.length;) {
+      const entry = queue[index];
+      if (activeWeight + entry.weight > maxWeight) {
+        index += 1;
+        continue;
+      }
+      queue.splice(index, 1);
+      activate(entry);
+    }
+  };
+
+  const acquire = (requestedWeight, { signal } = {}) => {
+    if (signal?.aborted) return Promise.reject(admissionAbortError(signal));
+    const parsedWeight = Number.isFinite(requestedWeight) && requestedWeight > 0
+      ? Math.ceil(requestedWeight)
+      : maxWeight;
+    const weight = Math.max(1, Math.min(parsedWeight, maxWeight));
+    if (queue.length >= maxQueued && activeWeight + weight > maxWeight) {
+      return Promise.reject(httpError(`${label} queue is full (${maxQueued} waiting)`, 503));
+    }
+
+    return new Promise((resolve, reject) => {
+      let timer;
+      const entry = {
+        weight,
+        resolve,
+        cleanup: () => {
+          if (timer) clearTimeout(timer);
+          signal?.removeEventListener("abort", onAbort);
+        },
+      };
+      const remove = () => {
+        const index = queue.indexOf(entry);
+        if (index >= 0) queue.splice(index, 1);
+      };
+      const fail = (error) => {
+        entry.cleanup();
+        remove();
+        reject(error);
+        drain();
+      };
+      const onAbort = () => fail(admissionAbortError(signal));
+      signal?.addEventListener("abort", onAbort, { once: true });
+      timer = setTimeout(() => {
+        fail(httpError(`${label} admission timed out after ${waitTimeoutMs}ms`, 503));
+      }, waitTimeoutMs);
+      timer.unref?.();
+      queue.push(entry);
+      if (signal?.aborted) onAbort();
+      else drain();
+    });
+  };
+
+  acquire.stats = () => ({ activeWeight, activeRequests, queued: queue.length, maxWeight });
+  return acquire;
+}
+
 export function createRequestAdmission({
   maxBytes = MAX_INFLIGHT_BODY_BYTES,
   maxQueued = MAX_QUEUED_REQUESTS,
@@ -55,6 +132,24 @@ export function createRequestAdmission({
   const byteLimit = parsePositiveInteger(maxBytes, MAX_INFLIGHT_BODY_BYTES);
   const queueLimit = parsePositiveInteger(maxQueued, MAX_QUEUED_REQUESTS);
   const timeoutMs = parsePositiveInteger(waitTimeoutMs, REQUEST_QUEUE_TIMEOUT_MS);
+  const acquireDecompression = createSupplementalAdmission({
+    maxWeight: 1,
+    maxQueued: queueLimit,
+    waitTimeoutMs: timeoutMs,
+    label: "Request decompression",
+  });
+  const acquireDecodedBody = createSupplementalAdmission({
+    maxWeight: byteLimit,
+    maxQueued: queueLimit,
+    waitTimeoutMs: timeoutMs,
+    label: "Decoded request body",
+  });
+  const acquireResponseHistory = createSupplementalAdmission({
+    maxWeight: byteLimit,
+    maxQueued: queueLimit,
+    waitTimeoutMs: timeoutMs,
+    label: "Response history",
+  });
   const queue = [];
   let activeBytes = 0;
   let activeRequests = 0;
@@ -83,13 +178,28 @@ export function createRequestAdmission({
     counters.waitMsTotal += waitMs;
     counters.waitMsMax = Math.max(counters.waitMsMax, waitMs);
     let released = false;
-    entry.resolve(() => {
+    const supplementalReleases = new Set();
+    const release = () => {
       if (released) return;
       released = true;
+      for (const releaseSupplemental of supplementalReleases) releaseSupplemental();
+      supplementalReleases.clear();
       activeBytes = Math.max(0, activeBytes - entry.weight);
       activeRequests = Math.max(0, activeRequests - 1);
       drain();
-    });
+    };
+    const reserve = async (gate, weight, options) => {
+      const releaseSupplemental = await gate(weight, options);
+      if (released) {
+        releaseSupplemental();
+        throw admissionAbortError(options?.signal);
+      }
+      supplementalReleases.add(releaseSupplemental);
+    };
+    release.acquireDecompression = (options) => acquireDecompression(1, options);
+    release.reserveDecodedBody = (bytes, options) => reserve(acquireDecodedBody, bytes, options);
+    release.reserveResponseHistory = (bytes, options) => reserve(acquireResponseHistory, bytes, options);
+    entry.resolve(release);
   };
 
   const drain = () => {
@@ -173,11 +283,64 @@ export function createRequestAdmission({
       ? Number((counters.waitMsTotal / counters.activated).toFixed(1))
       : 0,
     waitMsMax: counters.waitMsMax,
+    decompressionsActive: acquireDecompression.stats().activeRequests,
+    decompressionsQueued: acquireDecompression.stats().queued,
+    decodedBodyBytes: acquireDecodedBody.stats().activeWeight,
+    decodedBodiesActive: acquireDecodedBody.stats().activeRequests,
+    decodedBodiesQueued: acquireDecodedBody.stats().queued,
+    responseHistoryBytes: acquireResponseHistory.stats().activeWeight,
+    responseHistoriesActive: acquireResponseHistory.stats().activeRequests,
+    responseHistoriesQueued: acquireResponseHistory.stats().queued,
   });
   return acquire;
 }
 
-async function readRequestBuffer(req, maxBytes) {
+function consumeRequestChunks(req, { signal, onChunk }) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => {
+      req.off("data", handleData);
+      req.off("end", handleEnd);
+      req.off("error", handleError);
+      req.off("aborted", handleAborted);
+      signal?.removeEventListener("abort", handleSignalAbort);
+    };
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (error) reject(error);
+      else resolve();
+    };
+    const stopReading = (error) => {
+      req.pause?.();
+      finish(error);
+    };
+    const handleData = (chunk) => {
+      try {
+        onChunk(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      } catch (error) {
+        stopReading(error);
+      }
+    };
+    const handleEnd = () => finish();
+    const handleError = (error) => finish(error);
+    const handleAborted = () => finish(admissionAbortError(signal));
+    const handleSignalAbort = () => stopReading(admissionAbortError(signal));
+
+    req.once("end", handleEnd);
+    req.once("error", handleError);
+    req.once("aborted", handleAborted);
+    signal?.addEventListener("abort", handleSignalAbort, { once: true });
+    if (signal?.aborted) handleSignalAbort();
+    else {
+      req.on("data", handleData);
+      req.resume?.();
+    }
+  });
+}
+
+async function readRequestBuffer(req, maxBytes, signal) {
   const contentLength = requestContentLength(req);
   if (Number.isFinite(contentLength) && contentLength > maxBytes) {
     throw payloadTooLarge("Raw", maxBytes);
@@ -185,16 +348,18 @@ async function readRequestBuffer(req, maxBytes) {
 
   const chunks = [];
   let total = 0;
-  for await (const chunk of req) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    total += buffer.length;
-    if (total > maxBytes) throw payloadTooLarge("Raw", maxBytes);
-    chunks.push(buffer);
-  }
+  await consumeRequestChunks(req, {
+    signal,
+    onChunk(buffer) {
+      total += buffer.length;
+      if (total > maxBytes) throw payloadTooLarge("Raw", maxBytes);
+      chunks.push(buffer);
+    },
+  });
   return Buffer.concat(chunks);
 }
 
-async function readIdentityText(req, maxBodyBytes, maxDecodedBodyBytes) {
+async function readIdentityText(req, maxBodyBytes, maxDecodedBodyBytes, signal) {
   const contentLength = requestContentLength(req);
   if (Number.isFinite(contentLength) && contentLength > maxBodyBytes) {
     throw payloadTooLarge("Raw", maxBodyBytes);
@@ -206,13 +371,15 @@ async function readIdentityText(req, maxBodyBytes, maxDecodedBodyBytes) {
   const decoder = new TextDecoder();
   let text = "";
   let total = 0;
-  for await (const chunk of req) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    total += buffer.length;
-    if (total > maxBodyBytes) throw payloadTooLarge("Raw", maxBodyBytes);
-    if (total > maxDecodedBodyBytes) throw payloadTooLarge("Decoded", maxDecodedBodyBytes);
-    text += decoder.decode(buffer, { stream: true });
-  }
+  await consumeRequestChunks(req, {
+    signal,
+    onChunk(buffer) {
+      total += buffer.length;
+      if (total > maxBodyBytes) throw payloadTooLarge("Raw", maxBodyBytes);
+      if (total > maxDecodedBodyBytes) throw payloadTooLarge("Decoded", maxDecodedBodyBytes);
+      text += decoder.decode(buffer, { stream: true });
+    },
+  });
   return text + decoder.decode();
 }
 
@@ -267,22 +434,34 @@ function parseRequestJson(text) {
 }
 
 export async function readJsonBody(req, {
+  admission,
   maxBodyBytes = MAX_BODY_BYTES,
   maxDecodedBodyBytes = MAX_DECODED_BODY_BYTES,
+  signal,
 } = {}) {
+  if (signal?.aborted) throw admissionAbortError(signal);
   const encodings = contentEncodings(req.headers?.["content-encoding"]);
   if (encodings.every((encoding) => encoding === "identity")) {
-    return parseRequestJson(await readIdentityText(req, maxBodyBytes, maxDecodedBodyBytes));
+    return parseRequestJson(await readIdentityText(req, maxBodyBytes, maxDecodedBodyBytes, signal));
   }
-  const buffer = await readRequestBuffer(req, maxBodyBytes);
-  let decoded;
+  const buffer = await readRequestBuffer(req, maxBodyBytes, signal);
+  const releaseDecompression = await admission?.acquireDecompression?.({ signal }) || (() => {});
   try {
-    decoded = await decodeRequestBuffer(buffer, req.headers?.["content-encoding"], maxDecodedBodyBytes);
-  } catch (e) {
-    if (e?.statusCode) throw e;
-    throw httpError(`Invalid compressed request body: ${e.message}`, 400);
+    let decoded;
+    try {
+      decoded = await decodeRequestBuffer(buffer, req.headers?.["content-encoding"], maxDecodedBodyBytes);
+    } catch (e) {
+      if (e?.statusCode) throw e;
+      throw httpError(`Invalid compressed request body: ${e.message}`, 400);
+    }
+    if (signal?.aborted) throw admissionAbortError(signal);
+    if (decoded.length > 0) {
+      await admission?.reserveDecodedBody?.(decoded.length, { signal });
+    }
+    return parseRequestJson(decoded.toString("utf8"));
+  } finally {
+    releaseDecompression();
   }
-  return parseRequestJson(decoded.toString("utf8"));
 }
 
 export function sendJsonError(res, err, fallbackStatus = 400) {
@@ -291,7 +470,10 @@ export function sendJsonError(res, err, fallbackStatus = 400) {
     res.end();
     return;
   }
-  res.writeHead(err?.statusCode || fallbackStatus, { "Content-Type": "application/json" });
+  const statusCode = err?.statusCode || fallbackStatus;
+  const headers = { "Content-Type": "application/json" };
+  if (statusCode === 408 || statusCode === 413) headers.Connection = "close";
+  res.writeHead(statusCode, headers);
   res.end(JSON.stringify(err?.jsonBody || { error: err?.message || "Request failed" }));
 }
 
@@ -327,7 +509,8 @@ export function isAbortLikeError(err) {
 }
 
 export function abortErrorStatusCode(reason) {
-  if (["upstream_timeout", "stream_handshake_timeout", "stream_idle_timeout"].includes(reason)) return 504;
+  if (reason === "request_body_timeout") return 408;
+  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;
 }
@@ -352,6 +535,7 @@ export function createRequestAbort(req, res) {
   return {
     signal: controller.signal,
     get reason() { return reason; },
+    abort,
     setTimeout(ms, nextReason = "upstream_timeout") {
       if (timer) clearTimeout(timer);
       timer = null;

package/src/legacy-command-warning.mjs

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { atomicWriteFileSync } from "./atomic-file.mjs";
+
+export const LEGACY_COMMAND_WARNING_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
+export const LEGACY_COMMAND_WARNING = "codex-copilot-dx is deprecated; use ccdx instead. The compatibility alias will be removed in a future breaking release.";
+
+export function legacyCommandWarningPath({ env = process.env, home = os.homedir() } = {}) {
+  const xdgCacheHome = String(env.XDG_CACHE_HOME || "").trim();
+  const cacheRoot = xdgCacheHome || path.join(home, ".cache");
+  return path.join(cacheRoot, "codex-copilot-dx", "legacy-command-warning");
+}
+
+export function shouldShowLegacyCommandWarning({
+  env = process.env,
+  home = os.homedir(),
+  interactive = process.stderr.isTTY === true,
+  now = Date.now(),
+} = {}) {
+  if (!interactive) return false;
+  const filePath = legacyCommandWarningPath({ env, home });
+  try {
+    const previous = Number.parseInt(fs.readFileSync(filePath, "utf8"), 10);
+    if (Number.isFinite(previous) && Math.abs(now - previous) < LEGACY_COMMAND_WARNING_INTERVAL_MS) {
+      return false;
+    }
+  } catch {
+    // A missing or unreadable cache must not prevent the compatibility command.
+  }
+  try {
+    atomicWriteFileSync(filePath, `${now}\n`, { mode: 0o600 });
+  } catch {
+    // The warning remains best effort when the cache directory is read-only.
+  }
+  return true;
+}

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/pm-studio-relay.mjs

@@ -252,6 +252,9 @@ async function relayUpstreamResponse(response, reqBody, res, abort, streamIdleTi
 function safeFailure(error, abort) {
   if (error?.statusCode && !isAbortLikeError(error)) return error;
   if (abort?.signal.aborted || isAbortLikeError(error)) {
+    if (abort?.reason === "request_body_timeout") {
+      return localError(408, "request_timeout", "PM Studio relay request body timed out");
+    }
     return localError(
       abortErrorStatusCode(abort?.reason),
       "upstream_timeout",
@@ -277,6 +280,7 @@ export function createPmStudioRelayHandler(options = {}) {
   const upstreamTimeoutMs = parsePositiveInteger(options.upstreamTimeoutMs, runtime.upstreamTimeoutMs);
   const streamHandshakeTimeoutMs = parsePositiveInteger(options.streamHandshakeTimeoutMs, runtime.streamHandshakeTimeoutMs);
   const streamIdleTimeoutMs = parsePositiveInteger(options.streamIdleTimeoutMs, runtime.streamIdleTimeoutMs);
+  const requestBodyTimeoutMs = parsePositiveInteger(options.requestBodyTimeoutMs, runtime.requestBodyTimeoutMs);
   const validationTtlMs = parsePositiveInteger(options.validationTtlMs, DEFAULT_VALIDATION_TTL_MS);
   const validationCacheSize = parsePositiveInteger(options.validationCacheSize, DEFAULT_VALIDATION_CACHE_SIZE, 4096);
   const validationConcurrency = parsePositiveInteger(
@@ -430,8 +434,10 @@ export function createPmStudioRelayHandler(options = {}) {
   async function handlePost(req, res, pathname, token, abort) {
     let releaseRequest = releaseOnce();
     try {
-      releaseRequest = releaseOnce(await acquireRequest(req, { signal: abort.signal }));
-      const body = await readJsonBody(req);
+      const admission = await acquireRequest(req, { signal: abort.signal });
+      releaseRequest = releaseOnce(admission);
+      abort.setTimeout(requestBodyTimeoutMs, "request_body_timeout");
+      const body = await readJsonBody(req, { admission, signal: abort.signal });
       const supportsStream = pathname === "/chat/completions" || pathname === "/responses";
       const streaming = supportsStream && body?.stream === true;
       const requestTimeoutMs = streaming ? streamHandshakeTimeoutMs : upstreamTimeoutMs;

package/src/response-history.mjs

@@ -174,7 +174,11 @@ export function responseHistoryStats() {
   return { entries: histories.size, bytes: totalBytes, evicted: evictedIds.size };
 }
 
-export function materializeResponseHistory(responseId) {
+export function responseHistoryRootId(responseId) {
+  return histories.get(responseId)?.rootId || null;
+}
+
+function responseHistoryChain(responseId) {
   const chain = [];
   const seen = new Set();
   let currentId = responseId;
@@ -189,7 +193,16 @@ export function materializeResponseHistory(responseId) {
     chain.push(entry);
     currentId = entry.parentId;
   }
-  const rootId = chain[0]?.rootId;
+  return { chain, rootId: chain[0]?.rootId };
+}
+
+export function responseHistoryMaterializedBytes(responseId) {
+  const { chain } = responseHistoryChain(responseId);
+  return chain.reduce((bytes, entry) => bytes + entry.bytes, 0);
+}
+
+export function materializeResponseHistory(responseId) {
+  const { chain, rootId } = responseHistoryChain(responseId);
   const items = [];
   for (const entry of chain.reverse()) items.push(...entry.inputItems, ...entry.outputItems);
   const materialized = cloneJson(items);

package/src/responses-bridge.mjs

@@ -143,35 +143,55 @@ export function chatToResponses(chatResp, model) {
 
 export async function forwardToChat(chatReq, emitEvent, onDone, onError, options = {}) {
   delete chatReq.max_tokens;
-  const upstreamReq = withChatStreamUsage(chatReq);
-  const bodyText = upstreamReq === chatReq ? options.bodyText : undefined;
+  const requestModel = chatReq.model || "unknown";
+  let upstreamReq = withChatStreamUsage(chatReq);
+  let {
+    abort,
+    bodyText,
+    chatCompletionsFn: configuredChatCompletionsFn,
+    onUpstreamResponse,
+    onUpstreamStart,
+    releaseRequest,
+    signal,
+    streamIdleTimeoutMs,
+  } = options;
+  options = undefined;
+  if (upstreamReq !== chatReq) bodyText = undefined;
   let resp;
   try {
-    const chatCompletionsFn = options.chatCompletionsFn || chatCompletions;
+    const chatCompletionsFn = configuredChatCompletionsFn || chatCompletions;
     try {
-      resp = await chatCompletionsFn(upstreamReq, { signal: options.signal, bodyText });
+      onUpstreamStart?.();
+      resp = await chatCompletionsFn(upstreamReq, {
+        signal,
+        bodyText,
+        onUpstreamStart,
+      });
     } finally {
-      options.releaseRequest?.();
+      bodyText = undefined;
+      chatReq = undefined;
+      upstreamReq = undefined;
+      releaseRequest?.();
     }
   } catch (e) {
-    const statusCode = isAbortLikeError(e) ? abortErrorStatusCode(options.abort?.reason) : 502;
+    const statusCode = isAbortLikeError(e) ? abortErrorStatusCode(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");
+  onUpstreamResponse?.(resp);
+  abort?.setTimeout(streamIdleTimeoutMs, "stream_idle_timeout");
   const respId = `resp_${uid()}`;
-  let actualModel = chatReq.model || "unknown";
+  let actualModel = requestModel;
   let fullText = "";
   let messageItem = null;
   let nextOutputIndex = 0;
@@ -275,11 +295,11 @@ export async function forwardToChat(chatReq, emitEvent, onDone, onError, options
 
   try {
     for await (const line of webStreamLines(resp, {
-      onChunk: () => options.abort?.setTimeout(options.streamIdleTimeoutMs, "stream_idle_timeout"),
+      onChunk: () => abort?.setTimeout(streamIdleTimeoutMs, "stream_idle_timeout"),
     })) {
       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);
@@ -329,10 +349,11 @@ export async function forwardToChat(chatReq, emitEvent, onDone, onError, options
       }
     }
   } catch (e) {
-    const statusCode = isAbortLikeError(e) ? abortErrorStatusCode(options.abort?.reason) : (e?.statusCode || 502);
+    const statusCode = isAbortLikeError(e) ? abortErrorStatusCode(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) {