codex-copilot-dx 0.4.33 → 0.4.34

package/README.md

@@ -64,7 +64,15 @@ codex-copilot-dx doctor --online
 
 The online doctor never starts device flow, scans for replacement tokens, or changes the saved token.
 
-When the saved token is missing, `codex-copilot-dx` first looks for compatible local Copilot GitHub tokens, validates them with GitHub and Copilot, and imports a valid one before starting device login. It checks explicit token sources (`CCDX_GITHUB_TOKEN`, `CCDX_GITHUB_TOKEN_PATH`, `CCDX_GITHUB_TOKEN_PATHS`) plus common local `auth.json` layouts under application config directories. It does not rely on a specific app name. Generic discovery refuses to choose silently when valid tokens for multiple GitHub accounts are found. After an account is selected, automatic `401`/`403` recovery accepts only the same GitHub account. Explicit token variables remain the intentional way to switch accounts.
+To actively verify the protocol path through an already-running adapter, run:
+
+```bash
+codex-copilot-dx doctor --compat
+```
+
+The compatibility doctor sends a few minimal Copilot requests to check native Responses, streaming history, compaction, image tool namespace handling, and Anthropic streaming. It consumes a small amount of Copilot usage, never starts the adapter or device flow, and does not change client configuration. Combine it with `--online` when both the saved-token entitlement check and the adapter protocol checks are needed.
+
+When the saved token is missing, `codex-copilot-dx` first looks for compatible local Copilot GitHub tokens, validates them with GitHub and Copilot, and imports a valid one before starting device login. It checks explicit token sources (`CCDX_GITHUB_TOKEN`, `CCDX_GITHUB_TOKEN_PATH`, `CCDX_GITHUB_TOKEN_PATHS`) plus common local `auth.json` layouts under application config directories. It does not rely on a specific app name. Generic discovery refuses to choose silently when valid tokens for multiple GitHub accounts are found. After an account is selected, automatic `401`/`403` recovery and in-process token rotation accept only the same GitHub account. Concurrent callers share token refresh work without sharing cancellation, and a still-valid Copilot token may be used briefly after a transient refresh failure. Explicit token variables remain the intentional way to switch accounts.
 
 If Copilot token refresh still fails with `401` or `403`, the saved GitHub token may be expired, revoked, or missing Copilot access. Delete the saved token and start the tool again to trigger GitHub device login:
 
@@ -167,6 +175,7 @@ MIT
 ```bash
 npm ci
 npm run verify
+npm run bench:payload
 ```
 
-`npm test` runs the unit and handler-level suite. `npm run test:smoke` starts a real local HTTP adapter with fully injected offline upstreams. `npm run pack:check` verifies the npm tarball contents without publishing. The CI workflow runs all three checks on supported Node.js release lines.
+`npm test` runs the unit and handler-level suite. `npm run test:smoke` starts a real local HTTP adapter with fully injected offline upstreams. `npm run pack:check` verifies the npm tarball contents without publishing. `npm run bench:payload` is a report-only, isolated-process benchmark for 5-60 MiB image payloads and does not contact Copilot. The CI workflow runs the verification checks on supported Node.js release lines.

package/bin/cli.mjs

