@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/agent-settings.ts

@@ -0,0 +1,101 @@
+import { compactionRoutingSchema, memoryModelsSchema } from "../config/schema/leaf-validators";
+import { runCatalogAction } from "./catalog-command-result";
+import { readJsonInput, serializeManagementJson } from "./json-input";
+import { printSettingsResult } from "./settings-result";
+import {
+  CliUsageError, printData, runtimeBaseUrl, runtimeRequest, takeFlag,
+  takeOptionWithSyntax, type RuntimeApiDeps,
+} from "./runtime-api";
+
+type SettingCommand = "memory-models" | "compaction-routing";
+
+function usage(sub: SettingCommand): string {
+  const fields = sub === "memory-models"
+    ? "[--extract-model <model> [--extract-effort <effort>]] [--consolidation-model <model> [--consolidation-effort <effort>]]"
+    : "--model <model> [--effort <effort>] [--triggers <manual,auto>] [--sources <selector,...>]";
+  return `Usage: ocx agent ${sub} show|clear [--json]\n       ocx agent ${sub} set (--file <FILE|-> | ${fields}) [--json]`;
+}
+
+function scalarBlock(sub: SettingCommand, values: Record<string, string>): Record<string, unknown> {
+  if (sub === "memory-models") {
+    const block: Record<string, unknown> = {};
+    for (const phase of ["extract", "consolidation"]) {
+      const model = values[`--${phase}-model`], effort = values[`--${phase}-effort`];
+      if (effort !== undefined && model === undefined) {
+        throw new CliUsageError("A memory phase effort requires its model", usage(sub));
+      }
+      if (model !== undefined) block[phase] = { model, ...(effort === undefined ? {} : { reasoningEffort: effort }) };
+    }
+    if (!Object.keys(block).length) throw new CliUsageError("Set requires at least one memory phase model or an explicit file", usage(sub));
+    return block;
+  }
+  return {
+    ...(values["--model"] === undefined ? {} : { model: values["--model"] }),
+    ...(values["--effort"] === undefined ? {} : { reasoningEffort: values["--effort"] }),
+    // Deliberately preserve every CSV token: schema validation rejects blanks,
+    // duplicates and whitespace instead of changing the requested scope.
+    ...(values["--triggers"] === undefined ? {} : { triggers: values["--triggers"].split(",") }),
+    ...(values["--sources"] === undefined ? {} : { sourceModels: values["--sources"].split(",") }),
+  };
+}
+
+function normalizedBlock(sub: SettingCommand, value: unknown, input: boolean): Record<string, unknown> | null {
+  if (!input && value === null) return null;
+  const parsed = sub === "memory-models" ? memoryModelsSchema.safeParse(value) : compactionRoutingSchema.safeParse(value);
+  if (!parsed.success) {
+    if (input) throw new CliUsageError("Invalid model override block; check the supported fields and model/effort values", usage(sub));
+    throw new Error("Invalid settings response");
+  }
+  return parsed.data;
+}
+
+/** Task-only settings replacement; no local fallback, model probe or pipeline toggle. */
+export async function handleAgentSettingsCommand(
+  sub: SettingCommand, argv: string[], deps: RuntimeApiDeps = {},
+): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const action = args.shift();
+    if (action !== "show" && action !== "set" && action !== "clear") {
+      throw new CliUsageError("Expected show, set or clear", usage(sub));
+    }
+    const wantsJson = takeFlag(args, "--json");
+    const file = takeOptionWithSyntax(args, "--file")?.value;
+    const flags = sub === "memory-models"
+      ? ["--extract-model", "--extract-effort", "--consolidation-model", "--consolidation-effort"]
+      : ["--model", "--effort", "--triggers", "--sources"];
+    const values: Record<string, string> = {};
+    for (const flag of flags) {
+      const value = takeOptionWithSyntax(args, flag)?.value;
+      if (value !== undefined) values[flag] = value;
+    }
+    if (args.length) throw new CliUsageError("Unexpected or repeated settings argument", usage(sub));
+    const hasFields = Object.keys(values).length > 0;
+    if (action !== "set" && (file !== undefined || hasFields)) {
+      throw new CliUsageError("Only set accepts a file or model options", usage(sub));
+    }
+    if (file !== undefined && hasFields) throw new CliUsageError("--file cannot be combined with model options", usage(sub));
+    const key = sub === "memory-models" ? "memoryModels" : "compactionRouting";
+    const block = action === "set"
+      ? normalizedBlock(sub, file === undefined ? scalarBlock(sub, values) : await readJsonInput(file, deps), true)
+      : null;
+    const body = action === "show" ? undefined : serializeManagementJson({ [key]: block });
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    const response = await runtimeRequest("/api/settings", {
+      method: action === "show" ? "GET" : "PUT", redirect: "error", ...(body === undefined ? {} : { body }),
+    }, pinned);
+    if (!response || typeof response !== "object" || Array.isArray(response)) throw new Error("Invalid settings response");
+    const record = response as Record<string, unknown>;
+    if (action !== "show" && record.ok !== true) throw new Error("Settings acceptance was not reported");
+    const observed = normalizedBlock(sub, record[key], false);
+    const data = { [key]: observed };
+    const lines = [observed === null || Object.keys(observed).length === 0
+      ? `${sub}: no custom overrides; existing routing remains in use.`
+      : `${sub}: ${JSON.stringify(observed)}`];
+    if (action === "show") {
+      printData(data, wantsJson, lines);
+      return 0;
+    }
+    return printSettingsResult(data, record.catalogRefreshPending, wantsJson, lines);
+  });
+}

