@bitkyc08/opencodex 2.65.0 → 2.66.0

package/src/cli/account-target.ts

@@ -0,0 +1,115 @@
+/**
+ * Turn the account argument of a Codex pool command into a stored account id.
+ *
+ * `main` is the Codex App login. Anything else is tried as an id first and then as the
+ * display alias `ocx account alias` recorded, so an operator can type the name they gave an
+ * account instead of its generated id. An alias matches exactly, or case-insensitively when
+ * that still names one account; two accounts sharing a name is an error, not a guess.
+ */
+import { MAIN_CODEX_ACCOUNT_ID } from "../codex/account-id";
+import { apiError, apiJson, fetchRows, type AccountDeps } from "./account-api";
+
+/** `ocx account use <provider> auto`: clear the manual selection instead of making one. */
+export const AUTO_ACCOUNT_ARGUMENT = "auto";
+const MAIN_ALIAS = "main";
+
+export type CodexAccountTarget =
+  | { id: string }
+  | { error: string; kind: "not_found" | "ambiguous" | "reserved" }
+  | { networkDown: true; transportError?: string };
+
+/** Built-in selectors cannot be reused as Codex account aliases. */
+export function isReservedCodexAccountWord(value: string): boolean {
+  const word = value.toLowerCase();
+  return word === AUTO_ACCOUNT_ARGUMENT || word === MAIN_ALIAS || word === MAIN_CODEX_ACCOUNT_ID;
+}
+
+/** Keep a local resolution miss consistent with the account API's not-found exit code. */
+export function reportCodexAccountTargetError(target: Extract<CodexAccountTarget, { error: string }>): number {
+  return apiError({ error: target.error }, target.error, target.kind === "not_found" ? 404 : 400);
+}
+
+export async function resolveCodexAccountTarget(
+  deps: AccountDeps,
+  baseUrl: string,
+  requested: string,
+): Promise<CodexAccountTarget> {
+  if (requested === MAIN_ALIAS || requested === MAIN_CODEX_ACCOUNT_ID) return { id: MAIN_CODEX_ACCOUNT_ID };
+  if (isReservedCodexAccountWord(requested)) {
+    return { error: `"${requested}" is reserved; it clears the selection with \`ocx account use\` and names no account`, kind: "reserved" };
+  }
+  const res = await apiJson(deps, baseUrl, "GET", "/api/codex-auth/accounts");
+  if (res.status === 0) return { networkDown: true, transportError: res.transportError };
+  // The list is only needed to turn an alias into an id. If the proxy cannot produce it, send
+  // the argument as the id it may already be and let the route answer, as the CLI always did.
+  if (res.status !== 200) return { id: requested };
+  const accounts = (Array.isArray(res.json.accounts) ? res.json.accounts : [])
+    .filter((entry): entry is { id: string; alias?: unknown } =>
+      typeof entry === "object" && entry !== null && typeof (entry as { id?: unknown }).id === "string");
+  if (accounts.some(account => account.id === requested)) return { id: requested };
+  const exact = accounts.filter(account => account.alias === requested);
+  const matches = exact.length > 0
+    ? exact
+    : accounts.filter(account => typeof account.alias === "string" && account.alias.toLowerCase() === requested.toLowerCase());
+  if (matches.length === 1) return { id: matches[0].id };
+  if (matches.length > 1) {
+    return { error: `alias "${requested}" names ${matches.length} accounts; use the account id`, kind: "ambiguous" };
+  }
+  return { error: `Account not found: no Codex account has the id or alias "${requested}"`, kind: "not_found" };
+}
+
+export type CodexUseTarget =
+  | { accountId: string | null }
+  | Extract<CodexAccountTarget, { error: string }>
+  | { networkDown: true; transportError?: string };
+
+/** The `use` argument: `auto` clears the selection, everything else resolves like any other verb. */
+export async function resolveCodexUseTarget(
+  deps: AccountDeps,
+  baseUrl: string,
+  requested: string,
+): Promise<CodexUseTarget> {
+  if (requested === AUTO_ACCOUNT_ARGUMENT) return { accountId: null };
+  const target = await resolveCodexAccountTarget(deps, baseUrl, requested);
+  if ("networkDown" in target) return target;
+  if ("error" in target) return target;
+  return { accountId: target.id };
+}
+
+function displayCodexId(id: string): string {
+  return id === MAIN_CODEX_ACCOUNT_ID ? MAIN_ALIAS : id;
+}
+
+/**
+ * What the switch means for running work, printed to stderr after the route accepted it. The
+ * route reports `pinDrainReason` only when routing would drop the pin it just recorded, so an
+ * absent field means the pin survives (#4521); `null` means the pin was cleared and the pool
+ * decides from here.
+ */
+export async function explainCodexUseOutcome(
+  deps: AccountDeps,
+  baseUrl: string,
+  name: string,
+  activeId: string | null,
+  pinDrainReason: string | undefined,
+): Promise<void> {
+  if (activeId === null) {
+    console.error("Takes effect from the next unbound request; running threads keep their account until it cannot serve.");
+    return;
+  }
+  console.error("Takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.");
+  const state = await fetchRows(deps, baseUrl, name, "codex");
+  const selected = state.rows.find(row => row.id === activeId);
+  const threshold = selected?.autoSwitchThresholdOverride ?? state.autoSwitchThreshold;
+  if (pinDrainReason !== undefined) {
+    // "may override" is the right caveat for a pin that is currently fine and could be
+    // overtaken later. It is the wrong sentence for one the next request will discard, and
+    // printing only that is what left the operator believing the account was pinned.
+    const because = pinDrainReason === "quota_threshold"
+      ? `is at or above the auto-switch threshold${threshold !== undefined ? ` (${threshold}%)` : ""}`
+      : `cannot currently be selected (${pinDrainReason})`;
+    console.error(`Note: ${displayCodexId(activeId)} ${because}, so routing releases this pin on its next request.`);
+  } else if (state.status === 200 && typeof threshold === "number" && threshold > 0) {
+    console.error(`Note: auto-switch (threshold ${threshold}%) may override this pin.`);
+  }
+}

