UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,235 lines • 60 kB
import { isAnthropicOAuthInstance } from "../providers/anthropic-instance";
import { loadConfig } from "../config";
import { anthropicProviderIdentityError, cmdAnthropicAccountThreshold } from "./account-anthropic-threshold";
import { isReservedCodexAccountWord, reportCodexAccountTargetError, resolveCodexAccountTarget } from "./account-target";
import { hasPassiveAccountQuota } from "../providers/quota";
import { isWeeklyAllowancePercent } from "../providers/quota-types";
import { readSecretLine, terminalSafeText } from "./runtime-api";
import {
  ANTIGRAVITY_RISK_ACK_FIELD,
  ANTIGRAVITY_RISK_CLI_FLAG,
  ANTIGRAVITY_RISK_REFUSAL_CODE,
  antigravityRiskDecisionMessage,
  resolveAntigravityRiskAcknowledgement,
} from "../oauth/antigravity-risk";
import { isAgentDriven } from "./agent-driven";
import { closeSync, openSync, readSync, readFileSync, statSync } from "node:fs";
import {
  MAX_ACCOUNT_PRIORITY,
  MIN_ACCOUNT_PRIORITY,
  normalizeAccountPriority,
  parseAccountPriority,
} from "../codex/pool-rotation";
import {
  apiError,
  apiJson,
  classifyAccount,
  fetchCodexRows,
  fetchProviderQuotaReport,
  fetchRows,
  proxyUnreachable,
  resolveBaseUrl,
  type AccountDeps, type AccountStdin, type FamilyRows,
  type ProviderQuotaDto, type ProviderQuotaReportDto,
} from "./account-api";
import {
  codexCatalogRefreshPending,
  warnIfCodexCatalogRefreshPending,
} from "./account-catalog-refresh";
import {
  ACCOUNT_IMPORT_DEADLINE_MS,
  ACCOUNT_IMPORT_FORMAT,
  ACCOUNT_IMPORT_MAX_BYTES,
  ACCOUNT_IMPORT_PROVIDER,
  type AccountImportCode,
  type AccountImportRecordResult,
  type AccountImportResult,
  type AccountImportStatus,
} from "../oauth/account-import";

const MAIN_ID = "__main__";
const AUTO_NOTE = "auto (no pin — lowest-usage account is selected per request)";
const EXTENDED_USAGE = `Usage:
  ocx account refresh <provider> [--json]
  ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
  ocx account auto-switch <anthropic|anthropic2> <on|off|status|inherit|threshold <0-100>> --account <id> [--json]
  ocx account alias <provider> <id|alias|main> <display-name|-> [--json]
  ocx account priority <provider> <id|alias|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
  ocx account pause <provider> <id|alias|main> [--json]
  ocx account resume <provider> <id|alias|main> [--if-healthy] [--json]
  ocx account pause-exhausted <provider> [--json]
  ocx account strategy <provider> [<quota|round-robin|fill-first|reset-near-weighted|least-loaded|reset-first>] [--json]
  ocx account sticky <provider> [<1-100>] [--json]
  ocx account routes <anthropic|anthropic2> [--file <json-file>|--clear] [--json]
  ocx account remove <provider> <id|alias|main> --yes [--json]
  ocx account clear-cooldown <provider> <id|alias|main> [--json]
  ocx account add-key <provider> [--label <label>] [--json]
  ocx account import <provider> --format <format> (--file <path>|--stdin) [--json]`;
const PIPE_GUIDANCE = `Pipe the API key on stdin, for example:
  ocx account add-key <provider> <<< "$MY_KEY"
  security find-generic-password -w <item> | ocx account add-key <provider>`;
const ACCOUNT_IMPORT_TIMEOUT_MS = ACCOUNT_IMPORT_DEADLINE_MS;

function flag(args: string[], value: string): boolean {
  const index = args.indexOf(value);
  if (index < 0) return false;
  args.splice(index, 1);
  return true;
}

function flagValue(args: string[], value: string): { found: boolean; value?: string } {
  const index = args.indexOf(value);
  if (index < 0) return { found: false };
  if (index + 1 >= args.length) return { found: true };
  const result = args[index + 1];
  args.splice(index, 2);
  return { found: true, value: result };
}

function boundedUtf8(bytes: Uint8Array): string {
  try {
    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
  } catch {
    throw new Error("invalid_document");
  }
}

function readBoundedImportFile(path: string): string {
  let descriptor: number | undefined;
  try {
    descriptor = openSync(path, "r");
    const buffer = Buffer.allocUnsafe(ACCOUNT_IMPORT_MAX_BYTES + 1);
    let offset = 0;
    while (offset < buffer.length) {
      const read = readSync(descriptor, buffer, offset, buffer.length - offset, null);
      if (read === 0) break;
      offset += read;
    }
    if (offset > ACCOUNT_IMPORT_MAX_BYTES) throw new Error("invalid_document");
    return boundedUtf8(buffer.subarray(0, offset));
  } catch (error) {
    if (error instanceof Error && error.message === "invalid_document") throw error;
    throw new Error("source_read_failed");
  } finally {
    if (descriptor !== undefined) closeSync(descriptor);
  }
}

async function readBoundedImportStdin(deps: AccountDeps): Promise<string> {
  const input: AccountStdin = deps.stdinImpl ?? process.stdin;
  if (input.isTTY) throw new Error("stdin_required");
  const timeoutMs = deps.stdinTimeoutMs ?? 15_000;
  return await new Promise<string>((resolve, reject) => {
    const chunks: Buffer[] = [];
    let bytes = 0;
    let settled = false;
    const cleanup = () => {
      clearTimeout(timer);
      input.removeListener("data", onData);
      input.removeListener("end", onEnd);
      input.removeListener("error", onError);
    };
    const finish = (fn: () => void) => {
      if (settled) return;
      settled = true;
      cleanup();
      fn();
    };
    const onData = (chunk: unknown) => {
      const encoded = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
      bytes += encoded.byteLength;
      if (bytes > ACCOUNT_IMPORT_MAX_BYTES) {
        finish(() => reject(new Error("invalid_document")));
        return;
      }
      chunks.push(encoded);
    };
    const onEnd = () => finish(() => {
      try { resolve(boundedUtf8(Buffer.concat(chunks, bytes))); }
      catch (error) { reject(error); }
    });
    const onError = () => finish(() => reject(new Error("source_read_failed")));
    const timer = setTimeout(() => finish(() => reject(new Error("stdin_timeout"))), timeoutMs);
    input.on("data", onData);
    input.on("end", onEnd);
    input.on("error", onError);
  });
}

const IMPORT_STATUSES = new Set<AccountImportStatus>(["imported", "updated", "failed", "unsupported"]);
const IMPORT_CODES = new Set<AccountImportCode>([
  "imported", "updated", "import_cancelled", "unsupported_provider", "unsupported_format", "invalid_document",
  "invalid_record", "credential_rejected", "identity_mismatch", "missing_project", "persist_failed",
]);
const IMPORT_RESULT_FIELDS = new Set([
  "totalCount", "importedCount", "updatedCount", "failedCount", "unsupportedCount", "results",
]);
const IMPORT_RECORD_FIELDS = new Set(["index", "status", "code"]);
const IMPORT_STATUS_CODES: Record<AccountImportStatus, ReadonlySet<AccountImportCode>> = {
  imported: new Set(["imported"]),
  updated: new Set(["updated"]),
  failed: new Set(["invalid_record", "credential_rejected", "identity_mismatch", "missing_project", "persist_failed"]),
  unsupported: new Set(["unsupported_provider", "unsupported_format"]),
};

