@iislee/opencodex 2.31.0 → 2.35.0

package/src/cli/account-main.ts

@@ -190,8 +190,8 @@ export async function cmdNativeMainAccount(args: string[], deps: AccountDeps): P
     if (args.length > 0 || confirmed || rollback) return reject(args);
     const path = sub === "doctor" ? "/api/native-main-profiles/doctor" : "/api/native-main-profiles";
     const result = await apiJson(deps, baseUrl, "GET", path);
-    if (result.status === 0) return proxyUnreachable();
-    if (result.status !== 200) return apiError(result.json, `failed to ${sub} native profiles`);
+    if (result.status === 0) return proxyUnreachable(result.transportError);
+    if (result.status !== 200) return apiError(result.json, `failed to ${sub} native profiles`, result.status);
     if (wantsJson || sub === "doctor") console.log(JSON.stringify(result.json, null, 2));
     else printProfiles(Array.isArray(result.json.profiles) ? result.json.profiles as PublicProfile[] : []);
     return 0;
@@ -201,8 +201,8 @@ export async function cmdNativeMainAccount(args: string[], deps: AccountDeps): P
     const label = args.shift();
     if (!label || args.length > 0 || confirmed || rollback) return reject(args);
     const result = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/register", { label });
-    if (result.status === 0) return proxyUnreachable();
-    if (result.status !== 200) return apiError(result.json, "failed to register the current native login");
+    if (result.status === 0) return proxyUnreachable(result.transportError);
+    if (result.status !== 200) return apiError(result.json, "failed to register the current native login", result.status);
     if (wantsJson) console.log(JSON.stringify(result.json, null, 2));
     else console.log(`Registered '${label}' for ${effectiveCodexHome(result.json)}.`);
     return 0;
@@ -212,8 +212,8 @@ export async function cmdNativeMainAccount(args: string[], deps: AccountDeps): P
     const label = args.shift();
     if (!label || args.length > 0 || wantsJson || confirmed || rollback) return reject(args);
     const stage = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/stage", {});
-    if (stage.status === 0) return proxyUnreachable();
-    if (stage.status !== 200) return apiError(stage.json, "failed to prepare native login staging");
+    if (stage.status === 0) return proxyUnreachable(stage.transportError);
+    if (stage.status !== 200) return apiError(stage.json, "failed to prepare native login staging", stage.status);
     const stageId = typeof stage.json.stageId === "string" ? stage.json.stageId : "";
     const writerToken = typeof stage.json.writerToken === "string" ? stage.json.writerToken : "";
     const stagingHome = typeof stage.json.stagingCodexHome === "string" ? stage.json.stagingCodexHome : "";
@@ -258,8 +258,8 @@ export async function cmdNativeMainAccount(args: string[], deps: AccountDeps): P
       if (leaseLost) throw new Error("The native-login staging lease was lost before login completed.");
       if (exitCode !== 0) throw new Error("Official Codex login did not complete successfully.");
       const finish = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/stage/finish", { stageId, writerToken, label });
-      if (finish.status === 0) return proxyUnreachable();
-      if (finish.status !== 200) return apiError(finish.json, "failed to encrypt the staged native login");
+      if (finish.status === 0) return proxyUnreachable(finish.transportError);
+      if (finish.status !== 200) return apiError(finish.json, "failed to encrypt the staged native login", finish.status);
       finished = true;
       console.log(`Added encrypted native profile '${label}' for ${effectiveCodexHome(finish.json)}.`);
       return 0;
@@ -283,8 +283,8 @@ export async function cmdNativeMainAccount(args: string[], deps: AccountDeps): P
       return reject(args);
     }
     const result = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/switch", { target, confirmedStopped: true });