package/src/cli/agent.ts

@@ -24,7 +24,7 @@ interface WebSearchModelOption {
 const USAGE = `Usage:
   ocx agent [status] [--json]
   ocx agent injection <status|set> [--model <id|->] [--effort <level|->]
-      [--prompt <text|->] [--guidance <on|off>] [--json]
+      [--prompt <text|->] [--guidance <on|off>] [--sync-codex-defaults <on|off>] [--json]
   ocx agent injection suggest <work description> [--model <id>] [--apply] [--json]
   ocx agent effort <status|set> [--main <level|->] [--subagent <level|->] [--json]
   ocx agent subagents <status|set|clear> [model,model...] [--json]
@@ -33,7 +33,10 @@ const USAGE = `Usage:
   ocx agent roles [status|set <role> <model>|suggest [--model <id>] [--apply]] [--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>] [--enabled <on|off>] [--json]
+      [--reasoning <level>] [--max-descriptions <n> (vision)] [--enabled <on|off>]
+      [--stream-routed-output <on|off> (web)] [--timeout-ms <1-2147483647> (vision)] [--json]
+  ocx agent memory-models <show|set|clear> [options] [--json]
+  ocx agent compaction-routing <show|set|clear> [options] [--json]
   ocx agent request-user-input [on|off] [--json]`;
 
 function clearable(value: string | undefined): string | null | undefined {
@@ -257,6 +260,7 @@ async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const backend = takeOption(args, "--backend");
   const reasoning = takeOption(args, "--reasoning");
   const maxDescriptionsPerTurn = takeIntegerOption(args, "--max-descriptions", { min: 1 });
+  if (section === "web" && maxDescriptionsPerTurn !== undefined) throw new CliUsageError("--max-descriptions applies only to the vision sidecar", USAGE);
   const enabled = takeBooleanOption(args, "--enabled");
   rejectArgs(args, USAGE);
   const settings: Record<string, unknown> = {};
@@ -418,6 +422,19 @@ async function roles(argv: string[], deps: RuntimeApiDeps): Promise<void> {
 }
 
 export async function handleAgentCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  const has = (flag: string) => argv.some(arg => arg === flag || arg.startsWith(`${flag}=`));
+  if ((argv[0] === "injection" || argv[0] === "guidance") && has("--sync-codex-defaults")) {
+    const { handleInjectionDefaults } = await import("./agent-runtime-settings");
+    return handleInjectionDefaults(argv.slice(1), deps);
+  }
+  if (argv[0] === "sidecar" && (has("--stream-routed-output") || has("--timeout-ms"))) {
+    const { handleSidecarRuntimeSettings } = await import("./agent-runtime-settings");
+    return handleSidecarRuntimeSettings(argv.slice(1), deps);
+  }
+  if (argv[0] === "memory-models" || argv[0] === "compaction-routing") {
+    const { handleAgentSettingsCommand } = await import("./agent-settings");
+    return handleAgentSettingsCommand(argv[0], argv.slice(1), deps);
+  }
   return runCliAction(async () => {
     const [sub = "status", ...rest] = argv;
     if (sub === "status") await status(rest, deps);

package/src/cli/alias.ts

@@ -1,4 +1,4 @@
-import { CliUsageError, printData, rejectArgs, runtimeRequest, takeFlag, takeOption, type RuntimeApiDeps } from "./runtime-api";
+import { CliUsageError, printData, rejectArgs, runCliAction, runtimeRequest, takeFlag, takeOption, type RuntimeApiDeps } from "./runtime-api";
 
 const USAGE = `Usage:
   ocx alias list [--json]
@@ -14,6 +14,10 @@ function selector(value: string): { provider: string; model?: string } {
 
 /** Manage model aliases, consuming JSON output selection before the default list action. */
 export async function handleAliasCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => { await runAliasAction(argv, deps); });
+}
+
+async function runAliasAction(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   const args = [...argv];
   const wantsJson = takeFlag(args, "--json");
   const action = (args.shift() ?? "list").toLowerCase();
@@ -37,6 +41,7 @@ export async function handleAliasCommand(argv: string[], deps: RuntimeApiDeps =
     printData(result, wantsJson, [`Default aliases ${state}${provider ? ` for ${provider}` : " globally"}.`]);
     return 0;
   }
+  if (action !== "set" && action !== "rm") throw new CliUsageError(`Unknown alias action: ${action}. See: ocx help alias`, USAGE);
   const target = args.shift()?.trim();
   if (!target) throw new CliUsageError("alias target is required", USAGE);
   const parsed = selector(target);
@@ -63,5 +68,5 @@ export async function handleAliasCommand(argv: string[], deps: RuntimeApiDeps =
     printData(result, wantsJson, [`Removed alias for ${target}.`]);
     return 0;
   }
-  throw new CliUsageError(`unknown alias action '${action}'`, USAGE);
+  return 0;
 }