function isPlainObject(value: unknown): value is Record<string, unknown> {
  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
  const prototype = Object.getPrototypeOf(value);
  return prototype === Object.prototype || prototype === null;
}

function hasExactFields(value: Record<string, unknown>, allowed: ReadonlySet<string>): boolean {
  const fields = Object.keys(value);
  return fields.length === allowed.size && fields.every(field => allowed.has(field));
}

function isNonNegativeSafeInteger(value: unknown): value is number {
  return typeof value === "number" && Number.isFinite(value) && Number.isSafeInteger(value) && value >= 0;
}

function safeImportResult(json: unknown): AccountImportResult | null {
  if (!isPlainObject(json) || !hasExactFields(json, IMPORT_RESULT_FIELDS)) return null;
  if (
    !isNonNegativeSafeInteger(json.totalCount)
    || !isNonNegativeSafeInteger(json.importedCount)
    || !isNonNegativeSafeInteger(json.updatedCount)
    || !isNonNegativeSafeInteger(json.failedCount)
    || !isNonNegativeSafeInteger(json.unsupportedCount)
  ) return null;
  if (!Array.isArray(json.results)) return null;
  if (json.results.length !== json.totalCount) return null;

  const results: AccountImportRecordResult[] = [];
  const indices = new Set<number>();
  const aggregate: Record<AccountImportStatus, number> = {
    imported: 0,
    updated: 0,
    failed: 0,
    unsupported: 0,
  };
  for (const raw of json.results) {
    if (!isPlainObject(raw) || !hasExactFields(raw, IMPORT_RECORD_FIELDS)) return null;
    const item = raw;
    if (!isNonNegativeSafeInteger(item.index) || item.index >= json.totalCount || indices.has(item.index)) return null;
    if (!IMPORT_STATUSES.has(item.status as AccountImportStatus)) return null;
    if (!IMPORT_CODES.has(item.code as AccountImportCode)) return null;
    const status = item.status as AccountImportStatus;
    const code = item.code as AccountImportCode;
    if (!IMPORT_STATUS_CODES[status].has(code)) return null;
    indices.add(item.index);
    aggregate[status] += 1;
    results.push({
      index: item.index,
      status,
      code,
    });
  }
  if (
    indices.size !== json.totalCount
    || aggregate.imported !== json.importedCount
    || aggregate.updated !== json.updatedCount
    || aggregate.failed !== json.failedCount
    || aggregate.unsupported !== json.unsupportedCount
  ) return null;

  return {
    totalCount: json.totalCount,
    importedCount: json.importedCount,
    updatedCount: json.updatedCount,
    failedCount: json.failedCount,
    unsupportedCount: json.unsupportedCount,
    results,
  };
}

function usage(message?: string): number {
  if (message) console.error(message);
  console.error(EXTENDED_USAGE);
  return 1;
}

function configAndType(deps: AccountDeps, name: string) {
  return classifyAccount(deps.loadConfigImpl?.() ?? loadConfig(), name);
}

function familyFailure(result: FamilyRows, fallback: string): number | null {
  if (result.networkDown) return proxyUnreachable(result.transportError);
  if (result.errorJson) return apiError(result.errorJson, fallback, result.status);
  return null;
}

function errorText(json: Record<string, unknown> | undefined, fallback: string): string {
  return typeof json?.error === "string" ? json.error : fallback;
}

function resetIso(value: number | undefined): string | null {
  if (typeof value !== "number" || !Number.isFinite(value)) return null;
  const date = new Date(value < 10_000_000_000 ? value * 1000 : value);
  return Number.isNaN(date.getTime()) ? null : date.toISOString();
}

function refreshLine(row: FamilyRows["rows"][number]): string {
  const parts = [row.id === MAIN_ID ? "main" : row.id, row.email, row.plan];
  if (row.paused) parts.push(row.pauseDetails ? `paused(${row.pauseDetails.reason})` : "paused");
  // Was a second quota dialect: it gated the whole block on weekly/monthly, so an account
  // reporting only a 5h window printed `quota: unknown` while `quotaParts` five lines below
  // rendered the same data correctly for the provider path (#2703). Two halves of one file
  // disagreeing about how to read one DTO is the defect; delegating removes it rather than
  // teaching the second dialect a third window.
  const quotaText = row.quota ? quotaParts(row.quota).join(" ") : "";
  parts.push(quotaText.length > 0 ? quotaText : "quota: unknown");
  if (row.needsReauth) parts.push("needs-reauth");
  if (row.validationPending) parts.push("validation-pending (routing disabled; open 'ocx gui' and click Refresh quotas after recovery)");
  return parts.filter(Boolean).join(" ");
}

function quotaParts(quota: ProviderQuotaDto): string[] {
  const parts: string[] = [];
  const add = (label: string, percent: number | undefined, resetAt?: number, note?: string) => {
    if (percent === undefined) return;
    parts.push(`${label} ${percent}%${note ? ` (${note})` : ""}`);
    const reset = resetIso(resetAt);
    if (reset) parts.push(`resets ${reset}`);
  };
  add("5h", quota.fiveHourPercent, quota.fiveHourResetAt);
  add("weekly", quota.weeklyPercent, quota.weeklyResetAt);
  add("monthly", quota.monthlyPercent, quota.monthlyResetAt);
  for (const window of quota.customWindows ?? []) add(terminalSafeText(window.displayLabel ?? window.label), window.percent, window.resetAt);
  // Same rule as the dashboard: a routed row with the same label wins over a display-only one.
  const routed = new Set((quota.customWindows ?? []).map(window => window.label));
  for (const window of quota.displayWindows ?? []) {
    if (routed.has(window.label)) continue;
    const share = isWeeklyAllowancePercent(window.weeklyAllowancePercent) ? `up to ${window.weeklyAllowancePercent}% of weekly; ` : "";
    add(terminalSafeText(window.label), window.percent, window.resetAt, `${share}not in effect`);
  }
  for (const window of quota.unknownBudgetWindows ?? []) {
    parts.push(`${terminalSafeText(window.label)} unknown`);
    const reset = resetIso(window.resetAt);
    if (reset) parts.push(`resets ${reset}`);
  }
  return parts;
}

export function providerQuotaLine(name: string, report: ProviderQuotaReportDto): string {
  return [name, ...quotaParts(report.quota)].join(" ");
}

