codex-copilot-dx 0.6.14 → 0.6.15

package/README.md

@@ -91,7 +91,10 @@ Once enabled, routing is fixed by API surface rather than by model name:
 
 The two profiles keep separate service tokens, API bases, refresh/backoff state,
 model endpoint metadata, and credential-bound model caches. Switching either
-GitHub account invalidates that profile's old cache instead of borrowing it. If the isolated Claude profile later
+GitHub account invalidates that profile's old cache instead of borrowing it.
+Cached catalogs are fresh for two hours; older catalogs remain immediately
+available for up to seven days while CCDX refreshes them in the background.
+If the isolated Claude profile later
 becomes invalid, Claude requests fail with a reauthentication instruction while
 Codex remains available; CCDX never silently falls back to the enterprise
 account. Reauthorize it explicitly with:

package/package.json

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

package/src/adapter.mjs

@@ -41,14 +41,18 @@ export {
   responseHistoryStats,
 } from "./response-history.mjs";
 export { forwardToChat, responsesToChat } from "./responses-bridge.mjs";
+export {
+  openCopilotResponse,
+} from "./copilot-responses-compat.mjs";
 export {
   isEncryptedContentVerificationError,
   isImageNamespaceCollisionError,
-  openCopilotResponse,
+  sanitizeImageNamespaceCollisionRequest,
+} from "./copilot-responses-policy.mjs";
+export {
   prepareResponsesRequest,
   rememberResponseHistory,
   sanitizeEncryptedReasoningRequest,
-  sanitizeImageNamespaceCollisionRequest,
   stripInternalResponsesInputFields,
 } from "./responses-request.mjs";
 

package/src/anthropic-handler.mjs

@@ -20,6 +20,42 @@ import { requireUpstreamEventStream, withChatStreamUsage } from "./stream-contra
 import { safeUpstreamResponseHeaders } from "./upstream-headers.mjs";
 import { recordAnthropicUsage } from "./usage.mjs";
 
