@yansigit/opencodex 2.31.0

package/src/cli/models-runtime.ts

@@ -0,0 +1,245 @@
+import {
+  CliUsageError,
+  csv,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  summaryLines,
+  takeBooleanOption,
+  takeFlag,
+  takeIntegerOption,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+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|->]
+      [--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> [--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 = {
+  provider?: string;
+  id?: string;
+  namespaced?: string;
+  native?: boolean;
+  disabled?: boolean;
+  custom?: boolean;
+  customId?: string;
+  displayName?: string;
+};
+
+async function live(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const provider = takeOption(args, "--provider");
+  rejectArgs(args, USAGE);
+  const rows = await runtimeRequest<ModelRow[]>("/api/models", {}, deps);
+  const filtered = provider ? rows.filter(row => row.provider === provider) : rows;
+  printData(filtered, wantsJson, filtered.map(row => {
+    const flags = [row.native ? "native" : "routed", row.custom ? "custom" : "", row.disabled ? "disabled" : "enabled"].filter(Boolean);
+    return `${row.namespaced ?? `${row.provider}/${row.id}`}  [${flags.join(", ")}]`;
+  }));
+}
+
+async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const id = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  if (!id) throw new CliUsageError("custom model id is required", USAGE);
+  const patch: Record<string, unknown> = {};
+  const modelId = takeOption(args, "--model-id");
+  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;
+  if (contextRaw !== undefined) {
+    const value = Number(contextRaw.replace(/[_,]/g, ""));
+    if (!Number.isInteger(value) || value < 0) throw new CliUsageError("--context-window must be an integer >= 0", USAGE);
+    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",
+    body: JSON.stringify(patch),
+  }, deps);
+  printData(result, wantsJson, [`Updated custom model ${id}.`]);
+}
+
+function parseSelector(selector: string, forceNative: boolean): { provider: string; id: string; native: boolean } {
+  if (forceNative || !selector.includes("/")) return { provider: "openai", id: selector, native: true };
+  const slash = selector.indexOf("/");
+  const provider = selector.slice(0, slash);
+  const id = selector.slice(slash + 1);
+  if (!provider || !id) throw new CliUsageError("model selector must be provider/model or a native model id", USAGE);
+  return { provider, id, native: false };
+}
+
+async function visibility(enabled: boolean, argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const selector = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const native = takeFlag(args, "--native");
+  if (!selector) throw new CliUsageError("model selector is required", USAGE);
+  rejectArgs(args, USAGE);
+  const target = parseSelector(selector, native);
+  const result = await runtimeRequest("/api/model-visibility", {
+    method: "PUT",
+    body: JSON.stringify({ scope: "models", provider: target.provider, enabled, targets: [{ id: target.id, native: target.native }] }),
+  }, deps);
+  printData(result, wantsJson, [`${enabled ? "Enabled" : "Disabled"} ${selector}.`]);
+}
+
+async function providerVisibility(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const provider = args.shift()?.trim();
+  const state = args.shift()?.toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (!provider || (state !== "on" && state !== "off")) throw new CliUsageError("provider and on|off are required", USAGE);
+  rejectArgs(args, USAGE);
+  const rows = await runtimeRequest<ModelRow[]>("/api/models", {}, deps);
+  const targets = rows.filter(row => row.provider === provider && typeof row.id === "string")
+    .map(row => ({ id: row.id!, native: row.native === true }));
+  if (targets.length === 0) throw new CliUsageError(`no models are available for provider ${provider}`);
+  const result = await runtimeRequest("/api/model-visibility", {
+    method: "PUT",
+    body: JSON.stringify({ scope: "provider", provider, enabled: state === "on", targets }),
+  }, deps);
+  printData(result, wantsJson, [`${provider}: ${state}`]);
+}
+
+async function selected(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const provider = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const selectedModels = csv(takeOption(args, "--set"));
+  const clear = takeFlag(args, "--clear");
+  if (!provider) throw new CliUsageError("provider is required", USAGE);
+  if (selectedModels !== undefined && clear) throw new CliUsageError("--set and --clear cannot be combined", USAGE);
+  rejectArgs(args, USAGE);
+  if (selectedModels === undefined && !clear) {
+    const result = await runtimeRequest<Record<string, unknown>>("/api/selected-models", {}, deps);
+    const map = result.selected as Record<string, string[]> | undefined;
+    const available = result.available as Record<string, string[]> | undefined;
+    const view = { provider, selected: map?.[provider] ?? [], available: available?.[provider] ?? [] };
+    printData(view, wantsJson, [`${provider}: ${view.selected.join(", ") || "all models"}`]);
+    return;
+  }
+  const models = clear ? [] : selectedModels!;
+  const result = await runtimeRequest("/api/selected-models", {
+    method: "PUT",
+    body: JSON.stringify({ provider, models }),
+  }, deps);
+  printData(result, wantsJson, [`${provider}: ${models.length ? models.join(", ") : "all models"}`]);
+}
+
+async function context(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/provider-context-caps", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  let body: Record<string, unknown>;
+  if (action === "value") {
+    const raw = args.shift();
+    if (!raw) throw new CliUsageError("context value is required", USAGE);
+    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);
+    body = { setAll: state === "on" };
+  } else throw new CliUsageError(`unknown context action ${action}`, USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest("/api/provider-context-caps", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Context cap settings updated."]);
+}
+
+async function shadow(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/shadow-call-settings", {}, deps);
+    printData(result, wantsJson);
+    return;
+  }
+  if (action !== "set") throw new CliUsageError(`unknown shadow action ${action}`, USAGE);
+  const modelRaw = args[0] && !args[0].startsWith("--") ? args.shift() : undefined;
+  const enabled = takeBooleanOption(args, "--enabled");
+  rejectArgs(args, USAGE);
+  const body: Record<string, unknown> = {};
+  if (modelRaw !== undefined) body.model = modelRaw === "-" ? "" : modelRaw;
+  if (enabled !== undefined) body.enabled = enabled;
+  if (Object.keys(body).length === 0) throw new CliUsageError("model and/or --enabled is required", USAGE);
+  const result = await runtimeRequest("/api/shadow-call-settings", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Shadow-call settings updated."]);
+}
+
+export async function handleModelsRuntimeCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
+  let action: (() => Promise<void>) | undefined;
+  if (sub === "live") action = () => live(argv, deps);
+  else if (sub === "edit") action = () => edit(argv, deps);
+  else if (sub === "enable") action = () => visibility(true, argv, deps);
+  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 === "context") action = () => context(argv, deps);
+  else if (sub === "shadow") action = () => shadow(argv, deps);
+  if (!action) return null;
+  return runCliAction(action);
+}
+
+export const MODELS_RUNTIME_USAGE = USAGE;