export async function readStdinLine(deps: AccountDeps): Promise<string> {
  const input: AccountStdin = deps.stdinImpl ?? process.stdin;
  const timeoutMs = deps.stdinTimeoutMs ?? 15_000;
  return await new Promise<string>((resolve, reject) => {
    let buffer = "";
    let settled = false;
    const cleanup = () => {
      clearTimeout(timer);
      input.removeListener("data", onData);
      input.removeListener("end", onEnd);
      input.removeListener("error", onError);
    };
    const finish = (fn: () => void) => {
      if (settled) return;
      settled = true;
      cleanup();
      fn();
    };
    const onData = (chunk: unknown) => {
      buffer += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
      const newline = buffer.search(/[\r\n]/);
      if (newline >= 0) finish(() => resolve(buffer.slice(0, newline).trim()));
    };
    const onEnd = () => finish(() => resolve(buffer.trim()));
    const onError = (error: Error) => finish(() => reject(error));
    const timer = setTimeout(() => finish(() => reject(new Error("timed out waiting for API key on stdin"))), timeoutMs);
    input.on("data", onData);
    input.on("end", onEnd);
    input.on("error", onError);
  });
}

export async function cmdRefresh(args: string[], deps: AccountDeps): Promise<number> {
  const wantsJson = flag(args, "--json");
  const name = args.shift();
  if (!name || args.length) return usage();
  const classified = configAndType(deps, name);
  if ("error" in classified) return usage(`Error: ${classified.error}`);
  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();
  if (classified.type !== "codex") {
    const result = await fetchProviderQuotaReport(deps, baseUrl, name);
    if (result.status === 0) return proxyUnreachable(result.transportError);
    if (result.status !== 200) return apiError(result.errorJson ?? {}, `failed to refresh ${name}`, result.status);
    if (wantsJson) console.log(JSON.stringify({ provider: name, report: result.report }, null, 2));
    else if (result.report) console.log(providerQuotaLine(name, result.report));
    // A passive provider has no probe to run, so "no report available" reads as a
    // failure of something that was never attempted. Say what is actually true.
    else if (hasPassiveAccountQuota(name)) {
      console.log(`${name} reports usage only during a streaming response; there is nothing to refresh. Run a request through this provider to update it, then see \`ocx account list ${name}\`.`);
    } else console.log(`no quota report available for ${name}`);
    return 0;
  }
  const result = await fetchCodexRows(deps, baseUrl, true, true, { refreshAction: true });
  const failed = familyFailure(result, `failed to refresh ${name}`);
  if (failed !== null) return failed;
  if (wantsJson) console.log(JSON.stringify({ accounts: result.rows }, null, 2));
  else for (const row of result.rows) console.log(refreshLine(row));
  return 0;
}

export async function cmdAutoSwitch(args: string[], deps: AccountDeps): Promise<number> {
  const wantsJson = flag(args, "--json");
  const name = args.shift();
  const action = args.shift();
  if (!name || !action) return usage();
  const classified = configAndType(deps, name);
  // Anthropic keeps its threshold on its own pool contract; generic OAuth providers (#695)
  // and the Codex pool are accepted here.
  if (!("error" in classified) && classified.type === "oauth" && isAnthropicOAuthInstance(name)) return cmdAnthropicAccountThreshold(args, action, wantsJson, deps, name);
  if ("error" in classified || classified.type === "api-key" || isAnthropicOAuthInstance(name)) {
    return usage("Error: auto-switch only applies to the openai Codex account pool or a generic OAuth provider pool");
  }
  const genericPool = classified.type === "oauth";
  let threshold: number | undefined;
  if (action === "on" && args.length === 0) threshold = 80;
  else if (action === "off" && args.length === 0) threshold = 0;
  else if (action === "threshold" && args.length === 1 && /^\d+$/.test(args[0]!)) threshold = Number(args[0]);
  else if (action !== "status" || args.length !== 0) return usage();
  if (threshold !== undefined && (!Number.isInteger(threshold) || threshold < 0 || threshold > 100)) {
    return usage("Error: threshold must be an integer 0-100");
  }
  let settings: Record<string, unknown> = {};
  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();
  if (action === "status") {
    const response = await apiJson(
      deps, baseUrl, "GET",
      genericPool ? `/api/oauth/accounts/pool?provider=${encodeURIComponent(name)}` : "/api/codex-auth/active",
    );
    if (response.status === 0) return proxyUnreachable(response.transportError);
    if (response.status !== 200 || (!genericPool && typeof response.json.autoSwitchThreshold !== "number")) {
      return apiError(response.json, "failed to read auto-switch status", response.status);
    }
    settings = genericPool && (!response.json || typeof response.json !== "object" || Array.isArray(response.json))
      ? {} : response.json;
    threshold = typeof settings.autoSwitchThreshold === "number" ? settings.autoSwitchThreshold : 0;
  } else {
    const response = genericPool
      ? await apiJson(deps, baseUrl, "PUT", "/api/oauth/accounts/pool", { provider: name, autoSwitchThreshold: threshold })
      : await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/auto-switch", { threshold });
    if (response.status === 0) return proxyUnreachable(response.transportError);
    if (response.status !== 200) return apiError(response.json, "failed to update auto-switch", response.status);
    settings = genericPool && (!response.json || typeof response.json !== "object" || Array.isArray(response.json))
      ? {} : response.json;
  }
  if (genericPool) {
    // Generic thresholds are stored independently of the enabled override. The
    // latter may inherit global preference and never disables reactive rotation.
    const stored = settings.autoSwitchThreshold;
    const storedThreshold = typeof stored === "number" && Number.isInteger(stored) && stored >= 0 && stored <= 100
      ? stored : null;
    const poolEnabled = typeof settings.enabled === "boolean" ? settings.enabled : null;
    // Three states, not two. `true` is stored-but-not-applied, `false` is applied by the
    // shared kernel, and absent is a server that does not speak this field at all. Collapsing
    // false into absent would render the live feature as an unknown capability.
    const inert = typeof settings.inert === "boolean" ? settings.inert : null;
    // A positive stored threshold only steers selection once the pool consumes it, which is
    // exactly what `inert: false` reports. Zero remains the explicit disabled value.
    const enabled = inert === false && storedThreshold !== null && storedThreshold > 0;
    if (wantsJson) {
      console.log(JSON.stringify({ provider: name, autoSwitchThreshold: storedThreshold, enabled, poolEnabled, inert }, null, 2));
    } else {
      const value = storedThreshold === null ? "unset" : `${storedThreshold}%`;
      const state = inert === false ? (enabled ? "on" : "off") : inert === true ? "inactive" : "unavailable";
      const why = inert === false
        ? (enabled ? "applied by this pool" : storedThreshold === 0 ? "usage-based switching disabled" : "no threshold stored")
        : inert === true ? "not applied by this pool" : "threshold support is unknown";
      console.log(`auto-switch: ${state} (stored threshold ${value}; ${why})`);
    }
    return 0;
  }
  const enabled = threshold! > 0;
  if (wantsJson) console.log(JSON.stringify({ provider: name, autoSwitchThreshold: threshold, enabled }, null, 2));
  else console.log(enabled ? `auto-switch: on (threshold ${threshold}%)` : "auto-switch: off");
  return 0;
}

function deletePath(type: "codex" | "oauth" | "api-key", name: string, id: string): string {
  if (type === "codex") return `/api/codex-auth/accounts?id=${encodeURIComponent(id)}`;
  if (type === "oauth") return `/api/oauth/accounts?provider=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`;
  return `/api/providers/keys?name=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`;
}

