@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/agent-runtime-settings.ts

@@ -0,0 +1,130 @@
+import { isValidVisionTimeoutMs } from "../vision/plan";
+import { isDeclaredReasoningEffort } from "../reasoning-effort";
+import { runCatalogAction } from "./catalog-command-result";
+import { serializeManagementJson } from "./json-input";
+import { projectSettingsApply } from "./settings-result";
+import { CliUsageError, desktopSwitchApplyReason, printData, runtimeBaseUrl, runtimeRequest,
+  takeFlag, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function boolean(args: string[], flag: string): boolean | undefined {
+  const value = takeOptionWithSyntax(args, flag)?.value;
+  if (value === undefined) return undefined;
+  if (["on", "true", "yes", "1", "enabled"].includes(value.toLowerCase())) return true;
+  if (["off", "false", "no", "0", "disabled"].includes(value.toLowerCase())) return false;
+  throw new CliUsageError(`${flag} must be on or off`);
+}
+function invalid(): never { throw new Error("Invalid agent settings receipt"); }
+
+/** Additive default-sync option; normalized server state, not a native-write claim. */
+export async function handleInjectionDefaults(argsInput: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argsInput];
+    if (args.shift() !== "set") throw new CliUsageError("--sync-codex-defaults requires agent injection set");
+    const wantsJson = takeFlag(args, "--json");
+    const sync = boolean(args, "--sync-codex-defaults");
+    const guidance = boolean(args, "--guidance");
+    const body: Record<string, unknown> = {};
+    for (const [flag, key] of [["--model", "model"], ["--effort", "effort"], ["--prompt", "prompt"]] as const) {
+      const value = takeOptionWithSyntax(args, flag)?.value;
+      if (value !== undefined) body[key] = value === "-" ? null : value;
+    }
+    if (sync === undefined || args.length) throw new CliUsageError("Provide --sync-codex-defaults on or off and supported injection options");
+    body.syncCodexSubagentDefaults = sync;
+    if (guidance !== undefined) body.multiAgentGuidanceEnabled = guidance;
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    const value = await runtimeRequest("/api/injection-model", { method: "PUT", redirect: "error", body: serializeManagementJson(body) }, pinned);
+    if (!record(value) || value.ok !== true || typeof value.multiAgentGuidanceEnabled !== "boolean"
+      || typeof value.syncCodexSubagentDefaults !== "boolean"
+      || ["model", "effort", "prompt"].some(key => value[key] !== null && typeof value[key] !== "string")) invalid();
+    const data = { ok: true, multiAgentGuidanceEnabled: value.multiAgentGuidanceEnabled,
+      syncCodexSubagentDefaults: value.syncCodexSubagentDefaults, model: value.model, effort: value.effort, prompt: value.prompt };
+    printData(data, wantsJson, ["Injection settings saved.", `Guidance: ${data.multiAgentGuidanceEnabled}`,
+      `Effective default-sync setting: ${data.syncCodexSubagentDefaults}`]);
+    return 0;
+  });
+}
+
+/** New sidecar fields share the existing candidate normalization and partial PUT contract. */
+export async function handleSidecarRuntimeSettings(argsInput: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argsInput], section = args.shift();
+    if (section !== "web" && section !== "vision") throw new CliUsageError("Sidecar settings require web or vision");
+    const wantsJson = takeFlag(args, "--json");
+    const model = takeOptionWithSyntax(args, "--model")?.value;
+    const backend = takeOptionWithSyntax(args, "--backend")?.value;
+    const reasoning = takeOptionWithSyntax(args, "--reasoning")?.value;
+    const max = takeOptionWithSyntax(args, "--max-descriptions")?.value;
+    const timeout = takeOptionWithSyntax(args, "--timeout-ms")?.value;
+    const enabled = boolean(args, "--enabled");
+    const stream = boolean(args, "--stream-routed-output");
+    if (args.length || (section === "web" && (max !== undefined || timeout !== undefined))
+      || (section === "vision" && stream !== undefined)) throw new CliUsageError("Unsupported option for this sidecar section");
+    const settings: Record<string, unknown> = {};
+    if (model !== undefined) settings.model = model === "-" ? "" : model;
+    if (backend !== undefined) settings.backend = backend === "-" ? null : backend;
+    if (reasoning !== undefined) settings.reasoning = reasoning;
+    if (enabled !== undefined) settings.enabled = enabled;
+    if (stream !== undefined) settings.streamRoutedModelOutput = stream;
+    if (max !== undefined) {
+      const value = Number(max);
+      if (!max.trim() || !Number.isSafeInteger(value) || value < 1) throw new CliUsageError("--max-descriptions requires a positive integer");
+      settings.maxDescriptionsPerTurn = value;
+    }
+    if (timeout !== undefined) {
+      const value = Number(timeout);
+      if (!timeout.trim() || !isValidVisionTimeoutMs(value)) throw new CliUsageError("--timeout-ms requires an integer from 1 to 2147483647");
+      settings.timeoutMs = value;
+    }
+    if (!Object.keys(settings).length) throw new CliUsageError("Provide at least one sidecar setting");
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    if (section === "web" && model !== undefined && model !== "-") {
+      const offered = await runtimeRequest("/api/sidecar-settings", { redirect: "error" }, pinned);
+      if (!record(offered) || !Array.isArray(offered.webSearchModels)) invalid();
+      const requestedBackend = backend === "-" ? "openai" : backend;
+      const option = offered.webSearchModels.find(row => record(row)
+        && (row.value === model || row.model === model)
+        && (requestedBackend === undefined || row.backend === requestedBackend));
+      if (option !== undefined) {
+        if (!record(option) || typeof option.model !== "string" || typeof option.backend !== "string"
+          || !["openai", "anthropic", "xai", "gemini", "exa"].includes(option.backend)) invalid();
+        settings.model = option.model;
+        if (backend !== "-") settings.backend = option.backend;
+      }
+    }
+    const value = await runtimeRequest("/api/sidecar-settings", { method: "PUT", redirect: "error",
+      body: serializeManagementJson(section === "web" ? { webSearch: settings } : { vision: settings }) }, pinned);
+    if (!record(value) || value.ok !== true) invalid();
+    const raw = section === "web" ? value.webSearch : value.vision;
+    const backends = section === "web" ? ["openai", "anthropic", "xai", "gemini", "exa"] : ["openai", "anthropic", "routed"];
+    if (!record(raw) || typeof raw.enabled !== "boolean" || typeof raw.model !== "string" || !raw.model.trim()
+      || (raw.backend !== undefined && (typeof raw.backend !== "string" || !backends.includes(raw.backend)))) invalid();
+    const selected: Record<string, unknown> = { enabled: raw.enabled, model: raw.model,
+      ...(raw.backend !== undefined ? { backend: raw.backend } : {}) };
+    let verified = true;
+    if (section === "web") {
+      if (typeof raw.streamRoutedModelOutput !== "boolean") invalid();
+      selected.streamRoutedModelOutput = raw.streamRoutedModelOutput;
+      if (stream !== undefined && raw.streamRoutedModelOutput !== stream) verified = false;
+    } else {
+      if (!isValidVisionTimeoutMs(raw.timeoutMs) || typeof raw.maxDescriptionsPerTurn !== "number"
+        || !Number.isSafeInteger(raw.maxDescriptionsPerTurn) || raw.maxDescriptionsPerTurn < 1
+        || (raw.reasoning !== undefined && (typeof raw.reasoning !== "string" || !isDeclaredReasoningEffort(raw.reasoning)))) invalid();
+      selected.timeoutMs = raw.timeoutMs;
+      selected.maxDescriptionsPerTurn = raw.maxDescriptionsPerTurn;
+      if (raw.reasoning !== undefined) selected.reasoning = raw.reasoning;
+      if (timeout !== undefined && raw.timeoutMs !== Number(timeout)) verified = false;
+    }
+    const apply = projectSettingsApply(value.codexWebSearch);
+    if (!apply) invalid();
+    const data = { ok: true, [section === "web" ? "webSearch" : "vision"]: selected, codexWebSearch: apply,
+      ...(!verified ? { verification: "unverified" } : {}) };
+    const lines = [`${section} sidecar settings saved.`];
+    if (!apply.applied) lines.push(`Native apply: ${desktopSwitchApplyReason(apply.reason)}.`);
+    if (!verified) lines.push("The target did not confirm the requested new setting. Read back before retrying.");
+    printData(data, wantsJson, lines);
+    return !verified || (!apply.applied && apply.reason !== "not_requested") ? 1 : 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,15 +24,19 @@ 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]
+  ocx agent subagents force <model|-> [--json]
   ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
   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 {
@@ -169,6 +173,15 @@ async function subagents(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     printData(result, wantsJson, summaryLines(result));
     return;
   }
+  if (action === "force") {
+    const model = args.shift();
+    if (!model?.trim()) throw new CliUsageError("a force model or - is required", USAGE);
+    rejectArgs(args, USAGE);
+    const force = clearable(model);
+    const result = await runtimeRequest("/api/subagent-models", { method: "PUT", body: JSON.stringify({ force }) }, deps);
+    printData(result, wantsJson, [force ? `Claude subagent force: ${force}. Applies on the next routed ocx claude launch.` : "Claude subagent force cleared."]);
+    return;
+  }
   let models: string[];
   if (action === "clear") models = [];
   else if (action === "set") {
@@ -247,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> = {};
@@ -408,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."],
+  },
+];