codex-copilot-dx 0.4.17 → 0.4.19

package/README.md

@@ -83,11 +83,16 @@ Environment variables:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `ADAPTER_HOST` | `127.0.0.1` | Host for the adapter; set `0.0.0.0` only if you knowingly expose it on a trusted network |
+| `ADAPTER_HOST` | `127.0.0.1` | Host for the adapter; only loopback hosts are allowed by default |
 | `ADAPTER_PORT` | `2026` | Port for the adapter |
+| `CCDX_ALLOW_LAN` | unset | Set to `1` to allow non-loopback `ADAPTER_HOST` values such as `0.0.0.0`; exposes your Copilot-backed adapter beyond this machine |
 | `CCDX_MAX_BODY_BYTES` | `134217728` | Maximum compressed/raw request body size |
 | `CCDX_MAX_DECODED_BODY_BYTES` | `268435456` | Maximum decoded request body size after decompression |
 | `CCDX_UPSTREAM_TIMEOUT_MS` | `120000` | Timeout for non-streaming upstream Copilot requests |
+| `CCDX_UPSTREAM_RETRIES` | `2` | Retries for transient Copilot upstream network errors; capped at `5` |
+| `CCDX_UPSTREAM_RETRY_DELAY_MS` | `300` | Initial upstream retry backoff in milliseconds; capped at `5000` |
+| `CCDX_LOG_PATH` | unset | Mirror terminal logs to a file; set to `1` for `~/.local/share/codex-copilot-dx/debug.log` |
+| `CCDX_LOG_LEVEL` | `info` | Set to `debug` to include upstream request attempts, status codes, retry causes, and timings |
 | `CCDX_IMG_MAX_DIM` | `2048` | Max long edge in pixels for image downscaling |
 | `CCDX_IMG_QUALITY` | `85` | WebP quality used when re-encoding images |
 | `CCDX_IMG_MIN_BYTES` | `100000` | Images smaller than this are left untouched |
@@ -110,6 +115,10 @@ Environment variables:
 
 The adapter records token usage metadata to `~/.local/share/codex-copilot-dx/usage.jsonl` when upstream responses include usage fields. It logs counts, model names, API surface, and response IDs only; it does not log prompts, completions, tool arguments, or image content.
 
+### Debug logging
+
+Set `CCDX_LOG_PATH=1` to mirror terminal logs to `~/.local/share/codex-copilot-dx/debug.log`, or set `CCDX_LOG_PATH` to a custom file. Add `CCDX_LOG_LEVEL=debug` to include upstream request attempts, retry causes, status codes, and timings. Debug logs do not include prompts, completions, request bodies, or authorization tokens.
+
 ```bash
 codex-copilot-dx usage
 ```

package/bin/cli.mjs

@@ -8,10 +8,12 @@ import { startAdapter } from "../src/adapter.mjs";
 import { listModels, refreshVSCodeVersion } from "../src/copilot.mjs";
 import { claudeDesktopModelDefsFromCopilotModels, claudeDesktopModelIds, gptModelIdsFromCopilotModels, parseModelAliasEnv } from "../src/models.mjs";
 import { status } from "../src/status.mjs";
+import { configureLogging } from "../src/log.mjs";
 import { printUsageSummary } from "../src/usage.mjs";
 import { checkForUpdate, localPackageVersion } from "../src/version.mjs";
 import { runDoctor } from "../src/doctor.mjs";
 import { checkRunningAdapter } from "../src/running-adapter.mjs";
+import { assertSafeAdapterHost, isLoopbackHost } from "../src/security.mjs";
 
 const ADAPTER_PORT = parseInt(process.env.ADAPTER_PORT || "2026");
 const ADAPTER_HOST = process.env.ADAPTER_HOST || "127.0.0.1";