export async function cmdRemove(args: string[], deps: AccountDeps): Promise<number> {
  const wantsJson = flag(args, "--json");
  const fail = (message: string): number => {
    if (wantsJson) console.error(JSON.stringify({ error: message }));
    else console.error(`Error: ${message}`);
    return 1;
  };
  const confirmed = flag(args, "--yes");
  const name = args.shift();
  const requestedId = args.shift();
  if (!name || !requestedId || args.length) return wantsJson ? fail("provider and account id are required") : usage();
  if (!confirmed) {
    const message = `Confirmation required. Re-run: ocx account remove ${name} ${requestedId} --yes`;
    return wantsJson ? fail(message) : usage(message);
  }
  const classified = configAndType(deps, name);
  if ("error" in classified) return wantsJson ? fail(classified.error) : usage(`Error: ${classified.error}`);
  if (classified.type === "codex" && (requestedId === "main" || requestedId === MAIN_ID)) return wantsJson
    ? fail("the main Codex App login cannot be removed")
    : usage("Error: the main Codex App login cannot be removed");
  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
  let id = requestedId;
  if (classified.type === "codex") {
    const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
    if ("networkDown" in target) {
      const reason = target.transportError ? ` reason: ${target.transportError}` : "";
      return fail(`Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.${reason}`);
    }
    if ("error" in target) {
      const message = target.kind === "not_found" ? `account or key "${requestedId}" was not found` : target.error;
      return wantsJson ? fail(message) : usage(`Error: ${message}`);
    }
    id = target.id;
  }
  const before = await fetchRows(deps, baseUrl, name, classified.type);
  if (before.networkDown) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
  if (before.errorJson) return fail(errorText(before.errorJson, `failed to verify ${name} before removal`));
  if (!before.rows.some(row => row.id === id)) return wantsJson
    ? fail(`account or key "${requestedId}" was not found`)
    : usage(`Error: account or key "${requestedId}" was not found`);
  const response = await apiJson(deps, baseUrl, "DELETE", deletePath(classified.type, name, id));
  if (response.status === 0) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
  if (response.status !== 200) return fail(errorText(response.json, `failed to remove ${requestedId}`));
  const catalogRefreshPending = classified.type === "codex"
    && codexCatalogRefreshPending(response.json);
  const after = await fetchRows(deps, baseUrl, name, classified.type);
  if (after.networkDown || after.errorJson) {
    const detail = after.networkDown ? "proxy not reachable" : typeof after.errorJson?.error === "string" ? after.errorJson.error : "unknown error";
    return fail(`post-delete verification failed; delete may have succeeded: ${detail}`);
  }
  const removedActive = before.activeId === id;
  const result = {
    ok: true,
    provider: name,
    id,
    removedActive,
    promotedActiveId: after.activeId,
    ...(classified.type === "codex" ? { catalogRefreshPending } : {}),
  };
  if (wantsJson) console.log(JSON.stringify(result, null, 2));
  else if (classified.type === "codex" && removedActive && after.activeId === null) console.log(`openai: ${AUTO_NOTE}`);
  else if (classified.type === "oauth") console.log(after.rows.length ? `${name}: active account is now ${after.activeId}` : `${name}: no accounts remaining`);
  else if (classified.type === "api-key") console.log(after.rows.length ? `${name}: active key is now ${after.activeId}` : `${name}: no keys remaining`);
  else console.log(`${name}: removed account ${requestedId}`);
  if (!wantsJson && catalogRefreshPending) warnIfCodexCatalogRefreshPending(response.json);
  return 0;
}

export async function cmdAddKey(args: string[], deps: AccountDeps): Promise<number> {
  const wantsJson = flag(args, "--json");
  const labelArg = flagValue(args, "--label");
  const name = args.shift();
  if (!name || args.length || (labelArg.found && labelArg.value === undefined)) return usage();
  const classified = configAndType(deps, name);
  if ("error" in classified || classified.type !== "api-key") return usage("Error: add-key only applies to API-key providers");
  const input: AccountStdin = deps.stdinImpl ?? process.stdin;
  if (input.isTTY) return usage(PIPE_GUIDANCE);
  let key: string;
  try {
    key = await readStdinLine(deps);
  } catch (error) {
    return usage(`Error: ${error instanceof Error ? error.message : String(error)}\n${PIPE_GUIDANCE}`);
  }
  if (!key) return usage(`Error: API key input was empty\n${PIPE_GUIDANCE}`);
  const label = labelArg.value?.trim();
  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();
  const response = await apiJson(deps, baseUrl, "POST", "/api/providers/keys", { name, key, ...(label ? { label } : {}) });
  if (response.status === 0) return proxyUnreachable(response.transportError);
  if (response.status !== 201) return apiError(response.json, `failed to add a key for ${name}`, response.status);
  const id = typeof response.json.id === "string" ? response.json.id : null;
  // Redact the key inside the label BEFORE serialization — a key containing
  // JSON-escaped characters (" or \) would otherwise survive the whole-output
  // pass in escaped form (audit finding, Carver WP3-C).
  const safeLabel = label ? label.replaceAll(key, "[redacted]") : undefined;
  const result = { ok: true, id, ...(safeLabel ? { label: safeLabel } : {}) };
  const output = wantsJson ? JSON.stringify(result, null, 2)
    : `${name}: added API key ${id ?? ""}${safeLabel ? ` (${safeLabel})` : ""}`.trim();
  console.log(output.replaceAll(key, "[redacted]"));
  return 0;
}