+const PROMPT_TOO_LONG_MESSAGE = "prompt is too long: your prompt is too long. Please reduce the number of messages or use a model with a larger context window.";
+
+function contextWindowErrorBody(text) {
+  let error;
+  try {
+    const parsed = JSON.parse(text);
+    error = parsed && typeof parsed === "object" ? parsed.error : null;
+  } catch {
+    error = { message: text };
+  }
+  if (!error || typeof error !== "object") return null;
+  const code = error.code;
+  const message = typeof error.message === "string" ? error.message.toLowerCase() : "";
+  const matches = code === "context_length_exceeded"
+    || code === "model_max_prompt_tokens_exceeded"
+    || message.includes("exceeds the context window of this model")
+    || message.includes("maximum context length is")
+    || message.includes("request body is too large for model context window");
+  if (!matches) return null;
+  return JSON.stringify({
+    type: "error",
+    error: { type: "invalid_request_error", message: PROMPT_TOO_LONG_MESSAGE },
+  });
+}
+
+function sendAnthropicUpstreamError(res, response, text) {
+  const rewritten = contextWindowErrorBody(text);
+  if (!rewritten) {
+    sendUpstreamError(res, response, text);
+    return;
+  }
+  const headers = new Headers(response.headers);
+  headers.set("content-type", "application/json");
+  sendUpstreamError(res, { status: response.status, headers }, rewritten);
+}
+
 export function createAnthropicCountTokensHandler(options) {
   const { acquireRequest, requestBodyTimeoutMs } = options;
 
@@ -76,7 +112,7 @@ export function createAnthropicMessagesHandler(options) {
         const upstream = await chatCompletionsFn(withChatStreamUsage(chatReq), { signal: abort.signal });
         releaseRequest();
         if (!upstream.ok) {
-          sendUpstreamError(res, upstream, await upstream.text());
+          sendAnthropicUpstreamError(res, upstream, await upstream.text());
           return;
         }
         await requireUpstreamEventStream(upstream);
@@ -113,7 +149,7 @@ export function createAnthropicMessagesHandler(options) {
         releaseRequest();
         const data = await upstream.text();
         if (!upstream.ok) {
-          sendUpstreamError(res, upstream, data);
+          sendAnthropicUpstreamError(res, upstream, data);
           return;
         }
         const anthropicMessage = chatToAnthropic(JSON.parse(data), requestedModel, { forceModel: forceRequestedModel });

package/src/anthropic.mjs

@@ -44,26 +44,10 @@ function toolResultContent(content) {
 }
 
 // Convert one Anthropic message into zero or more OpenAI messages.
-function convertMessage(msg) {
-  const out = [];
-  const role = msg.role; // "user" | "assistant"
-
-  if (typeof msg.content === "string") {
-    out.push({ role, content: msg.content });
-    return out;
-  }
-  if (!Array.isArray(msg.content)) return out;
-
-  // tool_result blocks must become independent role:"tool" messages.
-  const toolResults = msg.content.filter((b) => b.type === "tool_result");
-  for (const tr of toolResults) {
-    out.push({ role: "tool", tool_call_id: tr.tool_use_id, content: toolResultContent(tr.content) });
-  }
-
-  // Convert remaining text, image, and tool_use blocks.
+function convertContentBlocks(role, blocks) {
   const textImageParts = [];
   const toolCalls = [];
-  for (const b of msg.content) {
+  for (const b of blocks) {
     if (b.type === "text") {
       textImageParts.push({ type: "text", text: b.text });
     } else if (b.type === "image") {
@@ -80,17 +64,66 @@ function convertMessage(msg) {
     const m = { role, content: null, tool_calls: toolCalls };
     if (textImageParts.length === 1 && textImageParts[0].type === "text") m.content = textImageParts[0].text;
     else if (textImageParts.length > 0) m.content = textImageParts;
-    out.push(m);
+    return m;
   } else if (textImageParts.length > 0) {
     if (textImageParts.length === 1 && textImageParts[0].type === "text") {
-      out.push({ role, content: textImageParts[0].text });
+      return { role, content: textImageParts[0].text };
     } else {
-      out.push({ role, content: textImageParts });
+      return { role, content: textImageParts };
+    }
+  }
+  return null;
+}
+
+function convertMessage(msg) {
+  const out = [];
+  const role = msg.role; // "user" | "assistant"
+
+  if (typeof msg.content === "string") {
+    out.push({ role, content: msg.content });
+    return out;
+  }
+  if (!Array.isArray(msg.content)) return out;
+
+  if (!msg.content.some((block) => block.type === "tool_result")) {
+    const converted = convertContentBlocks(role, msg.content);
+    if (converted) out.push(converted);
+    return out;
+  }
+
+  let contentBlocks = [];
+  const flushContent = () => {
+    const converted = convertContentBlocks(role, contentBlocks);
+    if (converted) out.push(converted);
+    contentBlocks = [];
+  };
+  for (const block of msg.content) {
+    if (block.type !== "tool_result") {
+      contentBlocks.push(block);
+      continue;
     }
+    flushContent();
+    out.push({
+      role: "tool",
+      tool_call_id: block.tool_use_id,
+      content: toolResultContent(block.content),
+    });
   }
+  flushContent();
   return out;
 }
 
+function toolInputSchema(inputSchema) {
+  if (inputSchema
+    && typeof inputSchema === "object"
+    && !Array.isArray(inputSchema)
+    && inputSchema.type === "object"
+    && Object.keys(inputSchema).length === 1) {
+    return { type: "object", properties: {} };
+  }
+  return inputSchema;
+}
+
 function mapToolChoice(tc) {
   if (!tc) return undefined;
   switch (tc.type) {
@@ -119,7 +152,7 @@ export function anthropicToChat(body, options = {}) {
   if (Array.isArray(body.tools) && body.tools.length) {
     chatReq.tools = body.tools.map((t) => ({
       type: "function",
-      function: { name: t.name, description: t.description, parameters: t.input_schema },
+      function: { name: t.name, description: t.description, parameters: toolInputSchema(t.input_schema) },
     }));
   }
   const tc = mapToolChoice(body.tool_choice);

package/src/copilot-responses-compat.mjs

@@ -0,0 +1,73 @@
+import { responses as copilotResponses } from "./copilot.mjs";
+import {
+  isEncryptedContentVerificationError,
+  isImageNamespaceCollisionError,
+  sanitizeImageNamespaceCollisionRequest,
+} from "./copilot-responses-policy.mjs";
+import { httpError } from "./http-transport.mjs";
+import {
+  finalizeEncryptedHistoryRebase,
+  sanitizeEncryptedReasoningRequest,
+} from "./responses-request.mjs";
+import { status } from "./status.mjs";
+
+// Ordered Copilot-only fallbacks. Each policy is single-use and must be gated
+// by an exact upstream failure plus a request transformation that changes the
+// payload. Generic Responses preparation does not decide whether to retry.
+const RETRY_POLICIES = Object.freeze([
+  Object.freeze({
+    id: "image-namespace-collision",
+    matches: isImageNamespaceCollisionError,
+    apply: sanitizeImageNamespaceCollisionRequest,
+    warning: "image_gen namespace rejected by upstream; retrying without the conflicting image tool",
+  }),
+  Object.freeze({
+    id: "encrypted-replay-rejected",
+    matches: isEncryptedContentVerificationError,
+    apply: sanitizeEncryptedReasoningRequest,
+    warning: "encrypted replay content rejected by upstream; retrying without unavailable encrypted content",
+  }),
+]);
+
+export async function openCopilotResponse(reqContext, upstream = copilotResponses, options = {}) {
+  const usedPolicies = new Set();
+  let payloadPrepared = false;
+  for (let attempt = 0; attempt <= RETRY_POLICIES.length; attempt += 1) {
+    options.assertPrepareActive?.();
+    const resp = await upstream(reqContext.body, {
+      assertActive: options.assertPrepareActive,
+      signal: options.signal,
+      currentInputStart: reqContext.currentInputStart,
+      onUpstreamStart: options.onUpstreamStart,
+      payloadPrepared,
+    });
+    options.assertPrepareActive?.();
+    payloadPrepared = true;
+    if (resp.ok) {
+      reqContext = finalizeEncryptedHistoryRebase(reqContext);
+      return { resp, reqContext };
+    }
+
+    const errorText = await resp.text();
+    options.assertPrepareActive?.();
+    let retryPolicy = null;
+    let retryContext = null;
+    for (const policy of RETRY_POLICIES) {
+      if (usedPolicies.has(policy.id) || !policy.matches(resp.status, errorText)) continue;
+      const candidate = policy.apply(reqContext);
+      if (candidate) {
+        retryPolicy = policy;
+        retryContext = candidate;
+        break;
+      }
+    }
+    if (retryPolicy && retryContext) {
+      usedPolicies.add(retryPolicy.id);
+      reqContext = retryContext;
+      console.warn(status("warn", retryPolicy.warning));
+      continue;
+    }
+    return { resp, reqContext, errorText };
+  }
+  throw httpError("Responses compatibility retry limit exceeded", 502);
+}

package/src/copilot-responses-policy.mjs

@@ -0,0 +1,78 @@
+function cloneJson(value) {
+  return value === undefined ? undefined : structuredClone(value);
+}
+
+export function isEncryptedContentVerificationError(statusCode, text) {
+  if (statusCode < 400 || !text) return false;
+  const lower = String(text).toLowerCase();
+  const reasoningFailure = lower.includes("encrypted content")
+    && lower.includes("could not be verified")
+    && (lower.includes("could not be decrypted") || lower.includes("could not be parsed"));
+  const functionOutputFailure = lower.includes("encrypted function output content")
+    && lower.includes("could not be decrypted or decoded");
+  const missingEncryptedContent = statusCode < 500
+    && /missing required parameter:\s*(['"]?)input\[\d+\](?:\.[a-z0-9_]+|\[\d+\])*\.encrypted_content\1(?=\.?(?:\s|$|["},\]]))/.test(lower);
+  return reasoningFailure || functionOutputFailure || missingEncryptedContent;
+}
+
+export function isImageNamespaceCollisionError(statusCode, text) {
+  if (statusCode < 400 || !text) return false;
+  const lower = String(text).toLowerCase();
+  return lower.includes("namespace")
+    && lower.includes("image_gen")
+    && lower.includes("collid");
+}
+
+export function isCopilotImageNamespaceTool(tool, { collisionFallback = false } = {}) {
+  if (!tool || typeof tool !== "object") return false;
+  const type = String(tool.type || "").toLowerCase();
+  if (["image_gen", "image_generation"].includes(type)) return true;
+  if (!collisionFallback) return false;
+  const name = String(tool.name || tool.function?.name || "").toLowerCase();
+  const namespace = String(tool.namespace || "").toLowerCase();
+  if (["image_gen", "image_generation"].includes(name)) return true;
+  if (namespace === "image_gen" || namespace === "image_generation") return true;
+  return [type, name, namespace].some((value) => value.startsWith("image_gen"));
+}
+
+function toolName(tool) {
+  return String(tool?.name || tool?.function?.name || "").trim();
+}
+
+// Copilot currently rejects the public image-generation tool. Keep this
+// provider-owned policy paired with tool_choice so request invariants survive
+// the removal. Revalidate against Copilot before deleting or broadening it.
+// Reference: https://github.com/Menci/Floway/blob/ac2bbb04352033a7d9d74574a9d465d40395ef06/packages/provider-copilot/src/interceptors/openai-responses/strip-image-generation.ts
+export function applyCopilotResponsesRequestPolicies(body, options = {}) {
+  if (!Array.isArray(body?.tools)) return false;
+  const removedNames = new Set();
+  const filtered = body.tools.filter((tool) => {
+    const removed = isCopilotImageNamespaceTool(tool, options);
+    if (removed) {
+      const name = toolName(tool);
+      if (name) removedNames.add(name);
+    }
+    return !removed;
+  });
+  if (filtered.length === body.tools.length) return false;
+  if (filtered.length) body.tools = filtered;
+  else delete body.tools;
+
+  const choiceName = toolName(body.tool_choice);
+  const choiceTargetsRemovedTool = choiceName
+    && removedNames.has(choiceName)
+    && !filtered.some((tool) => toolName(tool) === choiceName);
+  if (isCopilotImageNamespaceTool(body.tool_choice, options)
+    || choiceTargetsRemovedTool
+    || (body.tool_choice === "required" && !body.tools)) {
+    delete body.tool_choice;
+  }
+  return true;
+}
+
+export function sanitizeImageNamespaceCollisionRequest(reqContext) {
+  if (!Array.isArray(reqContext?.body?.tools)) return null;
+  const body = cloneJson(reqContext.body);
+  if (!applyCopilotResponsesRequestPolicies(body, { collisionFallback: true })) return null;
+  return { ...reqContext, body };
+}

package/src/model-cache.mjs

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-const DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export const MODEL_CACHE_SOFT_TTL_MS = 2 * 60 * 60 * 1000;
+export const MODEL_CACHE_HARD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 const MODEL_CACHE_PROFILES = new Set(["codex", "claude"]);
 
 export function modelCachePath(home = os.homedir(), profile = "codex") {
@@ -23,40 +24,69 @@ export function isValidModelList(models) {
   return modelData(models) !== null;
 }
 
-export function loadModelCache({
+function normalizedTtl(value, fallback) {
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+export function loadModelCacheEntry({
   home = os.homedir(),
   profile = "codex",
   credentialFingerprint = "",
-  maxAgeMs = DEFAULT_MAX_AGE_MS,
+  softTtlMs = MODEL_CACHE_SOFT_TTL_MS,
+  hardTtlMs,
+  maxAgeMs,
   now = Date.now,
 } = {}) {
   try {
     const parsed = JSON.parse(fs.readFileSync(modelCachePath(home, profile), "utf8"));
     const savedAt = Date.parse(parsed.saved_at);
-    if (!Number.isFinite(savedAt) || now() - savedAt > maxAgeMs) return null;
+    if (!Number.isFinite(savedAt)) return null;
     const expectedFingerprint = String(credentialFingerprint || "").trim();
     if (expectedFingerprint && parsed.credential_fingerprint !== expectedFingerprint) return null;
     if (!isValidModelList(parsed.models)) return null;
-    return parsed.models;
+    const resolvedHardTtlMs = normalizedTtl(
+      hardTtlMs,
+      normalizedTtl(maxAgeMs, MODEL_CACHE_HARD_TTL_MS),
+    );
+    const resolvedSoftTtlMs = Math.min(
+      normalizedTtl(softTtlMs, MODEL_CACHE_SOFT_TTL_MS),
+      resolvedHardTtlMs,
+    );
+    const ageMs = Math.max(0, now() - savedAt);
+    if (ageMs > resolvedHardTtlMs) return null;
+    return {
+      models: parsed.models,
+      savedAtMs: savedAt,
+      ageMs,
+      state: ageMs > resolvedSoftTtlMs ? "stale" : "fresh",
+    };
   } catch {
     return null;
   }
 }
 
+export function loadModelCache(options = {}) {
+  return loadModelCacheEntry(options)?.models || null;
+}
+
 export function saveModelCache(models, {
   home = os.homedir(),
   profile = "codex",
   credentialFingerprint = "",
+  isCurrent = () => true,
+  now = Date.now,
 } = {}) {
   if (!isValidModelList(models)) return false;
+  if (typeof isCurrent === "function" && !isCurrent()) return false;
   const filePath = modelCachePath(home, profile);
   const tempPath = `${filePath}.${process.pid}.tmp`;
-  const payload = { saved_at: new Date().toISOString(), models };
+  const payload = { saved_at: new Date(now()).toISOString(), models };
   const fingerprint = String(credentialFingerprint || "").trim();
   if (fingerprint) payload.credential_fingerprint = fingerprint;
   fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
   try {
     fs.writeFileSync(tempPath, `${JSON.stringify(payload)}\n`, { mode: 0o600 });
+    if (typeof isCurrent === "function" && !isCurrent()) return false;
     fs.renameSync(tempPath, filePath);
     fs.chmodSync(filePath, 0o600);
     return true;

package/src/observability.mjs

@@ -116,11 +116,23 @@ function modelRegistryStatus(modelRegistry) {
   const modelData = Array.isArray(modelRegistry?.models)
     ? modelRegistry.models
     : modelRegistry?.models?.data;
-  return {
+  const result = {
     source: String(modelRegistry?.source || "built-in"),
     models: Array.isArray(modelData) ? modelData.length : 0,
     claude_models: Array.isArray(modelRegistry?.modelDefs) ? modelRegistry.modelDefs.length : 0,
   };
+  if (typeof modelRegistry?.cacheState === "string") {
+    const savedAtMs = Number(modelRegistry.cacheSavedAtMs);
+    result.cache_state = modelRegistry.cacheState;
+    result.cache_age_ms = Number.isFinite(savedAtMs) ? Math.max(0, Date.now() - savedAtMs) : null;
+    result.refresh_in_flight = modelRegistry.refreshInFlight === true;
+    result.generation = finiteRuntimeNumber(modelRegistry.generation);
+    result.last_error = typeof modelRegistry.lastError === "string" ? modelRegistry.lastError : null;
+    result.last_error_at_ms = Number.isFinite(modelRegistry.lastErrorAtMs)
+      ? modelRegistry.lastErrorAtMs
+      : null;
+  }
+  return result;
 }
 
 function finiteRuntimeNumber(value, fallback = 0) {

package/src/pm-studio-relay.mjs

@@ -445,11 +445,14 @@ export function createPmStudioRelayHandler(options = {}) {
       releaseRequest = releaseOnce(admission);
       abort.setTimeout(requestBodyTimeoutMs, "request_body_timeout");
       const body = await readJsonBody(req, { admission, signal: abort.signal });
-      const modelType = modelRouter.classify(body?.model);
-      if (modelType === "unsupported_claude") {
+      const routePlan = modelRouter.plan(body?.model);
+      if (routePlan.disposition === "reject") {
         throw localError(400, "model_not_supported", "The requested Claude model is not enabled for PM Studio");
       }
-      if (modelType !== "claude") {
+      if (routePlan.disposition !== "relay"
+        || routePlan.origin !== "ccdx"
+        || routePlan.profile !== "claude"
+        || routePlan.protocol !== "openai-chat-completions") {
         throw localError(
           400,
           "native_route_required",

package/src/profile-model-runtime.mjs

@@ -1,6 +1,6 @@
 import {
   isValidModelList,
-  loadModelCache,
+  loadModelCacheEntry,
   saveModelCache,
 } from "./model-cache.mjs";
 import {
@@ -22,13 +22,48 @@ function parsedCatalog(result) {
   if (result?.status < 200 || result?.status >= 300) {
     throw new Error(`Copilot models returned HTTP ${result?.status}`);
   }
-  const models = JSON.parse(result.body);
+  let models;
+  try {
+    models = JSON.parse(result.body);
+  } catch {
+    throw new Error("Copilot models response was not valid JSON");
+  }
   if (!isValidModelList(models)) {
     throw new Error("Copilot models response contained no valid models");
   }
   return models;
 }
 
+function createModelRegistry() {
+  return {
+    modelDefs: undefined,
+    models: undefined,
+    source: "built-in",
+    cacheState: "none",
+    cacheSavedAtMs: null,
+    lastError: null,
+    lastErrorAtMs: null,
+    refreshInFlight: false,
+    generation: 0,
+  };
+}
+
+function sameModelDefs(left, right) {
+  if (left === right) return true;
+  if (!Array.isArray(left) || !Array.isArray(right)) return false;
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function safeRefreshError(error, { timedOut = false, timeoutMs } = {}) {
+  if (timedOut) return `Model refresh timed out after ${timeoutMs}ms`;
+  const raw = String(error?.message || error?.name || "Model refresh failed")
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .replace(/\b(?:github_pat_|gh[pousr]_|copilot_)[A-Za-z0-9._-]+\b/gi, "<redacted>")
+    .replace(/\bBearer\s+\S+/gi, "Bearer <redacted>")
+    .trim();
+  return (raw || "Model refresh failed").slice(0, 240);
+}
+
 export function createProfileModelRuntime({
   codexClient,
   claudeClient = codexClient,
@@ -51,11 +86,13 @@ export function createProfileModelRuntime({
     throw new Error("Isolated Claude models require an isolated Claude client");
   }
 
-  const codexRegistry = { modelDefs: undefined, models: undefined, source: "built-in" };
+  const codexRegistry = createModelRegistry();
   const claudeRegistry = claudeMode === "inherited"
     ? codexRegistry
-    : { modelDefs: undefined, models: undefined, source: "built-in" };
+    : createModelRegistry();
   const customClaudeDefs = parseModelAliasEnv(env.CCDX_CLAUDE_MODEL_ALIASES);
+  const refreshFlights = new Map();
+  const refreshGenerations = new Map();
   const refreshTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0
     ? timeoutMs
     : DEFAULT_TIMEOUT_MS;
@@ -85,8 +122,9 @@ export function createProfileModelRuntime({
       ? customClaudeDefs.map((model) => ({ ...model }))
       : claudeDesktopModelDefsFromCopilotModels(models);
     if (discovered.length) {
+      const changed = !sameModelDefs(registry.modelDefs, discovered);
       registry.modelDefs = discovered;
-      notifyClaudeModels(discovered);
+      if (changed) notifyClaudeModels(discovered);
     }
     return registry.modelDefs;
   }
@@ -96,11 +134,13 @@ export function createProfileModelRuntime({
       ? String(claudeCredentialFingerprint || "").trim()
       : String(codexCredentialFingerprint || "").trim();
     if (profile === "claude" && !credentialFingerprint) return false;
-    const cached = loadModelCache({ home, profile, credentialFingerprint });
+    const cached = loadModelCacheEntry({ home, profile, credentialFingerprint });
     if (!cached) return false;
     try {
-      applyCatalog({ client, models: cached, registry, source: "cache", ownsClaudeModels });
-      return true;
+      applyCatalog({ client, models: cached.models, registry, source: "cache", ownsClaudeModels });
+      registry.cacheState = cached.state;
+      registry.cacheSavedAtMs = cached.savedAtMs;
+      return { loaded: true, stale: cached.state === "stale" };
     } catch {
       return false;
     }
@@ -131,13 +171,22 @@ export function createProfileModelRuntime({
     }
   }
 
-  function persist(models, profile) {
+  function persist(models, profile, registry, generation) {
     const credentialFingerprint = profile === "claude"
       ? String(claudeCredentialFingerprint || "").trim()
       : String(codexCredentialFingerprint || "").trim();
     if (profile === "claude" && !credentialFingerprint) return;
     try {
-      saveModelCache(models, { home, profile, credentialFingerprint });
+      const saved = saveModelCache(models, {
+        home,
+        profile,
+        credentialFingerprint,
+        isCurrent: () => refreshGenerations.get(profile) === generation,
+      });
+      if (saved) {
+        registry.cacheState = "fresh";
+        registry.cacheSavedAtMs = Date.now();
+      }
     } catch (error) {
       const label = profile === "codex" ? "Copilot" : "Claude Copilot";
       emit("warn", `Could not persist the ${label} model cache (${error.message})`);
@@ -162,12 +211,13 @@ export function createProfileModelRuntime({
     return profile === "claude" ? "built-in model list" : "no cached model list";
   }
 
-  async function refreshProfile({ client, profile, registry, ownsClaudeModels, checksCodex }) {
+  async function performRefresh({ client, profile, registry, ownsClaudeModels, checksCodex }, generation) {
     const controllerLabel = claudeMode === "inherited"
       ? ""
       : `${profile === "codex" ? "Codex" : "Claude"} `;
     try {
       const models = await requestCatalog(client);
+      if (refreshGenerations.get(profile) !== generation) return registry.modelDefs;
       if (checksCodex) checkCodexCatalog(models);
       const modelDefs = applyCatalog({
         client,
@@ -176,20 +226,44 @@ export function createProfileModelRuntime({
         source: "live",
         ownsClaudeModels,
       });
-      persist(models, profile);
+      persist(models, profile, registry, generation);
+      registry.lastError = null;
+      registry.lastErrorAtMs = null;
       if (ownsClaudeModels) logClaudeCatalog(modelDefs);
       return modelDefs;
     } catch (error) {
+      if (refreshGenerations.get(profile) !== generation) return registry.modelDefs;
       const fallback = fallbackLabel(registry, profile);
       const timedOut = error?.name === "AbortError" || error?.code === "ABORT_ERR";
+      const diagnostic = safeRefreshError(error, { timedOut, timeoutMs: refreshTimeoutMs });
+      registry.lastError = diagnostic;
+      registry.lastErrorAtMs = Date.now();
       const message = timedOut
         ? `${controllerLabel}model refresh timed out after ${refreshTimeoutMs}ms; using ${fallback}`
-        : `Could not refresh ${controllerLabel.toLowerCase()}model list; using ${fallback} (${error.message})`;
+        : `Could not refresh ${controllerLabel.toLowerCase()}model list; using ${fallback} (${diagnostic})`;
       emit("warn", message[0].toUpperCase() + message.slice(1));
       return registry.modelDefs;
     }
   }
 
+  function refreshProfile(options) {
+    const { profile, registry } = options;
+    const existing = refreshFlights.get(profile);
+    if (existing) return existing.promise;
+
+    const generation = (refreshGenerations.get(profile) || 0) + 1;
+    refreshGenerations.set(profile, generation);
+    registry.generation = generation;
+    registry.refreshInFlight = true;
+    const flight = { generation, promise: null };
+    refreshFlights.set(profile, flight);
+    flight.promise = performRefresh(options, generation).finally(() => {
+      if (refreshFlights.get(profile) === flight) refreshFlights.delete(profile);
+      if (refreshGenerations.get(profile) === generation) registry.refreshInFlight = false;
+    });
+    return flight.promise;
+  }
+
   function refreshCodex() {
     return refreshProfile({
       client: codexClient,

package/src/profile-routing.mjs

@@ -2,6 +2,7 @@ import {
   isClaudeCopilotCatalogEntry,
   isClaudeCopilotModel,
 } from "./models.mjs";
+import { createRoutePlan } from "./route-plan.mjs";
 
 function catalogData(catalog) {
   if (Array.isArray(catalog)) return catalog;
@@ -47,14 +48,51 @@ export function createPmStudioModelRouter({ getCatalog, isClaudeEnabled } = {})
     return { allowed, known };
   }
 
+  function classify(modelId) {
+    const id = String(modelId || "").trim();
+    const { allowed, known } = availability();
+    if (allowed.has(id)) return "claude";
+    if (known.has(id) || id.toLowerCase().startsWith("claude-")) return "unsupported_claude";
+    return "enterprise";
+  }
+
+  function plan(modelId) {
+    const id = String(modelId || "").trim();
+    const modelType = classify(id);
+    const protocol = "openai-chat-completions";
+    if (modelType === "claude") {
+      return createRoutePlan({
+        disposition: "relay",
+        origin: "ccdx",
+        profile: "claude",
+        protocol,
+        model: id,
+        surface: "pm-studio",
+      });
+    }
+    if (modelType === "unsupported_claude") {
+      return createRoutePlan({
+        disposition: "reject",
+        origin: "ccdx",
+        profile: "claude",
+        protocol,
+        model: id || "unknown",
+        surface: "pm-studio",
+      });
+    }
+    return createRoutePlan({
+      disposition: "native",
+      origin: "pm-studio-native",
+      profile: "enterprise",
+      protocol,
+      model: id || "unknown",
+      surface: "pm-studio",
+    });
+  }
+
   return Object.freeze({
-    classify(modelId) {
-      const id = String(modelId || "").trim();
-      const { allowed, known } = availability();
-      if (allowed.has(id)) return "claude";
-      if (known.has(id) || id.toLowerCase().startsWith("claude-")) return "unsupported_claude";
-      return "enterprise";
-    },
+    plan,
+    classify,
     allowedModels() {
       return [...availability().allowed.values()];
     },

package/src/response-history.mjs

@@ -202,13 +202,17 @@ export function responseHistoryMaterializedBytes(responseId) {
   return chain.reduce((bytes, entry) => bytes + entry.bytes, 0);
 }
 
-export function materializeResponseHistory(responseId, { assertActive } = {}) {
+export function materializeResponseHistory(responseId, { assertActive, routeMetadata } = {}) {
   assertActive?.();
   const { chain, rootId } = responseHistoryChain(responseId);
   const items = [];
   for (let index = 0; index < chain.length; index += 1) {
     if ((index & 63) === 0) assertActive?.();
     const entry = chain[chain.length - index - 1];
+    routeMetadata?.push({
+      affinity: entry.routeAffinity || null,
+      hasOpaque: entry.hasOpaque === true,
+    });
     items.push(...entry.inputItems, ...entry.outputItems);
   }
   assertActive?.();
@@ -218,11 +222,22 @@ export function materializeResponseHistory(responseId, { assertActive } = {}) {
   return materialized;
 }
 
-export function rememberResponseHistoryNode({ id, parentId, inputItems, outputItems, takeOwnership = false }) {
+export function rememberResponseHistoryNode({
+  id,
+  parentId,
+  inputItems,
+  outputItems,
+  hasOpaque = false,
+  routeAffinity = null,
+  takeOwnership = false,
+}) {
   if (!id || !Array.isArray(inputItems)) return;
   clearResponsesToolOutputPartsCache(inputItems);
   clearResponsesToolOutputPartsCache(outputItems);
-  const bytes = jsonByteLength([inputItems, outputItems]);
+  const historyValue = routeAffinity
+    ? [inputItems, outputItems, { routeAffinity, hasOpaque: hasOpaque === true }]
+    : [inputItems, outputItems];
+  const bytes = jsonByteLength(historyValue);
   if (bytes > maxBytes) {
     if (histories.has(id)) removeSubtree(id);
     rememberEvictedId(id);
@@ -236,6 +251,8 @@ export function rememberResponseHistoryNode({ id, parentId, inputItems, outputIt
     rootId,
     inputItems: takeOwnership ? inputItems : cloneJson(inputItems),
     outputItems: takeOwnership ? outputItems : cloneJson(outputItems),
+    hasOpaque: hasOpaque === true,
+    routeAffinity: routeAffinity ? cloneJson(routeAffinity) : null,
     bytes,
   };
   const oldRootId = existing?.rootId;

package/src/responses-handler.mjs

@@ -1,4 +1,5 @@
 import { getCachedModelEndpoints } from "./copilot.mjs";
+import { applyCopilotResponsesRequestPolicies } from "./copilot-responses-policy.mjs";
 import {
   createRequestAbort,
   logRequestFailure,
@@ -20,10 +21,13 @@ import { clearResponsesToolOutputPartsCache } from "./responses-content.mjs";
 import { proxyCopilotResponses } from "./responses-proxy.mjs";
 import { responseHistoryMaterializedBytes } from "./response-history.mjs";
 import {
+  applyResponseHistoryRoutePlan,
   dropMaterializedResponseHistory,
   prepareResponsesRequest,
   rememberResponseHistory,
+  responseHistoryPressureRootId,
 } from "./responses-request.mjs";
+import { createRoutePlan } from "./route-plan.mjs";
 import { status } from "./status.mjs";
 import { endStreamWithError } from "./stream-errors.mjs";
 import { safeUpstreamResponseHeaders } from "./upstream-headers.mjs";
@@ -141,7 +145,7 @@ export function createResponsesHandler(options) {
     };
     const markAdaptiveHttpTimeout = (statusCode) => {
       if (statusCode !== 408) return false;
-      return imagePressure?.markTimeout?.(prepared?.historyRootId, {
+      return imagePressure?.markTimeout?.(responseHistoryPressureRootId(prepared), {
         eligible: imagePressureResult?.pressureEligible === true,
       }) || false;
     };
@@ -172,7 +176,11 @@ export function createResponsesHandler(options) {
         }
         assertPrepareActive();
       }
-      prepared = prepareResponsesRequest(parsed, { assertActive: assertPrepareActive, mutate: true });
+      prepared = prepareResponsesRequest(parsed, {
+        assertActive: assertPrepareActive,
+        copilotBoundary: false,
+        mutate: true,
+      });
       parsed = null;
       assertPrepareActive();
       imagePressureResult = imagePressure?.apply?.(prepared, { assertActive: assertPrepareActive }) || null;
@@ -192,7 +200,17 @@ export function createResponsesHandler(options) {
         || isResponsesOnlyModel(upstreamModel, getCachedModelEndpointsFn)
         || (usesCustomTools && cachedModelSupportsResponses(upstreamModel, getCachedModelEndpointsFn));
       if (usesCustomTools && !useNativeResponses) throw unsupportedCustomToolsError(upstreamModel);
-      if (useNativeResponses) {
+      const routePlan = createRoutePlan({
+        disposition: "relay",
+        origin: "ccdx",
+        profile: "codex",
+        protocol: useNativeResponses ? "openai-responses" : "openai-chat-completions",
+        model: upstreamModel,
+        surface: "responses",
+      });
+      prepared = applyResponseHistoryRoutePlan(prepared, routePlan);
+      applyCopilotResponsesRequestPolicies(prepared.body);
+      if (routePlan.protocol === "openai-responses") {
         const result = await proxyCopilotResponses(prepared, req, res, responsesFn, {
           assertPrepareActive,
           signal: abort.signal,
@@ -201,9 +219,9 @@ export function createResponsesHandler(options) {
           releaseRequest: releaseUpstreamPayload,
           streamIdleTimeoutMs,
         });
-        if (result?.successful) imagePressure?.markSuccess?.(prepared.historyRootId);
+        if (result?.successful) imagePressure?.markSuccess?.(responseHistoryPressureRootId(prepared));
         else markAdaptiveHttpTimeout(result?.upstreamStatus);
-      } else {
+      } else if (routePlan.protocol === "openai-chat-completions") {
         let { chatReq, bodyText } = await prepareResponsesChatPayload(prepared, {
           assertActive: assertPrepareActive,
           payloadOptions: responsesPayloadOptions,
@@ -254,7 +272,7 @@ export function createResponsesHandler(options) {
               });
             },
           });
-          if (successful) imagePressure?.markSuccess?.(prepared.historyRootId);
+          if (successful) imagePressure?.markSuccess?.(responseHistoryPressureRootId(prepared));
         } else {
           try {
             startUpstreamTimeout();
@@ -272,7 +290,7 @@ export function createResponsesHandler(options) {
             }
             const response = chatToResponses(JSON.parse(data), model);
             rememberResponseHistory(prepared, response);
-            imagePressure?.markSuccess?.(prepared.historyRootId);
+            imagePressure?.markSuccess?.(responseHistoryPressureRootId(prepared));
             recordResponsesUsage({ surface: prepared.surface, mode: "json", model, response, event: response });
             res.writeHead(200, safeUpstreamResponseHeaders(upstream.headers, {
               contentType: "application/json",
@@ -284,6 +302,8 @@ export function createResponsesHandler(options) {
             sendJsonError(res, responseError, 502);
           }
         }
+      } else {
+        throw new Error(`Unsupported Responses target protocol: ${routePlan.protocol}`);
       }
     } catch (error) {
       const responseError = applyAdaptiveTimeout(error);
@@ -351,7 +371,11 @@ export function createResponsesCompactHandler(options) {
         assertPrepareActive();
       }
       prepared = prepareResponsesCompactionRequest(
-        prepareResponsesRequest(parsed, { assertActive: assertPrepareActive, mutate: true }),
+        prepareResponsesRequest(parsed, {
+          assertActive: assertPrepareActive,
+          copilotBoundary: false,
+          mutate: true,
+        }),
       );
       assertPrepareActive();
       prepared.surface = "responses_compact";
@@ -360,6 +384,15 @@ 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`));
+      prepared = applyResponseHistoryRoutePlan(prepared, createRoutePlan({
+        disposition: "relay",
+        origin: "ccdx",
+        profile: "codex",
+        protocol: "openai-responses",
+        model: upstreamModel,
+        surface: "responses-compact",
+      }));
+      applyCopilotResponsesRequestPolicies(prepared.body);
       const result = await proxyCopilotResponses(prepared, req, res, responsesCompactFn, {
         assertPrepareActive,
         signal: abort.signal,
@@ -367,7 +400,7 @@ export function createResponsesCompactHandler(options) {
         onUpstreamStart: startUpstreamTimeout,
         releaseRequest: releaseUpstreamPayload,
       });
-      if (result?.compacted) imagePressure?.clear?.(prepared.historyRootId);
+      if (result?.compacted) imagePressure?.clear?.(responseHistoryPressureRootId(prepared));
     } catch (error) {
       logRequestFailure("Responses compact", error, abort);
       sendJsonError(res, error, 502);

package/src/responses-proxy.mjs

@@ -5,7 +5,8 @@ import {
   sendUpstreamError,
   writeOrDrain,
 } from "./http-transport.mjs";
-import { openCopilotResponse, rememberResponseHistory } from "./responses-request.mjs";
+import { openCopilotResponse } from "./copilot-responses-compat.mjs";
+import { rememberResponseHistory } from "./responses-request.mjs";
 import {
   compactionInputWithoutTrigger,
   parseResponsesCompactionResult,

package/src/responses-request.mjs

@@ -1,5 +1,4 @@
-import { responses as copilotResponses } from "./copilot.mjs";
-import { httpError } from "./http-transport.mjs";
+import { applyCopilotResponsesRequestPolicies } from "./copilot-responses-policy.mjs";
 import { debugLog } from "./log.mjs";
 import {
   materializeResponseHistory,
@@ -8,7 +7,20 @@ import {
 } from "./response-history.mjs";
 import { isResponsesToolOutputItem, readResponsesToolOutputParts } from "./responses-content.mjs";
 import { enforceResponsesImageLimit } from "./responses-image-limit.mjs";
-import { status } from "./status.mjs";
+import { routePlanAffinity, sameRoutePlanAffinity } from "./route-plan.mjs";
+
+export {
+  isEncryptedContentVerificationError,
+  isImageNamespaceCollisionError,
+  sanitizeImageNamespaceCollisionRequest,
+} from "./copilot-responses-policy.mjs";
+
+// Compatibility export for consumers that imported this helper before the
+// Copilot retry boundary moved into its provider-owned module.
+export async function openCopilotResponse(...args) {
+  const compatibility = await import("./copilot-responses-compat.mjs");
+  return compatibility.openCopilotResponse(...args);
+}
 
 function cloneJson(value) {
   return value === undefined ? undefined : structuredClone(value);
@@ -71,6 +83,8 @@ function isEncryptedContentPart(value) {
 
 const OMIT_ENCRYPTED_CONTENT = Symbol("omit-encrypted-content");
 const ENCRYPTED_HISTORY_REBASE = Symbol("encrypted-history-rebase");
+const RELEASE_HISTORY_INPUT = Symbol("release-history-input");
+const HISTORY_PRESSURE_ROOT = Symbol("history-pressure-root");
 const ENCRYPTED_TOOL_OUTPUT_MARKER = "[CCDX: encrypted tool output omitted because upstream could not decrypt it.]";
 
 function stripEncryptedReasoningValue(value, state) {
@@ -159,7 +173,21 @@ function isEncryptedReasoningInputItem(item) {
   return keys.length === 1 && keys[0] === "encrypted_content";
 }
 
-export function sanitizeEncryptedReasoningRequest(reqContext) {
+function responseValueHasOpaqueState(value) {
+  if (Array.isArray(value)) return value.some(responseValueHasOpaqueState);
+  if (!value || typeof value !== "object") return false;
+  if (isEncryptedReasoningInputItem(value)
+    || Object.prototype.hasOwnProperty.call(value, "encrypted_content")) {
+    return true;
+  }
+  if (isResponsesToolOutputItem(value) && typeof value.output === "string") {
+    const parsed = readResponsesToolOutputParts(value);
+    if (parsed?.parts.some(responseValueHasOpaqueState)) return true;
+  }
+  return Object.values(value).some(responseValueHasOpaqueState);
+}
+
+export function sanitizeEncryptedReasoningRequest(reqContext, { historicalOnly = false } = {}) {
   const state = { changed: false };
   let body = cloneJson(reqContext.body);
   let currentInputStart = reqContext.currentInputStart;
@@ -170,6 +198,10 @@ export function sanitizeEncryptedReasoningRequest(reqContext) {
     for (let index = 0; index < body.input.length; index += 1) {
       const item = body.input[index];
       const historical = Number.isFinite(currentInputStart) && index < currentInputStart;
+      if (historicalOnly && !historical) {
+        input.push(item);
+        continue;
+      }
       if (isEncryptedReasoningInputItem(item)) {
         state.changed = true;
         if (historical) historicalInputChanged = true;
@@ -188,11 +220,13 @@ export function sanitizeEncryptedReasoningRequest(reqContext) {
     }
     body.input = input;
     if (Number.isFinite(currentInputStart)) currentInputStart = retainedBeforeCurrent;
-  } else {
+  } else if (!historicalOnly) {
     body = stripEncryptedReasoningValue(body, state);
   }
   if (!state.changed) return null;
-  const historyInputItems = Array.isArray(reqContext.historyInputItems)
+  const historyInputItems = historicalOnly
+    ? reqContext.historyInputItems
+    : Array.isArray(reqContext.historyInputItems)
     ? reqContext.historyInputItems.flatMap((item) => {
       if (isEncryptedReasoningInputItem(item)) return [];
       const stripped = stripEncryptedReasoningInputValue(item, { changed: false });
@@ -210,10 +244,13 @@ export function sanitizeEncryptedReasoningRequest(reqContext) {
     currentInputStart,
     inputItems: Array.isArray(body.input) ? body.input : reqContext.inputItems,
     historyInputItems,
+    [RELEASE_HISTORY_INPUT]: historicalOnly
+      ? reqContext[RELEASE_HISTORY_INPUT]
+      : historyInputItems,
   };
 }
 
-function finalizeEncryptedHistoryRebase(reqContext) {
+export function finalizeEncryptedHistoryRebase(reqContext) {
   if (!reqContext[ENCRYPTED_HISTORY_REBASE]) return reqContext;
   const finalized = {
     ...reqContext,
@@ -226,98 +263,43 @@ function finalizeEncryptedHistoryRebase(reqContext) {
   return finalized;
 }
 
-export function isEncryptedContentVerificationError(statusCode, text) {
-  if (statusCode < 400 || !text) return false;
-  const lower = String(text).toLowerCase();
-  const reasoningFailure = lower.includes("encrypted content")
-    && lower.includes("could not be verified")
-    && (lower.includes("could not be decrypted") || lower.includes("could not be parsed"));
-  const functionOutputFailure = lower.includes("encrypted function output content")
-    && lower.includes("could not be decrypted or decoded");
-  const missingEncryptedContent = statusCode < 500
-    && /missing required parameter:\s*(['"]?)input\[\d+\](?:\.[a-z0-9_]+|\[\d+\])*\.encrypted_content\1(?=\.?(?:\s|$|["},\]]))/.test(lower);
-  return reasoningFailure || functionOutputFailure || missingEncryptedContent;
-}
-
-export function isImageNamespaceCollisionError(statusCode, text) {
-  if (statusCode < 400 || !text) return false;
-  const lower = String(text).toLowerCase();
-  return lower.includes("namespace")
-    && lower.includes("image_gen")
-    && lower.includes("collid");
-}
-
-function isImageNamespaceTool(tool, { collisionFallback = false } = {}) {
-  if (!tool || typeof tool !== "object") return false;
-  const type = String(tool.type || "").toLowerCase();
-  const name = String(tool.name || tool.function?.name || "").toLowerCase();
-  const namespace = String(tool.namespace || "").toLowerCase();
-  if (["image_gen", "image_generation"].includes(type)) return true;
-  if (["image_gen", "image_generation"].includes(name)) return true;
-  if (namespace === "image_gen" || namespace === "image_generation") return true;
-  return collisionFallback && [type, name, namespace].some((value) => value.startsWith("image_gen"));
-}
-
-export function sanitizeImageNamespaceCollisionRequest(reqContext) {
-  if (!Array.isArray(reqContext?.body?.tools)) return null;
-  const body = cloneJson(reqContext.body);
-  const filtered = body.tools.filter((tool) => !isImageNamespaceTool(tool, { collisionFallback: true }));
-  if (filtered.length === body.tools.length) return null;
-  if (filtered.length) body.tools = filtered;
-  else delete body.tools;
-  return { ...reqContext, body };
-}
-
-export async function openCopilotResponse(reqContext, upstream = copilotResponses, options = {}) {
-  let encryptedRetried = false;
-  let imageNamespaceRetried = false;
-  let payloadPrepared = false;
-  for (let attempt = 0; attempt < 3; attempt += 1) {
-    options.assertPrepareActive?.();
-    const resp = await upstream(reqContext.body, {
-      assertActive: options.assertPrepareActive,
-      signal: options.signal,
-      currentInputStart: reqContext.currentInputStart,
-      onUpstreamStart: options.onUpstreamStart,
-      payloadPrepared,
-    });
-    options.assertPrepareActive?.();
-    payloadPrepared = true;
-    if (resp.ok) {
-      reqContext = finalizeEncryptedHistoryRebase(reqContext);
-      return { resp, reqContext };
-    }
-
-    const errorText = await resp.text();
-    options.assertPrepareActive?.();
-    if (!imageNamespaceRetried && isImageNamespaceCollisionError(resp.status, errorText)) {
-      const retryContext = sanitizeImageNamespaceCollisionRequest(reqContext);
-      if (retryContext) {
-        imageNamespaceRetried = true;
-        reqContext = retryContext;
-        console.warn(status("warn", "image_gen namespace rejected by upstream; retrying without the conflicting image tool"));
-        continue;
-      }
-    }
-    if (!encryptedRetried && isEncryptedContentVerificationError(resp.status, errorText)) {
-      const retryContext = sanitizeEncryptedReasoningRequest(reqContext);
-      if (retryContext) {
-        encryptedRetried = true;
-        reqContext = retryContext;
-        console.warn(status("warn", "encrypted replay content rejected by upstream; retrying without unavailable encrypted content"));
-        continue;
-      }
-    }
-    return { resp, reqContext, errorText };
+export function applyResponseHistoryRoutePlan(reqContext, routePlan) {
+  const next = reqContext;
+  next.routePlan = routePlan;
+  if (!next.historyParentId) return next;
+  const currentAffinity = routePlanAffinity(routePlan);
+  const historyMetadata = next.historyRouteMetadata;
+  if (!currentAffinity
+    || !Array.isArray(historyMetadata)
+    || historyMetadata.length === 0
+    || historyMetadata.some((metadata) => metadata.affinity === null)) {
+    return next;
+  }
+  const hasMismatchedOpaqueState = historyMetadata.some((metadata) => (
+    metadata.hasOpaque && !sameRoutePlanAffinity(metadata.affinity, currentAffinity)
+  ));
+  if (!hasMismatchedOpaqueState) {
+    return next;
   }
-  throw httpError("Responses compatibility retry limit exceeded", 502);
+
+  const sanitized = sanitizeEncryptedReasoningRequest(next, { historicalOnly: true });
+  if (!sanitized) return next;
+  sanitized.routePlan = routePlan;
+  const historyRootId = next.historyRootId;
+  const rebased = finalizeEncryptedHistoryRebase(sanitized);
+  if (historyRootId) rebased[HISTORY_PRESSURE_ROOT] = historyRootId;
+  return rebased;
 }
 
-function isBuiltinImageTool(tool) {
-  return isImageNamespaceTool(tool);
+export function responseHistoryPressureRootId(reqContext) {
+  return reqContext?.[HISTORY_PRESSURE_ROOT] || reqContext?.historyRootId || null;
 }
 
-export function prepareResponsesRequest(reqBody, { assertActive, mutate = false } = {}) {
+export function prepareResponsesRequest(reqBody, {
+  assertActive,
+  copilotBoundary = true,
+  mutate = false,
+} = {}) {
   assertActive?.();
   const body = mutate ? reqBody : cloneJson(reqBody);
   assertActive?.();
@@ -328,9 +310,13 @@ export function prepareResponsesRequest(reqBody, { assertActive, mutate = false
   const previousId = body.previous_response_id;
   let historyItems = [];
   let historyRootId = null;
+  const historyRouteMetadata = [];
 
   if (previousId !== undefined && previousId !== null) {
-    historyItems = materializeResponseHistory(previousId, { assertActive });
+    historyItems = materializeResponseHistory(previousId, {
+      assertActive,
+      routeMetadata: historyRouteMetadata,
+    });
     historyRootId = responseHistoryRootId(previousId);
     body.input = [...historyItems, ...currentInputItems];
   } else {
@@ -351,10 +337,10 @@ export function prepareResponsesRequest(reqBody, { assertActive, mutate = false
 
   delete body.previous_response_id;
   delete body.store;
-  if (Array.isArray(body.tools)) {
-    body.tools = body.tools.filter((tool) => !isBuiltinImageTool(tool));
-    if (!body.tools.length) delete body.tools;
-  }
+  // Preserve the historical helper contract for embedders. Runtime handlers
+  // pass copilotBoundary:false and apply the policy only after selecting a
+  // concrete Copilot RoutePlan.
+  if (copilotBoundary) applyCopilotResponsesRequestPolicies(body);
   stripInternalResponsesInputFields(body.input, { assertActive });
   stripInternalResponsesInputFields(historyInputItems, { assertActive });
   assertActive?.();
@@ -366,15 +352,21 @@ export function prepareResponsesRequest(reqBody, { assertActive, mutate = false
     currentInputStart: retainedCurrentInputStart < 0 ? body.input.length : retainedCurrentInputStart,
     historyParentId: previousId ?? null,
     historyRootId,
+    historyRouteMetadata,
     historyInputItems,
+    ...(previousId !== undefined && previousId !== null
+      ? { [RELEASE_HISTORY_INPUT]: historyInputItems }
+      : {}),
     takeHistoryOwnership: mutate,
   };
 }
 
 export function dropMaterializedResponseHistory(reqContext) {
-  if (!reqContext?.historyParentId || !Array.isArray(reqContext.historyInputItems)) return false;
-  reqContext.body = { ...reqContext.body, input: reqContext.historyInputItems };
-  reqContext.inputItems = reqContext.historyInputItems;
+  const releaseInput = reqContext?.[RELEASE_HISTORY_INPUT];
+  if (!Array.isArray(releaseInput)) return false;
+  reqContext.body = { ...reqContext.body, input: releaseInput };
+  reqContext.inputItems = releaseInput;
+  delete reqContext[RELEASE_HISTORY_INPUT];
   reqContext.currentInputStart = 0;
   return true;
 }
@@ -391,6 +383,8 @@ export function rememberResponseHistory(reqContext, responseJson) {
     parentId: compacted ? null : reqContext.historyParentId,
     inputItems: sourceInputItems,
     outputItems: sourceOutputItems,
+    hasOpaque: responseValueHasOpaqueState([sourceInputItems, sourceOutputItems]),
+    routeAffinity: routePlanAffinity(reqContext.routePlan),
     takeOwnership: reqContext.takeHistoryOwnership,
   });
 }

package/src/route-plan.mjs

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+
+const DISPOSITIONS = new Set(["native", "relay", "reject"]);
+const MAX_AFFINITY_MODEL_BYTES = 512;
+
+function requiredString(value, name) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`Route plan ${name} is required`);
+  return normalized;
+}
+
+export function createRoutePlan({
+  disposition = "relay",
+  model,
+  origin,
+  profile,
+  protocol,
+  surface,
+} = {}) {
+  if (!DISPOSITIONS.has(disposition)) {
+    throw new Error(`Unsupported route disposition: ${disposition}`);
+  }
+  return Object.freeze({
+    disposition,
+    origin: requiredString(origin, "origin"),
+    profile: requiredString(profile, "profile"),
+    protocol: requiredString(protocol, "protocol"),
+    model: requiredString(model, "model"),
+    surface: requiredString(surface, "surface"),
+  });
+}
+
+export function routePlanAffinity(plan) {
+  if (!plan || typeof plan !== "object") return null;
+  const { origin, profile, protocol, model } = plan;
+  if (![origin, profile, protocol, model].every((value) => typeof value === "string" && value.length > 0)) {
+    return null;
+  }
+  const boundedModel = Buffer.byteLength(model) <= MAX_AFFINITY_MODEL_BYTES
+    ? model
+    : `sha256:${createHash("sha256").update(model).digest("hex")}`;
+  return Object.freeze({ origin, profile, protocol, model: boundedModel });
+}
+
+export function sameRoutePlanAffinity(left, right) {
+  return Boolean(left && right)
+    && left.origin === right.origin
+    && left.profile === right.profile
+    && left.protocol === right.protocol
+    && left.model === right.model;
+}

package/src/startup.mjs

@@ -2,9 +2,15 @@ export async function initializeModelRegistry({
   loadCached,
   currentModelDefs,
   refresh,
+  onBackgroundError = () => {},
 }) {
-  if (loadCached()) {
-    return { modelDefs: currentModelDefs(), source: "cache", backgroundRefresh: null };
+  const cached = loadCached();
+  const loaded = cached === true || cached?.loaded === true;
+  if (loaded) {
+    const backgroundRefresh = cached?.stale === true
+      ? runInBackground(refresh, onBackgroundError)
+      : null;
+    return { modelDefs: currentModelDefs(), source: "cache", backgroundRefresh };
   }
 
   return { modelDefs: await refresh(), source: "live", backgroundRefresh: null };