package/src/cli/models.ts

@@ -0,0 +1,422 @@
+/**
+ * `ocx models` subcommand — list configured models and manage custom models.
+ */
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { syncModelsToCodex } from "../codex/sync";
+import { hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
+import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort, modelRecordValue } from "../reasoning-effort";
+import { encodedModelIdCollides, routedSlug, slugEquals } from "../providers/slug-codec";
+import { knownModelIdsForProvider } from "../router";
+import { findLiveProxy } from "../server/proxy-liveness";
+import { modelInList, type OcxConfig, type OcxCustomModel } from "../types";
+
+const ADD_USAGE = "Usage: ocx models add <provider> <modelId> [--display-name <name>] [--context-window <tokens>] [--modalities text,image,audio] [--reasoning-efforts <none,minimal,low,medium,high,xhigh,max,ultra>] [--default-reasoning-effort <level>]";
+const REMOVE_USAGE = "Usage: ocx models remove <customId|provider/modelId> [--yes]";
+const LIST_CUSTOM_USAGE = "Usage: ocx models list-custom [--json]";
+const ALLOWED_MODALITIES = new Set(["text", "image", "audio"]);
+
+/**
+ * Parse and validate the reasoning flags shared by `ocx models add` (offline path).
+ * "-" means "inherit" and omits the field entirely; "" means an explicit empty ladder
+ * ("no reasoning" override, the same state the dashboard stores for the toggle-off
+ * checkbox set). Malformed CSV like `low,,high` or `,,` is rejected instead of being
+ * silently normalized. Values are canonicalized into Codex ladder order so the stored
+ * config matches what the API stores.
+ */
+export function parseReasoningArgs(
+  reasoningEffortsValue: string | undefined,
+  defaultEffortValue: string | undefined,
+): { reasoningEfforts?: string[]; defaultReasoningEffort?: string; error?: string } {
+  if (reasoningEffortsValue === undefined && defaultEffortValue === undefined) return {};
+  let reasoningEfforts: string[] | undefined;
+  if (reasoningEffortsValue !== undefined) {
+    const trimmed = reasoningEffortsValue.trim();
+    if (trimmed === "-") {
+      reasoningEfforts = undefined;
+    } else if (trimmed === "") {
+      // Explicit no-reasoning override, exactly like the API's [] / the dashboard's
+      // uncheck-all state.
+      reasoningEfforts = [];
+    } else {
+      const parts = trimmed.split(",").map(value => value.trim());
+      if (parts.some(part => part === "")) {
+        return { error: "--reasoning-efforts must be comma-separated values from none, minimal, low, medium, high, xhigh, max, ultra (\"\" for no reasoning, \"-\" to inherit)" };
+      }
+      const invalid = parts.filter(value => !isDeclaredReasoningEffort(value));
+      if (invalid.length > 0) {
+        return { error: `unsupported reasoning effort: ${invalid.join(", ")} (allowed: none, minimal, low, medium, high, xhigh, max, ultra)` };
+      }
+      reasoningEfforts = canonicalizeReasoningEfforts(parts);
+    }
+  }
+  let defaultReasoningEffort: string | undefined;
+  if (defaultEffortValue !== undefined) {
+    const trimmed = defaultEffortValue.trim();
+    if (trimmed === "-") {
+      defaultReasoningEffort = undefined;
+    } else {
+      if (!isDeclaredReasoningEffort(trimmed)) {
+        return { error: `unsupported reasoning effort: ${trimmed} (allowed: none, minimal, low, medium, high, xhigh, max, ultra)` };
+      }
+      if (!reasoningEfforts || reasoningEfforts.length === 0) {
+        return { error: "--default-reasoning-effort requires --reasoning-efforts" };
+      }
+      if (!reasoningEfforts.includes(trimmed)) {
+        return { error: `--default-reasoning-effort "${trimmed}" is not in the declared reasoning efforts` };
+      }
+      defaultReasoningEffort = trimmed;
+    }
+  }
+  return { reasoningEfforts, defaultReasoningEffort };
+}
+
+interface ModelEntry {
+  provider: string;
+  model: string;
+  isDefault: boolean;
+  contextWindow: number | null;
+  inputModalities: string[] | null;
+  reasoningEfforts: string[] | null;
+}
+
+function collectModels(config: OcxConfig, providerFilter?: string): ModelEntry[] {
+  const entries: ModelEntry[] = [];
+  const providers = providerFilter
+    ? { [providerFilter]: config.providers[providerFilter] }
+    : config.providers;
+
+  for (const [provName, prov] of Object.entries(providers)) {
+    if (!prov) continue;
+    const seen = new Set<string>();
+    const contextWindows = prov.modelContextWindows ?? {};
+    const inputModalities = prov.modelInputModalities ?? {};
+    const reasoningEfforts = prov.modelReasoningEfforts ?? {};
+    const globalContext = prov.contextWindow ?? null;
+
+    const addModel = (model: string, isDefault: boolean) => {
+      if (seen.has(model)) return;
+      seen.add(model);
+
+      // Resolve exactly as the runtime does, or this command reports capabilities the
+      // proxy will not honour: `isModelTextOnly` matches noVisionModels with modelInList
+      // and reads modelInputModalities with modelRecordValue, so a `gpt-oss` entry covers
+      // `gpt-oss:120b`. A bare lookup reported that model as unclassified on every field.
+      // noVisionModels is checked first because `isModelTextOnly` returns true on that
+      // match before it ever reads modelInputModalities: a `gpt-oss` noVision entry beats
+      // an exact `gpt-oss:120b` entry that lists "image", and the proxy rejects the image.
+      const noVision = modelInList(prov.noVisionModels, model);
+      const modalities = noVision ? ["text"] : (modelRecordValue(inputModalities, model) ?? null);
+      const efforts = modelRecordValue(reasoningEfforts, model) ?? prov.reasoningEfforts ?? null;
+
+      entries.push({
+        provider: provName,
+        model,
+        isDefault,
+        contextWindow: modelRecordValue(contextWindows, model) ?? globalContext,
+        inputModalities: modalities,
+        reasoningEfforts: efforts,
+      });
+    };
+
+    // defaultModel first
+    if (prov.defaultModel) addModel(prov.defaultModel, true);
+
+    // models array
+    if (prov.models) {
+      for (const m of prov.models) addModel(m, m === prov.defaultModel);
+    }
+  }
+
+  return entries;
+}
+
+function consumeFlag(args: string[], flag: string): boolean {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return false;
+  args.splice(idx, 1);
+  return true;
+}
+
+function consumeFlagValue(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  const value = args[idx + 1];
+  args.splice(idx, 2);
+  return value;
+}
+
+function fail(message: string, usage?: string): never {
+  console.error(`Error: ${message}`);
+  if (usage) console.error(usage);
+  process.exit(1);
+}
+
+function rejectUnexpectedArgs(args: string[], usage: string): void {
+  if (args.length === 0) return;
+  const unknown = args.filter(arg => arg.startsWith("-"));
+  fail(
+    unknown.length > 0
+      ? `Unknown flag(s): ${unknown.join(", ")}`
+      : `Unexpected argument(s): ${args.join(", ")}`,
+    usage,
+  );
+}
+
+async function syncCustomModelsIfLive(): Promise<void> {
+  const live = await findLiveProxy();
+  if (!live) return;
+  const synced = await syncModelsToCodex(live.port).catch(error => {
+    console.error(`Warning: custom model saved, but catalog sync failed: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  });
+  if (synced?.status === "skipped") {
+    console.log("Custom model saved; Codex integration is OFF, so its catalog was not changed.");
+  }
+}
+
+async function handleCustomAdd(args: string[]): Promise<void> {
+  const rest = [...args];
+  const provider = rest.shift()?.trim() ?? "";
+  const modelId = rest.shift()?.trim() ?? "";
+  const displayNameValue = consumeFlagValue(rest, "--display-name");
+  const contextWindowValue = consumeFlagValue(rest, "--context-window");
+  const modalitiesValue = consumeFlagValue(rest, "--modalities");
+  const reasoningEffortsValue = consumeFlagValue(rest, "--reasoning-efforts");
+  const defaultEffortValue = consumeFlagValue(rest, "--default-reasoning-effort");
+  rejectUnexpectedArgs(rest, ADD_USAGE);
+
+  if (!provider || !modelId) fail("provider and modelId are required", ADD_USAGE);
+  if (!isValidProviderName(provider)) fail(`invalid provider name "${provider}"`);
+
+  const config = loadConfig();
+  if (!hasOwnProvider(config.providers, provider)) {
+    fail(`provider "${provider}" is not configured. See: ocx provider list`);
+  }
+
+  const displayName = displayNameValue?.trim() || undefined;
+  if (displayName?.includes("/")) fail("displayName must not contain /");
+
+  let contextWindow: number | undefined;
+  if (contextWindowValue !== undefined) {
+    contextWindow = Number(contextWindowValue);
+    if (!Number.isInteger(contextWindow) || contextWindow <= 0) {
+      fail("context window must be a positive integer");
+    }
+  }
+
+  let inputModalities: string[] | undefined;
+  if (modalitiesValue !== undefined) {
+    inputModalities = modalitiesValue.split(",").map(value => value.trim());
+    const invalid = inputModalities.filter(value => !ALLOWED_MODALITIES.has(value));
+    if (inputModalities.length === 0 || invalid.length > 0) {
+      fail("modalities must be comma-separated values from text|image|audio");
+    }
+    inputModalities = [...new Set(inputModalities)];
+  }
+
+  const parsed = parseReasoningArgs(reasoningEffortsValue, defaultEffortValue);
+  if (parsed.error) fail(parsed.error);
+
+  const existing = config.customModels ?? [];
+  const slug = routedSlug(provider, modelId);
+  if (existing.some(model => routedSlug(model.provider, model.modelId) === slug)) {
+    fail(`custom model "${slug}" already exists`);
+  }
+  const known = knownModelIdsForProvider(provider, config.providers[provider], config);
+  if (encodedModelIdCollides(modelId, known)) {
+    fail(`custom model "${slug}" is ambiguous; it encodes to an existing model id`);
+  }
+
+  const entry: OcxCustomModel = {
+    id: randomUUID(),
+    provider,
+    modelId,
+    ...(displayName ? { displayName } : {}),
+    ...(contextWindow ? { contextWindow } : {}),
+    ...(inputModalities ? { inputModalities } : {}),
+    ...(parsed.reasoningEfforts ? { reasoningEfforts: parsed.reasoningEfforts } : {}),
+    ...(parsed.defaultReasoningEffort ? { defaultReasoningEffort: parsed.defaultReasoningEffort } : {}),
+    addedAt: new Date().toISOString(),
+  };
+  config.customModels = [...existing, entry];
+  saveConfig(config);
+  await syncCustomModelsIfLive();
+  console.log(`Added custom model ${slug} (${entry.id}).`);
+}
+
+async function confirmCustomRemoval(model: OcxCustomModel): Promise<boolean> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    fail("remove requires --yes in non-interactive mode");
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(`Remove custom model ${routedSlug(model.provider, model.modelId)}? [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function handleCustomRemove(args: string[]): Promise<void> {
+  const rest = [...args];
+  const confirmed = consumeFlag(rest, "--yes");
+  const target = rest.shift()?.trim() ?? "";
+  rejectUnexpectedArgs(rest, REMOVE_USAGE);
+  if (!target) fail("custom model id or provider/modelId is required", REMOVE_USAGE);
+
+  const config = loadConfig();
+  const existing = config.customModels ?? [];
+  const matchingIndexes = existing.flatMap((model, index) => (
+    target.includes("/")
+      ? slugEquals(target, model.provider, model.modelId)
+      : model.id === target
+  ) ? [index] : []);
+  if (matchingIndexes.length === 0) fail(`custom model "${target}" not found`);
+  if (matchingIndexes.length > 1) {
+    fail(`custom model selector "${target}" is ambiguous; use the custom model id`);
+  }
+  const index = matchingIndexes[0]!;
+
+  const model = existing[index];
+  if (!confirmed && !(await confirmCustomRemoval(model))) {
+    console.log("Cancelled.");
+    return;
+  }
+
+  const next = existing.filter((_, modelIndex) => modelIndex !== index);
+  config.customModels = next.length > 0 ? next : undefined;
+  saveConfig(config);
+  await syncCustomModelsIfLive();
+  console.log(`Removed custom model ${routedSlug(model.provider, model.modelId)}.`);
+}
+
+function customModelCells(model: OcxCustomModel): string[] {
+  return [
+    model.id.slice(0, 8),
+    model.modelId,
+    model.displayName ?? "-",
+    model.contextWindow ? `${Math.round(model.contextWindow / 1000)}k` : "-",
+    model.inputModalities?.join(",") ?? "-",
+    model.reasoningEfforts?.join(",") ?? "-",
+    model.defaultReasoningEffort ?? "-",
+  ];
+}
+
+function printCustomModelGroup(provider: string, models: OcxCustomModel[]): void {
+  const rows = models.map(customModelCells);
+  const headers = ["ID", "MODEL", "DISPLAY NAME", "CONTEXT", "MODALITIES", "EFFORTS", "DEFAULT EFFORT"];
+  const widths = headers.map((header, column) => Math.max(header.length, ...rows.map(row => row[column].length)));
+  const line = (cells: string[]) => cells.map((cell, column) => cell.padEnd(widths[column])).join("  ");
+  console.log(`${provider}:`);
+  console.log(`  ${line(headers)}`);
+  for (const row of rows) console.log(`  ${line(row)}`);
+  console.log();
+}
+
+function handleCustomList(args: string[]): void {
+  const rest = [...args];
+  const wantsJson = consumeFlag(rest, "--json");
+  rejectUnexpectedArgs(rest, LIST_CUSTOM_USAGE);
+  const models = loadConfig().customModels ?? [];
+  if (wantsJson) {
+    console.log(JSON.stringify(models, null, 2));
+    return;
+  }
+  if (models.length === 0) {
+    console.log("No custom models registered.");
+    return;
+  }
+  const byProvider = new Map<string, OcxCustomModel[]>();
+  for (const model of models) {
+    const group = byProvider.get(model.provider) ?? [];
+    group.push(model);
+    byProvider.set(model.provider, group);
+  }
+  for (const [provider, providerModels] of byProvider) printCustomModelGroup(provider, providerModels);
+}
+
+function handleConfiguredModels(args: string[]): void {
+  const restArgs = [...args];
+  const wantsJson = consumeFlag(restArgs, "--json");
+  const providerFilter = consumeFlagValue(restArgs, "--provider");
+
+  if (restArgs.length > 0) {
+    const unknown = restArgs.filter(a => a.startsWith("-"));
+    if (unknown.length > 0) {
+      console.error(`Unknown flag(s): ${unknown.join(", ")}`);
+    } else {
+      console.error(`Unexpected argument(s): ${restArgs.join(", ")}`);
+    }
+    console.error("Usage: ocx models [--provider <name>] [--json]");
+    process.exit(1);
+  }
+
+  const config = loadConfig();
+
+  if (providerFilter && !hasOwnProvider(config.providers, providerFilter)) {
+    console.error(`Provider "${providerFilter}" is not configured. See: ocx provider list`);
+    process.exit(1);
+  }
+
+  const models = collectModels(config, providerFilter ?? undefined);
+
+  if (wantsJson) {
+    console.log(JSON.stringify({
+      models,
+      note: "Static config models only. Providers with liveModels=true may have additional models at runtime.",
+    }, null, 2));
+    return;
+  }
+
+  if (models.length === 0) {
+    console.log("No models found in configured providers.");
+    if (!providerFilter) console.log("Providers may discover models dynamically at runtime (liveModels).");
+    return;
+  }
+
+  // Group by provider
+  const byProvider = new Map<string, ModelEntry[]>();
+  for (const entry of models) {
+    const list = byProvider.get(entry.provider) ?? [];
+    list.push(entry);
+    byProvider.set(entry.provider, list);
+  }
+
+  for (const [provName, provModels] of byProvider) {
+    const isDefaultProv = provName === config.defaultProvider ? " (default provider)" : "";
+    console.log(`${provName}${isDefaultProv}:`);
+    for (const m of provModels) {
+      const marker = m.isDefault ? " *" : "";
+      const ctx = m.contextWindow ? ` (${Math.round(m.contextWindow / 1000)}k)` : "";
+      console.log(`  ${m.model}${marker}${ctx}`);
+    }
+    console.log();
+  }
+
+  console.log("* = default model for provider");
+  console.log("Note: providers with liveModels may have additional models at runtime.");
+}
+
+export async function handleModels(args: string[]): Promise<void> {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "add") {
+    await handleCustomAdd(rest);
+    return;
+  }
+  if (subcommand === "remove") {
+    await handleCustomRemove(rest);
+    return;
+  }
+  if (subcommand === "list-custom") {
+    handleCustomList(rest);
+    return;
+  }
+  if (["live", "edit", "enable", "disable", "provider", "selected", "context", "shadow"].includes(subcommand ?? "")) {
+    const { handleModelsRuntimeCommand } = await import("./models-runtime");
+    const code = await handleModelsRuntimeCommand(subcommand!, rest);
+    if (code !== null) process.exitCode = code;
+    return;
+  }
+  handleConfiguredModels(subcommand === "list" ? rest : args);
+}