-    if (result.status === 0) return proxyUnreachable();
-    if (result.status !== 200) return apiError(result.json, "failed to switch the native login");
+    if (result.status === 0) return proxyUnreachable(result.transportError);
+    if (result.status !== 200) return apiError(result.json, "failed to switch the native login", result.status);
     if (wantsJson) console.log(JSON.stringify(result.json, null, 2));
     else {
       const profile = result.json.activeProfile as PublicProfile | undefined;
@@ -301,8 +301,8 @@ export async function cmdNativeMainAccount(args: string[], deps: AccountDeps): P
     const result = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/recover", rollback
       ? { rollback: true, confirmedStopped: true }
       : { rollback: false });
-    if (result.status === 0) return proxyUnreachable();
-    if (result.status !== 200) return apiError(result.json, "failed to recover the native-profile transaction");
+    if (result.status === 0) return proxyUnreachable(result.transportError);
+    if (result.status !== 200) return apiError(result.json, "failed to recover the native-profile transaction", result.status);
     if (wantsJson) console.log(JSON.stringify(result.json, null, 2));
     else {
       const home = effectiveCodexHome(result.json);

package/src/cli/account.ts

@@ -2,7 +2,20 @@
 import { loadConfig } from "../config";
 import { providerCodexAccountMode } from "../providers/registry";
 import type { OcxConfig } from "../types";
-import { cmdAddKey, cmdAlias, cmdAutoSwitch, cmdClearCooldown, cmdImport, cmdPriority, cmdRefresh, cmdRemove } from "./account-extended";
+import {
+  cmdAddKey,
+  cmdAlias,
+  cmdAutoSwitch,
+  cmdClearCooldown,
+  cmdImport,
+  cmdPause,
+  cmdPauseExhausted,
+  cmdPriority,
+  cmdRefresh,
+  cmdRemove,
+  cmdSticky,
+  cmdStrategy,
+} from "./account-extended";
 import { apiError, apiJson, classifyAccount, fetchRows, proxyUnreachable, resolveBaseUrl, type AccountDeps, type AccountRow, type AccountType, type ApiResult }
   from "./account-api";
 
@@ -16,13 +29,18 @@ const MAIN_CODEX_ID = "__main__";
 const REPLACEMENT_STYLE_OAUTH = new Set(["kiro"]);
 
 const ACCOUNT_USAGE = `Usage:
-  ocx account list [provider] [--json] [--all]
+  ocx account list [provider] [--json] [--all] [--quota [--refresh]]
   ocx account current <provider> [--json]
   ocx account use <provider> <account-or-key-id|main> [--json]
   ocx account refresh <provider> [--json]
   ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
   ocx account alias <provider> <account-or-key-id> <display-name|-> [--json]
   ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
+  ocx account pause <provider> <account-id|main> [--json]
+  ocx account resume <provider> <account-id|main> [--json]
+  ocx account pause-exhausted <provider> [--json]
+  ocx account strategy <provider> [<quota|round-robin|fill-first>] [--json]
+  ocx account sticky <provider> [<1-100>] [--json]
   ocx account remove <provider> <account-or-key-id|main> --yes [--json]
   ocx account clear-cooldown <provider> <account-id|main> [--json]
   ocx account add-key <provider> [--label <label>] [--json]
@@ -64,6 +82,10 @@ function displayId(id: string): string {
 
 function statusText(row: AccountRow): string {
   const parts: string[] = [];
+  // `paused` leads, and does NOT replace `selected`. A paused-but-selected account is the
+  // state an operator most needs named -- requests route to it while the pool believes it is
+  // held out -- so printing only one of the two would hide exactly the confusing case (#2703).
+  if (row.paused) parts.push("paused");
   if (row.active) parts.push(row.type === "codex" ? "selected" : "active");
   if (row.needsReauth) parts.push("needs-reauth");
   return parts.join(" ");
@@ -75,11 +97,29 @@ function priorityText(row: AccountRow): string {
   return row.priority > 0 ? `+${row.priority}` : String(row.priority);
 }
 
-export function formatAccountTable(rows: AccountRow[]): string {
+/**
+ * Compact per-account quota for the opt-in QUOTA column: the two windows an operator actually
+ * decides on before a long session. The full breakdown stays in `--json`.
+ */
+function quotaText(row: AccountRow): string {
+  if ((row as { quotaUnavailable?: boolean }).quotaUnavailable) return "unavailable";
+  const quota = row.quota;
+  if (!quota) return "-";
+  const parts: string[] = [];
+  // Two spellings reach this DTO: the per-account provider probe reports `fiveHourPercent`,
+  // while the Codex pool reports the same idea as `shortPercent`.
+  const short = quota.fiveHourPercent ?? quota.shortPercent;
+  if (typeof short === "number") parts.push(`5h ${short}%`);
+  if (typeof quota.weeklyPercent === "number") parts.push(`wk ${quota.weeklyPercent}%`);
+  return parts.length > 0 ? parts.join(" ") : "-";
+}
+
+export function formatAccountTable(rows: AccountRow[], withQuota = false): string {
   const header = ["PROVIDER", "TYPE", "ID", "PLAN/LABEL", "PRIORITY", "STATUS"];
+  if (withQuota) header.push("QUOTA");
   const data = rows.map(r => {
     const keyLabel = r.masked && r.label !== r.masked ? `${r.masked} (${r.label})` : r.masked;
-    return [
+    const cols = [
       r.provider,
       r.type,
       displayId(r.id),
@@ -87,6 +127,8 @@ export function formatAccountTable(rows: AccountRow[]): string {
       priorityText(r),
       statusText(r),
     ];
+    if (withQuota) cols.push(quotaText(r));
+    return cols;
   });
   const widths = header.map((h, i) => Math.max(h.length, ...data.map(d => d[i]!.length)));
   const line = (cols: string[]) => cols.map((c, i) => c.padEnd(widths[i]!)).join("  ").trimEnd();
@@ -96,6 +138,10 @@ export function formatAccountTable(rows: AccountRow[]): string {
 async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
   const wantsJson = consumeFlag(rest, "--json");
   const showAll = consumeFlag(rest, "--all");
+  // Opt-in: the server probes the upstream once per stored credential, so the default listing
+  // stays a cheap local read (#2566). --refresh bypasses the server-side TTL.
+  const wantsQuota = consumeFlag(rest, "--quota");
+  const refreshQuota = consumeFlag(rest, "--refresh");
   const name = rest.shift();
   const leftover = leftoverArgsError(rest);
   if (leftover) {
@@ -126,8 +172,8 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
     };
     push("openai", "codex");
     const providersRes = await apiJson(deps, baseUrl, "GET", "/api/oauth/providers");
-    if (providersRes.status === 0) return proxyUnreachable();
-    if (providersRes.status !== 200) return apiError(providersRes.json, "failed to list OAuth providers");
+    if (providersRes.status === 0) return proxyUnreachable(providersRes.transportError);
+    if (providersRes.status !== 200) return apiError(providersRes.json, "failed to list OAuth providers", providersRes.status);
     if (Array.isArray(providersRes.json.providers)) {
       for (const p of providersRes.json.providers) {
         if (typeof p === "string") push(p, "live-oauth-list");
@@ -139,10 +185,11 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
   const rows: AccountRow[] = [];
   const notes: string[] = [];
   for (const t of targets) {
-    const r = await fetchRows(deps, baseUrl, t.name, t.type);
-    if (r.networkDown) return proxyUnreachable();
+    const r = await fetchRows(deps, baseUrl, t.name, t.type, wantsQuota ? { refresh: refreshQuota } : undefined);
+    if (r.networkDown) return proxyUnreachable(r.transportError);
     if (r.errorJson) {
-      if (name) return apiError(r.errorJson, `failed to list ${t.name}`);
+      if (name) return apiError(r.errorJson, `failed to list ${t.name}`, r.status);
+
       const errorText = typeof r.errorJson.error === "string" ? r.errorJson.error : "";
       const skipUnknownKey = t.type === "api-key"
         && r.status === 404
@@ -152,7 +199,7 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
         && r.status === 400
         && errorText.includes("unknown oauth provider");
       if (skipUnknownKey || skipConfigOAuth) continue;
-      return apiError(r.errorJson, `failed to list ${t.name}`);
+      return apiError(r.errorJson, `failed to list ${t.name}`, r.status);
     }
     if (r.rows.length === 0) {
       if (showAll) notes.push(`${t.name}: no stored accounts or keys`);
@@ -174,7 +221,7 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
     console.log(JSON.stringify({ accounts: rows, notes }, null, 2));
     return 0;
   }
-  if (rows.length > 0) console.log(formatAccountTable(rows));
+  if (rows.length > 0) console.log(formatAccountTable(rows, wantsQuota));
   for (const n of notes) console.log(n);
   if (rows.length === 0 && notes.length === 0) console.log("No stored accounts or keys.");
   return 0;
@@ -198,8 +245,8 @@ async function cmdCurrent(rest: string[], deps: AccountDeps): Promise<number> {
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
   const r = await fetchRows(deps, baseUrl, name, c.type);
-  if (r.networkDown) return proxyUnreachable();
-  if (r.errorJson) return apiError(r.errorJson, `failed to read ${name}`);
+  if (r.networkDown) return proxyUnreachable(r.transportError);
+  if (r.errorJson) return apiError(r.errorJson, `failed to read ${name}`, r.status);
 
   const activeRow = r.rows.find(row => row.active) ?? null;
   if (wantsJson) {
@@ -253,8 +300,8 @@ async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
     activeId = id;
     res = await apiJson(deps, baseUrl, "PUT", "/api/providers/keys/active", { name, id });
   }
-  if (res.status === 0) return proxyUnreachable();
-  if (res.status !== 200) return apiError(res.json, `failed to switch ${name}`);
+  if (res.status === 0) return proxyUnreachable(res.transportError);
+  if (res.status !== 200) return apiError(res.json, `failed to switch ${name}`, res.status);
 
   if (wantsJson) console.log(JSON.stringify({ ok: true, provider: name, type: c.type, activeId }, null, 2));
   else console.log(`${name}: active ${c.type === "api-key" ? "key" : "account"} is now ${displayId(activeId)}`);
@@ -278,6 +325,13 @@ export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promis
     if (sub === "auto-switch") return await cmdAutoSwitch(rest, deps);
     if (sub === "alias" || sub === "rename") return await cmdAlias(rest, deps);
     if (sub === "priority") return await cmdPriority(rest, deps);
+    // #2702: the server routes existed and only the CLI caller was missing, so these were
+    // dashboard-only capabilities.
+    if (sub === "pause") return await cmdPause(rest, deps, true);
+    if (sub === "resume") return await cmdPause(rest, deps, false);
+    if (sub === "pause-exhausted") return await cmdPauseExhausted(rest, deps);
+    if (sub === "strategy") return await cmdStrategy(rest, deps);
+    if (sub === "sticky") return await cmdSticky(rest, deps);
     if (sub === "remove") return await cmdRemove(rest, deps);
     if (sub === "clear-cooldown") return await cmdClearCooldown(rest, deps);
     if (sub === "add-key") return await cmdAddKey(rest, deps);

package/src/cli/agent.ts

@@ -29,7 +29,8 @@ const USAGE = `Usage:
   ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
   ocx agent sidecar <status|web|vision> [--list] [--model <id|->]
       [--backend web:<openai|anthropic|xai|gemini|exa|-> vision:<openai|anthropic|routed|->]
-      [--reasoning <level>] [--max-descriptions <n>] [--json]`;
+      [--reasoning <level>] [--max-descriptions <n>] [--json]
+  ocx agent request-user-input [on|off] [--json]`;
 
 function clearable(value: string | undefined): string | null | undefined {
   return value === "-" ? null : value;
@@ -221,6 +222,12 @@ export async function handleAgentCommand(argv: string[], deps: RuntimeApiDeps =
     else if (sub === "subagents" || sub === "roster") await subagents(rest, deps);
     else if (sub === "fallback") await fallback(rest, deps);
     else if (sub === "sidecar") await sidecar(rest, deps);
+    // Lives here rather than as a top-level verb because it is an agent-behavior feature flag:
+    // it controls whether default mode may ask the operator a question mid-task.
+    else if (sub === "request-user-input") {
+      const { requestUserInputAction } = await import("./inspect");
+      await requestUserInputAction(rest, deps);
+    }
     else throw new CliUsageError(`unknown agent command ${sub}`, USAGE);
   });
 }

