@bitkyc08/opencodex 2.7.41 → 2.7.42

package/src/cli/access.ts

@@ -0,0 +1,108 @@
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx access key [list] [--json]
+  ocx access key create [name] [--json]
+  ocx access key remove <id> --yes [--json]
+  ocx access endpoints [--json]
+  ocx access models [--json]
+  ocx access test <model> [--protocol <chat|responses|messages>] [--json]`;
+
+async function key(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "list").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "list") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest<Record<string, unknown>>("/api/keys", {}, deps);
+    const keys = Array.isArray(result.keys) ? result.keys as Array<Record<string, unknown>> : [];
+    printData(result, wantsJson, keys.length
+      ? keys.map(entry => `${String(entry.id)}  ${String(entry.name)}  ${String(entry.prefix ?? "")}`)
+      : ["No API access keys configured."]);
+    return;
+  }
+  if (action === "create") {
+    const name = args.shift() ?? "default";
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest<Record<string, unknown>>("/api/keys", {
+      method: "POST",
+      body: JSON.stringify({ name }),
+    }, deps);
+    // The plaintext key is returned once. Keep text output explicit so callers know to store it.
+    printData(result, wantsJson, [
+      `Created API key ${String(result.name ?? name)} (${String(result.id ?? "")}).`,
+      `Key (shown once): ${String(result.key ?? "")}`,
+    ]);
+    return;
+  }
+  if (action === "remove" || action === "delete") {
+    const id = args.shift();
+    const yes = takeFlag(args, "--yes");
+    if (!id) throw new CliUsageError("key id is required", USAGE);
+    if (!yes) throw new CliUsageError("remove requires --yes", USAGE);
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/keys", { method: "DELETE", body: JSON.stringify({ id }) }, deps);
+    printData(result, wantsJson, [`Removed API key ${id}.`]);
+    return;
+  }
+  throw new CliUsageError(`unknown key command ${action}`, USAGE);
+}
+
+async function endpoints(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<Record<string, unknown>>("/api/keys", {}, deps);
+  const view = Object.fromEntries(Object.entries(result).filter(([key]) => key.endsWith("Endpoint") || key === "baseUrl" || key === "endpoint"));
+  printData(view, wantsJson, Object.entries(view).map(([name, value]) => `${name}: ${String(value)}`));
+}
+
+async function models(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<Record<string, unknown>>("/v1/models", {}, deps);
+  const rows = Array.isArray(result.data) ? result.data as Array<Record<string, unknown>> : [];
+  printData(result, wantsJson, rows.map(row => `${String(row.id)}  ${String(row.owned_by ?? "")}`.trimEnd()));
+}
+
+async function testModel(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const model = args.shift();
+  const wantsJson = takeFlag(args, "--json");
+  const protocol = takeOption(args, "--protocol") ?? "chat";
+  if (!model) throw new CliUsageError("model is required", USAGE);
+  if (!(["chat", "responses", "messages"] as const).includes(protocol as "chat" | "responses" | "messages")) {
+    throw new CliUsageError("--protocol must be chat, responses, or messages", USAGE);
+  }
+  rejectArgs(args, USAGE);
+  const request = protocol === "responses"
+    ? { path: "/v1/responses", body: { model, input: "Reply with OK.", max_output_tokens: 16 } }
+    : protocol === "messages"
+      ? { path: "/v1/messages", body: { model, messages: [{ role: "user", content: "Reply with OK." }], max_tokens: 16 } }
+      : { path: "/v1/chat/completions", body: { model, messages: [{ role: "user", content: "Reply with OK." }], max_tokens: 16, stream: false } };
+  const result = await runtimeRequest(request.path, { method: "POST", body: JSON.stringify(request.body) }, deps);
+  printData(result, wantsJson, [`${model}: ${protocol} request succeeded.`]);
+}
+
+export async function handleAccessCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "key", ...rest] = argv;
+    if (sub === "key" || sub === "keys") await key(rest, deps);
+    else if (sub === "endpoints") await endpoints(rest, deps);
+    else if (sub === "models") await models(rest, deps);
+    else if (sub === "test") await testModel(rest, deps);
+    else throw new CliUsageError(`unknown access command ${sub}`, USAGE);
+  });
+}
+
+export const ACCESS_USAGE = USAGE;

package/src/cli/account-auth.ts

@@ -0,0 +1,223 @@
+import {
+  CliUsageError,
+  printData,
+  readSecretLine,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  takeFlag,
+  takeOption,
+  takeOptionWithSyntax,
+  type CliStdin,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx account login <provider> [--id <account-id>] [--reauth] [--code -] [--no-wait] [--json]
+  ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
+  ocx account cancel <provider> [--flow <flow-id>] [--json]
+  ocx account reset-credits <account-id|main> [--consume --yes] [--json]
+
+The redirect URL or authorization code is a short-lived credential. Pipe it in
+rather than passing it as an argument, where it lands in shell history and is
+visible to anyone who can run ps:
+  pbpaste | ocx account code <provider> --flow <flow-id>
+  ocx account login <provider> --code -   (same, for the login flow)`;
+
+const CODEX_NAMES = new Set(["openai", "codex", "chatgpt"]);
+
+interface LoginStart {
+  url?: string;
+  flowId?: string;
+  instructions?: string;
+  deviceCode?: string;
+}
+
+/** `-` means "read it from stdin", the documented way to pass a code silently. */
+const STDIN_SENTINEL = "-";
+
+const ARGV_WARNING =
+  "warning: the authorization code was passed as a command-line argument, so it is now in your shell history and was visible in the process list while this ran. Pipe it on stdin instead, or pass `-` to read from stdin.";
+
+/**
+ * Resolve the code, preferring stdin.
+ *
+ * Never logs the value itself — the warning names the exposure, not the
+ * credential. What this closes is shell history, `ps`, and this program's own
+ * output; a code pasted at an interactive prompt is still visible on the
+ * terminal, exactly as it is in the existing interactive login.
+ */
+async function resolveCode(
+  supplied: { value: string; inline: boolean } | undefined,
+  deps: RuntimeApiDeps,
+  required: boolean,
+): Promise<string | undefined> {
+  if (supplied && supplied.value !== STDIN_SENTINEL) {
+    console.error(ARGV_WARNING);
+    return supplied.value;
+  }
+  if (!supplied && !required) return undefined;
+  const input: CliStdin = deps.stdinImpl ?? process.stdin;
+  if (input.isTTY) console.error("Paste the redirect URL or authorization code, then press Enter:");
+  return await readSecretLine(deps, "authorization code");
+}
+
+async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const provider = args.shift()?.trim().toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  const noWait = takeFlag(args, "--no-wait");
+  const reauth = takeFlag(args, "--reauth");
+  const id = takeOption(args, "--id");
+  const suppliedCode = takeOptionWithSyntax(args, "--code");
+  if (!provider) throw new CliUsageError("provider is required", USAGE);
+  rejectArgs(args, USAGE);
+  // Only resolve when --code was actually given: a plain `ocx account login`
+  // opens the browser flow and polls, and must not block on stdin.
+  const code = await resolveCode(suppliedCode, deps, false);
+
+  if (CODEX_NAMES.has(provider)) {
+    const start = await runtimeRequest<LoginStart>("/api/codex-auth/login", {
+      method: "POST",
+      body: JSON.stringify({ ...(id ? { id } : {}), ...(reauth ? { reauth: true } : {}) }),
+    }, deps);
+    if (!wantsJson) {
+      if (start.url) console.log(`Open this URL to sign in:\n${start.url}`);
+      if (start.instructions) console.log(start.instructions);
+      if (start.flowId) console.log(`Flow: ${start.flowId}`);
+    }
+    if (code && start.flowId) {
+      await runtimeRequest("/api/codex-auth/login/code", {
+        method: "POST",
+        body: JSON.stringify({ flowId: start.flowId, input: code }),
+      }, deps);
+    }
+    if (noWait) {
+      if (wantsJson) printData(start, true);
+      return;
+    }
+    if (!start.flowId) throw new CliUsageError("login did not return a flow id");
+    for (let attempt = 0; attempt < 150; attempt++) {
+      await Bun.sleep(2_000);
+      const state = await runtimeRequest<Record<string, unknown>>(
+        `/api/codex-auth/login-status?flowId=${encodeURIComponent(start.flowId)}${id ? `&accountId=${encodeURIComponent(id)}` : ""}${reauth ? "&reauth=1" : ""}`,
+        {}, deps,
+      );
+      if (state.status === "done") {
+        printData(state, wantsJson, [`Logged in${state.email ? ` as ${String(state.email)}` : ""}.`]);
+        return;
+      }
+      if (state.status === "error" || state.status === "expired") {
+        throw new CliUsageError(String(state.error ?? `login ${state.status}`));
+      }
+    }
+    throw new CliUsageError("login timed out");
+  }
+
+  if (id && !reauth) throw new CliUsageError("--id is only valid with --reauth for provider OAuth accounts", USAGE);
+  const start = await runtimeRequest<LoginStart>("/api/oauth/login", {
+    method: "POST",
+    body: JSON.stringify({ provider, addAccount: !reauth, ...(reauth && id ? { accountId: id, reauth: true } : {}) }),
+  }, deps);
+  if (!wantsJson) {
+    if (start.url) console.log(`Open this URL to sign in:\n${start.url}`);
+    if (start.instructions) console.log(start.instructions);
+    if (start.deviceCode) console.log(`Device code: ${start.deviceCode}`);
+  }
+  if (code) {
+    await runtimeRequest("/api/oauth/login/code", {
+      method: "POST",
+      body: JSON.stringify({ provider, input: code }),
+    }, deps);
+  }
+  if (noWait) {
+    if (wantsJson) printData(start, true);
+    return;
+  }
+  for (let attempt = 0; attempt < 100; attempt++) {
+    await Bun.sleep(2_000);
+    const state = await runtimeRequest<Record<string, unknown>>(`/api/oauth/status?provider=${encodeURIComponent(provider)}`, {}, deps);
+    if (state.loggedIn === true) {
+      printData(state, wantsJson, [`Logged in to ${provider}.`]);
+      return;
+    }
+    if (state.error) throw new CliUsageError(String(state.error));
+  }
+  throw new CliUsageError("login timed out");
+}
+
+async function code(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const provider = args.shift()?.trim().toLowerCase();
+  // Flags first. Taking the positional before parsing them made
+  // `ocx account code openai --flow f1` read `--flow` as the code and then
+  // reject `f1` as an unexpected argument.
+  const wantsJson = takeFlag(args, "--json");
+  const flowId = takeOption(args, "--flow");
+  const suppliedCode = takeOptionWithSyntax(args, "--code");
+  // An unknown flag is not a credential. Without this guard `--nope` becomes
+  // the positional code and the real complaint ("unexpected argument") is
+  // replaced by a confusing one about how the code was passed.
+  const positional = args[0]?.startsWith("--") ? undefined : args.shift();
+  if (!provider) throw new CliUsageError("provider is required", USAGE);
+  // A second positional here is most likely the code, split by an unquoted
+  // space or a stray shell expansion. Naming it back would put it on stderr.
+  rejectArgs(args, USAGE, { redactValues: true });
+  if (suppliedCode && positional !== undefined) {
+    throw new CliUsageError("pass the code either positionally or with --code, not both", USAGE);
+  }
+  const input = await resolveCode(
+    suppliedCode ?? (positional === undefined ? undefined : { value: positional, inline: false }),
+    deps,
+    true,
+  );
+  if (!input) throw new CliUsageError("provider and redirect/code are required", USAGE);
+  const path = CODEX_NAMES.has(provider) ? "/api/codex-auth/login/code" : "/api/oauth/login/code";
+  if (CODEX_NAMES.has(provider) && !flowId) throw new CliUsageError("Codex login code requires --flow <flow-id>", USAGE);
+  const body = CODEX_NAMES.has(provider) ? { flowId, input } : { provider, input };
+  const result = await runtimeRequest(path, { method: "POST", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Login code submitted."]);
+}
+
+async function cancel(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const provider = args.shift()?.trim().toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  const flowId = takeOption(args, "--flow");
+  if (!provider) throw new CliUsageError("provider is required", USAGE);
+  rejectArgs(args, USAGE);
+  const codex = CODEX_NAMES.has(provider);
+  const result = await runtimeRequest(codex ? "/api/codex-auth/login/cancel" : "/api/oauth/login/cancel", {
+    method: "POST",
+    body: JSON.stringify(codex ? { flowId } : { provider }),
+  }, deps);
+  printData(result, wantsJson, [`Cancelled ${provider} login.`]);
+}
+
+async function resetCredits(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const rawId = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const consume = takeFlag(args, "--consume");
+  const yes = takeFlag(args, "--yes");
+  if (!rawId) throw new CliUsageError("account id is required", USAGE);
+  if (consume && !yes) throw new CliUsageError("consuming a reset credit requires --yes", USAGE);
+  rejectArgs(args, USAGE);
+  const accountId = rawId === "main" ? "__main__" : rawId;
+  const result = consume
+    ? await runtimeRequest("/api/codex-auth/reset-credits/consume", { method: "POST", body: JSON.stringify({ accountId }) }, deps)
+    : await runtimeRequest(`/api/codex-auth/reset-credits?accountId=${encodeURIComponent(accountId)}`, {}, deps);
+  printData(result, wantsJson);
+}
+
+export async function handleAccountAuthCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
+  let action: (() => Promise<void>) | undefined;
+  if (sub === "login" || sub === "reauth") action = () => login(sub === "reauth" ? [...argv, "--reauth"] : argv, deps);
+  else if (sub === "code") action = () => code(argv, deps);
+  else if (sub === "cancel") action = () => cancel(argv, deps);
+  else if (sub === "reset-credits") action = () => resetCredits(argv, deps);
+  if (!action) return null;
+  return runCliAction(action);
+}
+
+export const ACCOUNT_AUTH_USAGE = USAGE;

package/src/cli/account.ts

@@ -25,6 +25,10 @@ const ACCOUNT_USAGE = `Usage:
   ocx account remove <provider> <account-or-key-id|main> --yes [--json]
   ocx account clear-cooldown <provider> <account-id|main> [--json]
   ocx account add-key <provider> [--label <label>] [--json]
+  ocx account login <provider> [--id <account-id>] [--reauth] [--code -] [--no-wait] [--json]
+  ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
+  ocx account cancel <provider> [--flow <flow-id>] [--json]
+  ocx account reset-credits <account-id|main> [--consume --yes] [--json]
 
 List and switch provider accounts and API-key pools (masked output only).
 'main' selects the Codex App login for the openai account pool.`;
@@ -57,7 +61,7 @@ function displayId(id: string): string {
 
 function statusText(row: AccountRow): string {
   const parts: string[] = [];
-  if (row.active) parts.push(row.type === "codex" ? "next session" : "active");
+  if (row.active) parts.push(row.type === "codex" ? "selected" : "active");
   if (row.needsReauth) parts.push("needs-reauth");
   return parts.join(" ");
 }
@@ -260,6 +264,10 @@ export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promis
     if (sub === "remove") return await cmdRemove(rest, deps);
     if (sub === "clear-cooldown") return await cmdClearCooldown(rest, deps);
     if (sub === "add-key") return await cmdAddKey(rest, deps);
+    if (["login", "reauth", "code", "cancel", "reset-credits"].includes(sub ?? "")) {
+      const { handleAccountAuthCommand } = await import("./account-auth");
+      return await handleAccountAuthCommand(sub!, rest, deps) ?? 1;
+    }
     console.error(ACCOUNT_USAGE);
     return 1;
   } catch (err) {

package/src/cli/agent.ts

@@ -0,0 +1,184 @@
+import {
+  CliUsageError,
+  csv,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  summaryLines,
+  takeBooleanOption,
+  takeFlag,
+  takeIntegerOption,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx agent [status] [--json]
+  ocx agent injection <status|set> [--model <id|->] [--effort <level|->]
+      [--prompt <text|->] [--guidance <on|off>] [--json]
+  ocx agent effort <status|set> [--main <level|->] [--subagent <level|->] [--json]
+  ocx agent subagents <status|set|clear> [model,model...] [--json]
+  ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
+  ocx agent sidecar <status|web|vision> [--model <id|->] [--backend <openai|anthropic|->]
+      [--reasoning <level>] [--max-descriptions <n>] [--json]`;
+
+function clearable(value: string | undefined): string | null | undefined {
+  return value === "-" ? null : value;
+}
+
+async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const [v2, injection, caps, subagents, fallback, sidecars] = await Promise.all([
+    runtimeRequest("/api/v2", {}, deps),
+    runtimeRequest("/api/injection-model", {}, deps),
+    runtimeRequest("/api/effort-caps", {}, deps),
+    runtimeRequest("/api/subagent-models", {}, deps),
+    runtimeRequest("/api/subagent-model-fallback", {}, deps),
+    runtimeRequest("/api/sidecar-settings", {}, deps),
+  ]);
+  const result = { v2, injection, caps, subagents, fallback, sidecars };
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function injection(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/injection-model", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (action !== "set") throw new CliUsageError(`unknown injection action ${action}`, USAGE);
+  const model = clearable(takeOption(args, "--model"));
+  const effort = clearable(takeOption(args, "--effort"));
+  const prompt = clearable(takeOption(args, "--prompt"));
+  const guidance = takeBooleanOption(args, "--guidance");
+  rejectArgs(args, USAGE);
+  const body: Record<string, unknown> = {};
+  if (model !== undefined) body.model = model;
+  if (effort !== undefined) body.effort = effort;
+  if (prompt !== undefined) body.prompt = prompt;
+  if (guidance !== undefined) body.multiAgentGuidanceEnabled = guidance;
+  if (Object.keys(body).length === 0) throw new CliUsageError("at least one injection option is required", USAGE);
+  const result = await runtimeRequest("/api/injection-model", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Agent injection settings updated."]);
+}
+
+async function effort(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/effort-caps", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (action !== "set") throw new CliUsageError(`unknown effort action ${action}`, USAGE);
+  const main = clearable(takeOption(args, "--main"));
+  const subagent = clearable(takeOption(args, "--subagent"));
+  rejectArgs(args, USAGE);
+  const body: Record<string, unknown> = {};
+  if (main !== undefined) body.effortCap = main;
+  if (subagent !== undefined) body.subagentEffortCap = subagent;
+  if (Object.keys(body).length === 0) throw new CliUsageError("--main and/or --subagent is required", USAGE);
+  const result = await runtimeRequest("/api/effort-caps", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Agent effort caps updated."]);
+}
+
+async function subagents(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/subagent-models", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  let models: string[];
+  if (action === "clear") models = [];
+  else if (action === "set") {
+    const raw = args.shift();
+    if (!raw) throw new CliUsageError("comma-separated subagent models are required", USAGE);
+    models = csv(raw) ?? [];
+  } else throw new CliUsageError(`unknown subagents action ${action}`, USAGE);
+  rejectArgs(args, USAGE);
+  if (models.length > 5) throw new CliUsageError("at most 5 subagent models are allowed", USAGE);
+  const result = await runtimeRequest("/api/subagent-models", { method: "PUT", body: JSON.stringify({ models }) }, deps);
+  printData(result, wantsJson, [`Subagent roster: ${models.join(", ") || "cleared"}`]);
+}
+
+async function fallback(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/subagent-model-fallback", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  const body: Record<string, unknown> = {};
+  if (action === "clear") body.models = [];
+  else if (action === "set") {
+    const raw = args[0] && !args[0].startsWith("--") ? args.shift() : undefined;
+    if (raw) body.models = csv(raw) ?? [];
+  } else throw new CliUsageError(`unknown fallback action ${action}`, USAGE);
+  const pollMs = takeIntegerOption(args, "--poll-ms", { min: 5_000 });
+  if (pollMs !== undefined) {
+    if (pollMs > 600_000) throw new CliUsageError("--poll-ms must be <= 600000", USAGE);
+    body.pollMs = pollMs;
+  }
+  rejectArgs(args, USAGE);
+  if (Object.keys(body).length === 0) throw new CliUsageError("models and/or --poll-ms is required", USAGE);
+  const result = await runtimeRequest("/api/subagent-model-fallback", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Subagent fallback settings updated."]);
+}
+
+async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const section = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (section === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/sidecar-settings", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (section !== "web" && section !== "vision") throw new CliUsageError("sidecar must be web, vision, or status", USAGE);
+  const model = takeOption(args, "--model");
+  const backend = takeOption(args, "--backend");
+  const reasoning = takeOption(args, "--reasoning");
+  const maxDescriptionsPerTurn = takeIntegerOption(args, "--max-descriptions", { min: 1 });
+  rejectArgs(args, USAGE);
+  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 (maxDescriptionsPerTurn !== undefined) settings.maxDescriptionsPerTurn = maxDescriptionsPerTurn;
+  if (Object.keys(settings).length === 0) throw new CliUsageError("at least one sidecar option is required", USAGE);
+  const body = section === "web" ? { webSearch: settings } : { vision: settings };
+  const result = await runtimeRequest("/api/sidecar-settings", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, [`${section} sidecar settings updated.`]);
+}
+
+export async function handleAgentCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "status", ...rest] = argv;
+    if (sub === "status") await status(rest, deps);
+    else if (sub === "injection" || sub === "guidance") await injection(rest, deps);
+    else if (sub === "effort") await effort(rest, deps);
+    else if (sub === "subagents" || sub === "roster") await subagents(rest, deps);
+    else if (sub === "fallback") await fallback(rest, deps);
+    else if (sub === "sidecar") await sidecar(rest, deps);
+    else throw new CliUsageError(`unknown agent command ${sub}`, USAGE);
+  });
+}
+
+export const AGENT_USAGE = USAGE;

package/src/cli/combo.ts

@@ -0,0 +1,119 @@
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  takeFlag,
+  takeIntegerOption,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx combo [list] [--json]
+  ocx combo show <id> [--json]
+  ocx combo set <id> --targets <provider/model[:weight],...>
+      [--strategy <failover|round-robin>] [--sticky <1-100>]
+      [--effort <low|medium|high|xhigh|max|ultra|->] [--alias <name|->]
+      [--rename-from <id>] [--json]
+  ocx combo remove <id> --yes [--json]`;
+
+type ComboRow = Record<string, unknown> & { id?: string; model?: string };
+
+function parseTargets(value: string): Array<{ provider: string; model: string; weight?: number }> {
+  const targets = value.split(",").map(part => part.trim()).filter(Boolean).map(part => {
+    const colon = part.lastIndexOf(":");
+    let selector = part;
+    let weight: number | undefined;
+    if (colon > part.indexOf("/")) {
+      const maybeWeight = Number(part.slice(colon + 1));
+      if (Number.isInteger(maybeWeight)) {
+        selector = part.slice(0, colon);
+        weight = maybeWeight;
+      }
+    }
+    const slash = selector.indexOf("/");
+    if (slash <= 0 || slash === selector.length - 1) throw new CliUsageError(`invalid target "${part}"; use provider/model[:weight]`, USAGE);
+    const target = { provider: selector.slice(0, slash), model: selector.slice(slash + 1), ...(weight !== undefined ? { weight } : {}) };
+    if (weight !== undefined && (weight < 1 || weight > 10_000)) throw new CliUsageError(`target weight must be 1-10000: ${part}`, USAGE);
+    return target;
+  });
+  if (targets.length === 0) throw new CliUsageError("--targets requires at least one provider/model", USAGE);
+  return targets;
+}
+
+async function list(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps);
+  const rows = result.combos ?? [];
+  printData(result, wantsJson, rows.length ? rows.map(row => `${String(row.id)}  ${String(row.model ?? `combo/${row.id}`)}`) : ["No combos configured."]);
+}
+
+async function show(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const id = args.shift();
+  const wantsJson = takeFlag(args, "--json");
+  if (!id) throw new CliUsageError("combo id is required", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps);
+  const combo = (result.combos ?? []).find(row => row.id === id);
+  if (!combo) throw new CliUsageError(`unknown combo ${id}`);
+  printData(combo, wantsJson);
+}
+
+async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const id = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  if (!id) throw new CliUsageError("combo id is required", USAGE);
+  const targetsRaw = takeOption(args, "--targets");
+  if (!targetsRaw) throw new CliUsageError("--targets is required", USAGE);
+  const strategy = takeOption(args, "--strategy") ?? "failover";
+  if (strategy !== "failover" && strategy !== "round-robin") throw new CliUsageError("--strategy must be failover or round-robin", USAGE);
+  const stickyLimit = takeIntegerOption(args, "--sticky", { min: 1 }) ?? 1;
+  if (stickyLimit > 100) throw new CliUsageError("--sticky must be <= 100", USAGE);
+  const effort = takeOption(args, "--effort");
+  const alias = takeOption(args, "--alias");
+  const renameFrom = takeOption(args, "--rename-from");
+  rejectArgs(args, USAGE);
+  const combo: Record<string, unknown> = {
+    strategy,
+    stickyLimit,
+    targets: parseTargets(targetsRaw),
+  };
+  if (effort !== undefined) combo.defaultEffort = effort === "-" ? null : effort;
+  if (alias !== undefined) combo.alias = alias === "-" ? "" : alias;
+  const result = await runtimeRequest("/api/combos", {
+    method: "PUT",
+    body: JSON.stringify({ id, combo, ...(renameFrom ? { renameFrom } : {}) }),
+  }, deps);
+  printData(result, wantsJson, [`Saved combo ${id}.`]);
+}
+
+async function remove(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const id = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const yes = takeFlag(args, "--yes");
+  if (!id) throw new CliUsageError("combo id is required", USAGE);
+  if (!yes) throw new CliUsageError("remove requires --yes", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest(`/api/combos?id=${encodeURIComponent(id)}`, { method: "DELETE" }, deps);
+  printData(result, wantsJson, [`Removed combo ${id}.`]);
+}
+
+export async function handleComboCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "list", ...rest] = argv;
+    if (sub === "list") await list(rest, deps);
+    else if (sub === "show") await show(rest, deps);
+    else if (sub === "set" || sub === "create" || sub === "update") await set(rest, deps);
+    else if (sub === "remove" || sub === "delete") await remove(rest, deps);
+    else throw new CliUsageError(`unknown combo command ${sub}`, USAGE);
+  });
+}
+
+export const COMBO_USAGE = USAGE;