export async function cmdImport(args: string[], deps: AccountDeps): Promise<number> {
  const wantsJson = flag(args, "--json");
  const formatArg = flagValue(args, "--format");
  const fileArg = flagValue(args, "--file");
  const fromStdin = flag(args, "--stdin");
  const acceptRisk = flag(args, ANTIGRAVITY_RISK_CLI_FLAG);
  const provider = args.shift();

  // Admission happens before source I/O. In particular, an inline JSON positional argument is
  // rejected without inspecting or echoing it, keeping secrets out of any subsequent surface.
  if (
    provider !== ACCOUNT_IMPORT_PROVIDER
    || formatArg.value !== ACCOUNT_IMPORT_FORMAT
    || formatArg.found !== true
  ) {
    const code = provider === ACCOUNT_IMPORT_PROVIDER ? "unsupported_format" : "unsupported_provider";
    console.error(`Error: ${code}`);
    return 1;
  }
  const hasFile = fileArg.found && typeof fileArg.value === "string" && fileArg.value.length > 0;
  if (args.length > 0 || hasFile === fromStdin || (fileArg.found && !hasFile)) {
    return usage("Error: choose exactly one bounded source: --file <path> or --stdin");
  }

  // Before reading the document: an imported Antigravity credential carries the same account
  // risk as a fresh login. With --stdin the document owns stdin, so only the flag can accept.
  const stdinInput: AccountStdin = deps.stdinImpl ?? process.stdin;
  const decision = await resolveAntigravityRiskAcknowledgement({
    flag: acceptRisk,
    interactive: !fromStdin && stdinInput.isTTY === true
      && (deps.antigravityRisk?.promptVisible ?? (() => process.stderr.isTTY === true))(),
    agentDriven: (deps.antigravityRisk?.agentDriven ?? isAgentDriven)(),
    warn: text => console.error(text),
    ask: async question => {
      process.stderr.write(question);
      return await readSecretLine(deps, "confirmation");
    },
  });
  if (decision !== "accepted") {
    console.error(antigravityRiskDecisionMessage(decision));
    return 1;
  }

  let source: string;
  try {
    source = hasFile ? readBoundedImportFile(fileArg.value!) : await readBoundedImportStdin(deps);
  } catch (error) {
    const code = error instanceof Error ? error.message : "source_read_failed";
    console.error(`Error: ${["invalid_document", "source_read_failed", "stdin_required", "stdin_timeout"].includes(code) ? code : "source_read_failed"}`);
    return 1;
  }

  let document: unknown;
  try {
    document = JSON.parse(source) as unknown;
  } catch {
    console.error("Error: invalid_document");
    return 1;
  }

  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();
  const configuredImportTimeout = deps.importTimeoutMs;
  const importTimeoutMs = typeof configuredImportTimeout === "number" && Number.isFinite(configuredImportTimeout)
    ? Math.min(ACCOUNT_IMPORT_TIMEOUT_MS, Math.max(1, Math.floor(configuredImportTimeout)))
    : ACCOUNT_IMPORT_TIMEOUT_MS;
  const controller = new AbortController();
  let timedOut = false;
  const timer = setTimeout(() => {
    timedOut = true;
    controller.abort();
  }, importTimeoutMs);
  let response;
  try {
    response = await apiJson(deps, baseUrl, "POST", "/api/oauth/accounts/import", {
      provider,
      format: formatArg.value,
      document,
      [ANTIGRAVITY_RISK_ACK_FIELD]: true,
    }, { signal: controller.signal });
  } finally {
    clearTimeout(timer);
  }
  if (response.status === 0) {
    if (!timedOut) return proxyUnreachable(response.transportError);
    console.error(`Error: import_timeout after ${importTimeoutMs}ms`);
    return 1;
  }
  if (response.status !== 200) {
    if (response.json.code === ANTIGRAVITY_RISK_REFUSAL_CODE) {
      console.error(`Error: ${ANTIGRAVITY_RISK_REFUSAL_CODE}`);
    } else if (IMPORT_CODES.has(response.json.code as AccountImportCode)) {
      console.error(`Error: ${response.json.code as AccountImportCode}`);
    } else {
      console.error(`Error: import_request_failed (status ${response.status})`);
    }
    return 1;
  }
  const result = safeImportResult(response.json);
  if (!result) {
    console.error("Error: invalid_response");
    return 1;
  }

  if (wantsJson) {
    console.log(JSON.stringify(result, null, 2));
  } else {
    console.log(
      `${provider}: ${result.importedCount} imported, ${result.updatedCount} updated, ${result.failedCount} failed, ${result.unsupportedCount} unsupported`,
    );
    for (const item of result.results) console.log(`  #${item.index + 1} ${item.status} (${item.code})`);
  }
  return result.failedCount > 0 || result.unsupportedCount > 0 ? 1 : 0;
}

/** Lift a process-local cooldown through the management route that owns that pool. */
export async function cmdClearCooldown(args: string[], deps: AccountDeps): Promise<number> {
  const wantsJson = flag(args, "--json");
  const name = args.shift();
  const requestedId = args.shift();
  if (!name || !requestedId || args.length) return usage();
  const classified = configAndType(deps, name);
  if ("error" in classified) return usage(`Error: ${classified.error}`);
  if (classified.type !== "codex" && !(classified.type === "oauth" && isAnthropicOAuthInstance(name))) {
    return usage(`Error: ${name} has no operator-clearable account cooldown`);
  }
  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();
  let id: string;
  let response: Awaited<ReturnType<typeof apiJson>>;
  if (classified.type === "codex") {
    const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
    if ("networkDown" in target) return proxyUnreachable(target.transportError);
    if ("error" in target) return reportCodexAccountTargetError(target);
    id = target.id;
    response = await apiJson(deps, baseUrl, "POST", "/api/codex-auth/accounts/clear-cooldown", { id });
  } else {
    const list = await apiJson(deps, baseUrl, "GET", `/api/oauth/accounts?provider=${encodeURIComponent(name)}`);
    if (list.status === 0) return proxyUnreachable(list.transportError);
    if (list.status !== 200) return apiError(list.json, `failed to list ${name} OAuth accounts`, list.status);
    const target = resolveGenericOAuthAccountTarget(
      Array.isArray(list.json.accounts) ? list.json.accounts : [],
      requestedId,
    );
    if ("error" in target) return usage(`Error: ${target.error}`);
    id = target.id;
    response = await apiJson(deps, baseUrl, "POST", "/api/oauth/accounts/clear-cooldown", {
      provider: name,
      accountId: id,
    });
  }
  if (response.status === 0) return proxyUnreachable(response.transportError);
  if (response.status !== 200) return apiError(response.json, `failed to clear cooldown for ${requestedId}`, response.status);
  const cleared = response.json?.cleared === true;
  if (wantsJson) console.log(JSON.stringify({ ok: true, provider: name, id, cleared }, null, 2));
  else if (cleared) console.log(`${name}: cooldown lifted for ${requestedId}`);
  else console.log(`${name}: no active cooldown for ${requestedId}`);
  return 0;
}

/**
 * Named selection orders. The words convey sequence rather than rank because the
 * pool moves down the list only when everything above it is drained — "high
 * priority" would suggest the account gets more traffic, which is not what
 * ordering does.
 */
const PRIORITY_PRESETS: Record<string, number> = {
  first: 2,
  earlier: 1,
  normal: 0,
  later: -1,
  last: -2,
};

function priorityPresetName(priority: number): string | null {
  return Object.entries(PRIORITY_PRESETS).find(([, value]) => value === priority)?.[0] ?? null;
}

function formatPriority(priority: number): string {
  const preset = priorityPresetName(priority);
  const signed = priority > 0 ? `+${priority}` : String(priority);
  return preset ? `${signed} (${preset})` : signed;
}

/** `null` = reset to the default; `undefined` = unparseable. */
function parsePriorityArgument(raw: string): number | null | undefined {
  const word = raw.trim().toLowerCase();
  if (word === "reset") return null;
  // Own keys only: `in` also matches "constructor", "__proto__", and friends.
  if (Object.hasOwn(PRIORITY_PRESETS, word)) return PRIORITY_PRESETS[word];
  // The regex only rules out shapes Number() would coerce ("1e2", " 1 ", ""); the range
  // itself comes from the core parser so the CLI cannot drift from what the API accepts.
  if (!/^[+-]?\d+$/.test(word)) return undefined;
  return parseAccountPriority(Number(word)) ?? undefined;
}

