codex-account-orchestrator 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-01-27
+
+### Added
+
+- `cao switch` interactive account picker and `cao current` convenience command
+- `cao status --compact` for one-line per-account summaries
+- `cao import codex-auth` to migrate snapshots from codex-auth
+- `cao run --gateway` for running through the local gateway without CLI fallback
+
+### Changed
+
+- Gateway status now includes token expiry and last refresh hints
+- README expanded with migration, switching, and gateway run guidance
+
 ## [1.1.1] - 2026-01-27
 
 ### Fixed

package/README.md

@@ -17,6 +17,7 @@ Codex OAuth account fallback orchestrator. CAO keeps **separate `CODEX_HOME` dir
 - Automatic fallback on quota exhaustion (keyword-based detector)
 - Gateway mode for seamless account switching without session drops
 - Lightweight observability via `cao status` and `cao list --details`
+- Interactive switching and codex-auth snapshot import
 - Strict TypeScript build with a small, dependency-light CLI
 
 ## Requirements
@@ -67,6 +68,18 @@ cao add accountA --device-auth
 cao use accountA
 ```
 
+Or pick interactively:
+
+```bash
+cao switch
+```
+
+Check the current default account:
+
+```bash
+cao current
+```
+
 ### 3. Run with fallback
 
 ```bash
@@ -99,6 +112,12 @@ cao list
 cao status
 ```
 
+### Compact summary
+
+```bash
+cao status --compact
+```
+
 You can also use:
 
 ```bash
@@ -128,6 +147,12 @@ Gateway mode keeps the Codex session open while switching accounts on quota erro
 cao gateway start
 ```
 
+Run Codex through the gateway (no CLI fallback, gateway handles switching):
+
+```bash
+cao run --gateway
+```
+
 Tune upstream retry/backoff (for transient 5xx/network errors):
 
 ```bash
@@ -192,6 +217,26 @@ Key files:
 - `<account>/auth.json`: account-scoped tokens managed by Codex
 - `<account>/config.toml`: account-scoped Codex configuration
 
+## Migration from codex-auth
+
+Import snapshots created by `codex-auth`:
+
+```bash
+cao import codex-auth
+```
+
+Custom source directory:
+
+```bash
+cao import codex-auth --source ~/.codex/accounts
+```
+
+Overwrite existing auth files if needed:
+
+```bash
+cao import codex-auth --overwrite
+```
+
 ## Development
 
 Build:

package/dist/cli_main.js

@@ -6,7 +6,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const promises_1 = require("readline/promises");
 const account_manager_1 = require("./account_manager");
 const account_inspector_1 = require("./account_inspector");
 const account_status_store_1 = require("./account_status_store");
@@ -78,10 +80,44 @@ program
     }
     renderAccountDetails(inspections);
 });
+program
+    .command("switch")
+    .argument("[name]", "Account name")
+    .description("Switch the default account (interactive if omitted)")
+    .action(async (name) => {
+    const baseDir = (0, paths_1.getBaseDir)(program.opts().dataDir);
+    (0, account_manager_1.ensureBaseDir)(baseDir);
+    const inspections = (0, account_inspector_1.inspectAccounts)(baseDir);
+    if (inspections.length === 0) {
+        process.stdout.write("No accounts registered. Use `cao add <name>` first.\n");
+        return;
+    }
+    const resolved = name ?? (await promptForAccountSelection(inspections));
+    if (!resolved) {
+        process.stdout.write("No account selected.\n");
+        return;
+    }
+    const registry = (0, account_manager_1.setDefaultAccount)(baseDir, resolved);
+    process.stdout.write(`Default account set to: ${registry.default_account}\n`);
+});
+program
+    .command("current")
+    .description("Show the current default account")
+    .action(() => {
+    const baseDir = (0, paths_1.getBaseDir)(program.opts().dataDir);
+    (0, account_manager_1.ensureBaseDir)(baseDir);
+    const registry = (0, registry_store_1.loadRegistry)(baseDir);
+    if (!registry.default_account) {
+        process.stdout.write("No default account set.\n");
+        return;
+    }
+    process.stdout.write(`${registry.default_account}\n`);
+});
 program
     .command("status")
     .description("Show detailed account status and cooldown/usage signals")
     .option("--json", "Output account status as JSON")
+    .option("--compact", "Output a compact one-line summary per account")
     .action((options) => {
     const baseDir = (0, paths_1.getBaseDir)(program.opts().dataDir);
     (0, account_manager_1.ensureBaseDir)(baseDir);
@@ -94,8 +130,97 @@ program
         renderAccountDetailsJson(inspections);
         return;
     }
+    if (options.compact) {
+        renderAccountCompact(inspections);
+        return;
+    }
     renderAccountDetails(inspections);
 });