@@ -20,9 +22,11 @@ const EXISTING_ADAPTER_TIMEOUT_MS = parseInt(process.env.CCDX_EXISTING_ADAPTER_T
 const LOCAL_VERSION = localPackageVersion();
 const command = process.argv[2];
 const CONFIGURE_CLAUDE_DESKTOP = command === "--configure-claude-desktop" || process.env.CCDX_CONFIGURE_CLAUDE_DESKTOP === "1";
+const LOGGING = configureLogging();
 
-function isLoopbackHost(host) {
-  return ["127.0.0.1", "localhost", "::1"].includes(String(host).toLowerCase());
+if (LOGGING.filePath) {
+  console.log(status("info", `Debug log: ${LOGGING.filePath}`));
+  if (LOGGING.level === "debug") console.log(status("debug", "Debug logging enabled"));
 }
 
 async function refreshClaudeDesktopModelDefs() {
@@ -128,6 +132,7 @@ checkForUpdate({ currentVersion: LOCAL_VERSION }).then(({ latestVersion, updateA
 });
 
 try {
+  assertSafeAdapterHost(ADAPTER_HOST, process.env);
   if (await reuseRunningAdapterIfAvailable()) process.exit(0);
 
   // Ensure GitHub login, using device flow if no token exists.
@@ -138,7 +143,7 @@ try {
   const claudeDesktopModelDefs = await refreshClaudeDesktopModelDefs();
 
   if (!isLoopbackHost(ADAPTER_HOST)) {
-    console.log(status("warn", `ADAPTER_HOST=${ADAPTER_HOST} exposes the adapter beyond loopback. Use only on trusted networks.`));
+    console.log(status("warn", `ADAPTER_HOST=${ADAPTER_HOST} exposes the adapter beyond loopback because CCDX_ALLOW_LAN=1 is set. Use only on trusted networks.`));
   }
 
   const claudeDesktopApiKey = CONFIGURE_CLAUDE_DESKTOP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot",
   "type": "module",
   "bin": {

package/src/copilot.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import { randomUUID } from "node:crypto";
 import { status } from "./status.mjs";
+import { debugLog } from "./log.mjs";
 import { githubReauthMessage, githubTokenPath, importDiscoveredGithubToken } from "./auth.mjs";
 
 export const DEFAULT_API_BASE = "https://api.githubcopilot.com";
@@ -11,8 +12,14 @@ const IMG_QUALITY = parseInt(process.env.CCDX_IMG_QUALITY || "85", 10);
 const IMG_MIN_BYTES = parseInt(process.env.CCDX_IMG_MIN_BYTES || "100000", 10);
 const DEFAULT_IMG_CONCURRENCY = 4;
 const IMG_MAX_CONCURRENCY = 12;
+const DEFAULT_UPSTREAM_RETRIES = 2;
+const MAX_UPSTREAM_RETRIES = 5;
+const DEFAULT_UPSTREAM_RETRY_DELAY_MS = 300;
+const MAX_UPSTREAM_RETRY_DELAY_MS = 5000;
 const IMG_OPT_DISABLED = process.env.CCDX_DISABLE_IMG_OPT === "1";
 const IMG_CONCURRENCY = parseImageConcurrency(process.env.CCDX_IMG_CONCURRENCY);
+const UPSTREAM_RETRIES = parseUpstreamRetries(process.env.CCDX_UPSTREAM_RETRIES);
+const UPSTREAM_RETRY_DELAY_MS = parseUpstreamRetryDelayMs(process.env.CCDX_UPSTREAM_RETRY_DELAY_MS);
 let sharpImport = null;
 
 export function parseImageConcurrency(value) {
@@ -20,6 +27,16 @@ export function parseImageConcurrency(value) {
   return Number.isFinite(n) && n > 0 ? Math.min(n, IMG_MAX_CONCURRENCY) : DEFAULT_IMG_CONCURRENCY;
 }
 
+export function parseUpstreamRetries(value) {
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) && n >= 0 ? Math.min(n, MAX_UPSTREAM_RETRIES) : DEFAULT_UPSTREAM_RETRIES;
+}
+
+export function parseUpstreamRetryDelayMs(value) {
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) && n > 0 ? Math.min(n, MAX_UPSTREAM_RETRY_DELAY_MS) : DEFAULT_UPSTREAM_RETRY_DELAY_MS;
+}
+
 export function parseApiBase(data) {
   return (data && data.endpoints && typeof data.endpoints.api === "string" && data.endpoints.api)
     ? data.endpoints.api
@@ -34,6 +51,126 @@ export function responsesEndpointPath() {
   return "/responses";
 }
 const GITHUB_API = "https://api.github.com";
+const RETRYABLE_UPSTREAM_ERROR_CODES = new Set([
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "ETIMEDOUT",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "EPIPE",
+  "EAI_AGAIN",
+  "ENOTFOUND",
+]);
+const RETRYABLE_UPSTREAM_STATUSES = new Set([408, 502, 503, 504]);
+
+function upstreamTarget(url) {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.hostname}${parsed.pathname}`;
+  } catch {
+    return String(url);
+  }
+}
+
+function upstreamErrorCode(err) {
+  return err?.cause?.code || err?.code || "";
+}
+
+function isAbortError(err, signal) {
+  return signal?.aborted || err?.name === "AbortError" || err?.code === "ABORT_ERR";
+}
+
+function abortError(signal) {
+  if (signal?.reason instanceof Error) return signal.reason;
+  const err = new Error("The operation was aborted");
+  err.name = "AbortError";
+  return err;
+}
+
+function sleep(ms, { signal } = {}) {
+  if (signal?.aborted) return Promise.reject(abortError(signal));
+  return new Promise((resolve, reject) => {
+    let timer;
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const onAbort = () => {
+      cleanup();
+      reject(abortError(signal));
+    };
+    timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    if (!signal) return;
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function requestMethod(init = {}) {
+  return String(init.method || "GET").toUpperCase();
+}
+
+export function isRetryableUpstreamError(err, { signal } = {}) {
+  if (isAbortError(err, signal)) return false;
+  return RETRYABLE_UPSTREAM_ERROR_CODES.has(upstreamErrorCode(err));
+}
+
+export function isRetryableUpstreamStatus(status, method = "GET") {
+  const safeMethod = ["GET", "HEAD", "OPTIONS"].includes(String(method || "GET").toUpperCase());
+  return safeMethod && RETRYABLE_UPSTREAM_STATUSES.has(status);
+}
+
+function upstreamRetryDelay(attempt, baseDelayMs) {
+  return Math.min(baseDelayMs * (2 ** attempt), MAX_UPSTREAM_RETRY_DELAY_MS);
+}
+
+function describeUpstreamError(err) {
+  const code = upstreamErrorCode(err);
+  return [code, err?.cause?.message || err?.message].filter(Boolean).join(": ") || "network error";
+}
+
+export async function fetchCopilotUpstream(
+  url,
+  init = {},
+  {
+    fetchImpl = fetch,
+    retries = UPSTREAM_RETRIES,
+    retryDelayMs = UPSTREAM_RETRY_DELAY_MS,
+  } = {},
+) {
+  const retryCount = parseUpstreamRetries(retries);
+  const baseDelay = parseUpstreamRetryDelayMs(retryDelayMs);
+  const method = requestMethod(init);
+  const signal = init.signal;
+  const target = upstreamTarget(url);
+  const totalStart = Date.now();
+
+  for (let attempt = 0; ; attempt += 1) {
+    const attemptStart = Date.now();
+    debugLog(`upstream ${method} ${target} attempt=${attempt + 1}/${retryCount + 1}`);
+    try {
+      const resp = await fetchImpl(url, init);
+      debugLog(`upstream ${method} ${target} status=${resp.status} attempt=${attempt + 1}/${retryCount + 1} attempt_ms=${Date.now() - attemptStart} total_ms=${Date.now() - totalStart}`);
+      if (attempt < retryCount && isRetryableUpstreamStatus(resp.status, method)) {
+        await resp.arrayBuffer?.().catch(() => {});
+        const delay = upstreamRetryDelay(attempt, baseDelay);
+        console.warn(status("warn", `upstream ${target} returned ${resp.status}; retry ${attempt + 1}/${retryCount} in ${delay}ms`));
+        await sleep(delay, { signal });
+        continue;
+      }
+      return resp;
+    } catch (e) {
+      debugLog(`upstream ${method} ${target} error=${describeUpstreamError(e)} attempt=${attempt + 1}/${retryCount + 1} attempt_ms=${Date.now() - attemptStart} total_ms=${Date.now() - totalStart}`);
+      if (attempt >= retryCount || !isRetryableUpstreamError(e, { signal })) throw e;
+      const delay = upstreamRetryDelay(attempt, baseDelay);
+      console.warn(status("warn", `upstream ${target} ${describeUpstreamError(e)}; retry ${attempt + 1}/${retryCount} in ${delay}ms`));
+      await sleep(delay, { signal });
+    }
+  }
+}
 
 async function sharp() {
   sharpImport ||= import("sharp");
@@ -326,7 +463,7 @@ export function resetCopilotTokenForTests() {
 }
 
 // chatReq is already converted by the adapter. The caller parses the raw Response.
-export async function chatCompletions(chatReq, { signal } = {}) {
+export async function chatCompletions(chatReq, { signal, fetchImpl, retryOptions } = {}) {
   const token = await getCopilotToken({ signal });
   const messages = chatReq.messages || [];
   const headers = buildHeaders({
@@ -335,25 +472,25 @@ export async function chatCompletions(chatReq, { signal } = {}) {
     initiator: computeInitiator(messages),
     vision: computeVision(messages),
   });
-  return fetch(`${getApiBase()}/chat/completions`, {
+  return fetchCopilotUpstream(`${getApiBase()}/chat/completions`, {
     method: "POST",
     headers,
     body: JSON.stringify(chatReq),
     signal,
-  });
+  }, { fetchImpl, ...retryOptions });
 }
 
-export async function listModels({ signal } = {}) {
+export async function listModels({ signal, fetchImpl, retryOptions } = {}) {
   const token = await getCopilotToken({ signal });
   const headers = buildHeaders({
     token, version: getVSCodeVersion(), initiator: "user", vision: false,
   });
-  const resp = await fetch(`${getApiBase()}/models`, { headers, signal });
+  const resp = await fetchCopilotUpstream(`${getApiBase()}/models`, { headers, signal }, { fetchImpl, ...retryOptions });
   return { status: resp.status, body: await resp.text() };
 }
 
 // Responses-only models go directly to Copilot's /responses endpoint.
-export async function responses(reqBody, { signal } = {}) {
+export async function responses(reqBody, { signal, fetchImpl, retryOptions } = {}) {
   const token = await getCopilotToken({ signal });
   const beforeBytes = Buffer.byteLength(JSON.stringify(reqBody));
   await optimizeImagesInBody(reqBody);
@@ -371,12 +508,12 @@ export async function responses(reqBody, { signal } = {}) {
   headers["Accept"] = reqBody.stream ? "text/event-stream" : "application/json";
 
   try {
-    return await fetch(`${getApiBase()}${responsesEndpointPath()}`, {
+    return await fetchCopilotUpstream(`${getApiBase()}${responsesEndpointPath()}`, {
       method: "POST",
       headers,
       body: bodyBuf,
       signal,
-    });
+    }, { fetchImpl, ...retryOptions });
   } catch (e) {
     const cause = e?.cause;
     const causeText = cause ? ` (${[cause.code, cause.message].filter(Boolean).join(": ")})` : "";

package/src/log.mjs

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { format } from "node:util";
+import { status } from "./status.mjs";
+
+let globalInstall = null;
+
+export function normalizeLogLevel(value) {
+  return String(value || "info").trim().toLowerCase() === "debug" ? "debug" : "info";
+}
+
+export function defaultLogPath({ home = os.homedir() } = {}) {
+  return path.join(home, ".local", "share", "codex-copilot-dx", "debug.log");
+}
+
+export function resolveLogPath(value, { home = os.homedir() } = {}) {
+  const raw = String(value || "").trim();
+  if (!raw) return null;
+  if (["1", "true", "yes"].includes(raw.toLowerCase())) return defaultLogPath({ home });
+  if (raw === "~") return home;
+  if (raw.startsWith("~/")) return path.join(home, raw.slice(2));
+  return raw;
+}
+
+export function isDebugLoggingEnabled(env = process.env) {
+  return normalizeLogLevel(env.CCDX_LOG_LEVEL) === "debug";
+}
+
+function renderLogPayload(args) {
+  const stamp = new Date().toISOString();
+  const text = format(...args);
+  return `${text.split(/\r?\n/).map((line) => `${stamp} ${line}`).join("\n")}\n`;
+}
+
+export function configureLogging({
+  env = process.env,
+  consoleObj = console,
+  home = os.homedir(),
+} = {}) {
+  const level = normalizeLogLevel(env.CCDX_LOG_LEVEL);
+  const filePath = resolveLogPath(env.CCDX_LOG_PATH, { home });
+  if (!filePath) return { level, filePath: null, cleanup: () => {} };
+  if (consoleObj === console && globalInstall) {
+    return { level, filePath: globalInstall.filePath, cleanup: globalInstall.cleanup };
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+
+  const methods = ["log", "warn", "error", "debug"];
+  const originals = Object.fromEntries(methods.map((method) => [
+    method,
+    typeof consoleObj[method] === "function" ? consoleObj[method].bind(consoleObj) : () => {},
+  ]));
+  let writeFailed = false;
+
+  function append(args) {
+    try {
+      fs.appendFileSync(filePath, renderLogPayload(args), { encoding: "utf8", mode: 0o600 });
+    } catch (e) {
+      if (writeFailed) return;
+      writeFailed = true;
+      originals.error(`codex-copilot-dx log write failed: ${e.message}`);
+    }
+  }
+
+  for (const method of methods) {
+    consoleObj[method] = (...args) => {
+      originals[method](...args);
+      append(args);
+    };
+  }
+
+  const cleanup = () => {
+    for (const method of methods) consoleObj[method] = originals[method];
+    if (consoleObj === console && globalInstall?.cleanup === cleanup) globalInstall = null;
+  };
+
+  if (consoleObj === console) globalInstall = { filePath, cleanup };
+  return { level, filePath, cleanup };
+}
+
+export function debugLog(message, env = process.env) {
+  if (isDebugLoggingEnabled(env)) console.log(status("debug", message));
+}

package/src/security.mjs

@@ -0,0 +1,13 @@
+export function isLoopbackHost(host) {
+  const normalized = String(host || "").toLowerCase().replace(/^\[(.*)\]$/, "$1");
+  return ["127.0.0.1", "localhost", "::1"].includes(normalized);
+}
+
+export function isLanAllowed(env = process.env) {
+  return ["1", "true", "yes"].includes(String(env.CCDX_ALLOW_LAN || "").toLowerCase());
+}
+
+export function assertSafeAdapterHost(host = "127.0.0.1", env = process.env) {
+  if (isLoopbackHost(host) || isLanAllowed(env)) return;
+  throw new Error(`Refusing to bind ADAPTER_HOST=${host} beyond loopback without CCDX_ALLOW_LAN=1. This adapter carries your GitHub Copilot access.`);
+}

package/src/status.mjs

@@ -4,6 +4,7 @@ const LABELS = {
   wait: "[WAIT]",
   warn: "[WARN]",
   err: "[ERR]",
+  debug: "[DEBUG]",
 };
 
 export function status(kind, message) {