export async function cmdPriority(args: string[], deps: AccountDeps): Promise<number> {
  const wantsJson = flag(args, "--json");
  const name = args.shift();
  const requestedId = args.shift();
  const requestedPriority = args.shift();
  if (!name || !requestedId || args.length) return usage();
  const classified = configAndType(deps, name);
  if ("error" in classified) return usage(`Error: ${classified.error}`);
  if (classified.type !== "codex") {
    return usage("Error: selection order only applies to the openai Codex account pool");
  }
  // Validate before touching the network so a typo never reaches the proxy.
  let priority: number | null | undefined;
  if (requestedPriority !== undefined) {
    priority = parsePriorityArgument(requestedPriority);
    if (priority === undefined) {
      return usage(`Error: selection order must be an integer ${MIN_ACCOUNT_PRIORITY}..${MAX_ACCOUNT_PRIORITY}, one of ${Object.keys(PRIORITY_PRESETS).join("/")}, or reset`);
    }
  }

  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();
  const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
  if ("networkDown" in target) return proxyUnreachable(target.transportError);
  if ("error" in target) {
    if (target.kind === "not_found" && priority === undefined) return usage(`Error: no ${name} account ${requestedId}`);
    return reportCodexAccountTargetError(target);
  }
  const id = target.id;

  // No value means "show" — a read must not rewrite what it is reporting.
  if (priority === undefined) {
    const result = await fetchCodexRows(deps, baseUrl);
    const failed = familyFailure(result, `failed to read ${name} accounts`);
    if (failed !== null) return failed;
    const row = result.rows.find(candidate => candidate.id === id);
    if (!row) return usage(`Error: no ${name} account ${requestedId}`);
    const current = normalizeAccountPriority(row.priority);
    if (wantsJson) {
      console.log(JSON.stringify(
        { ok: true, provider: name, id, priority: current, preset: priorityPresetName(current) },
        null,
        2,
      ));
    } else {
      console.log(`${name}: ${requestedId} selection order is ${formatPriority(current)}`);
    }
    return 0;
  }

  const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/priority", { id, priority });
  if (response.status === 0) return proxyUnreachable(response.transportError);
  if (response.status !== 200) return apiError(response.json, `failed to set selection order for ${requestedId}`, response.status);
  const applied = typeof response.json.priority === "number" ? response.json.priority : (priority ?? 0);
  if (wantsJson) {
    console.log(JSON.stringify(
      { ok: true, provider: name, id, priority: applied, preset: priorityPresetName(applied) },
      null,
      2,
    ));
  } else {
    console.log(`${name}: ${requestedId} selection order is now ${formatPriority(applied)}`);
  }
  // Not cmdUse's note: re-ordering takes effect on the next unbound request rather than
  // only on new sessions, because preemption moves those requests up immediately.
  console.error("Takes effect from the next unbound request; running threads keep their current account until drained.");
  // The release is not optional and not conditional on the value changing, so it has to be
  // stated: this route is the only way to clear a pin without immediately setting another,
  // which means a write storing the order an account already had still releases it. Without
  // this line that is a silent side effect of a command that looks purely declarative.
  console.error('Also releases any manual "use this account now" pin, on any account.');
  return 0;
}

function resolveGenericOAuthAccountTarget(accounts: unknown[], requested: string, kind: "OAuth" | "API key" = "OAuth"): { id: string } | { error: string } {
  const rows = accounts.filter((value): value is { id: string; alias?: unknown } =>
    typeof value === "object" && value !== null && typeof (value as { id?: unknown }).id === "string",
  );
  if (rows.some(account => account.id === requested)) return { id: requested };
  const exact = rows.filter(account => account.alias === requested);
  const matches = exact.length > 0
    ? exact
    : rows.filter(account => typeof account.alias === "string" && account.alias.toLowerCase() === requested.toLowerCase());
  if (matches.length === 1) return { id: matches[0]!.id };
  if (matches.length > 1) return { error: `alias "${requested}" names ${matches.length} accounts; use the account id` };
  return { error: `Account not found: no ${kind} account has the id or alias "${requested}"` };
}

/** Pause or resume a Codex, OAuth, or API-key pool account. */
export async function cmdPause(args: string[], deps: AccountDeps, paused: boolean): Promise<number> {
  const wantsJson = flag(args, "--json");
  // #8398: an explicit resume the server performs only after an account-bound health read.
  const ifHealthy = flag(args, "--if-healthy");
  const name = args.shift();
  const requestedId = args.shift();
  const verb = paused ? "pause" : "resume";
  if (!name || !requestedId || args.length) return usage();
  if (ifHealthy && paused) return usage("Error: --if-healthy applies only to resume");
  const classified = configAndType(deps, name);
  if ("error" in classified) return usage(`Error: ${classified.error}`);
  if (ifHealthy && classified.type === "api-key") return usage("Error: --if-healthy applies to the openai Codex account pool or an OAuth provider pool");
  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();
  const healthGate = ifHealthy ? { ifHealthy: true } : {};
  // A refused health-gated resume is an answer, not a failure: exit 3 lets a supervisor tell it apart.
  const refusedResume = (json: Record<string, unknown>, id: string): number | undefined => {
    if (!ifHealthy || json.code !== "resume_refused" || typeof json.reason !== "string") return undefined;
    if (wantsJson) console.log(JSON.stringify({ ok: false, provider: name, id, resumed: false, reason: json.reason }, null, 2));
    else console.log(`${name}: ${requestedId} not resumed: ${json.reason}`);
    return 3;
  };

  if (classified.type === "oauth") {
    const list = await apiJson(deps, baseUrl, "GET", `/api/oauth/accounts?provider=${encodeURIComponent(name)}`);
    if (list.status === 0) return proxyUnreachable(list.transportError);
    if (list.status !== 200) return apiError(list.json, `failed to list ${name} OAuth accounts`, list.status);
    const target = resolveGenericOAuthAccountTarget(Array.isArray(list.json.accounts) ? list.json.accounts : [], requestedId);
    if ("error" in target) return usage(`Error: ${target.error}`);

    const response = await apiJson(deps, baseUrl, "PUT", "/api/oauth/accounts/pause", {
      provider: name,
      accountId: target.id,
      paused,
      ...healthGate,
    });
    if (response.status === 0) return proxyUnreachable(response.transportError);
    if (response.status === 409) { const refused = refusedResume(response.json, target.id); if (refused !== undefined) return refused; }
    if (response.status !== 200) return apiError(response.json, `failed to ${verb} ${requestedId}`, response.status);

    if (wantsJson) {
      console.log(JSON.stringify({ ok: true, provider: name, id: target.id, paused,
        activeAccountId: response.json.activeAccountId }, null, 2));
    } else {
      console.log(`${name}: ${requestedId} ${paused ? "paused" : "resumed"}`);
      if (response.json.activeAccountChanged === true) {
        console.error(`Active account changed to ${String(response.json.activeAccountId)}.`);
      }
    }
    return 0;
  }

  if (classified.type === "api-key") {
    const rows = await fetchRows(deps, baseUrl, name, "api-key");
    if (rows.status === 0) return proxyUnreachable(rows.transportError);
    if (rows.status !== 200) return apiError(rows.errorJson ?? {}, "failed to list API key accounts", rows.status);
    const target = resolveGenericOAuthAccountTarget(rows.rows.map(row => ({ id: row.id, alias: row.label })), requestedId, "API key");
    if ("error" in target) return usage(`Error: ${target.error}`);
    const result = await apiJson(deps, baseUrl, "PUT", "/api/providers/keys/pause", { name, id: target.id, paused });
    if (result.status === 0) return proxyUnreachable(result.transportError);
    if (result.status !== 200) return apiError(result.json, `failed to ${verb} account`, result.status);
    const idx = rows.rows.findIndex(row => row.id === target.id);
    const ordered = idx >= 0 ? [...rows.rows.slice(idx + 1), ...rows.rows.slice(0, idx)] : rows.rows;
    const beforeActiveId = rows.rows.find(row => row.active && !row.paused)?.id ?? null;
    const inferredActiveId = paused
      ? (beforeActiveId === target.id
        ? (ordered.find(row => row.id !== target.id && !row.paused)?.id ?? null)
        : beforeActiveId)
      : (beforeActiveId ?? (rows.rows.some(row => row.paused) ? target.id : null));
    const activeAccountId = result.json.activeAccountId !== undefined
      ? result.json.activeAccountId
      : result.json.activeId !== undefined
        ? result.json.activeId
        : inferredActiveId;
    const activeAccountChanged = typeof result.json.activeAccountChanged === "boolean"
      ? result.json.activeAccountChanged
      : beforeActiveId !== activeAccountId;
    if (wantsJson) {
      console.log(JSON.stringify({ ok: true, provider: name, id: target.id, paused,
        activeAccountId: activeAccountId ?? null,
        activeAccountChanged }, null, 2));
    } else {
      console.log(`${name}: account ${paused ? "paused" : "resumed"}`);
      if (activeAccountChanged) {
        console.error(`Active account changed to ${String(activeAccountId ?? "none")}.`);
      }
    }
    return 0;
  }
  if (classified.type !== "codex") {
    return usage(`Error: ${verb} applies to the openai Codex account pool, a generic OAuth provider, or an API-key pool`);
  }
  const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
  if ("networkDown" in target) return proxyUnreachable(target.transportError);
  if ("error" in target) return reportCodexAccountTargetError(target);
  const id = target.id;

  const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/pause", { id, paused, ...healthGate });
  // Transport sentinel first: status 0 means the proxy never answered, and comparing it to
  // 200 would report an unreachable proxy as a management error.
  if (response.status === 0) return proxyUnreachable(response.transportError);
  if (response.status === 409) { const refused = refusedResume(response.json, id); if (refused !== undefined) return refused; }
  if (response.status !== 200) return apiError(response.json, `failed to ${verb} ${requestedId}`, response.status);

  if (wantsJson) {
    console.log(JSON.stringify({ ok: true, provider: name, id, paused }, null, 2));
  } else {
    console.log(`${name}: ${requestedId} ${paused ? "paused" : "resumed"}`);
  }
  if (paused) {
    // Both are server-side effects of this route (auth-api.ts:1508-1510), not consequences
    // the operator would infer from the word "pause".
    console.error("Threads bound to this account are unbound, and a fallback account is selected if this one was active.");
  }
  return 0;
}