package/src/cli/aside-profiles.ts

@@ -4,7 +4,7 @@ import { createLocalAttestationChallenge, LOCAL_ATTESTATION_CHALLENGE_HEADER, LO
 import { createLocalAsideSyncCapability, LOCAL_ASIDE_SYNC_CAPABILITY_HEADER, LOCAL_ASIDE_SYNC_CAPABILITY_TTL_MS, LOCAL_ASIDE_SYNC_CAPABILITY_VERSION, LOCAL_ASIDE_SYNC_EXPECTED_PID_HEADER, LOCAL_ASIDE_SYNC_EXPIRES_AT_HEADER, LOCAL_ASIDE_SYNC_METHOD, LOCAL_ASIDE_SYNC_NONCE_HEADER, LOCAL_ASIDE_SYNC_PATH } from "../lib/local-aside-sync-contract";
 import { directLocalHttpFetch } from "../server/direct-local-http";
 import { findLiveProxy, isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
-import { runtimeRequest, RuntimeApiError, type RuntimeApiDeps } from "./runtime-api";
+import { runtimeRequest, RuntimeApiError, PROXY_NOT_RUNNING_MESSAGE, type RuntimeApiDeps } from "./runtime-api";
 
 /** Aside policy and file writes share the running server's mutation owner. Never fall back locally. */
 export async function refreshAsideProfilesThroughServer(
@@ -27,7 +27,7 @@ export async function refreshAsideProfilesThroughServer(
     const deadline = controller.signal;
     try {
       const live = await (deps.findLiveProxy ?? findLiveProxy)();
-      if (!live) throw new RuntimeApiError("Proxy is not running. Start it with: ocx start", 503, null);
+      if (!live) throw new RuntimeApiError(PROXY_NOT_RUNNING_MESSAGE, 503, null, "proxy_not_running");
       if (live.source !== "runtime" || live.pid === null) {
         throw new RuntimeApiError("Aside profile synchronization requires an attested running proxy", 503, null);
       }

package/src/cli/capabilities-access-remote.ts

@@ -0,0 +1,147 @@
+import type { Capability } from "./capability-types";
+
+/** Verified existing handlers only; local operations never claim management routes. */
+export const ACCESS_REMOTE_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["access", "key"], summary: "Manage API access keys and inspect masked metadata.",
+    usage: "ocx access key list [--json]",
+    routes: [{"method": "GET", "path": "/api/keys"}, {"method": "POST", "path": "/api/keys"}, {"method": "PATCH", "path": "/api/keys"}, {"method": "DELETE", "path": "/api/keys"}, {"method": "POST", "path": "/api/keys/rotate"}, {"method": "POST", "path": "/api/keys/rotate/commit"}, {"method": "DELETE", "path": "/api/keys/rotate"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Mixed family: list/get read masked metadata; scope edits, revocation and rotation change authorization.", "Creation and rotation initiation return plaintext secrets once and are human-only handoffs. Ask the operator to perform them in their terminal or dashboard; never capture the returned credential.", "Use the separately documented safe follow-up leaves. keys and top-level api-key are aliases."],
+  },
+  {
+    command: ["access", "key", "list"], summary: "List masked access keys, usage, endpoints and pending rotations.",
+    usage: "ocx access key list [--json]",
+    routes: [{"method": "GET", "path": "/api/keys"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["No plaintext secret is returned by the list route."],
+  },
+  {
+    command: ["access", "key", "get"], summary: "Read one masked key and its access scope.",
+    usage: "ocx access key get <id-or-name> [--json]",
+    routes: [{"method": "GET", "path": "/api/keys"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Case-insensitive ID takes precedence over name; ambiguous names are refused."],
+  },
+  {
+    command: ["access", "key", "set"], summary: "Replace selected provider/model scope dimensions.",
+    usage: "ocx access key set <id-or-name> [--allow-provider <name>]... [--allow-model <id>]... [--clear] [--json]",
+    routes: [{"method": "GET", "path": "/api/keys"}, {"method": "PATCH", "path": "/api/keys"}],
+    flags: [{"name": "--allow-provider", "value": "string", "summary": "Provider scope; repeatable, replaces that dimension."}, {"name": "--allow-model", "value": "string", "summary": "Model scope; repeatable, replaces that dimension."}, {"name": "--clear", "value": "boolean", "summary": "Clear both dimensions; submitted allow options then override their dimension."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["At least one scope option is required. Unspecified dimensions are preserved; this command does not rename keys."],
+  },
+  {
+    command: ["access", "key", "rotate", "commit"], summary: "Commit a pending key rotation.",
+    usage: "ocx access key rotate commit <id> <rotation-id> [--json]",
+    routes: [{"method": "POST", "path": "/api/keys/rotate/commit"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Use IDs from the human-authorized rotation. Commit only after the client accepts the replacement; the old credential is retired."],
+  },
+  {
+    command: ["access", "key", "rotate", "abort"], summary: "Abort a pending key rotation.",
+    usage: "ocx access key rotate abort <id> <rotation-id> [--json]",
+    routes: [{"method": "DELETE", "path": "/api/keys/rotate"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Use IDs from the human-authorized rotation. Abort discards the pending replacement credential."],
+  },
+  {
+    command: ["access", "key", "remove"], summary: "Revoke one API access key.",
+    usage: "ocx access key remove <id> --yes [--json]",
+    routes: [{"method": "DELETE", "path": "/api/keys"}],
+    flags: [{"name": "--yes", "value": "boolean", "summary": "Required confirmation before revoking the key.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Uses the exact ID, not name resolution; delete is an alias."],
+  },
+  {
+    command: ["access", "endpoints"], summary: "Read endpoint URLs from the access-key metadata.",
+    usage: "ocx access endpoints [--json]",
+    routes: [{"method": "GET", "path": "/api/keys"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "envelope",
+    details: ["Projects only baseUrl, endpoint and fields ending in Endpoint; use key list for the full metadata payload."],
+  },
+  {
+    command: ["access", "models"], summary: "Read the public external-model catalog.",
+    usage: "ocx access models [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Data-plane GET /v1/models via the runtime client; differs from management models live. The routes field indexes management API routes only."],
+  },
+  {
+    command: ["access","test"],
+    summary: "Send a small inference request through the selected protocol.",
+    usage: "ocx access test <model> [--protocol <chat|responses|messages>] [--api-key-stdin] [--json]",
+    routes: [],
+    flags: [{"name":"--protocol","value":"string","summary":"chat | responses | messages; default chat."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."},{"name":"--api-key-stdin","value":"boolean","summary":"Read one explicit data key from bounded piped stdin; no secret argv/env or management/enrolled-key fallback."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Data-plane model POSTs are not management routes. The request may spend provider quota; run only for an explicitly authorized model probe. Legacy unkeyed behavior/JSON remains unchanged.","Explicit-key mode first sends a credentialless malformed-body control to the same protocol endpoint. Only the native key-required401 permits one16-token keyed request. Authless/unrecognized targets refuse before inference.","Version1 selected-key JSON reports control/request observations and a safe text/completion/usage projection. Limited output stays limited; neither control nor response certifies billing identity, key scopes or atomic policy stability.","Keys use explicit bounded stdin and printableASCII input compatible with issued keys. Same-target identity checks, deadlines, redirect refusal, exact-key redaction and cancellation apply; no retries or fallback credential."],
+  },
+  {
+    command: ["remote-workspace","hub","status"],
+    usage: "ocx remote-workspace hub status [--json]",
+    summary: "Read Hub devices, runtime availability and sessions.",
+    routes: [{"method":"GET","path":"/api/remote-workspace"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit one validated task result as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["Existing remote-workspace status remains executor-local. These fixed reads use the selected management Hub; they do not create pairing grants, sessions or remote commands.","Available empty lists succeed. Disabled Hub observations return explicit available:false and exit1; malformed or refused responses are not presented as empty success. Runtime reads can perform availability probes."],
+  },
+  {
+    command: ["remote-workspace","hub","runtimes"],
+    usage: "ocx remote-workspace hub runtimes [--json]",
+    summary: "Read Codex, Claude and Pi availability on the Hub.",
+    routes: [{"method":"GET","path":"/api/remote-workspace/runtimes"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit one validated task result as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["Existing remote-workspace status remains executor-local. These fixed reads use the selected management Hub; they do not create pairing grants, sessions or remote commands.","Available empty lists succeed. Disabled Hub observations return explicit available:false and exit1; malformed or refused responses are not presented as empty success. Runtime reads can perform availability probes."],
+  },
+  {
+    command: ["remote-workspace","hub","sessions"],
+    usage: "ocx remote-workspace hub sessions [--json]",
+    summary: "Read Hub sessions and their public recent events.",
+    routes: [{"method":"GET","path":"/api/remote-workspace/sessions"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit one validated task result as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["Existing remote-workspace status remains executor-local. These fixed reads use the selected management Hub; they do not create pairing grants, sessions or remote commands.","Available empty lists succeed. Disabled Hub observations return explicit available:false and exit1; malformed or refused responses are not presented as empty success. Runtime reads can perform availability probes."],
+  },
+  {
+    command: ["access","key","rename"],
+    usage: "ocx access key rename <id-or-name> <name> [--json]",
+    summary: "Rename an unambiguously selected API key while preserving its scopes.",
+    routes: [{"method":"GET","path":"/api/keys"},{"method":"PATCH","path":"/api/keys"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the command result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Resolves a unique ID/name from the pinned management roster and sends only id/name. Duplicate-ID ambiguity is refused; no plaintext, scope clear, rotation or deletion is involved.","Name follows existing trimmed nonempty64-unit/control-character rules. Resolution is not revision CAS; API-key root alias shares the operation."],
+  },
+  {
+    command: ["access","audio","transcribe"],
+    usage: "ocx access audio transcribe <file> --model <gpt-4o-transcribe|gpt-4o-mini-transcribe|whisper-1> --api-key-stdin [--json]",
+    summary: "Transcribe an explicitly chosen bounded audio file with a supplied data key.",
+    routes: [],
+    flags: [{"name":"--model","value":"string","summary":"Required supported transcription model; no silent model fallback.","required":true},{"name":"--api-key-stdin","value":"boolean","summary":"Required bounded explicit data key on piped stdin; no management/enrolled-key substitution.","required":true},{"name":"--json","value":"boolean","summary":"Emit the command result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Fixed data-plane POST /v1/audio/transcriptions with file/model/response_format=json. May use provider quota; requires explicit upload/inference authority.","File must be nonempty regular input≤25,000,000bytes; multipart≤32MiB, response≤2MiB, request130s. Only the requested text result is returned, with exact supplied-key redaction.","Audio uses its own explicit-key admission, including on an otherwise authless model listener. No generic model control, retries, secret argv/env or redirect following."],
+  },
+  {
+    command: ["access","audio","live-check"],
+    usage: "ocx access audio live-check --model <id> --api-key-stdin [--json]",
+    summary: "Check actual live-session readiness, then close the connection.",
+    routes: [],
+    flags: [{"name":"--model","value":"string","summary":"Required live model; sent to the existing live route.","required":true},{"name":"--api-key-stdin","value":"boolean","summary":"Required bounded printableASCII key, encoded only in the established audio subprotocol.","required":true},{"name":"--json","value":"boolean","summary":"Emit the command result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Fixed data-plane WebSocket /v1/live with the existing audio key carrier and session.update, then session.close. It contacts upstream and may incur provider usage; no microphone, audio upload, tool execution or voice-roundtrip claim.","Version1 report distinguishes readiness from confirmed normal close. Socket-open alone is not ready.15s readiness,2s close deadline; stuck/abnormal closure remains unverified/nonzero, with local socket termination.","No raw frames/session IDs/encoded credentials are printed. NativeWebSocket redirect refusal is verified separately from HTTP upload behavior."],
+  },
+];

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."],
+  },
+];