@@ -187,6 +187,7 @@ if (CLI.command === "doctor") {
     port: ADAPTER_PORT,
     host: ADAPTER_HOST,
     online: CLI.online,
+    compat: CLI.compat,
   });
   process.exit(checks.some((check) => check.kind === "err") ? 1 : 0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.4.33",
+  "version": "0.4.34",
   "description": "Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",
@@ -43,6 +43,7 @@
     "test:smoke": "node scripts/offline-smoke.mjs",
     "test:e2e": "bash test/e2e.sh",
     "bench": "node scripts/benchmark.mjs",
+    "bench:payload": "node scripts/benchmark.mjs --large-payload",
     "pack:check": "npm pack --dry-run --json",
     "verify": "npm test && npm run test:smoke && npm run pack:check",
     "prepublishOnly": "npm run verify"

package/scripts/benchmark.mjs

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import sharp from "sharp";
@@ -29,6 +32,114 @@ function deterministicPixels(byteLength, initialSeed) {
   return pixels;
 }
 
+function largePayloadProbe(targetMiB, concurrency) {
+  const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), "ccdx-payload-bench-"));
+  const fixtureStarted = performance.now();
+  try {
+    const generator = spawnSync(process.execPath, ["--input-type=module", "-e", `
+      import fs from "node:fs";
+      import path from "node:path";
+      import sharp from "sharp";
+      const targetBytes = ${targetMiB} * 1024 * 1024;
+      const requestConcurrency = ${concurrency};
+      const imageCount = 8;
+      const fixtureDir = ${JSON.stringify(fixtureDir)};
+      const basePng = await sharp({
+        create: { width: 32, height: 32, channels: 3, background: { r: 40, g: 90, b: 140 } },
+      }).png().toBuffer();
+      for (let requestIndex = 0; requestIndex < requestConcurrency; requestIndex += 1) {
+        const approximateDataUrlBytes = Math.floor(targetBytes / imageCount);
+        const rawBytes = Math.max(basePng.length, Math.floor((approximateDataUrlBytes - 32) * 3 / 4));
+        const content = [];
+        for (let imageIndex = 0; imageIndex < imageCount; imageIndex += 1) {
+          const raw = Buffer.alloc(rawBytes, (requestIndex * imageCount + imageIndex + 1) % 251);
+          basePng.copy(raw, 0);
+          content.push({ type: "input_image", image_url: \`data:image/png;base64,\${raw.toString("base64")}\` });
+        }
+        const source = {
+          model: "gpt-benchmark",
+          stream: false,
+          input: [{ type: "message", role: "user", content }],
+        };
+        fs.writeFileSync(path.join(fixtureDir, \`request-\${requestIndex}.json\`), JSON.stringify(source));
+      }
+    `], { cwd: packageRoot, encoding: "utf8" });
+    if (generator.status !== 0) {
+      throw new Error(generator.stderr.trim() || `benchmark fixture generator exited with ${generator.status}`);
+    }
+    const fixturePrepareMs = performance.now() - fixtureStarted;
+    const fixtureFiles = Array.from({ length: concurrency }, (_, index) => path.join(fixtureDir, `request-${index}.json`));
+    const result = runProbe(`
+      import fs from "node:fs";
+      import { prepareResponsesRequest } from "./src/adapter.mjs";
+      import { readJsonBody } from "./src/http-transport.mjs";
+      import { prepareResponsesPayload } from "./src/image-optimization.mjs";
+
+      const fixtureFiles = ${JSON.stringify(fixtureFiles)};
+      const memoryFields = ["rss", "heapUsed", "external", "arrayBuffers"];
+      const peak = {};
+      const sample = () => {
+        const memory = process.memoryUsage();
+        for (const field of memoryFields) peak[field] = Math.max(peak[field] || 0, memory[field] || 0);
+      };
+      globalThis.gc?.();
+      const idleMemory = process.memoryUsage();
+      for (const field of memoryFields) peak[field] = idleMemory[field] || 0;
+      const timer = setInterval(sample, 5);
+      timer.unref?.();
+
+      async function processRequest(filePath) {
+        const inputBytes = fs.statSync(filePath).size;
+        const req = fs.createReadStream(filePath);
+        req.headers = { "content-length": String(inputBytes), "content-encoding": "identity" };
+        const parsed = await readJsonBody(req);
+        req.destroy();
+        sample();
+        const prepared = prepareResponsesRequest(parsed, { mutate: true });
+        const result = await prepareResponsesPayload(prepared.body);
+        sample();
+        return { inputBytes, outputBytes: result.bodyBytes };
+      }
+
+      const originalLog = console.log;
+      const originalWarn = console.warn;
+      console.log = () => {};
+      console.warn = () => {};
+      const started = performance.now();
+      let results;
+      try {
+        results = await Promise.all(fixtureFiles.map(processRequest));
+      } finally {
+        clearInterval(timer);
+        console.log = originalLog;
+        console.warn = originalWarn;
+      }
+      sample();
+      const finalMemory = process.memoryUsage();
+      const mib = (bytes) => +(bytes / 1048576).toFixed(1);
+      const memory = Object.fromEntries(memoryFields.map((field) => [field.replace("Used", "_used").replace("Buffers", "_buffers").toLowerCase(), {
+        idle_mib: mib(idleMemory[field] || 0),
+        peak_mib: mib(peak[field] || 0),
+        peak_delta_mib: mib((peak[field] || 0) - (idleMemory[field] || 0)),
+        final_mib: mib(finalMemory[field] || 0),
+      }]));
+      process.stdout.write(JSON.stringify({
+        target_request_mib: ${targetMiB},
+        concurrency: fixtureFiles.length,
+        elapsed_ms: +(performance.now() - started).toFixed(1),
+        input_body_mib: results.map((entry) => mib(entry.inputBytes)),
+        output_body_mib: results.map((entry) => mib(entry.outputBytes)),
+        output_body_kib: results.map((entry) => +(entry.outputBytes / 1024).toFixed(1)),
+        memory,
+      }));
+    `);
+    result.fixture_prepare_ms = +fixturePrepareMs.toFixed(1);
+    return result;
+  } finally {
+    fs.rmSync(fixtureDir, { recursive: true, force: true });
+  }
+}
+
 const adapterImport = runProbe(`
   const started = performance.now();
   await import("./src/adapter.mjs");
@@ -126,10 +237,22 @@ try {
   console.warn = originalWarn;
 }
 
-console.log(JSON.stringify({
+const report = {
   note: "Report-only benchmark; timings vary by machine and are not pass/fail thresholds.",
   adapter_import: adapterImport,
   token_count_100kb: tokenCount,
   duplicate_images: duplicateImages,
   oversized_payload: oversizedPayload,
-}, null, 2));
+};
+
+if (process.argv.includes("--large-payload")) {
+  report.large_payload_peak = [
+    largePayloadProbe(5, 1),
+    largePayloadProbe(5, 4),
+    largePayloadProbe(30, 1),
+    largePayloadProbe(30, 2),
+    largePayloadProbe(60, 1),
+  ];
+}
+
+console.log(JSON.stringify(report, null, 2));

package/src/cli-options.mjs

@@ -7,28 +7,36 @@ function unexpectedArgs(args) {
 
 export function parseCliArgs(args = []) {
   const [command, ...rest] = args;
-  if (!command) return { command: "start", configureClaudeDesktop: false, online: false };
+  if (!command) return { command: "start", configureClaudeDesktop: false, online: false, compat: false };
   if (HELP_COMMANDS.has(command)) {
     if (rest.length) unexpectedArgs(rest);
-    return { command: "help", configureClaudeDesktop: false, online: false };
+    return { command: "help", configureClaudeDesktop: false, online: false, compat: false };
   }
   if (VERSION_COMMANDS.has(command)) {
     if (rest.length) unexpectedArgs(rest);
-    return { command: "version", configureClaudeDesktop: false, online: false };
+    return { command: "version", configureClaudeDesktop: false, online: false, compat: false };
   }
   if (command === "usage") {
     if (rest.length) unexpectedArgs(rest);
-    return { command: "usage", configureClaudeDesktop: false, online: false };
+    return { command: "usage", configureClaudeDesktop: false, online: false, compat: false };
   }
   if (command === "doctor" || command === "--doctor") {
-    const invalid = rest.filter((arg) => arg !== "--online");
+    const supported = new Set(["--online", "--compat"]);
+    const invalid = rest.filter((arg) => !supported.has(arg));
     if (invalid.length) unexpectedArgs(invalid);
-    if (rest.filter((arg) => arg === "--online").length > 1) unexpectedArgs(["--online"]);
-    return { command: "doctor", configureClaudeDesktop: false, online: rest.includes("--online") };
+    for (const option of supported) {
+      if (rest.filter((arg) => arg === option).length > 1) unexpectedArgs([option]);
+    }
+    return {
+      command: "doctor",
+      configureClaudeDesktop: false,
+      online: rest.includes("--online"),
+      compat: rest.includes("--compat"),
+    };
   }
   if (command === "--configure-claude-desktop") {
     if (rest.length) unexpectedArgs(rest);
-    return { command: "start", configureClaudeDesktop: true, online: false };
+    return { command: "start", configureClaudeDesktop: true, online: false, compat: false };
   }
   throw new Error(`Unknown command or option: ${command}`);
 }
@@ -62,7 +70,7 @@ export function parseRuntimeOptions(env = process.env) {
 export function cliHelp() {
   return `Usage:
   codex-copilot-dx [--configure-claude-desktop]
-  codex-copilot-dx doctor [--online]
+  codex-copilot-dx doctor [--online] [--compat]
   codex-copilot-dx usage
   codex-copilot-dx --version
   codex-copilot-dx --help`;

package/src/copilot.mjs

@@ -1,9 +1,16 @@
 import fs from "node:fs";
 import os from "node:os";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { status } from "./status.mjs";
 import { debugLog } from "./log.mjs";
-import { ensureGithubTokenMetadata, githubReauthMessage, githubTokenPath, importDiscoveredGithubToken } from "./auth.mjs";
+import {
+  fetchGithubIdentity,
+  githubReauthMessage,
+  githubTokenPath,
+  importDiscoveredGithubToken,
+  readGithubTokenMetadata,
+  writeGithubTokenMetadata,
+} from "./auth.mjs";
 import { prepareResponsesPayload } from "./image-optimization.mjs";
 
 export {
@@ -267,6 +274,10 @@ export async function refreshVSCodeVersion() {
 let copilotToken = null;
 let copilotTokenExpiry = 0;
 let copilotTokenRefresh = null;
+let copilotTokenSourceKey = null;
+let copilotTokenGithubFingerprint = "";
+let copilotTokenGithubIdentity = null;
+let copilotTokenRefreshRetryAt = 0;
 const modelListFlights = new Map();
 
 function getGithubToken({ home = os.homedir() } = {}) {
@@ -286,17 +297,76 @@ function requestCopilotToken(ghToken, { fetchImpl = fetch, signal } = {}) {
   });
 }
 
-function cacheCopilotTokenData(data) {
+function githubTokenFingerprint(token) {
+  return createHash("sha256").update(String(token || "")).digest("hex").slice(0, 24);
+}
+
+function normalizeGithubIdentity(identity) {
+  if (!identity || typeof identity !== "object") return null;
+  const login = typeof identity.login === "string" ? identity.login.trim() : "";
+  const id = identity.id === undefined || identity.id === null ? "" : String(identity.id).trim();
+  return login || id ? { login, id } : null;
+}
+
+function githubIdentitiesMatch(first, second) {
+  const a = normalizeGithubIdentity(first);
+  const b = normalizeGithubIdentity(second);
+  if (!a || !b) return false;
+  if (a.id && b.id) return a.id === b.id;
+  return Boolean(a.login && b.login && a.login.toLowerCase() === b.login.toLowerCase());
+}
+
+function githubIdentityLabel(identity) {
+  const normalized = normalizeGithubIdentity(identity);
+  return normalized?.login || normalized?.id || "unknown";
+}
+
+function cacheCopilotTokenData(data, {
+  sourceKey,
+  githubToken,
+  githubIdentity,
+  allowAccountSwitch = false,
+} = {}) {
   if (!data.token) throw new Error("Copilot token response missing token field");
+  const fingerprint = githubTokenFingerprint(githubToken);
+  const identity = normalizeGithubIdentity(githubIdentity);
+  const tokenChanged = Boolean(copilotTokenGithubFingerprint && fingerprint !== copilotTokenGithubFingerprint);
+  if (!allowAccountSwitch && copilotTokenGithubIdentity && identity
+    && !githubIdentitiesMatch(copilotTokenGithubIdentity, identity)) {
+    throw new Error(`Refusing to switch GitHub Copilot account from ${githubIdentityLabel(copilotTokenGithubIdentity)} to ${githubIdentityLabel(identity)} while the adapter is running. Restart codex-copilot-dx to switch accounts intentionally.`);
+  }
+  if (!allowAccountSwitch && copilotTokenGithubIdentity && tokenChanged && !identity) {
+    const error = new Error("The saved GitHub token changed, but its account could not be verified. Keeping the running adapter bound to the existing GitHub account.");
+    error.transient = true;
+    throw error;
+  }
   copilotToken = data.token;
   apiBase = parseApiBase(data);
   copilotTokenExpiry = typeof data.expires_at === "number"
     ? data.expires_at * 1000
     : Date.now() + 25 * 60 * 1000; // fallback if expires_at absent: refresh in ~25min
+  copilotTokenSourceKey = sourceKey || copilotTokenSourceKey;
+  copilotTokenGithubFingerprint = fingerprint;
+  if (identity) copilotTokenGithubIdentity = identity;
+  copilotTokenRefreshRetryAt = 0;
   console.log(status("ok", "Copilot token refreshed"));
   return copilotToken;
 }
 
+async function githubIdentityForToken(token, { home, fetchImpl, signal }) {
+  const cached = readGithubTokenMetadata(home, token);
+  if (cached) return cached;
+  const identity = await fetchGithubIdentity(token, { fetchImpl, signal });
+  return identity.ok ? identity : null;
+}
+
+function tokenRefreshError(message, { statusCode, transient = false } = {}) {
+  const error = new Error(message);
+  if (statusCode) error.statusCode = statusCode;
+  if (transient) error.transient = true;
+  return error;
+}
+
 async function refreshCopilotToken({
   signal,
   home = os.homedir(),
@@ -304,7 +374,14 @@ async function refreshCopilotToken({
   fetchImpl = fetch,
 } = {}) {
   const ghToken = getGithubToken({ home });
-  const resp = await requestCopilotToken(ghToken, { fetchImpl, signal });
+  const sourceKey = githubTokenPath(home);
+  let resp;
+  try {
+    resp = await requestCopilotToken(ghToken, { fetchImpl, signal });
+  } catch (e) {
+    if (!isAbortError(e, signal)) e.transient = true;
+    throw e;
+  }
   if (!resp.ok) {
     if (resp.status === 401 || resp.status === 403) {
       const imported = await importDiscoveredGithubToken({
@@ -316,34 +393,87 @@ async function refreshCopilotToken({
         validateSavedToken: true,
       });
       if (imported?.validation?.copilotTokenData?.token) {
-        return cacheCopilotTokenData(imported.validation.copilotTokenData);
+        const explicitSource = imported.source?.type === "env" || imported.source?.type === "token-file";
+        return cacheCopilotTokenData(imported.validation.copilotTokenData, {
+          sourceKey,
+          githubToken: imported.token,
+          githubIdentity: imported.validation,
+          allowAccountSwitch: explicitSource,
+        });
       }
       throw new Error(githubReauthMessage(`Failed to get Copilot token: ${resp.status}. The saved GitHub token may be expired, revoked, or missing Copilot access.`));
     }
-    throw new Error(`Failed to get Copilot token: ${resp.status}`);
+    throw tokenRefreshError(`Failed to get Copilot token: ${resp.status}`, {
+      statusCode: resp.status,
+      transient: resp.status === 408 || resp.status === 425 || resp.status === 429 || resp.status >= 500,
+    });
   }
   const data = await resp.json();
-  await ensureGithubTokenMetadata(ghToken, { home, fetchImpl, signal });
-  return cacheCopilotTokenData(data);
+  const identity = await githubIdentityForToken(ghToken, { home, fetchImpl, signal });
+  const token = cacheCopilotTokenData(data, {
+    sourceKey,
+    githubToken: ghToken,
+    githubIdentity: identity,
+  });
+  if (identity) writeGithubTokenMetadata(identity, home, ghToken);
+  return token;
 }
 
-export async function getCopilotToken(options = {}) {
-  if (copilotToken && Date.now() < copilotTokenExpiry - 60000) return copilotToken;
+function canUseCachedToken(sourceKey, now = Date.now(), allowCurrentProcessToken = false) {
+  const sameSource = copilotTokenSourceKey === sourceKey || allowCurrentProcessToken;
+  return Boolean(copilotToken && sameSource && now < copilotTokenExpiry);
+}
+
+export function getCopilotToken(options = {}) {
   const home = options.home || os.homedir();
-  const refreshKey = githubTokenPath(home);
-  if (copilotTokenRefresh?.key === refreshKey) return copilotTokenRefresh.promise;
+  const sourceKey = githubTokenPath(home);
+  const now = Date.now();
+  const allowCurrentProcessToken = options.home === undefined;
+  if (canUseCachedToken(sourceKey, now, allowCurrentProcessToken) && now < copilotTokenExpiry - 60000) {
+    return Promise.resolve(copilotToken);
+  }
+  if (canUseCachedToken(sourceKey, now, allowCurrentProcessToken) && now < copilotTokenRefreshRetryAt) {
+    return Promise.resolve(copilotToken);
+  }
+  if (options.signal?.aborted) return Promise.reject(abortError(options.signal));
 
-  const promise = refreshCopilotToken(options).finally(() => {
-    if (copilotTokenRefresh?.promise === promise) copilotTokenRefresh = null;
-  });
-  copilotTokenRefresh = { key: refreshKey, promise };
-  return promise;
+  let flight = copilotTokenRefresh?.key === sourceKey ? copilotTokenRefresh : null;
+  if (flight?.controller.signal.aborted) {
+    if (copilotTokenRefresh === flight) copilotTokenRefresh = null;
+    flight = null;
+  }
+
+  if (!flight) {
+    const controller = new AbortController();
+    flight = { key: sourceKey, controller, waiters: 0, settled: false, promise: null };
+    flight.promise = refreshCopilotToken({ ...options, home, signal: controller.signal })
+      .catch((error) => {
+        const fallbackNow = Date.now();
+        if (error?.transient && canUseCachedToken(sourceKey, fallbackNow)) {
+          copilotTokenRefreshRetryAt = Math.min(copilotTokenExpiry, fallbackNow + 5000);
+          console.warn(status("warn", `Copilot token refresh failed temporarily; using the existing token until ${new Date(copilotTokenExpiry).toISOString()} (${error.message})`));
+          return copilotToken;
+        }
+        throw error;
+      })
+      .finally(() => {
+        flight.settled = true;
+        if (copilotTokenRefresh === flight) copilotTokenRefresh = null;
+      });
+    copilotTokenRefresh = flight;
+  }
+  return waitForSingleflight(flight, options.signal);
 }
 
 export function resetCopilotTokenForTests() {
+  copilotTokenRefresh?.controller.abort();
   copilotToken = null;
   copilotTokenExpiry = 0;
   copilotTokenRefresh = null;
+  copilotTokenSourceKey = null;
+  copilotTokenGithubFingerprint = "";
+  copilotTokenGithubIdentity = null;
+  copilotTokenRefreshRetryAt = 0;
   apiBase = DEFAULT_API_BASE;
   resetModelListSingleflightForTests();
 }
@@ -379,7 +509,7 @@ async function fetchModels({ signal, fetchImpl, retryOptions }) {
   return { status: resp.status, body };
 }
 
-function waitForModelListFlight(flight, signal) {
+function waitForSingleflight(flight, signal) {
   if (signal?.aborted) return Promise.reject(abortError(signal));
   flight.waiters += 1;
 
@@ -422,7 +552,7 @@ export function listModels({ signal, fetchImpl = fetch, retryOptions } = {}) {
     modelListFlights.set(fetchImpl, flight);
   }
 
-  return waitForModelListFlight(flight, signal);
+  return waitForSingleflight(flight, signal);
 }
 
 export function resetModelListSingleflightForTests() {

package/src/doctor.mjs

@@ -48,6 +48,152 @@ function valueLabel(value) {
   return value ? `"${value}"` : "missing";
 }
 
+function copilotModelData(models) {
+  const data = Array.isArray(models) ? models : models?.data;
+  return Array.isArray(data) ? data : [];
+}
+
+function modelEndpoints(model) {
+  return Array.isArray(model?.supported_endpoints) ? model.supported_endpoints : [];
+}
+
+export function selectCompatibilityModels(models) {
+  const data = copilotModelData(models).filter((model) => model?.model_picker_enabled !== false);
+  const responsesCandidates = data.filter((model) => {
+    const id = String(model?.id || "");
+    const endpoints = modelEndpoints(model);
+    return id.startsWith("gpt-") && (endpoints.includes("/responses") || endpoints.includes("/v1/responses"));
+  });
+  const responsesOnly = [...responsesCandidates].reverse()
+    .find((model) => !modelEndpoints(model).includes("/chat/completions"));
+  const claude = data.find((model) => {
+    const id = String(model?.id || "");
+    const vendor = String(model?.vendor || "").toLowerCase();
+    return (id.startsWith("claude-") || vendor === "anthropic")
+      && modelEndpoints(model).includes("/chat/completions");
+  });
+  return {
+    responsesModel: String((responsesOnly || responsesCandidates[0])?.id || ""),
+    claudeModel: String(claude?.id || ""),
+  };
+}
+
+async function fetchTextWithTimeout(fetchImpl, url, init, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetchImpl(url, { ...init, signal: controller.signal });
+    return { resp, text: await resp.text() };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function responseFailure(resp, text) {
+  const detail = String(text || "").replace(/\s+/g, " ").trim().slice(0, 240);
+  return new Error(`HTTP ${resp.status}${detail ? `: ${detail}` : ""}`);
+}
+
+async function compatibilityRequest(fetchImpl, url, body, timeoutMs) {
+  const { resp, text } = await fetchTextWithTimeout(fetchImpl, url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: body.stream ? "text/event-stream" : "application/json" },
+    body: JSON.stringify(body),
+  }, timeoutMs);
+  if (!resp.ok) throw responseFailure(resp, text);
+  return text;
+}
+
+async function runCompatibilityCheck(checks, label, task) {
+  const started = Date.now();
+  try {
+    const value = await task();
+    checks.push({ kind: "ok", message: `${label} passed (${Date.now() - started}ms)` });
+    return value;
+  } catch (e) {
+    const reason = e?.name === "AbortError" ? "timed out" : e?.message || "unknown error";
+    checks.push({ kind: "err", message: `${label} failed: ${reason}` });
+    return null;
+  }
+}
+
+function parseResponseObject(text) {
+  const response = JSON.parse(text);
+  if (!response?.id || !Array.isArray(response.output)) throw new Error("response body is missing id or output");
+  return response;
+}
+
+export async function inspectAdapterCompatibility({
+  host = "127.0.0.1",
+  port = 2026,
+  fetchImpl = fetch,
+  timeoutMs = 120000,
+} = {}) {
+  const baseUrl = localGatewayBaseUrl(connectHost(host), port);
+  const checks = [];
+  const models = await runCompatibilityCheck(checks, "Compatibility model discovery", async () => {
+    const { resp, text } = await fetchTextWithTimeout(fetchImpl, `${baseUrl}/v1/models`, { headers: { Accept: "application/json" } }, timeoutMs);
+    if (!resp.ok) throw responseFailure(resp, text);
+    const parsed = JSON.parse(text);
+    if (!copilotModelData(parsed).length) throw new Error("model list is empty");
+    return parsed;
+  });
+  if (!models) return checks;
+
+  const { responsesModel, claudeModel } = selectCompatibilityModels(models);
+  if (!responsesModel) {
+    checks.push({ kind: "err", message: "Compatibility Responses check failed: no GPT model advertises /responses" });
+    return checks;
+  }
+
+  const firstResponse = await runCompatibilityCheck(checks, `Native Responses (${responsesModel})`, async () => {
+    const text = await compatibilityRequest(fetchImpl, `${baseUrl}/v1/responses`, {
+      model: responsesModel,
+      stream: false,
+      input: "Reply with OK only.",
+    }, timeoutMs);
+    return parseResponseObject(text);
+  });
+
+  if (firstResponse) {
+    await runCompatibilityCheck(checks, "Responses stream, history, and image tool compatibility", async () => {
+      const text = await compatibilityRequest(fetchImpl, `${baseUrl}/v1/responses`, {
+        model: responsesModel,
+        stream: true,
+        previous_response_id: firstResponse.id,
+        input: "Reply with OK again.",
+        tools: [{ type: "image_generation" }],
+      }, timeoutMs);
+      if (!/^event:\s*response\.completed\s*$/m.test(text)) throw new Error("stream did not contain response.completed");
+    });
+  }
+
+  await runCompatibilityCheck(checks, "Responses compact", async () => {
+    const text = await compatibilityRequest(fetchImpl, `${baseUrl}/v1/responses/compact`, {
+      model: responsesModel,
+      stream: false,
+      input: "Compact this short context.",
+    }, timeoutMs);
+    parseResponseObject(text);
+  });
+
+  if (!claudeModel) {
+    checks.push({ kind: "warn", message: "Anthropic stream compatibility skipped because no Claude chat model was advertised" });
+    return checks;
+  }
+
+  await runCompatibilityCheck(checks, `Anthropic Messages stream (${claudeModel})`, async () => {
+    const text = await compatibilityRequest(fetchImpl, `${baseUrl}/v1/messages`, {
+      model: claudeModel,
+      max_tokens: 16,
+      stream: true,
+      messages: [{ role: "user", content: "Reply with OK only." }],
+    }, timeoutMs);
+    if (!/^event:\s*message_stop\s*$/m.test(text)) throw new Error("stream did not contain message_stop");
+  });
+  return checks;
+}
+
 export function inspectGitHubToken({ home = os.homedir() } = {}) {
   const filePath = githubTokenPath(home);
   const token = readText(filePath);
@@ -237,8 +383,11 @@ export async function collectDoctorChecks({
   checkAdapterListeningFn = checkAdapterListening,
   checkRunningAdapterFn = checkRunningAdapter,
   online = false,
+  compat = false,
   fetchImpl = fetch,
   onlineTimeoutMs = 10000,
+  compatTimeoutMs = 120000,
+  inspectAdapterCompatibilityFn = inspectAdapterCompatibility,
 } = {}) {
   const checks = [
     ...inspectGitHubToken({ home }),
@@ -251,13 +400,16 @@ export async function collectDoctorChecks({
     checks.push(...await inspectGitHubTokenOnline({ home, fetchImpl, timeoutMs: onlineTimeoutMs }));
   }
 
-  if (checkAdapter) {
-    let running;
+  let running = null;
+  if (checkAdapter || compat) {
     try {
       running = await checkRunningAdapterFn({ host, port, fetchImpl });
     } catch {
       running = null;
     }
+  }
+
+  if (checkAdapter) {
     if (running?.ok) {
       checks.push({ kind: "ok", message: `Adapter ${running.data.version} is listening on ${running.baseUrl}` });
     } else if (running?.incompatible) {
@@ -270,12 +422,21 @@ export async function collectDoctorChecks({
     }
   }
 
+  if (compat) {
+    if (!running?.ok) {
+      checks.push({ kind: "err", message: "Compatibility checks require a running, version-compatible codex-copilot-dx adapter" });
+    } else {
+      checks.push(...await inspectAdapterCompatibilityFn({ host, port, fetchImpl, timeoutMs: compatTimeoutMs }));
+    }
+  }
+
   return checks;
 }
 
 export async function runDoctor(options = {}) {
   const log = options.log || console.log;
-  log(`codex-copilot-dx doctor${options.online ? " --online" : ""}`);
+  const flags = [options.online ? "--online" : "", options.compat ? "--compat" : ""].filter(Boolean);
+  log(`codex-copilot-dx doctor${flags.length ? ` ${flags.join(" ")}` : ""}`);
   const checks = await collectDoctorChecks(options);
   for (const check of checks) log(status(check.kind, check.message));
   return checks;