package/src/cli/account.ts

@@ -1,5 +1,6 @@
 /** `ocx account` — list and switch provider credentials (issue #180). */
 import { loadConfig } from "../config";
+import { explainCodexUseOutcome, reportCodexAccountTargetError, resolveCodexUseTarget } from "./account-target";
 import { providerCodexAccountMode } from "../providers/registry";
 import type { OcxConfig } from "../types";
 import {
@@ -43,18 +44,18 @@ const ACCOUNT_USAGE = `Usage:
   ocx account list [provider] [--json] [--all] [--quota [--refresh]]
   ocx account history openai <pool-account-id> [--limit <1-200>] [--json]
   ocx account current <provider> [--json]
-  ocx account use <provider> <account-or-key-id|main> [--json]
+  ocx account use <provider> <account-or-key-id|alias|main|auto> [--json]
   ocx account refresh <provider> [--json]
   ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
-  ocx account alias <provider> <account-or-key-id> <display-name|-> [--json]
-  ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
-  ocx account pause <provider> <account-id|main> [--json]
-  ocx account resume <provider> <account-id|main> [--json]
+  ocx account alias <provider> <account-or-key-id|alias> <display-name|-> [--json]
+  ocx account priority <provider> <account-id|alias|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
+  ocx account pause <provider> <account-id|alias|main> [--json]
+  ocx account resume <provider> <account-id|alias|main> [--json]
   ocx account pause-exhausted <provider> [--json]
   ocx account strategy <provider> [<quota|round-robin|fill-first|reset-first>] [--json]
   ocx account sticky <provider> [<1-100>] [--json]
-  ocx account remove <provider> <account-or-key-id|main> --yes [--json]
-  ocx account clear-cooldown <provider> <account-id|main> [--json]
+  ocx account remove <provider> <account-or-key-id|alias|main> --yes [--json]
+  ocx account clear-cooldown <provider> <account-id|alias|main> [--json]
   ocx account add-key <provider> [--label <label>] [--json]
   ocx account import <provider> --format <format> (--file <path>|--stdin) [--json]
   ocx account import-orca --source <orca-data-directory> --registry <orca-data.json> [--apply] [--json]
@@ -66,7 +67,9 @@ const ACCOUNT_USAGE = `Usage:
   ocx account main <doctor|list|register|add|reauth|switch|recover> ...
 
 List and switch provider accounts and API-key pools (masked output only).
-'main' selects the Codex App login for the openai account pool.`;
+'main' selects the Codex App login for the openai account pool; 'auto' clears the
+selection so the pool places work by its own strategy. A Codex account can be named
+by the alias set with 'ocx account alias' wherever an id is accepted.`;
 
 function consumeFlag(args: string[], flag: string): boolean {
   const idx = args.indexOf(flag);
@@ -310,9 +313,12 @@ async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
   if (!baseUrl) return proxyUnreachable();
 
   let res: ApiResult;
-  let activeId: string;
+  let activeId: string | null;
   if (c.type === "codex") {
-    activeId = id === MAIN_ALIAS ? MAIN_CODEX_ID : id;
+    const target = await resolveCodexUseTarget(deps, baseUrl, id);
+    if ("networkDown" in target) return proxyUnreachable(target.transportError);
+    if ("error" in target) return reportCodexAccountTargetError(target);
+    activeId = target.accountId;
     res = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/active", { accountId: activeId });
   } else if (c.type === "oauth") {
     activeId = id;
@@ -336,25 +342,11 @@ async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
       ...(pinDrainReason !== undefined ? { pinDrained: true, pinDrainReason } : {}),
     }, null, 2));
   } else {
-    console.log(`${name}: active ${c.type === "api-key" ? "key" : "account"} is now ${displayId(activeId)}`);
-  }
-  if (c.type === "codex") {
-    console.error("Takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.");
-    const state = await fetchRows(deps, baseUrl, name, "codex");
-    const selected = state.rows.find(row => row.id === activeId);
-    const threshold = selected?.autoSwitchThresholdOverride ?? state.autoSwitchThreshold;
-    if (pinDrainReason !== undefined) {
-      // "may override" is the right caveat for a pin that is currently fine and could be
-      // overtaken later. It is the wrong sentence for one the next request will discard, and
-      // printing only that is what left the operator believing the account was pinned.
-      const because = pinDrainReason === "quota_threshold"
-        ? `is at or above the auto-switch threshold${threshold !== undefined ? ` (${threshold}%)` : ""}`
-        : `cannot currently be selected (${pinDrainReason})`;
-      console.error(`Note: ${displayId(activeId)} ${because}, so routing releases this pin on its next request.`);
-    } else if (state.status === 200 && typeof threshold === "number" && threshold > 0) {
-      console.error(`Note: auto-switch (threshold ${threshold}%) may override this pin.`);
-    }
+    console.log(activeId === null
+      ? `${name}: automatic account selection (pin cleared)`
+      : `${name}: active ${c.type === "api-key" ? "key" : "account"} is now ${displayId(activeId)}`);
   }
