@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/capabilities-accounts.ts

@@ -0,0 +1,195 @@
+import type { Capability } from "./capability-types";
+
+/** Account pool operations and physical native-login profiles have separate owners. */
+export const ACCOUNT_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["logout"],
+    summary: "Remove the active stored OAuth credential for a provider locally.",
+    usage: "ocx logout <provider> [--live] [--json]",
+    routes: [{"method":"POST","path":"/api/oauth/logout"}],
+    flags: [{"name":"--live","value":"boolean","summary":"Use the selected public-OAuth runtime logout; no local credential fallback."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
+    mutates: true,
+    json: "envelope",
+    details: ["No-live retains atomic local removed/not-found results and exits0/4. Live sends one provider-level OAuth logout and reports only its success receipt, not removed:true or global sign-out.","Live does not sign out Codex/native-main. Target/argument failure never causes local credential removal."],
+  },
+  {
+    command: ["account", "current"], summary: "Read the active account or API key for a provider.",
+    usage: "ocx account current <provider> [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "GET", path: "/api/codex-auth/active" }, { method: "GET", path: "/api/oauth/accounts" }, { method: "GET", path: "/api/providers/keys" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit provider, type, activeId and the projected account." }], mutates: false, json: "envelope",
+    details: ["Uses the live route for the configured account family; this does not report the physical native-main profile."],
+  },
+  {
+    command: ["account", "use"], summary: "Select a provider's pool account or API key.",
+    usage: "ocx account use <provider> <account-or-key-id|alias|main|auto> [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "GET", path: "/api/codex-auth/active" }, { method: "PUT", path: "/api/codex-auth/active" }, { method: "PUT", path: "/api/oauth/accounts/active" }, { method: "PUT", path: "/api/providers/keys/active" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the selection receipt, including pin-drain information when present." }], mutates: true, json: "envelope",
+    details: ["Codex resolves IDs and aliases before reserved words; an account actually named auto wins. account clear openai always clears. OAuth and API-key selection pass the ID directly. This does not switch the physical Codex App login."],
+  },
+  {
+    command: ["account", "clear"], summary: "Clear a Codex pool's manual account selection pin.",
+    usage: "ocx account clear <provider> [--json]",
+    routes: [{ method: "PUT", path: "/api/codex-auth/active" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the clear receipt." }], mutates: true, json: "envelope",
+    details: ["Only Codex account pools are supported; other families are refused. Sends accountId:null without interpreting auto as an account ID."],
+  },
+  {
+    command: ["account", "alias"], summary: "Set or clear an account's display alias.",
+    usage: "ocx account alias <provider> <account-or-key-id|alias> <display-name|-> [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "PUT", path: "/api/codex-auth/accounts/alias" }, { method: "PUT", path: "/api/oauth/accounts/alias" }, { method: "PUT", path: "/api/providers/keys/alias" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the applied alias, or null after clearing." }], mutates: true, json: "envelope",
+    details: ["- clears with an empty string. Codex resolves existing aliases; other families take an ID. Native main cannot be renamed; aliases are at most 80 printable characters. rename is an existing command alias."],
+  },
+  {
+    command: ["account", "priority"], summary: "Read or change Codex account selection order.",
+    usage: "ocx account priority <provider> <account-id|alias|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "GET", path: "/api/codex-auth/active" }, { method: "PUT", path: "/api/codex-auth/accounts/priority" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the normalized priority and named preset." }], mutates: true, json: "envelope",
+    details: ["Only Codex pools support selection order. Omitting the value reads; reset sends null. Every write releases any manual pin, even if the value is unchanged; running threads retain their account until drained."],
+  },
+  {
+    command: ["account", "clear-cooldown"], summary: "Lift an operator-clearable Codex or Anthropic account cooldown.",
+    usage: "ocx account clear-cooldown <provider> <account-id|alias|main> [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "GET", path: "/api/oauth/accounts" }, { method: "POST", path: "/api/codex-auth/accounts/clear-cooldown" }, { method: "POST", path: "/api/oauth/accounts/clear-cooldown" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit whether a cooldown was actually cleared." }], mutates: true, json: "envelope",
+    details: ["Other provider families are refused. Resolves Codex or Anthropic account aliases before writing."],
+  },
+  {
+    command: ["account", "remove"], summary: "Remove a pool account or provider API key with explicit confirmation.",
+    usage: "ocx account remove <provider> <account-or-key-id|alias> --yes [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "GET", path: "/api/codex-auth/active" }, { method: "GET", path: "/api/oauth/accounts" }, { method: "GET", path: "/api/providers/keys" }, { method: "DELETE", path: "/api/codex-auth/accounts" }, { method: "DELETE", path: "/api/oauth/accounts" }, { method: "DELETE", path: "/api/providers/keys" }],
+    flags: [{ name: "--yes", value: "boolean", required: true, summary: "Confirm account/key deletion." }, { name: "--json", value: "boolean", summary: "Emit removal and promoted-account information." }], mutates: true, json: "envelope",
+    details: ["Native main removal is refused. Reads the account family before and after deletion; a failed post-delete read means deletion may have succeeded. Only Codex resolves aliases here."],
+  },
+  {
+    command: ["account", "add-key"], summary: "Import an existing provider API key from a human-controlled stdin source.",
+    usage: "ocx account add-key <provider> [--label <label>] [--json]",
+    routes: [{ method: "POST", path: "/api/providers/keys" }],
+    flags: [{ name: "--label", value: "string", summary: "Optional label for the imported key." }, { name: "--json", value: "boolean", summary: "Emit a redacted receipt containing the key ID, never the key." }], mutates: true, json: "envelope",
+    details: ["API-key providers only. Requires non-TTY stdin and reads one secret line; never put plaintext keys in command arguments or agent transcripts. This imports an upstream credential, not an OpenCodex access-key creation workflow."],
+  },
+  {
+    command: ["account", "import"], summary: "Import Google Antigravity accounts from a bounded Cockpit Tools document.",
+    usage: "ocx account import google-antigravity --format cockpit-tools (--file <path>|--stdin) [--json]",
+    routes: [{ method: "POST", path: "/api/oauth/accounts/import" }],
+    flags: [{ name: "--format", value: "string", required: true, summary: "Only cockpit-tools is supported." }, { name: "--file", value: "string", summary: "Bounded source document; exclusive with --stdin." }, { name: "--stdin", value: "boolean", summary: "Read the document from non-TTY stdin." }, { name: "--json", value: "boolean", summary: "Emit sanitized per-record import outcomes." }], mutates: true, json: "envelope",
+    details: ["Human-controlled credential handoff: choose exactly one source. Unsupported providers/formats are refused before source I/O. Partial failures or unsupported records return nonzero; do not echo the document."],
+  },
+  {
+    command: ["account","reauth"],
+    summary: "Reauthenticate a provider account through the existing login flow.",
+    usage: "ocx account reauth <provider> [--id <account-id>] [--device] [--code -] [--no-wait] [--open-browser <on|off>] [--json]",
+    routes: [{"method":"POST","path":"/api/codex-auth/login"},{"method":"GET","path":"/api/codex-auth/login-status"},{"method":"POST","path":"/api/codex-auth/login/code"},{"method":"POST","path":"/api/oauth/login"},{"method":"GET","path":"/api/oauth/status"},{"method":"POST","path":"/api/oauth/login/code"}],
+    flags: [{"name":"--id","value":"string","summary":"Account identity to reauthenticate."},{"name":"--device","value":"boolean","summary":"Codex device login; accepted for already-device-native kimi, nous and github-copilot."},{"name":"--code","value":"string","summary":"Use - to read the short-lived authorization code from stdin."},{"name":"--no-wait","value":"boolean","summary":"Return after starting the flow."},{"name":"--json","value":"boolean","summary":"Emit login instructions or completion state."},{"name":"--open-browser","value":"string","summary":"on or off for browser-capable login; rejected for explicit/native device flows."}],
+    mutates: true,
+    json: "payload",
+    details: ["Alias of account login with --reauth. openai, codex and chatgpt address the pool; native main uses account main reauth. Human completes authorization; keep returned login material out of transcripts. Kiro --method cannot be combined with reauth.","Explicit add-account is incompatible with reauth. Browser preference is accepted only by browser-capable flows; device verification remains manual."],
+  },
+  {
+    command: ["account", "code"], summary: "Submit a login redirect or authorization code from stdin.",
+    usage: "ocx account code <provider> [--flow <flow-id>] [--code -] [--json]",
+    routes: [{ method: "POST", path: "/api/codex-auth/login/code" }, { method: "POST", path: "/api/oauth/login/code" }],
+    flags: [{ name: "--flow", value: "string", summary: "Required for openai, codex or chatgpt pool flows." }, { name: "--code", value: "string", summary: "Use - for stdin; omission also reads stdin." }, { name: "--json", value: "boolean", summary: "Emit submission receipt." }], mutates: true, json: "payload",
+    details: ["A short-lived credential is a human handoff. Legacy positional/argv code input exists but warns about exposure; use stdin and never echo it."],
+  },
+  {
+    command: ["account", "cancel"], summary: "Cancel a pending account login flow.",
+    usage: "ocx account cancel <provider> [--flow <flow-id>] [--json]",
+    routes: [{ method: "POST", path: "/api/codex-auth/login/cancel" }, { method: "POST", path: "/api/oauth/login/cancel" }],
+    flags: [{ name: "--flow", value: "string", summary: "Required for Codex; selects a native Kiro flow when supplied." }, { name: "--json", value: "boolean", summary: "Emit cancellation receipt." }], mutates: true, json: "payload",
+    details: ["Codex cancellation sends flowId. Other providers send provider; Kiro additionally forwards a supplied flowId."],
+  },
+  {
+    command: ["account", "reset-credits"], summary: "Read Codex reset-credit state, or explicitly consume one with operator authorization.",
+    usage: "ocx account reset-credits <account-id|main> [--consume --yes [--operation-id <uuid>]] [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/reset-credits" }, { method: "POST", path: "/api/codex-auth/reset-credits/consume" }],
+    flags: [{ name: "--consume", value: "boolean", summary: "Spend a reset credit; requires operator intent and --yes." }, { name: "--yes", value: "boolean", summary: "Confirm consumption." }, { name: "--operation-id", value: "string", summary: "UUIDv4 retry identity; only valid with --consume." }, { name: "--json", value: "boolean", summary: "Emit reset-credit state or receipt." }], mutates: true, json: "payload",
+    details: ["A bare invocation reads only. main maps to __main__; reads never consume a credit. This does not control credits-after-limit settings."],
+  },
+  {
+    command: ["account", "main", "doctor"], summary: "Diagnose native Codex login profile storage and recovery state.",
+    usage: "ocx account main doctor [--json]", routes: [{ method: "GET", path: "/api/native-main-profiles/doctor" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit diagnosis; this command also prints JSON by default." }], mutates: false, json: "payload",
+    details: ["Reports the physical login in the server's effective CODEX_HOME, independently of pool account selection."],
+  },
+  {
+    command: ["account", "main", "list"], summary: "List encrypted native Codex login profiles.",
+    usage: "ocx account main list [--json]", routes: [{ method: "GET", path: "/api/native-main-profiles" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit public profile metadata, not stored credentials." }], mutates: false, json: "payload",
+  },
+  {
+    command: ["account", "main", "register"], summary: "Register the current physical Codex login as an encrypted profile.",
+    usage: "ocx account main register <label> [--json]", routes: [{ method: "POST", path: "/api/native-main-profiles/register" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the registration receipt." }], mutates: true, json: "payload",
+    details: ["Captures the current login in the effective CODEX_HOME; it does not start a new login or select a pool account."],
+  },
+  {
+    command: ["account", "main", "add"], summary: "Add a native login profile through a human-operated official Codex login.",
+    usage: "ocx account main add <label>",
+    routes: [{ method: "POST", path: "/api/native-main-profiles/stage" }, { method: "POST", path: "/api/native-main-profiles/stage/heartbeat" }, { method: "POST", path: "/api/native-main-profiles/stage/finish" }, { method: "POST", path: "/api/native-main-profiles/stage/cancel" }],
+    flags: [], mutates: true, json: "none",
+    details: ["Human handoff: runs official Codex login locally in the server-provided restricted staging home, maintains a writer lease and encrypts the result. No --json, --yes or --rollback mode. Cleanup failure requires account main doctor; never expose writer tokens or credential files."],
+  },
+  {
+    command: ["account", "main", "reauth", "status"], summary: "Read an existing same-identity native-main reauthentication flow.",
+    usage: "ocx account main reauth status --flow <id> [--json]", routes: [{ method: "GET", path: "/api/codex-auth/main/reauth-device" }],
+    flags: [{ name: "--flow", value: "string", required: true, summary: "Flow ID returned by the human-started reauthentication." }, { name: "--json", value: "boolean", summary: "Emit flow state; pending state may include human login material." }], mutates: false, json: "payload",
+  },
+  {
+    command: ["account", "main", "reauth", "cancel"], summary: "Cancel a native-main reauthentication flow.",
+    usage: "ocx account main reauth cancel --flow <id> [--json]", routes: [{ method: "DELETE", path: "/api/codex-auth/main/reauth-device" }],
+    flags: [{ name: "--flow", value: "string", required: true, summary: "Flow ID to cancel." }, { name: "--json", value: "boolean", summary: "Emit cancellation state." }], mutates: true, json: "payload",
+  },
+  {
+    command: ["account", "main", "switch"], summary: "Switch the physical Codex App/CLI login to a registered profile.",
+    usage: "ocx account main switch <profile-id-or-label> --yes [--json]", routes: [{ method: "POST", path: "/api/native-main-profiles/switch" }],
+    flags: [{ name: "--yes", value: "boolean", required: true, summary: "Confirm the operator has closed Codex App/CLI." }, { name: "--json", value: "boolean", summary: "Emit the native-login switch receipt." }], mutates: true, json: "payload",
+    details: ["Changes the effective CODEX_HOME login, independently of account use openai. The operator must stop Codex first and restart it afterwards; no automatic restart is performed."],
+  },
+  {
+    command: ["account", "main", "recover"], summary: "Recover an interrupted native-login profile transaction.",
+    usage: "ocx account main recover [--rollback --yes] [--json]", routes: [{ method: "POST", path: "/api/native-main-profiles/recover" }],
+    flags: [{ name: "--rollback", value: "boolean", summary: "Restore the previous login; requires --yes." }, { name: "--yes", value: "boolean", summary: "Confirm Codex App/CLI is stopped for rollback." }, { name: "--json", value: "boolean", summary: "Emit recovery outcome." }], mutates: true, json: "payload",
+    details: ["Even without --rollback this calls recovery with rollback:false; it is not the doctor read. Rollback writes the native login only after explicit confirmation."],
+  },
+  {
+    command: ["account","pool"],
+    usage: "ocx account pool <provider> [--enabled <on|off>] [--threshold <0-100>] [--strategy <name>] [--sticky <1-100>] [--quota-window <five-hour|weekly|max-utilization>] [--json]",
+    summary: "Read or edit the selected runtime's supported pool policy fields.",
+    routes: [{"method":"GET","path":"/api/pool/settings"},{"method":"PUT","path":"/api/pool/settings"}],
+    flags: [{"name":"--enabled","value":"string","summary":"Stored pool preference; unsupported for Codex. Not equivalent to threshold0."},{"name":"--threshold","value":"number","summary":"Auto-switch threshold0–100."},{"name":"--strategy","value":"string","summary":"Use a strategy supported by this provider kind; reset-first is Codex, least-loaded is Kiro."},{"name":"--sticky","value":"number","summary":"Sticky limit1–100."},{"name":"--quota-window","value":"string","summary":"Anthropic only: five-hour, weekly or max-utilization."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Reads the target supported-field list before a narrow PUT. Null/unsupported, stored/effective and generic inert policy stay distinct; disabling does not promise that reactive429 rotation stops.","No local classification/defaults are round-tripped into the live target; supported-field reads are not CAS."],
+  },
+  {
+    command: ["account","credits"],
+    usage: "ocx account credits openai <id|alias|main> <on|off> [--json]; ocx account credits openai --all <on|off> [--json]",
+    summary: "Explicitly opt one or all current Codex accounts into paid credits after quota limits.",
+    routes: [{"method":"GET","path":"/api/codex-auth/accounts"},{"method":"PUT","path":"/api/codex-auth/accounts/credits"}],
+    flags: [{"name":"--all","value":"boolean","summary":"Exclusive with one account selector. On covers current selectable accounts plus main; off clears the opt-in set."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Requires explicit operator on/off intent. Showing credit balances does not grant paid-use permission; no login/quota failure auto-enables it.","One/all shapes are exclusive. Strict selected-runtime account resolution refuses ambiguity/unavailable roster; the response owns the applied set. It never consumes a reset grant."],
+  },
+  {
+    command: ["account","quota-activation"],
+    usage: "ocx account quota-activation openai <id|alias|main> --window <fiveHour|weekly> <on|off> [--json]",
+    summary: "Enable or disable a Codex account window's automatic quota refresh policy.",
+    routes: [{"method":"GET","path":"/api/codex-auth/accounts"},{"method":"PUT","path":"/api/settings"}],
+    flags: [{"name":"--window","value":"string","summary":"fiveHour or weekly; these spellings differ from pool quota-window.","required":true},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Writes only the selected account/window mutation, preserving siblings. Enabling an unavailable window returns conflict; disabling remains allowed.","The server may schedule a quota refresh. This does not redeem a reset grant or opt into paid credits."],
+  },
+  {
+    command: ["account","anthropic-reset-grants"],
+    usage: "ocx account anthropic-reset-grants [account-id] [--json]",
+    summary: "Read Anthropic reset-grant eligibility and pending status without consuming a grant.",
+    routes: [{"method":"GET","path":"/api/anthropic/reset-grants"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Optional identity is the exact Anthropic account ID. Omission delegates active/fallback account choice to the server, not the Codex alias resolver.","This GET can refresh access/status information upstream. Empty grants, unavailable status, pending operation and unavailable journal remain distinct. Consume remains a GUI-session-only human handoff; no session acquisition or retry is performed."],
+  },
+];