/**
 * `ocx account pause-exhausted [--off]` (#2702).
 *
 * Pauses every account whose quota is spent. The route refreshes quota for each account, so
 * it can partially fail; the response distinguishes "checked none and some failed" from
 * "checked some", and that distinction is reported rather than flattened into ok/not-ok.
 */
export async function cmdPauseExhausted(args: string[], deps: AccountDeps): Promise<number> {
  const wantsJson = flag(args, "--json");
  const name = args.shift();
  if (!name || args.length) return usage();
  const classified = configAndType(deps, name);
  if ("error" in classified) return usage(`Error: ${classified.error}`);
  if (classified.type !== "codex") {
    return usage("Error: pause-exhausted applies to the openai Codex account pool");
  }

  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();

  const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/pause-exhausted", {});
  if (response.status === 0) return proxyUnreachable(response.transportError);
  if (response.status !== 200) return apiError(response.json, "failed to pause exhausted accounts", response.status);

  const pausedIds = Array.isArray(response.json.pausedAccountIds)
    ? (response.json.pausedAccountIds as unknown[]).filter((value): value is string => typeof value === "string")
    : [];
  const checked = typeof response.json.checkedAccountCount === "number" ? response.json.checkedAccountCount : null;
  const failed = typeof response.json.failedAccountCount === "number" ? response.json.failedAccountCount : null;

  const complete = failed === null || failed === 0;
  const ok = complete;
  if (failed !== null && failed > 0) {
    console.error(`Quota refresh failed for ${failed} account(s); those were not evaluated.`);
  }
  if (wantsJson) {
    console.log(JSON.stringify({
      ok,
      complete,
      provider: name,
      pausedAccountIds: pausedIds,
      checkedAccountCount: checked,
      failedAccountCount: failed,
    }, null, 2));
    return ok ? 0 : 1;
  }
  console.log(pausedIds.length > 0
    ? `${name}: paused ${pausedIds.length} exhausted account(s): ${pausedIds.join(", ")}`
    : `${name}: no exhausted accounts to pause`);
  return ok ? 0 : 1;
}

/**
 * One transport, because there is now one contract.
 *
 * This used to be a table of the differences between the Codex and Anthropic pools -- different
 * read path, different write path, different response keys, and a `provider` field mandatory on
 * one body and forbidden on the other. That table existed only because the two contracts
 * disagreed; `/api/pool/settings` answers with the same keys for every kind, so the table
 * collapses to a single shape and the asymmetry it encoded is gone rather than relocated.
 *
 * The legacy paths still work and still have their own goldens. Nothing here reads them.
 */
interface PoolTransport {
  readPath: string;
  writePath: string;
  /** Response key carrying the applied strategy. */
  strategyKey: string;
  /** Response key carrying the applied sticky limit. */
  stickyKey: string;
  writeBody: (field: "strategy" | "stickyLimit", value: unknown) => Record<string, unknown>;
}

function unifiedPoolTransport(provider: string): PoolTransport {
  return {
    readPath: `/api/pool/settings?provider=${encodeURIComponent(provider)}`,
    writePath: "/api/pool/settings",
    strategyKey: "strategy",
    stickyKey: "stickyLimit",
    writeBody: (field, value) => ({ provider, [field]: value }),
  };
}

/**
 * Codex and Anthropic keep their own pool transports; every other OAuth provider speaks the
 * generic pool-settings contract on the same `/api/oauth/accounts/pool` route (#695).
 * API-key providers have no pool and are refused here without a round-trip.
 */
function poolTransportFor(
  classified: { type: "codex" | "oauth" | "api-key" },
  name: string,
): PoolTransport | string {
  if (classified.type === "codex" || classified.type === "oauth") return unifiedPoolTransport(name);
  return `pool settings apply to OAuth account pools, not the API-key provider "${name}"`;
}

