codex-copilot-dx 0.4.44 → 0.5.0

package/README.md

@@ -30,6 +30,8 @@ ccdx
 The shorter `ccdx` command is the primary launcher. The existing `codex-copilot-dx`
 command remains an equivalent compatibility alias. For a one-off run without a
 global install, use `npx codex-copilot-dx@latest`.
+Both installed commands expose the same options and subcommands; help, version,
+doctor, status, and argument-error output use the command name that was invoked.
 
 On first run, it will:
 1. Authenticate with GitHub via device flow (if needed), after first trying compatible local Copilot token sources
@@ -75,7 +77,15 @@ ccdx doctor --compat
 
 The compatibility doctor sends a few minimal Copilot requests to check Codex Auto-review, 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.
 
-For live runtime diagnostics, query the running adapter from the same machine:
+For a read-only summary of the running adapter, use:
+
+```bash
+ccdx status
+```
+
+The compatibility alias supports the same command as
+`codex-copilot-dx status`. For the complete machine-readable payload, query the
+loopback endpoint directly:
 
 ```bash
 curl -s http://127.0.0.1:2026/_ccdx/status | jq

package/bin/cli.mjs

@@ -16,23 +16,25 @@ import { adapterBaseUrl, checkRunningAdapter } from "../src/running-adapter.mjs"
 import { assertSafeAdapterHost, isLoopbackHost } from "../src/security.mjs";
 import { isValidModelList, loadModelCache, saveModelCache } from "../src/model-cache.mjs";
 import { initializeModelRegistry, runInBackground } from "../src/startup.mjs";
-import { cliHelp, parseCliArgs, parseRuntimeOptions } from "../src/cli-options.mjs";
+import { cliCommandName, cliHelp, parseAdapterProbeOptions, parseCliArgs, parseRuntimeOptions } from "../src/cli-options.mjs";
+import { formatAdapterStatus, readAdapterStatus } from "../src/cli-status.mjs";
 import { closeHttpServer } from "../src/shutdown.mjs";
 
 const LOCAL_VERSION = localPackageVersion();
-const CLI_BANNER = `codex-copilot-dx v${LOCAL_VERSION} by Dale Xiao`;
+const CLI_NAME = cliCommandName();
+const CLI_BANNER = `${CLI_NAME} v${LOCAL_VERSION} by Dale Xiao`;
 
 let CLI;
 try {
   CLI = parseCliArgs(process.argv.slice(2));
 } catch (e) {
   console.error(e.message);
-  console.error("Run ccdx --help for usage.");
+  console.error(`Run ${CLI_NAME} --help for usage.`);
   process.exit(2);
 }
 
 if (CLI.command === "help") {
-  console.log(cliHelp());
+  console.log(cliHelp(CLI_NAME));
   process.exit(0);
 }
 if (CLI.command === "version") {
@@ -43,6 +45,27 @@ if (CLI.command === "usage") {
   await printUsageSummary();
   process.exit(0);
 }
+if (CLI.command === "status") {
+  let probe;
+  try {
+    probe = parseAdapterProbeOptions(process.env);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+  }
+  try {
+    const snapshot = await readAdapterStatus({
+      host: probe.adapterHost,
+      port: probe.adapterPort,
+      timeoutMs: probe.existingAdapterTimeoutMs,
+    });
+    console.log(formatAdapterStatus(snapshot, { commandName: CLI_NAME, cliVersion: LOCAL_VERSION }));
+    process.exit(0);
+  } catch (e) {
+    console.error(status("err", e.message));
+    process.exit(1);
+  }
+}
 
 let RUNTIME;
 try {
@@ -107,7 +130,7 @@ async function refreshClaudeDesktopModelDefs() {
     const models = JSON.parse(body);
     const autoReview = codexAutoReviewModelStatus(models);
     if (!autoReview.available) {
-      console.log(status("warn", `Auto-review target ${autoReview.upstreamModel} is unavailable: ${autoReview.reason}. Run ccdx doctor --compat to verify the live path.`));
+      console.log(status("warn", `Auto-review target ${autoReview.upstreamModel} is unavailable: ${autoReview.reason}. Run ${CLI_NAME} doctor --compat to verify the live path.`));
     }
     const gptModelIds = gptModelIdsFromCopilotModels(models);
     if (gptModelIds.length) {
@@ -169,7 +192,7 @@ async function reuseRunningAdapterIfAvailable() {
   });
   if (running.incompatible) {
     const found = running.data?.version || "unknown";
-    throw new Error(`Adapter ${found} is already running at ${running.baseUrl}, but this CLI is ${LOCAL_VERSION}. Stop the existing process and run ccdx again.`);
+    throw new Error(`Adapter ${found} is already running at ${running.baseUrl}, but this CLI is ${LOCAL_VERSION}. Stop the existing process and run ${CLI_NAME} again.`);
   }
   if (!running.ok) return false;
 
@@ -206,6 +229,7 @@ async function reuseRunningAdapterIfAvailable() {
 
 if (CLI.command === "doctor") {
   const checks = await runDoctor({
+    commandName: CLI_NAME,
     port: ADAPTER_PORT,
     host: ADAPTER_HOST,
     online: CLI.online,

package/bin/codex-copilot-dx.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./cli.mjs";

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.4.44",
+  "version": "0.5.0",
   "description": "Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",
   "bin": {
     "ccdx": "bin/cli.mjs",
-    "codex-copilot-dx": "bin/cli.mjs"
+    "codex-copilot-dx": "bin/codex-copilot-dx.mjs"
   },
   "files": [
     "bin/",

package/src/cli-options.mjs

@@ -1,6 +1,7 @@
 const HELP_COMMANDS = new Set(["help", "--help", "-h"]);
 const VERSION_COMMANDS = new Set(["version", "--version", "-v"]);
 const START_OPTIONS = new Set(["--configure-claude-desktop", "--show-request-id"]);
+const CLI_COMMANDS = new Set(["ccdx", "codex-copilot-dx"]);
 
 function unexpectedArgs(args) {
   throw new Error(`Unexpected argument${args.length === 1 ? "" : "s"}: ${args.join(" ")}`);
@@ -17,6 +18,10 @@ export function parseCliArgs(args = []) {
     if (rest.length) unexpectedArgs(rest);
     return { command: "version", configureClaudeDesktop: false, showRequestId: false, online: false, compat: false };
   }
+  if (command === "status" || command === "--status") {
+    if (rest.length) unexpectedArgs(rest);
+    return { command: "status", configureClaudeDesktop: false, showRequestId: false, online: false, compat: false };
+  }
   if (command === "usage") {
     if (rest.length) unexpectedArgs(rest);
     return { command: "usage", configureClaudeDesktop: false, showRequestId: false, online: false, compat: false };
@@ -80,13 +85,30 @@ export function parseRuntimeOptions(env = process.env) {
   };
 }
 
-export function cliHelp() {
+export function parseAdapterProbeOptions(env = process.env) {
+  return {
+    adapterPort: integerEnv(env, "ADAPTER_PORT", 2026, { min: 1, max: 65535 }),
+    adapterHost: String(env.ADAPTER_HOST || "127.0.0.1").trim() || "127.0.0.1",
+    existingAdapterTimeoutMs: integerEnv(env, "CCDX_EXISTING_ADAPTER_TIMEOUT_MS", 500, { min: 1 }),
+  };
+}
+
+export function cliCommandName(executable = process.argv[1]) {
+  const name = String(executable || "").split(/[\\/]/).pop();
+  if (name === "codex-copilot-dx.mjs") return "codex-copilot-dx";
+  return CLI_COMMANDS.has(name) ? name : "ccdx";
+}
+
+export function cliHelp(commandName = "ccdx") {
+  const name = CLI_COMMANDS.has(commandName) ? commandName : "ccdx";
+  const alias = name === "ccdx" ? "codex-copilot-dx" : "ccdx";
   return `Usage:
-  ccdx [--configure-claude-desktop] [--show-request-id]
-  ccdx doctor [--online] [--compat]
-  ccdx usage
-  ccdx --version
-  ccdx --help
+  ${name} [--configure-claude-desktop] [--show-request-id]
+  ${name} doctor [--online] [--compat]
+  ${name} status
+  ${name} usage
+  ${name} --version
+  ${name} --help
 
-Compatibility alias: codex-copilot-dx`;
+Equivalent command: ${alias}`;
 }

package/src/cli-status.mjs

@@ -0,0 +1,122 @@
+import { ADAPTER_STATUS_PATH, adapterBaseUrl } from "./running-adapter.mjs";
+import { status } from "./status.mjs";
+
+function finiteNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function count(value) {
+  const number = finiteNumber(value);
+  return number === null ? "n/a" : String(Math.max(0, Math.round(number)));
+}
+
+function duration(value) {
+  const milliseconds = finiteNumber(value);
+  if (milliseconds === null) return "n/a";
+  const seconds = Math.max(0, Math.round(milliseconds / 1000));
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor((seconds % 86400) / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const remainder = seconds % 60;
+  if (days) return `${days}d ${hours}h`;
+  if (hours) return `${hours}h ${minutes}m`;
+  if (minutes) return `${minutes}m ${remainder}s`;
+  return `${remainder}s`;
+}
+
+function latency(value) {
+  const milliseconds = finiteNumber(value);
+  if (milliseconds === null) return "n/a";
+  if (milliseconds >= 1000) return `${(milliseconds / 1000).toFixed(2)}s`;
+  return `${milliseconds.toFixed(1)}ms`;
+}
+
+function mebibytes(value) {
+  const bytes = finiteNumber(value);
+  return bytes === null ? "n/a" : `${(bytes / (1024 * 1024)).toFixed(1)}MiB`;
+}
+
+function tpot(metric) {
+  const average = finiteNumber(metric?.avg);
+  if (average === null) return "n/a";
+  const milliseconds = metric?.unit === "us" ? average / 1000 : average;
+  return `${milliseconds.toFixed(2)}ms/token`;
+}
+
+function cacheHitRate(cache = {}) {
+  const hits = finiteNumber(cache.cache_hits);
+  const misses = finiteNumber(cache.cache_misses);
+  if (hits === null || misses === null || hits + misses <= 0) return "n/a";
+  return `${((hits / (hits + misses)) * 100).toFixed(1)}%`;
+}
+
+export async function readAdapterStatus({
+  host = "127.0.0.1",
+  port = 2026,
+  timeoutMs = 500,
+  fetchImpl = fetch,
+} = {}) {
+  const baseUrl = adapterBaseUrl(host, port);
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(`${baseUrl}${ADAPTER_STATUS_PATH}`, {
+      headers: { Accept: "application/json" },
+      redirect: "error",
+      signal: ctrl.signal,
+    });
+    if (!response.ok) throw new Error(`returned HTTP ${response.status}`);
+
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      throw new Error("returned invalid JSON");
+    }
+    if (data?.ok !== true
+      || data?.name !== "codex-copilot-dx"
+      || typeof data.version !== "string"
+      || !Number.isInteger(data.pid)) {
+      throw new Error("returned an incompatible status payload");
+    }
+    return { baseUrl, data };
+  } catch (error) {
+    const reason = ctrl.signal.aborted
+      ? `timed out after ${timeoutMs}ms`
+      : error?.cause?.code === "ECONNREFUSED"
+        ? "adapter is not running"
+        : error?.message || String(error);
+    throw new Error(`Could not read adapter status at ${baseUrl}: ${reason}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function formatAdapterStatus({ baseUrl, data }, { commandName = "ccdx", cliVersion = data.version } = {}) {
+  const requests = data.requests || {};
+  const performance = data.stream_performance?.by_route?.responses || {};
+  const admission = data.admission || {};
+  const history = data.response_history || {};
+  const images = data.image_optimization || {};
+  const models = data.models || {};
+  const copilot = data.copilot || {};
+  const limits = data.limits || {};
+  const processStats = data.process || {};
+  const adapterLine = data.version === cliVersion
+    ? status("ok", `Adapter ${data.version} is running at ${baseUrl} (PID ${data.pid}, uptime ${duration(data.uptime_ms)})`)
+    : status("warn", `Adapter ${data.version} is running at ${baseUrl}, but this CLI is ${cliVersion}; stop the running adapter before switching versions`);
+
+  return [
+    `${commandName} status`,
+    adapterLine,
+    status("info", `Requests: ${count(requests.completed)}/${count(requests.total)} completed, ${count(requests.active)} active, ${count(requests.status_4xx)} 4xx, ${count(requests.status_5xx)} 5xx, ${count(requests.aborted)} aborted`),
+    status("info", `Responses stream: TTFT avg ${latency(performance.ttft_ms?.avg)} (${count(performance.ttft_ms?.samples)} samples), TPOT avg ${tpot(performance.tpot_us)}`),
+    status("info", `Admission: ${count(admission.activeRequests)} active, ${count(admission.queued)} queued, ${count(admission.rejected)} rejected, ${count(admission.timedOut)} timed out, wait avg ${latency(admission.waitMsAvg)}`),
+    status("info", `Memory: RSS ${mebibytes(processStats.rss_bytes)}, heap ${mebibytes(processStats.heap_used_bytes)}`),
+    status("info", `History: ${mebibytes(history.bytes)} / ${mebibytes(limits.response_history_max_bytes)}, ${count(history.entries)} entries, ${count(history.evicted)} evicted`),
+    status("info", `Image cache: ${count(images.cache_entries)} entries, ${cacheHitRate(images)} hits, ${mebibytes(images.cache_bytes)} / ${mebibytes(images.cache_max_bytes)}`),
+    status("info", `Models: ${count(models.models)} total, ${count(models.claude_models)} Claude; Copilot token ${copilot.token_cached ? `cached (${duration(copilot.token_expires_in_ms)} remaining)` : "not cached"}`),
+    status("info", `Limits: request body ${mebibytes(limits.max_body_bytes)}, decoded body ${mebibytes(limits.max_decoded_body_bytes)}`),
+  ].join("\n");
+}

package/src/doctor.mjs

@@ -455,7 +455,7 @@ export async function collectDoctorChecks({
 export async function runDoctor(options = {}) {
   const log = options.log || console.log;
   const flags = [options.online ? "--online" : "", options.compat ? "--compat" : ""].filter(Boolean);
-  log(`ccdx doctor${flags.length ? ` ${flags.join(" ")}` : ""}`);
+  log(`${options.commandName || "ccdx"} doctor${flags.length ? ` ${flags.join(" ")}` : ""}`);
   const checks = await collectDoctorChecks(options);
   for (const check of checks) log(status(check.kind, check.message));
   return checks;

package/src/observability.mjs

@@ -1,11 +1,11 @@
 import { isIP } from "node:net";
-import { adapterHealthPayload } from "./running-adapter.mjs";
+import { ADAPTER_STATUS_PATH, adapterHealthPayload } from "./running-adapter.mjs";
 import { copilotRuntimeStatus } from "./copilot.mjs";
 import { imageOptimizationStats } from "./image-optimization.mjs";
 import { responseHistoryStats } from "./response-history.mjs";
 import { loadRuntimeConfig } from "./runtime-config.mjs";
 
-export const ADAPTER_STATUS_PATH = "/_ccdx/status";
+export { ADAPTER_STATUS_PATH };
 const OBSERVABILITY_RUNTIME_CONFIG = loadRuntimeConfig();
 
 const ROUTE_NAMES = Object.freeze([

package/src/running-adapter.mjs

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { localPackageVersion } from "./version.mjs";
 
 export const ADAPTER_HEALTH_PATH = "/_ccdx/health";
+export const ADAPTER_STATUS_PATH = "/_ccdx/status";
 export const ADAPTER_PROTOCOL_VERSION = 2;
 export const ADAPTER_VERSION = localPackageVersion();
 const ADAPTER_INSTANCE_ID = randomUUID();