@iislee/opencodex 2.11.0 → 2.35.0

package/src/cli/minimax.ts

@@ -0,0 +1,497 @@
+/**
+ * MiniMax client launchers.
+ *
+ * `ocx mcode` uses the managed `custom_provider.opencodex` block written by the
+ * existing file-integration subsystem. `ocx mmx` is intentionally text-only:
+ * the official platform CLI's text commands speak Anthropic Messages, while its
+ * image/video/speech/music/search/quota endpoints are MiniMax-specific APIs that
+ * OpenCodex does not claim to implement.
+ */
+import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ClientPathError, mcodeConfigPath, LOOPBACK_API_KEY_PLACEHOLDER } from "../clients/config-export";
+import { loadConfig } from "../config";
+import { clearableDeadline } from "../lib/abort";
+import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
+import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { commandInvocation } from "../lib/win-exec";
+import { isLoopbackHostname } from "../server/auth-cors";
+import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
+import type { OcxConfig } from "../types";
+import { opencodeProxyStartEnv } from "./opencode";
+
+export interface MinimaxLaunchEnv {
+  [key: string]: string | undefined;
+}
+
+export interface MmxTextBridge {
+  baseUrl: string;
+  port: number;
+  stop(): Promise<void>;
+}
+
+export interface MmxTextBridgeOptions {
+  /** Optional outer guard; production delegates timeout policy to `/v1/messages`. */
+  headerTimeoutMs?: number;
+}
+
+export interface MmxTerminationTarget {
+  pid?: number;
+  exitCode: number | null;
+  signalCode: NodeJS.Signals | null;
+  kill(signal?: NodeJS.Signals | number): boolean;
+}
+
+export interface MmxTerminationDeps {
+  platform?: NodeJS.Platform;
+  killWindowsTree?: (pid: number) => void;
+}
+
+export interface MmxSignalHost {
+  on(signal: "SIGINT" | "SIGTERM", listener: () => void): unknown;
+  off(signal: "SIGINT" | "SIGTERM", listener: () => void): unknown;
+}
+
+export interface MmxTerminationHandlersOptions {
+  getChild: () => MmxTerminationTarget | null;
+  cleanup: () => Promise<void>;
+  host?: MmxSignalHost;
+  now?: () => number;
+  terminationDeps?: MmxTerminationDeps;
+  onCleanupError?: (error: unknown) => void;
+}
+
+const MMX_TERMINATION_DUPLICATE_WINDOW_MS = 500;
+
+const MMX_CHILD_OWNED_ENV_KEYS = new Set([
+  "MMX_CONFIG_DIR",
+  "MINIMAX_BASE_URL",
+  "MINIMAX_REGION",
+  "MINIMAX_API_KEY",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+]);
+
+const MMX_GLOBAL_BOOLEAN_FLAGS = new Set([
+  "--quiet",
+  "--verbose",
+  "--no-color",
+  "--dry-run",
+  "--non-interactive",
+  "--yes",
+  "--async",
+  "--stream",
+  "--no-stream",
+  "--no-wait",
+  "--help",
+  "--version",
+]);
+
+/** Mirrors the official mmx command scanner's global-flag skipping behavior. */
+export function mmxCommandPath(argv: readonly string[]): string[] {
+  const path: string[] = [];
+  for (let index = 0; index < argv.length;) {
+    const arg = argv[index]!;
+    if (arg === "--") break;
+    if (arg.startsWith("--")) {
+      const equals = arg.indexOf("=");
+      const name = equals >= 0 ? arg.slice(0, equals) : arg;
+      index += equals < 0 && !MMX_GLOBAL_BOOLEAN_FLAGS.has(name) ? 2 : 1;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      index += 1;
+      continue;
+    }
+    path.push(arg);
+    index += 1;
+  }
+  return path;
+}
+
+/** Caller credentials and destinations may never override the proxy wrapper. */
+export function mmxUnsafeOverride(argv: readonly string[]): string | null {
+  for (const arg of argv) {
+    if (arg === "--api-key" || arg.startsWith("--api-key=")) return "--api-key";
+    if (arg === "--base-url" || arg.startsWith("--base-url=")) return "--base-url";
+    if (arg === "--region" || arg.startsWith("--region=")) return "--region";
+  }
+  return null;
+}
+
+export function buildMmxEnv(
+  live: Pick<LiveProxy, "hostname" | "port">,
+  configDir: string,
+  base: MinimaxLaunchEnv = process.env,
+): MinimaxLaunchEnv {
+  const env: MinimaxLaunchEnv = { ...base };
+  // The official MMX client installs one ProxyAgent whenever any proxy variable
+  // is present and does not apply NO_PROXY. Its OpenCodex destination is always
+  // loopback, so carrying these variables could send the request off-machine.
+  // Windows environment names are case-insensitive; strip every inherited
+  // spelling before installing the wrapper-owned values below.
+  for (const key of Object.keys(env)) {
+    if (MMX_CHILD_OWNED_ENV_KEYS.has(key.toUpperCase())) delete env[key];
+  }
+  env.MMX_CONFIG_DIR = configDir;
+  env.MINIMAX_BASE_URL = `http://${probeHostname(live.hostname)}:${live.port}`;
+  // Prevent a parent-shell region from triggering key detection against the
+  // official MiniMax hosts. The base URL above remains authoritative.
+  env.MINIMAX_REGION = "global";
+  return env;
+}
+
+/**
+ * MMX hard-codes `/anthropic/v1/messages` below its configured base URL while
+ * OpenCodex already exposes the canonical Anthropic data plane at
+ * `/v1/messages`. Keep that client-specific path adaptation inside the checked
+ * launcher instead of widening the proxy server's authentication surface.
+ */
+export function startMmxTextBridge(
+  live: Pick<LiveProxy, "hostname" | "port">,
+  options: MmxTextBridgeOptions = {},
+): MmxTextBridge {
+  const upstreamOrigin = `http://${probeHostname(live.hostname)}:${live.port}`;
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    async fetch(req) {
+      const incoming = new URL(req.url);
+      const canonicalPath = incoming.pathname === "/anthropic/v1/messages"
+        ? "/v1/messages"
+        : incoming.pathname === "/anthropic/v1/messages/count_tokens"
+          ? "/v1/messages/count_tokens"
+          : null;
+      if (req.method !== "POST" || !canonicalPath) {
+        return Response.json({
+          type: "error",
+          error: { type: "not_found_error", message: "unsupported MMX bridge route" },
+        }, { status: 404 });
+      }
+
+      const target = new URL(canonicalPath, `${upstreamOrigin}/`);
+      target.search = incoming.search;
+      const headers = new Headers(req.headers);
+      // The bridge is loopback-only and OpenCodex does not require a real key
+      // there. Pin the public placeholder even if a future MMX release loads a
+      // credential from somewhere outside the isolated config directory.
+      headers.delete("authorization");
+      headers.delete("x-opencodex-api-key");
+      headers.set("x-api-key", LOOPBACK_API_KEY_PLACEHOLDER);
+      headers.delete("host");
+      headers.delete("content-length");
+      // The canonical data plane owns its configured response-header, retry,
+      // and stream-stall budgets. An extra default here would cut off valid
+      // non-streaming or failover completions before their real response.
+      const headerDeadline = options.headerTimeoutMs === undefined
+        ? null
+        : clearableDeadline(options.headerTimeoutMs, req.signal);
+      try {
+        const upstreamRequest = new Request(target, {
+          method: "POST",
+          headers,
+          body: req.body,
+          signal: headerDeadline?.signal ?? req.signal,
+        });
+        return await fetch(upstreamRequest, {
+          // Override HTTP(S)_PROXY with the loopback listener itself. Bun sends
+          // the HTTP proxy-form request directly to this exact origin, so the
+          // hop cannot leave the machine even when the parent has proxy vars.
+          proxy: { url: upstreamOrigin },
+        });
+      } catch {
+        return Response.json({
+          type: "error",
+          error: { type: "api_error", message: "OpenCodex proxy unavailable" },
+        }, { status: 502 });
+      } finally {
+        // Once response headers arrive, streaming body cancellation remains
+        // linked to the client while this response-header timer is disarmed.
+        headerDeadline?.clear();
+      }
+    },
+  });
+  const bridgePort = server.port;
+  if (bridgePort === undefined) {
+    void server.stop(true);
+    throw new Error("MMX text bridge did not receive a TCP port");
+  }
+  return {
+    baseUrl: `http://127.0.0.1:${bridgePort}`,
+    port: bridgePort,
+    stop: () => server.stop(true),
+  };
+}
+
+function normalizedMcodeBaseUrl(value: string): string | null {
+  try {
+    const url = new URL(value);
+    if (
+      url.username
+      || url.password
+      || (url.pathname !== "" && url.pathname !== "/")
+      || url.search
+      || url.hash
+    ) return null;
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+
+/** Read only the provider destination; never return or log the persisted key. */
+export function mcodeOpenCodexBaseUrl(text: string): string | null {
+  try {
+    const parsed = Bun.YAML.parse(text) as {
+      custom_provider?: { opencodex?: { options?: { baseURL?: unknown } } };
+    };
+    const baseURL = parsed?.custom_provider?.opencodex?.options?.baseURL;
+    return typeof baseURL === "string" ? baseURL : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Reject stale runtime metadata that points a loopback-only launcher off-machine. */
+export function usableMinimaxLiveProxy(live: LiveProxy | null): LiveProxy | null {
+  if (!live) return null;
+  return isLoopbackHostname(probeHostname(live.hostname)) ? live : null;
+}
+
+async function ensureProxy(config: OcxConfig): Promise<LiveProxy | null> {
+  const live = usableMinimaxLiveProxy(await findLiveProxy());
+  if (live) return live;
+  const pinPort = typeof config.port === "number" && config.port > 0 ? config.port : 10100;
+  const child = spawn(process.execPath, selfLaunchArgv(["start", "--port", String(pinPort)]), {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    // Reuse the established service-token lookup so a detached start works
+    // when admission lives in the hardened token file rather than this shell.
+    env: withProcessRuntimeProvenance(opencodeProxyStartEnv(process.env) as NodeJS.ProcessEnv),
+  });
+  child.on("error", () => { /* the bounded health poll reports failure */ });
+  child.unref();
+  const deadline = Date.now() + 8_000;
+  while (Date.now() < deadline) {
+    const started = usableMinimaxLiveProxy(await findLiveProxy());
+    if (started) return started;
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+  return null;
+}
+
+/** Only a root-level, single-token info request may bypass proxy isolation. */
+export function isStandaloneInformationalInvocation(
+  argv: readonly string[],
+  client: "mcode" | "mmx",
+): boolean {
+  if (argv.length !== 1) return false;
+  const arg = argv[0];
+  if (arg === "--help" || arg === "-h" || arg === "--version") return true;
+  // MMX 1.0.19 implements -v for version and does not implement -V. Preserve
+  // MCode's established -V passthrough separately.
+  return client === "mmx" ? arg === "-v" : arg === "-v" || arg === "-V";
+}
+
+/** Forward wrapper termination only while the MMX child is still live. */
+export function forwardMmxTerminationSignal(
+  child: MmxTerminationTarget,
+  signal: "SIGINT" | "SIGTERM",
+  deps: MmxTerminationDeps = {},
+): boolean {
+  if (child.exitCode !== null || child.signalCode !== null) return false;
+  try {
+    if ((deps.platform ?? process.platform) === "win32") {
+      if (!Number.isInteger(child.pid) || child.pid === undefined || child.pid <= 0) return false;
+      const killWindowsTree = deps.killWindowsTree ?? (pid => {
+        const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
+        execFileSync(taskkill, ["/PID", String(pid), "/T", "/F"], {
+          stdio: "ignore",
+          windowsHide: true,
+        });
+      });
+      killWindowsTree(child.pid);
+      return true;
+    }
+    return child.kill(signal);
+  } catch {
+    return false;
+  }
+}
+
+/** Install persistent, duplicate-aware wrapper signal handlers. */
+export function installMmxTerminationHandlers(
+  options: MmxTerminationHandlersOptions,
+): () => void {
+  const host = options.host ?? process;
+  const now = options.now ?? Date.now;
+  let lastTerminationSignalAt: number | null = null;
+  const onTerminationSignal = (signal: "SIGINT" | "SIGTERM") => {
+    const receivedAt = now();
+    // Ctrl-C reaches the foreground Bun process directly and is also
+    // forwarded by bin/ocx.mjs. Keep the listener installed and coalesce the
+    // near-simultaneous duplicate so async cleanup cannot be interrupted by
+    // the default signal action after a once-listener disappears.
+    if (
+      lastTerminationSignalAt !== null
+      && receivedAt - lastTerminationSignalAt < MMX_TERMINATION_DUPLICATE_WINDOW_MS
+    ) return;
+    lastTerminationSignalAt = receivedAt;
+    const child = options.getChild();
+    if (child) forwardMmxTerminationSignal(child, signal, options.terminationDeps);
+    try {
+      void options.cleanup().catch(error => { options.onCleanupError?.(error); });
+    } catch (error) {
+      options.onCleanupError?.(error);
+    }
+  };
+  const onSigint = () => onTerminationSignal("SIGINT");
+  const onSigterm = () => onTerminationSignal("SIGTERM");
+  host.on("SIGINT", onSigint);
+  host.on("SIGTERM", onSigterm);
+  return () => {
+    host.off("SIGINT", onSigint);
+    host.off("SIGTERM", onSigterm);
+  };
+}
+
+/** Keep signal handlers active until asynchronous bridge cleanup has settled. */
+export async function finishMmxClientCleanup(
+  cleanup: () => Promise<void>,
+  removeTerminationHandlers: () => void,
+): Promise<void> {
+  try {
+    await cleanup();
+  } finally {
+    removeTerminationHandlers();
+  }
+}
+
+function spawnClient(
+  command: "mcode" | "mmx",
+  args: readonly string[],
+  env: NodeJS.ProcessEnv,
+  installHint: string,
+  onSpawn?: (child: ChildProcess) => void,
+): Promise<number> {
+  return new Promise(resolve => {
+    const inv = commandInvocation(command, [...args]);
+    const child = spawn(inv.file, inv.args, { stdio: "inherit", env, ...inv.options });
+    onSpawn?.(child);
+    child.on("error", (error: NodeJS.ErrnoException) => {
+      console.error(error.code === "ENOENT" ? installHint : `❌ Failed to launch ${command}: ${error.message}`);
+      resolve(1);
+    });
+    child.on("exit", (code, signal) => {
+      if (process.platform === "win32" && code === 9009 && !signal) console.error(installHint);
+      resolve(signal ? 1 : code ?? 0);
+    });
+  });
+}
+
+const MCODE_INSTALL_HINT = "❌ `mcode` CLI not found. Install MiniMax Code first: https://github.com/MiniMax-AI/minimax-code";
+const MMX_INSTALL_HINT = "❌ `mmx` CLI not found. Install it first: npm install -g mmx-cli";
+
+export async function cmdMcode(args: string[]): Promise<number> {
+  if (isStandaloneInformationalInvocation(args, "mcode")) return spawnClient("mcode", args, process.env, MCODE_INSTALL_HINT);
+  const config = loadConfig();
+  if (!isLoopbackHostname(config.hostname)) {
+    console.error("❌ MiniMax Code integration is loopback-only; its config cannot carry OpenCodex's dedicated remote-admission header.");
+    return 2;
+  }
+  const live = await ensureProxy(config);
+  if (!live) {
+    console.error("❌ Proxy did not become healthy after starting.");
+    return 1;
+  }
+  let configuredBase: string | null = null;
+  try {
+    configuredBase = mcodeOpenCodexBaseUrl(readFileSync(mcodeConfigPath(process.env), "utf8"));
+  } catch (error) {
+    // Missing or unreadable is reported as not connected below. An unstable
+    // relative override needs its own message because re-enabling cannot fix it.
+    if (error instanceof ClientPathError) {
+      console.error(`❌ ${error.message}`);
+      return 2;
+    }
+  }
+  if (!configuredBase) {
+    console.error("❌ MiniMax Code is not connected. Run: ocx integration client enable --client mcode");
+    return 2;
+  }
+  const expected = `http://${probeHostname(live.hostname)}:${live.port}`;
+  if (normalizedMcodeBaseUrl(configuredBase) !== normalizedMcodeBaseUrl(expected)) {
+    console.error("❌ MiniMax Code's OpenCodex provider points at a stale proxy address. Re-run: ocx integration client enable --client mcode");
+    return 2;
+  }
+  console.error(`✅ MiniMax Code wired to ${expected}; select custom_provider:opencodex/<model> in MCode.`);
+  return spawnClient("mcode", args, process.env, MCODE_INSTALL_HINT);
+}
+
+export async function cmdMmx(args: string[]): Promise<number> {
+  if (isStandaloneInformationalInvocation(args, "mmx")) return spawnClient("mmx", args, process.env, MMX_INSTALL_HINT);
+  const unsafe = mmxUnsafeOverride(args);
+  if (unsafe) {
+    console.error(`❌ ${unsafe} is not accepted by ocx mmx because it could bypass the proxy or expose a caller credential.`);
+    return 2;
+  }
+  const commandPath = mmxCommandPath(args);
+  if (commandPath[0] !== "text") {
+    console.error("❌ ocx mmx supports only `mmx text` commands. Use plain `mmx` for MiniMax image, video, speech, music, vision, search, quota, auth, config, file, and update APIs.");
+    return 2;
+  }
+  const config = loadConfig();
+  if (!isLoopbackHostname(config.hostname)) {
+    console.error("❌ ocx mmx is loopback-only; MMX has no field for OpenCodex's dedicated remote-admission header.");
+    return 2;
+  }
+  const live = await ensureProxy(config);
+  if (!live) {
+    console.error("❌ Proxy did not become healthy after starting.");
+    return 1;
+  }
+
+  const configDir = mkdtempSync(join(tmpdir(), "opencodex-mmx-"));
+  let bridge: MmxTextBridge | null = null;
+  let mmxChild: ChildProcess | null = null;
+  let cleanupPromise: Promise<void> | null = null;
+  let removeTerminationHandlers = () => {};
+  const cleanup = (): Promise<void> => {
+    cleanupPromise ??= (async () => {
+      const activeBridge = bridge;
+      bridge = null;
+      try {
+        if (activeBridge) await activeBridge.stop();
+      } finally {
+        rmSync(configDir, { recursive: true, force: true });
+      }
+    })();
+    return cleanupPromise;
+  };
+  try {
+    // Isolate MMX from ~/.mmx OAuth/API-key state. The only credential in this
+    // temporary file is a public loopback placeholder, and the directory is
+    // removed as soon as the child exits.
+    writeFileSync(join(configDir, "config.json"), `${JSON.stringify({
+      api_key: LOOPBACK_API_KEY_PLACEHOLDER,
+      region: "global",
+    }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    bridge = startMmxTextBridge(live);
+    const env = buildMmxEnv({ hostname: "127.0.0.1", port: bridge.port }, configDir, process.env) as NodeJS.ProcessEnv;
+    console.error(`✅ MiniMax CLI text bridged to http://${probeHostname(live.hostname)}:${live.port}/v1/messages.`);
+    removeTerminationHandlers = installMmxTerminationHandlers({
+      getChild: () => mmxChild,
+      cleanup,
+      onCleanupError: error => {
+        console.error(`❌ Failed to clean up the MMX bridge after a termination signal: ${String(error)}`);
+      },
+    });
+    return await spawnClient("mmx", args, env, MMX_INSTALL_HINT, child => { mmxChild = child; });
+  } finally {
+    await finishMmxClientCleanup(cleanup, removeTerminationHandlers);
+  }
+}

package/src/cli/models-runtime.ts

@@ -16,11 +16,17 @@ import {
 const USAGE = `Usage:
   ocx models live [--provider <name>] [--json]
   ocx models edit <custom-id> [--model-id <id>] [--display-name <name|->]
-      [--context-window <tokens|0>] [--modalities <text,image,audio|->] [--json]
+      [--context-window <tokens|0>] [--modalities <text,image,audio|->]
+      [--reasoning-efforts <none,minimal,low,medium,high,xhigh,max,ultra|->]
+      [--default-reasoning-effort <level|->] [--json]
   ocx models <enable|disable> <provider/model|native-model> [--native] [--json]
   ocx models provider <name> <on|off> [--json]
   ocx models selected <provider> [--set <id,id...>|--clear] [--json]
-  ocx models context <status|value <tokens>|provider <name> <on|off>|all <on|off>> [--json]
+  ocx models preset show [--provider <name>] [--json]
+  ocx models preset apply <provider> [--all] [--json]
+  ocx models new-policy [on|off] [--provider <name>] [--json]
+  ocx models new-arrivals [--json]
+  ocx models context <status|value <tokens> [--set-all]|provider <name> on [--value <tokens>]|provider <name> off|all <on|off>> [--json]
   ocx models shadow <status|set> [model|-] [--enabled <on|off>] [--json]`;
 
 type ModelRow = {
@@ -57,6 +63,8 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const displayName = takeOption(args, "--display-name");
   const contextRaw = takeOption(args, "--context-window");
   const modalitiesRaw = takeOption(args, "--modalities");
+  const reasoningEffortsRaw = takeOption(args, "--reasoning-efforts");
+  const defaultEffortRaw = takeOption(args, "--default-reasoning-effort");
   rejectArgs(args, USAGE);
   if (modelId !== undefined) patch.modelId = modelId;
   if (displayName !== undefined) patch.displayName = displayName === "-" ? "" : displayName;
@@ -66,6 +74,23 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     patch.contextWindow = value === 0 ? null : value;
   }
   if (modalitiesRaw !== undefined) patch.inputModalities = modalitiesRaw === "-" ? [] : csv(modalitiesRaw);
+  // "-" restores inheritance by clearing the stored ladder (null); "" stores an explicit
+  // empty ladder (the "no reasoning" override, same as the dashboard's uncheck-all).
+  // Embedded blank CSV members (`low,,high`, `,,`) are malformed and must be rejected, not
+  // silently normalized by csv().
+  if (reasoningEffortsRaw !== undefined) {
+    if (reasoningEffortsRaw === "-") {
+      patch.reasoningEfforts = null;
+    } else {
+      const trimmed = reasoningEffortsRaw.trim();
+      const values = trimmed === "" ? [] : trimmed.split(",").map(value => value.trim());
+      if (values.some(value => value === "")) {
+        throw new CliUsageError("--reasoning-efforts must be comma-separated values from none, minimal, low, medium, high, xhigh, max, ultra (\"\" for no reasoning, \"-\" to inherit)", USAGE);
+      }
+      patch.reasoningEfforts = values;
+    }
+  }
+  if (defaultEffortRaw !== undefined) patch.defaultReasoningEffort = defaultEffortRaw === "-" ? null : defaultEffortRaw;
   if (Object.keys(patch).length === 0) throw new CliUsageError("at least one edit option is required", USAGE);
   const result = await runtimeRequest(`/api/custom-models/${encodeURIComponent(id)}`, {
     method: "PUT",
@@ -141,6 +166,94 @@ async function selected(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, [`${provider}: ${models.length ? models.join(", ") : "all models"}`]);
 }
 
+
+interface ModelPresetView {
+  mode: string;
+  appliedVersion?: number;
+  availableVersion: number;
+  presetIds: string[];
+  presetCount: number;
+  totalCount: number;
+  fallback?: string;
+}
+
+function presetLine(name: string, view: ModelPresetView): string {
+  const parts = [`${name}: mode=${view.mode}`];
+  if (view.appliedVersion !== undefined && view.appliedVersion !== view.availableVersion) {
+    parts.push(`applied v${view.appliedVersion}, available v${view.availableVersion}`);
+  } else {
+    parts.push(`preset v${view.availableVersion}`);
+  }
+  parts.push(`(${view.presetCount} of ${view.totalCount} models)`);
+  if (view.fallback) parts.push(`fallback=${view.fallback}`);
+  return parts.join(" ");
+}
+
+async function preset(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "show").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "show") {
+    const only = takeOption(args, "--provider")?.trim();
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest<{ providers?: Record<string, ModelPresetView> }>("/api/model-presets", {}, deps);
+    const providers = result.providers ?? {};
+    const entries = Object.entries(providers).filter(([name]) => !only || name === only);
+    const lines = entries.length > 0
+      ? entries.map(([name, view]) => presetLine(name, view))
+      // A provider with no shipped preset is not an error: it simply has nothing to curate.
+      : [only ? `${only}: no model preset is shipped for this provider` : "no providers have a shipped model preset"];
+    printData(only ? providers[only] ?? {} : result, wantsJson, lines);
+    return;
+  }
+  if (action !== "apply") throw new CliUsageError(`unknown preset action '${action}'`, USAGE);
+  const provider = args.shift()?.trim();
+  const all = takeFlag(args, "--all");
+  if (!provider) throw new CliUsageError("provider is required", USAGE);
+  rejectArgs(args, USAGE);
+  const mode = all ? "all" : "preset";
+  const result = await runtimeRequest<{ selected?: string[]; fallback?: string; appliedVersion?: number }>(
+    "/api/model-presets",
+    { method: "PUT", body: JSON.stringify({ provider, mode }) },
+    deps,
+  );
+  const selectedIds = result.selected ?? [];
+  const line = result.fallback === "preset-empty"
+    // Never silently narrow to nothing: empty means ALL, so a zero-match preset keeps what was
+    // there and says so.
+    ? `${provider}: preset matched no models — selection unchanged (fallback to all)`
+    : all
+      ? `${provider}: showing all models (allowlist cleared)`
+      : `${provider}: preset v${result.appliedVersion ?? "?"} applied — ${selectedIds.length} models selected`;
+  printData(result, wantsJson, [line]);
+}
+
+async function newPolicy(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const state = args[0] && !args[0].startsWith("--") ? args.shift()!.toLowerCase() : undefined;
+  const provider = takeOption(args, "--provider")?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  if (state !== undefined && state !== "on" && state !== "off") throw new CliUsageError("new policy must be on or off", USAGE);
+  rejectArgs(args, USAGE);
+  if (!state) {
+    const result = await runtimeRequest<{ policy: string; providers: Record<string, string> }>("/api/model-discovery", {}, deps);
+    const value = provider ? result.providers[provider] ?? "inherit" : result.policy;
+    printData(provider ? { provider, policy: value } : result, wantsJson, [`${provider ?? "global"}: ${value}`]);
+    return;
+  }
+  const result = await runtimeRequest<{ baselineBootstrapped?: boolean }>("/api/model-discovery", {
+    method: "PUT", body: JSON.stringify({ policy: state, provider: provider ?? null }),
+  }, deps);
+  printData(result, wantsJson, [`${provider ?? "global"}: ${state}${result.baselineBootstrapped ? " (current models recorded as known)" : ""}`]);
+}
+
+async function newArrivals(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ recentArrivals: Record<string, Array<{ id: string; at: string; state: string }>> }>("/api/model-discovery", {}, deps);
+  const lines = Object.entries(result.recentArrivals).flatMap(([provider, rows]) => rows.map(row => `${provider}/${row.id}  [${row.state}]  ${row.at}`));
+  printData(result.recentArrivals, wantsJson, lines.length ? lines : ["no recent model arrivals"]);
+}
+
 async function context(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const action = (args.shift() ?? "status").toLowerCase();
@@ -158,11 +271,23 @@ async function context(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     const value = Number(raw.replace(/[_,]/g, ""));
     if (!Number.isInteger(value) || value <= 0) throw new CliUsageError("context value must be a positive integer", USAGE);
     body = { value };
+    // Explicit apply-to-all switch for headless use: re-points every routed provider to
+    // the new value, mirroring the dashboard's "apply to every routed provider" toggle.
+    // Without it the value only becomes the default for future toggles.
+    if (takeFlag(args, "--set-all")) body.setAll = true;
   } else if (action === "provider") {
     const provider = args.shift()?.trim();
     const state = args.shift()?.toLowerCase();
     if (!provider || (state !== "on" && state !== "off")) throw new CliUsageError("provider and on|off are required", USAGE);
     body = { provider, enabled: state === "on" };
+    // Optional explicit cap value for this provider only (`ocx models context provider
+    // openai on --value 128000`). Mirrors the dashboard's per-provider cap picker; the
+    // value never leaks to other providers.
+    const value = takeIntegerOption(args, "--value", { min: 1 });
+    if (value !== undefined && state !== "on") {
+      throw new CliUsageError("--value can only be used with on", USAGE);
+    }
+    if (value !== undefined) body.value = value;
   } else if (action === "all") {
     const state = args.shift()?.toLowerCase();
     if (state !== "on" && state !== "off") throw new CliUsageError("all requires on|off", USAGE);
@@ -203,6 +328,9 @@ export async function handleModelsRuntimeCommand(sub: string, argv: string[], de
   else if (sub === "disable") action = () => visibility(false, argv, deps);
   else if (sub === "provider") action = () => providerVisibility(argv, deps);
   else if (sub === "selected") action = () => selected(argv, deps);
+  else if (sub === "preset") action = () => preset(argv, deps);
+  else if (sub === "new-policy") action = () => newPolicy(argv, deps);
+  else if (sub === "new-arrivals") action = () => newArrivals(argv, deps);
   else if (sub === "context") action = () => context(argv, deps);
   else if (sub === "shadow") action = () => shadow(argv, deps);
   if (!action) return null;