/**
 * `ocx account strategy <provider> [<name>]` and `ocx account sticky <provider> [<n>]` (#2702).
 *
 * One implementation rather than two near-duplicates, because strategy and sticky are two
 * fields of one setting on every pool that has them.
 *
* Values are NOT re-validated here. The server owns both contracts -- three strategy names,
* a 1-100 sticky bound -- and a duplicated bound is a second thing to keep in sync. Its 400
* is actionable now that the CLI prints `reason`.
*/
async function poolSetting(
  args: string[],
  deps: AccountDeps,
  field: "strategy" | "stickyLimit",
): Promise<number> {
  const wantsJson = flag(args, "--json");
  const name = args.shift();
  const requested = args.shift();
  const label = field === "strategy" ? "pool strategy" : "sticky limit";
  if (!name || args.length) return usage();
  const classified = configAndType(deps, name);
  if ("error" in classified) return usage(`Error: ${classified.error}`);
  const transport = poolTransportFor(classified, name);
  if (typeof transport === "string") return usage(`Error: ${transport}`);

  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();

  // No value means show. A read must not rewrite what it is reporting.
  if (requested === undefined) {
    const response = await apiJson(deps, baseUrl, "GET", transport.readPath);
    if (response.status === 0) return proxyUnreachable(response.transportError);
    if (response.status !== 200) return apiError(response.json, `failed to read ${label}`, response.status);
    const strategy = response.json[transport.strategyKey];
    const sticky = response.json[transport.stickyKey];
    const autoSwitchThreshold = typeof response.json.autoSwitchThreshold === "number"
      ? response.json.autoSwitchThreshold
      : undefined;
    if (wantsJson) {
      // Pool-neutral key names: the two routes spell the same two settings differently, and a
      // `--json` consumer should not have to branch on which pool answered.
      const payload: Record<string, unknown> = { ok: true, provider: name, strategy, stickyLimit: sticky };
      if (autoSwitchThreshold !== undefined) {
        payload.autoSwitchThreshold = autoSwitchThreshold;
      }
      console.log(JSON.stringify(payload, null, 2));
    } else {
      if (field === "strategy" && autoSwitchThreshold !== undefined) {
        const thresholdSummary = strategy === "least-loaded"
          ? "fewest active requests"
          : strategy === "round-robin"
          ? "threshold not used"
          : autoSwitchThreshold > 0
          ? (strategy === "fill-first"
              ? `drain at ${autoSwitchThreshold}%`
              : strategy === "reset-first"
              ? `nearest reset below ${autoSwitchThreshold}%`
              : `switch at ${autoSwitchThreshold}%`)
          : "proactive switching off";
        console.log(`${name}: ${label} is ${String(strategy)} (${thresholdSummary})`);
      } else {
        console.log(`${name}: ${label} is ${String(field === "strategy" ? strategy : sticky)}`);
      }
    }
    return 0;
  }

  // Sent as a number when it parses as one so the server sees the type it validates;
  // a non-numeric string still goes through and earns the server's own 400.
  const value = field === "strategy"
    ? requested
    : (Number.isNaN(Number(requested)) ? requested : Number(requested));
  const response = await apiJson(deps, baseUrl, "PUT", transport.writePath, transport.writeBody(field, value));
  if (response.status === 0) return proxyUnreachable(response.transportError);
  if (response.status !== 200) return apiError(response.json, `failed to set ${label}`, response.status);

  if (wantsJson) {
    console.log(JSON.stringify({
      ok: true,
      provider: name,
      strategy: response.json[transport.strategyKey],
      stickyLimit: response.json[transport.stickyKey],
    }, null, 2));
  } else {
    // Echo the APPLIED value from the response, not the requested one: the server normalizes,
    // and printing the request would hide a normalization the operator should see.
    const applied = field === "strategy" ? response.json[transport.strategyKey] : response.json[transport.stickyKey];
    console.log(`${name}: ${label} is now ${String(applied)}`);
  }
  return 0;
}

export function cmdStrategy(args: string[], deps: AccountDeps): Promise<number> {
  return poolSetting(args, deps, "strategy");
}

export function cmdSticky(args: string[], deps: AccountDeps): Promise<number> {
  return poolSetting(args, deps, "stickyLimit");
}

export async function cmdAlias(args: string[], deps: AccountDeps): Promise<number> {
  const wantsJson = flag(args, "--json");
  const name = args.shift();
  const requestedId = args.shift();
  const requestedAlias = args.shift();
  if (!name || !requestedId || requestedAlias === undefined || args.length) return usage();
  const classified = configAndType(deps, name);
  if ("error" in classified) return usage(`Error: ${classified.error}`);
  if (classified.type === "codex" && (requestedId === "main" || requestedId === MAIN_ID)) {
    return usage("Error: the main Codex App login cannot be renamed");
  }
  const alias = requestedAlias === "-" ? "" : requestedAlias.trim();
  if (alias.length > 80 || /[\x00-\x1f\x7f]/.test(alias)) return usage("Error: alias must be at most 80 printable characters");
  if (classified.type === "codex" && isReservedCodexAccountWord(alias)) return usage(`Error: "${alias}" is reserved for \`ocx account use\` and cannot be an alias`);
  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();
  let id = requestedId;
  if (classified.type === "codex") {
    const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
    if ("networkDown" in target) return proxyUnreachable(target.transportError);
    if ("error" in target) return reportCodexAccountTargetError(target);
    id = target.id;
  }
  const path = classified.type === "codex"
    ? "/api/codex-auth/accounts/alias"
    : classified.type === "oauth"
      ? "/api/oauth/accounts/alias"
      : "/api/providers/keys/alias";
  const body = classified.type === "codex"
    ? { id, alias }
    : classified.type === "oauth"
      ? { provider: name, accountId: id, alias }
      : { name, id, alias };
  const response = await apiJson(deps, baseUrl, "PUT", path, body);
  if (response.status === 0) return proxyUnreachable(response.transportError);
  if (response.status !== 200) return apiError(response.json, `failed to rename ${requestedId}`, response.status);
  const result = { ok: true, provider: name, id, alias: alias || null };
  if (wantsJson) console.log(JSON.stringify(result, null, 2));
  else console.log(alias ? `${name}: ${requestedId} is now “${alias}”` : `${name}: cleared alias for ${requestedId}`);
  return 0;
}

/** Read or replace the ordered Anthropic model routes through the unified settings API. */
export async function cmdRoutes(args: string[], deps: AccountDeps): Promise<number> {
  const wantsJson = flag(args, "--json");
  const file = flagValue(args, "--file");
  const clear = flag(args, "--clear");
  const provider = args.shift();
  if (!isAnthropicOAuthInstance(provider) || args.length || (file.found && (!file.value || clear))) return usage();
  const baseUrl = await resolveBaseUrl(deps);
  if (!baseUrl) return proxyUnreachable();
  let routes: unknown;
  if (file.found) {
    try {
      const info = statSync(file.value!);
      if (!info.isFile() || info.size > 64 * 1024) return usage("Error: route file must be a regular JSON file of at most 64 KiB");
      routes = JSON.parse(readFileSync(file.value!, "utf8"));
    } catch {
      return usage("Error: could not read a valid JSON route file");
    }
  }
  const writing = file.found || clear;
  const response = await apiJson(deps, baseUrl, writing ? "PUT" : "GET",
    writing ? "/api/pool/settings" : `/api/pool/settings?provider=${provider}`,
    writing ? { provider, routes: clear ? null : routes } : undefined);
  if (response.status === 0) return proxyUnreachable(response.transportError);
  if (response.status !== 200) return apiError(response.json, "failed to manage Anthropic routes", response.status);
  const identityError = anthropicProviderIdentityError(response.json, provider, "Anthropic routes");
  if (identityError !== undefined) return identityError;
  if (wantsJson) console.log(JSON.stringify(response.json, null, 2));
  else console.log(JSON.stringify(response.json.routes ?? [], null, 2));
  return 0;
}