+  if (c.type === "codex") await explainCodexUseOutcome(deps, baseUrl, name, activeId, pinDrainReason);
   return 0;
 }
 

package/src/cli/agent.ts

@@ -220,9 +220,18 @@ async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const apply = (result as { codexWebSearch?: { applied?: boolean; reason?: string; detail?: string } } | null)?.codexWebSearch;
   if (apply && apply.reason !== "not_requested") {
     const detail = typeof apply.detail === "string" && apply.detail.length > 0 ? ` Details: ${apply.detail}` : "";
+    // `ocx sync` re-runs the same injection the external provider owns — the retry
+    // advice is meaningless on that outcome, same as the Desktop-switch report.
+    const retry = apply.reason === "external_provider"
+      ? ""
+      : apply.reason === "ownership_undetermined"
+      ? " Resolve the reported config.toml read error, then inspect 'ocx system settings --json'."
+      : apply.reason === "integration_disabled"
+      ? " Enable Codex integration before applying the stored settings."
+      : " Run 'ocx sync' to apply the stored settings.";
     lines.push(apply.applied === true
       ? "Codex config: ~/.codex/config.toml was rewritten."
-      : `Codex config: ~/.codex/config.toml was not rewritten because ${desktopSwitchApplyReason(apply.reason)}.${detail} Run 'ocx sync' to apply the stored settings.`);
+      : `Codex config: ~/.codex/config.toml was not rewritten because ${desktopSwitchApplyReason(apply.reason)}.${detail}${retry}`);
   }
   printData(result, wantsJson, lines);
 }

package/src/cli/api-protocols.ts