+const importCommand = program.command("import").description("Import accounts from other tools");
+importCommand
+    .command("codex-auth")
+    .description("Import account snapshots from codex-auth")
+    .option("--source <path>", "Source directory with codex-auth snapshots", path_1.default.join(os_1.default.homedir(), ".codex", "accounts"))
+    .option("--overwrite", "Overwrite existing auth.json files")
+    .option("--current <name>", "Treat this account as active during import")
+    .option("--default <name>", "Set this account as the default after import")
+    .action((options) => {
+    const baseDir = (0, paths_1.getBaseDir)(program.opts().dataDir);
+    (0, account_manager_1.ensureBaseDir)(baseDir);
+    const sourceDir = path_1.default.resolve(options.source);
+    if (!fs_1.default.existsSync(sourceDir)) {
+        process.stderr.write(`Source directory not found: ${sourceDir}\n`);
+        process.exit(1);
+        return;
+    }
+    const entries = fs_1.default.readdirSync(sourceDir);
+    const snapshotFiles = entries.filter((entry) => entry.endsWith(".json"));
+    if (snapshotFiles.length === 0) {
+        process.stdout.write(`No snapshot files found in ${sourceDir}.\n`);
+        return;
+    }
+    const importedNames = [];
+    let importedCount = 0;
+    let skippedCount = 0;
+    let errorCount = 0;
+    for (const fileName of snapshotFiles) {
+        const rawName = path_1.default.basename(fileName, ".json");
+        let normalizedName;
+        try {
+            normalizedName = (0, account_manager_1.validateAccountName)(rawName);
+        }
+        catch (error) {
+            process.stderr.write(`Skipping snapshot '${fileName}': ${error.message}\n`);
+            errorCount += 1;
+            continue;
+        }
+        const sourcePath = path_1.default.join(sourceDir, fileName);
+        let parsed;
+        try {
+            parsed = JSON.parse(fs_1.default.readFileSync(sourcePath, "utf8"));
+        }
+        catch (error) {
+            process.stderr.write(`Skipping snapshot '${fileName}': invalid JSON (${error.message}).\n`);
+            errorCount += 1;
+            continue;
+        }
+        (0, account_manager_1.addAccount)(baseDir, normalizedName);
+        const accountDir = (0, paths_1.getAccountDir)(baseDir, normalizedName);
+        (0, account_manager_1.ensureAccountConfig)(accountDir);
+        const authPath = getAuthFilePath(accountDir);
+        if (fs_1.default.existsSync(authPath) && !options.overwrite) {
+            skippedCount += 1;
+            continue;
+        }
+        fs_1.default.writeFileSync(authPath, JSON.stringify(parsed, null, 2) + "\n", "utf8");
+        importedNames.push(normalizedName);
+        importedCount += 1;
+    }
+    const activeName = options.default ??
+        options.current ??
+        findCodexAuthActiveAccount(sourceDir) ??
+        undefined;
+    if (activeName) {
+        try {
+            const normalizedActive = (0, account_manager_1.validateAccountName)(activeName);
+            const registry = (0, registry_store_1.loadRegistry)(baseDir);
+            if (registry.accounts.includes(normalizedActive)) {
+                (0, account_manager_1.setDefaultAccount)(baseDir, normalizedActive);
+                process.stdout.write(`Default account set to: ${normalizedActive}\n`);
+            }
+            else {
+                process.stderr.write(`Requested default '${normalizedActive}' not found in imported accounts.\n`);
+            }
+        }
+        catch (error) {
+            process.stderr.write(`Unable to set default account '${activeName}': ${error.message}\n`);
+        }
+    }
+    process.stdout.write(`Import complete. Imported: ${importedCount}, skipped: ${skippedCount}, errors: ${errorCount}.\n`);
+    if (importedNames.length > 0) {
+        process.stdout.write(`Imported accounts: ${importedNames.join(", ")}\n`);
+    }
+});
 program
     .command("use")
     .argument("<name>", "Account name")
@@ -221,6 +346,8 @@ program
     .command("run")
     .option("--account <name>", "Run with a specific account")
     .option("--codex <path>", "Path to the codex binary", "codex")
+    .option("--gateway", "Route Codex traffic through the local gateway")
+    .option("--gateway-url <url>", "Gateway base URL", "http://127.0.0.1:4319")
     .option("--no-fallback", "Disable automatic fallback")
     .option("--max-passes <count>", "Retry passes when all accounts hit quota", "2")
     .option("--retry-delay <seconds>", "Delay between retry passes in seconds", "0")