package/src/cli/alias.ts

@@ -0,0 +1,66 @@
+import { CliUsageError, printData, rejectArgs, runtimeRequest, takeFlag, takeOption, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx alias list [--json]
+  ocx alias set <provider> <alias>
+  ocx alias set <provider>/<native-model-id> <alias>
+  ocx alias rm <provider>[/<native-model-id>]
+  ocx alias defaults <on|off> [--provider <name>]`;
+
+function selector(value: string): { provider: string; model?: string } {
+  const slash = value.indexOf("/");
+  return slash < 0 ? { provider: value } : { provider: value.slice(0, slash), model: value.slice(slash + 1) };
+}
+
+export async function handleAliasCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  const args = [...argv];
+  const action = (args.shift() ?? "list").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "list") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest<Record<string, unknown>>("/api/aliases", {}, deps);
+    const lines: string[] = [];
+    for (const [target, alias] of Object.entries((result.providers ?? {}) as Record<string, string>)) lines.push(`provider  ${target}  ${alias}  user`);
+    for (const [provider, rows] of Object.entries((result.models ?? {}) as Record<string, Record<string, { alias: string; source: string }>>)) {
+      for (const [model, value] of Object.entries(rows)) lines.push(`model     ${provider}/${model}  ${value.alias}  ${value.source}`);
+    }
+    printData(result, wantsJson, lines.length ? lines : ["No aliases configured."]);
+    return 0;
+  }
+  if (action === "defaults") {
+    const state = args.shift()?.toLowerCase();
+    const provider = takeOption(args, "--provider");
+    rejectArgs(args, USAGE);
+    if (state !== "on" && state !== "off") throw new CliUsageError("defaults requires on or off", USAGE);
+    const result = await runtimeRequest("/api/default-aliases", { method: "PUT", body: JSON.stringify({ enabled: state === "on", ...(provider ? { provider } : {}) }) }, deps);
+    printData(result, wantsJson, [`Default aliases ${state}${provider ? ` for ${provider}` : " globally"}.`]);
+    return 0;
+  }
+  const target = args.shift()?.trim();
+  if (!target) throw new CliUsageError("alias target is required", USAGE);
+  const parsed = selector(target);
+  if (!parsed.provider || parsed.model === "") throw new CliUsageError("target must be provider or provider/native-model-id", USAGE);
+  if (action === "set") {
+    const alias = args.shift()?.trim();
+    rejectArgs(args, USAGE);
+    if (!alias) throw new CliUsageError("alias value is required", USAGE);
+    const path = parsed.model === undefined
+      ? `/api/providers/${encodeURIComponent(parsed.provider)}/alias`
+      : `/api/providers/${encodeURIComponent(parsed.provider)}/model-aliases`;
+    const body = parsed.model === undefined ? { alias } : { set: { [parsed.model]: alias } };
+    const result = await runtimeRequest(path, { method: "PUT", body: JSON.stringify(body) }, deps);
+    printData(result, wantsJson, [`${target} → ${alias}`]);
+    return 0;
+  }
+  if (action === "rm") {
+    rejectArgs(args, USAGE);
+    const path = parsed.model === undefined
+      ? `/api/providers/${encodeURIComponent(parsed.provider)}/alias`
+      : `/api/providers/${encodeURIComponent(parsed.provider)}/model-aliases`;
+    const body = parsed.model === undefined ? { alias: null } : { remove: [parsed.model] };
+    const result = await runtimeRequest(path, { method: "PUT", body: JSON.stringify(body) }, deps);
+    printData(result, wantsJson, [`Removed alias for ${target}.`]);
+    return 0;
+  }
+  throw new CliUsageError(`unknown alias action '${action}'`, USAGE);
+}

package/src/cli/capabilities-command.ts

@@ -0,0 +1,94 @@
+/**
+ * `ocx capabilities` -- the surface index an agent reads first.
+ *
+ * The point of this verb is that driving `ocx` programmatically should not require
+ * parsing help text. `--json` emits the capability table with the management routes each
+ * capability drives; `--route` answers the inverse question.
+ */
+import {
+  CAPABILITIES,
+  HEAD_CAPABILITIES,
+  capabilitiesForRoute,
+  capabilityInvocation,
+  type Capability,
+} from "./capabilities";
+import { takeFlag } from "./runtime-api";
+
+function takeValueFlag(args: string[], flag: string): string | undefined {
+  // Order-independent by construction: scan for the flag anywhere in argv rather than
+  // reading a fixed position. Positional flag handling is exactly why
+  // `ocx restore back --json` ignored its flag.
+  const idx = args.indexOf(flag);
+  if (idx === -1) return undefined;
+  const value = args[idx + 1];
+  args.splice(idx, value === undefined || value.startsWith("-") ? 1 : 2);
+  if (value === undefined || value.startsWith("-")) return "";
+  return value;
+}
+
+function renderHuman(caps: readonly Capability[], includeHead: boolean): void {
+  for (const cap of caps) {
+    const marker = cap.mutates ? "!" : " ";
+    console.log(`${marker} ${capabilityInvocation(cap)}`);
+    console.log(`    ${cap.summary}`);
+    if (cap.routes.length > 0) {
+      console.log(`    routes: ${cap.routes.map(r => `${r.method} ${r.path}`).join(", ")}`);
+    }
+    if (cap.flags.length > 0) {
+      console.log(`    flags:  ${cap.flags.map(f => f.name).join(" ")}`);
+    }
+  }
+  if (!includeHead) return;
+  for (const head of HEAD_CAPABILITIES) {
+    console.log(`  ocx ${head.invocations[0]}`);
+    console.log(`    ${head.summary}`);
+  }
+}
+
+export async function runCapabilities(argv: string[]): Promise<number> {
+  const args = [...argv];
+  const json = takeFlag(args, "--json");
+  const mutatingOnly = takeFlag(args, "--mutating-only");
+  const route = takeValueFlag(args, "--route");
+
+  if (route !== undefined && route.length === 0) {
+    console.error("Usage: ocx capabilities --route <path>");
+    return 64;
+  }
+
+  let selected: readonly Capability[] = route === undefined ? CAPABILITIES : capabilitiesForRoute(route);
+  if (mutatingOnly) selected = selected.filter(cap => cap.mutates);
+
+  if (route !== undefined && selected.length === 0) {
+    // An unmatched route is a real answer, not an error: the route may be exempt or may
+    // not exist. Say which, rather than exiting 0 with silence.
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, route, capabilities: [] }, null, 2));
+    } else {
+      console.error(`No CLI capability drives ${route}.`);
+    }
+    return 4;
+  }
+
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      ...(route === undefined ? {} : { route }),
+      capabilities: selected.map(cap => ({
+        command: cap.command,
+        invocation: capabilityInvocation(cap),
+        summary: cap.summary,
+        routes: cap.routes,
+        flags: cap.flags,
+        mutates: cap.mutates,
+        json: cap.json,
+        ...(cap.details ? { details: cap.details } : {}),
+      })),
+      ...(route === undefined && !mutatingOnly ? { headCapabilities: HEAD_CAPABILITIES } : {}),
+    }, null, 2));
+    return 0;
+  }
+
+  renderHuman(selected, route === undefined && !mutatingOnly);
+  return 0;
+}