@@ -0,0 +1,206 @@
+/**
+ * `ocx api protocols | explain | policy`: the CLI side of the protocol management routes
+ * (`src/server/management/protocol-routes.ts`).
+ *
+ * - `protocols` reads `GET /api/protocols` (optionally `?provider=<name>`).
+ * - `explain` posts `POST /api/protocols/plan`: a preview computed from config that sends
+ *   nothing upstream.
+ * - `policy` with no setting flag reads the same GET; with one it sends
+ *   `PATCH /api/protocols/settings`, which changes the operator's config. It is only ever
+ *   invoked explicitly: nothing in the CLI calls it on the operator's behalf.
+ *
+ * Validation of values the server owns (rollout switch names, cross-field rules) stays on the
+ * server, so the two cannot drift; the CLI rejects only malformed argv.
+ */
+import { isProtocol } from "../protocols/contract";
+import { isProtocolFeature } from "../protocols/features";
+import {
+  CliUsageError,
+  csv,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx api protocols [--provider <name>] [--json]
+  ocx api explain --model <id> --inbound <responses|chat|messages> [--feature <key>[,<key>]]... [--json]
+  ocx api policy [--messages <on|off>] [--unrepresentable <legacy|reject>]
+      [--rollout <switch>=<on|off>]... [--json]`;
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Every value of a repeatable option, in argv order. */
+function takeRepeated(args: string[], flag: string): string[] {
+  const values: string[] = [];
+  for (let value = takeOption(args, flag); value !== undefined; value = takeOption(args, flag)) values.push(value);
+  return values;
+}
+
+function onOff(flag: string, raw: string): boolean {
+  if (raw === "on") return true;
+  if (raw === "off") return false;
+  throw new CliUsageError(`${flag} must be on or off`, USAGE);
+}
+
+function text(value: unknown): string {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : "-";
+}
+
+function list(value: unknown): string {
+  return Array.isArray(value) && value.length > 0 ? value.map(text).join(", ") : "none";
+}
+
+/** Human view of the `GET /api/protocols` body (also the PATCH answer). */
+export function protocolInfoLines(payload: unknown): string[] {
+  if (!isRec(payload)) return [text(payload)];
+  const lines = [
+    `Contract: ${text(payload.contractVersion)}  policy revision: ${text(payload.policyRevision)}`,
+  ];
+  if (isRec(payload.surfaces)) {
+    for (const [name, surface] of Object.entries(payload.surfaces)) {
+      if (!isRec(surface)) continue;
+      lines.push(`API ${name}: ${surface.enabled === true ? "open" : "closed"} (${text(surface.source)})`);
+    }
+  }
+  if (isRec(payload.settings)) {
+    lines.push(`Unrepresentable features: ${text(payload.settings.unrepresentable)}`);
+    if (isRec(payload.settings.rollout)) {
+      for (const [name, on] of Object.entries(payload.settings.rollout)) {
+        lines.push(`Rollout ${name}: ${on === true ? "on" : "off"}`);
+      }
+    }
+  }
+  if (Array.isArray(payload.features)) lines.push(`Features: ${payload.features.length} known (--json lists them)`);
+  if (isRec(payload.provider)) {
+    const provider = payload.provider;
+    lines.push(
+      `Provider ${text(provider.name)}: adapter ${text(provider.adapter)} (${text(provider.adapterSource)}), `
+        + `upstream ${text(provider.upstream)}, auth ${text(provider.authMode)}`,
+    );
+    const overrides = Array.isArray(provider.modelOverrides) ? provider.modelOverrides : [];
+    for (const override of overrides) {
+      if (!isRec(override)) continue;
+      lines.push(`  model ${text(override.model)}: adapter ${text(override.adapter)} (${text(override.source)})`);
+    }
+    if (provider.modelOverridesTruncated === true) lines.push("  more model overrides exist; --json has the same capped list");
+  }
+  return lines;
+}
+
+/** Human view of a `ProtocolPlanV1`. */
+export function protocolPlanLines(plan: unknown): string[] {
+  if (!isRec(plan)) return [text(plan)];
+  const lines = [
+    `${text(plan.inbound)} ${text(plan.requestedModel)}: ${text(plan.mode)} (${text(plan.routeKind)} route, ${text(plan.basis)})`,
+    `Reasons: ${list(plan.reasonCodes)}`,
+  ];
+  const candidates = Array.isArray(plan.candidates) ? plan.candidates : [];
+  for (const candidate of candidates) {
+    if (!isRec(candidate)) continue;
+    const path = Array.isArray(candidate.requestPath) && candidate.requestPath.length > 0
+      ? candidate.requestPath.map(text).join(" > ")
+      : "no path";
+    lines.push(
+      `  ${text(candidate.provider)}/${text(candidate.model)}: ${text(candidate.mode)} ${path}`
+        + `${candidate.eligible === false ? " (refused under reject)" : ""}`,
+    );
+  }
+  lines.push(`Guaranteed features: ${list(plan.guaranteedFeatures)}`);
+  lines.push(`Partial features: ${list(plan.partialFeatures)}`);
+  return lines;
+}
+
+async function protocols(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const provider = takeOption(args, "--provider");
+  rejectArgs(args, USAGE);
+  const path = provider === undefined ? "/api/protocols" : `/api/protocols?provider=${encodeURIComponent(provider)}`;
+  const result = await runtimeRequest(path, {}, deps);
+  printData(result, wantsJson, protocolInfoLines(result));
+}
+
+async function explain(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const model = takeOption(args, "--model");
+  const inbound = takeOption(args, "--inbound");
+  const features = takeRepeated(args, "--feature").flatMap(value => csv(value) ?? []);
+  rejectArgs(args, USAGE);
+  if (!model) throw new CliUsageError("--model is required", USAGE);
+  if (!isProtocol(inbound)) throw new CliUsageError("--inbound must be responses, chat or messages", USAGE);
+  const unknown = features.filter(feature => !isProtocolFeature(feature));
+  if (unknown.length > 0) throw new CliUsageError("--feature names a feature this CLI does not know; `ocx api protocols --json` lists them", USAGE);
+  const body = { model, inbound, ...(features.length > 0 ? { features: [...new Set(features)] } : {}) };
+  const result = await runtimeRequest("/api/protocols/plan", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  }, deps);
+  printData(result, wantsJson, protocolPlanLines(result));
+}
+
+/** The `PATCH /api/protocols/settings` body the flags describe, or `undefined` for a read. */
+export function protocolPolicyPatch(args: string[]): Rec | undefined {
+  const messages = takeOption(args, "--messages");
+  const unrepresentable = takeOption(args, "--unrepresentable");
+  const rolloutArgs = takeRepeated(args, "--rollout");
+  const body: Rec = {};
+  if (messages !== undefined) body.messagesEnabled = onOff("--messages", messages);
+  if (unrepresentable !== undefined) {
+    if (unrepresentable !== "legacy" && unrepresentable !== "reject") {
+      throw new CliUsageError("--unrepresentable must be legacy or reject", USAGE);
+    }
+    body.unrepresentable = unrepresentable;
+  }
+  if (rolloutArgs.length > 0) {
+    const rollout: Rec = {};
+    for (const entry of rolloutArgs) {
+      const match = /^([A-Za-z]+)=(on|off)$/.exec(entry);
+      if (!match) throw new CliUsageError("--rollout takes <switch>=<on|off>", USAGE);
+      if (Object.hasOwn(rollout, match[1]!)) throw new CliUsageError("--rollout names the same switch twice", USAGE);
+      rollout[match[1]!] = match[2] === "on";
+    }
+    body.rollout = rollout;
+  }
+  return Object.keys(body).length > 0 ? body : undefined;
+}
+
+async function policy(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const patch = protocolPolicyPatch(args);
+  rejectArgs(args, USAGE);
+  // No setting flag means show. A read must not write the value it is reporting.
+  if (!patch) {
+    const result = await runtimeRequest("/api/protocols", {}, deps);
+    printData(result, wantsJson, protocolInfoLines(result));
+    return;
+  }
+  const result = await runtimeRequest("/api/protocols/settings", {
+    method: "PATCH",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(patch),
+  }, deps);
+  printData(result, wantsJson, ["Protocol settings updated.", ...protocolInfoLines(result)]);
+}
+
+export async function handleApiCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub, ...rest] = argv;
+    if (sub === "protocols") await protocols(rest, deps);
+    else if (sub === "explain") await explain(rest, deps);
+    else if (sub === "policy") await policy(rest, deps);
+    else throw new CliUsageError(sub ? `unknown api command ${sub}` : "an api command is required", USAGE);
+  });
+}
+
+export const API_USAGE = USAGE;

package/src/cli/capabilities.ts

@@ -95,6 +95,47 @@ export const HEAD_CAPABILITIES: readonly HeadCapability[] = [
  * A capability must not name a route the command does not actually fetch.
  */
 export const CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["link", "port"],
+    summary: "Allocate a free loopback port for a remote home link.",
+    routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the selected port as JSON." }],
+    mutates: false,
+    json: "payload",
+  },
+  {
+    command: ["link", "issue"],
+    summary: "Issue one link credential and record its tunnel metadata.",
+    routes: [{ method: "POST", path: "/api/link/issue" }],
+    flags: [
+      { name: "--alias", value: "string", required: true, summary: "SSH host alias for the linked machine." },
+      { name: "--tunnel-port", value: "number", required: true, summary: "Remote loopback port for the reverse tunnel." },
+      { name: "--json", value: "boolean", summary: "Emit the issue result as JSON." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: ["Requires the running proxy's admin token on loopback; the one-time data key is printed only on stdout."],
+  },
+  {
+    command: ["link", "status"],
+    summary: "Read link listener and tunnel status.",
+    routes: [{ method: "GET", path: "/api/link/status" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the K16 status payload as JSON." }],
+    mutates: false,
+    json: "payload",
+  },
+  {
+    command: ["link", "revoke"],
+    summary: "Revoke a link credential and remove its link record.",
+    routes: [{ method: "DELETE", path: "/api/link/{id}" }],
+    flags: [
+      { name: "--link-id", value: "string", required: true, summary: "Link id to revoke." },
+      { name: "--json", value: "boolean", summary: "Emit the revoked link id as JSON." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: ["Requires the running proxy's admin token on loopback."],
+  },
   {
     "command": [
       "remote-workspace",
@@ -946,6 +987,51 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: ["A bare invocation reads and never writes."],
   },
+  {
+    command: ["api", "protocols"],
+    summary: "Read the protocol contract version, API surfaces, protocol settings and feature vocabulary.",
+    routes: [{ method: "GET", path: "/api/protocols" }],
+    flags: [
+      { name: "--provider", value: "string", summary: "Add one configured provider's upstream wire and who decided it." },
+      { name: "--json", value: "boolean", summary: "Emit the GET /api/protocols body." },
+    ],
+    mutates: false,
+    json: "payload",
+  },
+  {
+    command: ["api", "explain"],
+    summary: "Preview the request path a model would take from one inbound API, computed from config.",
+    routes: [{ method: "POST", path: "/api/protocols/plan" }],
+    flags: [
+      { name: "--model", value: "string", required: true, summary: "Model selector as a client would send it." },
+      { name: "--inbound", value: "string", required: true, summary: "Inbound API: responses, chat or messages." },
+      { name: "--feature", value: "string", summary: "Request feature key to judge; repeatable or comma-separated." },
+      { name: "--json", value: "boolean", summary: "Emit the ProtocolPlanV1 preview." },
+    ],
+    mutates: false,
+    json: "payload",
+    details: ["A read-only POST: nothing is sent upstream, no combo state advances and the input is not logged."],
+  },
+  {
+    command: ["api", "policy"],
+    summary: "Read the protocol policy, or change the Messages surface, unrepresentable policy and rollout switches.",
+    routes: [
+      { method: "GET", path: "/api/protocols" },
+      { method: "PATCH", path: "/api/protocols/settings" },
+    ],
+    flags: [
+      { name: "--messages", value: "string", summary: "Open or close the Messages API: on or off. Off also turns the Claude integration off." },
+      { name: "--unrepresentable", value: "string", summary: "legacy keeps today's behavior; reject refuses a request its path cannot carry." },
+      { name: "--rollout", value: "string", summary: "One switch as name=on or name=off; repeatable. Every switch defaults off." },
+      { name: "--json", value: "boolean", summary: "Emit the resulting GET /api/protocols body." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: [
+      "A bare invocation reads and never writes.",
+      "A setting flag changes the operator's config; run it only when the operator asks for that change.",
+    ],
+  },
 ];
 
 /** Capabilities that drive `route`, for `ocx capabilities --route`. */

package/src/cli/combo.ts

@@ -14,7 +14,7 @@ const USAGE = `Usage:
   ocx combo [list] [--json]
   ocx combo show <id> [--json]
   ocx combo set <id> --targets <provider/model[:weight],...>
-      [--strategy <failover|round-robin|random|least-used|reset-window>] [--sticky <1-100>]
+      [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100>]
       [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force>]
       (force overrides valid client effort and can increase cost/latency) [--alias <name|->]
       [--native-alias] [--display-name <label|->]
@@ -74,7 +74,7 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   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" && strategy !== "random" && strategy !== "least-used" && strategy !== "reset-window") throw new CliUsageError("--strategy must be failover, round-robin, random, least-used, or reset-window", USAGE);
+  if (strategy !== "failover" && strategy !== "round-robin" && strategy !== "random" && strategy !== "least-used" && strategy !== "reset-window" && strategy !== "jev") throw new CliUsageError("--strategy must be failover, round-robin, random, least-used, reset-window, or jev", USAGE);
   const stickyLimit = takeIntegerOption(args, "--sticky", { min: 1 });
   if (stickyLimit !== undefined) {
     if (stickyLimit > 100) throw new CliUsageError("--sticky must be <= 100", USAGE);