@@ -276,6 +403,74 @@ function normalizeCodexArgs(args, codexBin) {
 function getAuthFilePath(accountDir) {
     return path_1.default.join(accountDir, constants_1.AUTH_FILE_NAME);
 }
+async function promptForAccountSelection(inspections) {
+    if (!process.stdin.isTTY) {
+        process.stderr.write("No TTY available. Please provide an account name.\n");
+        return undefined;
+    }
+    process.stdout.write("Select an account:\n");
+    for (let index = 0; index < inspections.length; index += 1) {
+        const inspection = inspections[index];
+        const marker = inspection.isDefault ? "*" : " ";
+        process.stdout.write(`${index + 1}. ${marker} ${inspection.name}\n`);
+    }
+    const rl = (0, promises_1.createInterface)({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question("Enter a number or name (blank to cancel): ")).trim();
+    rl.close();
+    if (!answer) {
+        return undefined;
+    }
+    const index = Number.parseInt(answer, 10);
+    if (!Number.isNaN(index)) {
+        const selected = inspections[index - 1];
+        return selected?.name;
+    }
+    try {
+        const normalized = (0, account_manager_1.validateAccountName)(answer);
+        const exists = inspections.some((inspection) => inspection.name === normalized);
+        if (!exists) {
+            process.stderr.write(`Account not found: ${normalized}\n`);
+            return undefined;
+        }
+        return normalized;
+    }
+    catch (error) {
+        process.stderr.write(`Invalid account name: ${error.message}\n`);
+        return undefined;
+    }
+}
+function findCodexAuthActiveAccount(sourceDir) {
+    const parentDir = path_1.default.dirname(sourceDir);
+    const candidates = [
+        path_1.default.join(sourceDir, ".active"),
+        path_1.default.join(sourceDir, "active"),
+        path_1.default.join(sourceDir, ".current"),
+        path_1.default.join(sourceDir, "current"),
+        path_1.default.join(sourceDir, ".selected"),
+        path_1.default.join(sourceDir, "selected"),
+        path_1.default.join(parentDir, ".active"),
+        path_1.default.join(parentDir, "active"),
+        path_1.default.join(parentDir, ".current"),
+        path_1.default.join(parentDir, "current"),
+        path_1.default.join(parentDir, ".selected"),
+        path_1.default.join(parentDir, "selected")
+    ];
+    for (const candidate of candidates) {
+        if (!fs_1.default.existsSync(candidate)) {
+            continue;
+        }
+        try {
+            const value = fs_1.default.readFileSync(candidate, "utf8").trim();
+            if (value.length > 0) {
+                return value;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
 function renderAccountSummary(inspections) {
     for (const inspection of inspections) {
         const marker = inspection.isDefault ? "*" : " ";
@@ -351,6 +546,18 @@ function renderAccountDetailsJson(inspections) {
     const payload = inspections.map((inspection) => toAccountDetailRecord(inspection, referenceMs));
     process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
 }
+function renderAccountCompact(inspections) {
+    const referenceMs = Date.now();
+    for (const inspection of inspections) {
+        const marker = inspection.isDefault ? "*" : " ";
+        const status = inspection.status ?? {};
+        const loginStatus = inspection.loggedIn ? "logged-in" : "not-logged-in";
+        const expires = formatExpiryShort(inspection.tokenDetails?.expiresAtMs, referenceMs);
+        const lastQuota = formatRelativeShort(status.lastQuotaAtMs, referenceMs);
+        const cooldown = formatCooldownShort(status.cooldownUntilMs, referenceMs);
+        process.stdout.write(`${marker} ${inspection.name} (${loginStatus}) | expires: ${expires} | cooldown: ${cooldown} | last_quota: ${lastQuota} | failures: ${status.consecutiveFailures ?? 0}\n`);
+    }
+}
 function formatDuration(durationMs) {
     const totalSeconds = Math.max(0, Math.floor(durationMs / 1000));
     if (totalSeconds < 60) {
@@ -382,6 +589,32 @@ function formatTimestampWithRelative(timestampMs, referenceMs) {
     const relative = diffMs > 0 ? `in ${formatDuration(diffMs)}` : `${formatDuration(-diffMs)} ago`;
     return `${iso} (${relative})`;
 }
+function formatRelativeShort(timestampMs, referenceMs) {
+    if (!timestampMs) {
+        return "none";
+    }
+    const diffMs = timestampMs - referenceMs;
+    if (diffMs <= 0) {
+        return `${formatDuration(-diffMs)} ago`;
+    }
+    return `in ${formatDuration(diffMs)}`;
+}
+function formatExpiryShort(timestampMs, referenceMs) {
+    if (!timestampMs) {
+        return "unknown";
+    }
+    const diffMs = timestampMs - referenceMs;
+    if (diffMs <= 0) {
+        return "expired";
+    }
+    return `in ${formatDuration(diffMs)}`;
+}
+function formatCooldownShort(timestampMs, referenceMs) {
+    if (!timestampMs || timestampMs <= referenceMs) {
+        return "none";
+    }
+    return `in ${formatDuration(timestampMs - referenceMs)}`;
+}
 function formatCooldown(cooldownUntilMs, referenceMs) {
     if (!cooldownUntilMs) {
         return "none";
@@ -433,8 +666,16 @@ function buildGatewayOverrides(options) {
 }
 async function runWithFallback(options, baseDir, accounts, codexArgs) {
     const codexBin = options.codex;
+    const gatewayUrl = options.gateway ? options.gatewayUrl : undefined;
+    const fallbackEnabled = options.fallback && !options.gateway;
     const maxPasses = normalizeMaxPasses(options.maxPasses);
     const retryDelayMs = normalizeDelay(options.retryDelay);
+    if (options.gateway && gatewayUrl) {
+        process.stderr.write(`Gateway routing enabled: ${gatewayUrl}\n`);
+        if (options.fallback) {
+            process.stderr.write("Gateway mode disables CLI fallback (handled by gateway).\n");
+        }
+    }
     for (let passIndex = 0; passIndex < maxPasses; passIndex += 1) {
         let quotaFailures = 0;
         let lastExitCode = 1;
@@ -448,7 +689,7 @@ async function runWithFallback(options, baseDir, accounts, codexArgs) {
                 lastAttemptAtMs: attemptAtMs
             }));
             process.stderr.write(`Using account: ${name}\n`);
-            const result = await (0, process_runner_1.runCodexOnce)(codexBin, codexArgs, accountDir, options.fallback);
+            const result = await (0, process_runner_1.runCodexOnce)(codexBin, codexArgs, accountDir, fallbackEnabled, gatewayUrl ? { OPENAI_BASE_URL: gatewayUrl } : {});
             lastExitCode = result.exitCode;
             if (result.exitCode === 0) {
                 (0, account_status_store_1.updateAccountStatus)(baseDir, name, (previous) => ({
@@ -462,7 +703,7 @@ async function runWithFallback(options, baseDir, accounts, codexArgs) {
                 process.exit(0);
                 return;
             }
-            if (!options.fallback) {
+            if (!fallbackEnabled) {
                 (0, account_status_store_1.updateAccountStatus)(baseDir, name, (previous) => ({
                     ...previous,
                     lastAttemptAtMs: attemptAtMs,
@@ -500,7 +741,7 @@ async function runWithFallback(options, baseDir, accounts, codexArgs) {
                 process.stderr.write(`Quota exhausted. Falling back to: ${nextName}\n`);
             }
         }
-        if (!options.fallback) {
+        if (!fallbackEnabled) {
             process.exit(lastExitCode);
             return;
         }

package/dist/process_runner.d.ts

@@ -2,4 +2,4 @@ export interface RunResult {
     exitCode: number;
     quotaError: boolean;
 }
-export declare function runCodexOnce(codexBin: string, codexArgs: string[], accountDir: string, captureOutput: boolean): Promise<RunResult>;
+export declare function runCodexOnce(codexBin: string, codexArgs: string[], accountDir: string, captureOutput: boolean, envOverrides?: Record<string, string | undefined>): Promise<RunResult>;

package/dist/process_runner.js

@@ -4,9 +4,13 @@ exports.runCodexOnce = runCodexOnce;
 const child_process_1 = require("child_process");
 const output_capture_1 = require("./output_capture");
 const quota_detector_1 = require("./quota_detector");
-async function runCodexOnce(codexBin, codexArgs, accountDir, captureOutput) {
+async function runCodexOnce(codexBin, codexArgs, accountDir, captureOutput, envOverrides = {}) {
     const capture = new output_capture_1.OutputCapture();
-    const env = { ...process.env, CODEX_HOME: accountDir };
+    const env = {
+        ...process.env,
+        CODEX_HOME: accountDir,
+        ...envOverrides
+    };
     const child = (0, child_process_1.spawn)(codexBin, codexArgs, {
         env,
         stdio: captureOutput ? ["inherit", "pipe", "pipe"] : ["inherit", "inherit", "inherit"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-account-orchestrator",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Codex OAuth account fallback orchestrator with seamless gateway mode",
   "main": "dist/cli_main.js",
   "types": "dist/cli_main.d.ts",