@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
text/typescript
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;
}