@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/models-custom-runtime.ts

@@ -0,0 +1,112 @@
+import { isValidProviderName } from "../config/provider-name";
+import { isDeclaredReasoningEffort } from "../reasoning-effort";
+import { resolveSlugSelection } from "../providers/slug-codec";
+import { printCatalogResult, runCatalogAction } from "./catalog-command-result";
+import { serializeManagementJson } from "./json-input";
+import { parseCustomModelAddInput } from "./models-custom-input";
+import {
+  CliUsageError, RuntimeApiError, runtimeBaseUrl, runtimeRequest, takeFlag,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function identity(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0 && value.trim() === value;
+}
+
+function modelIdentity(value: unknown): { id: string; provider: string; modelId: string } {
+  if (!record(value) || !identity(value.id) || !identity(value.provider)
+    || !isValidProviderName(value.provider) || !identity(value.modelId)) {
+    throw new Error("Invalid custom model identity");
+  }
+  return { id: value.id, provider: value.provider, modelId: value.modelId };
+}
+
+/** Rebuild the public stored-entry DTO; never copy arbitrary response properties. */
+function addedModel(value: unknown, provider: string, modelId: string): Record<string, unknown> {
+  const result: Record<string, unknown> = modelIdentity(value);
+  if (!record(value) || result.provider !== provider || result.modelId !== modelId
+    || !identity(value.addedAt) || !Number.isFinite(Date.parse(value.addedAt))) {
+    throw new Error("Invalid custom model response");
+  }
+  result.addedAt = value.addedAt;
+  if (value.displayName !== undefined) {
+    if (!identity(value.displayName) || value.displayName.includes("/")) throw new Error("Invalid display name response");
+    result.displayName = value.displayName;
+  }
+  if (value.contextWindow !== undefined) {
+    if (typeof value.contextWindow !== "number" || !Number.isSafeInteger(value.contextWindow) || value.contextWindow <= 0) {
+      throw new Error("Invalid context response");
+    }
+    result.contextWindow = value.contextWindow;
+  }
+  for (const key of ["inputModalities", "reasoningEfforts"] as const) {
+    const values = value[key];
+    if (values === undefined) continue;
+    if (!Array.isArray(values) || !values.every(item => typeof item === "string"
+      && (key === "inputModalities" ? ["text", "image", "audio"].includes(item) : isDeclaredReasoningEffort(item)))
+      || new Set(values).size !== values.length || (key === "inputModalities" && values.length === 0)) {
+      throw new Error("Invalid model metadata response");
+    }
+    result[key] = [...values];
+  }
+  if (value.defaultReasoningEffort !== undefined) {
+    if (typeof value.defaultReasoningEffort !== "string" || !Array.isArray(result.reasoningEfforts)
+      || !result.reasoningEfforts.includes(value.defaultReasoningEffort)) throw new Error("Invalid default effort response");
+    result.defaultReasoningEffort = value.defaultReasoningEffort;
+  }
+  return result;
+}
+
+function resolveRemoval(value: unknown, target: string): { id: string; provider: string; modelId: string } {
+  if (!Array.isArray(value)) throw new Error("Invalid custom model roster");
+  const rows = value.map(modelIdentity);
+  if (new Set(rows.map(row => row.id)).size !== rows.length) throw new Error("Duplicate stored model IDs");
+  const byId = rows.find(row => row.id === target);
+  if (byId) return byId;
+  const separator = target.indexOf("/");
+  const provider = separator >= 0 ? target.slice(0, separator) : undefined;
+  const roster = provider === undefined ? [] : rows.filter(row => row.provider === provider);
+  const admitted = new Set(provider === undefined ? []
+    : resolveSlugSelection(provider, target, roster.map(row => row.modelId)).matched);
+  const matches = roster.filter(row => admitted.has(row.modelId));
+  if (matches.length === 0) throw new RuntimeApiError("Custom model not found", 404, null);
+  if (matches.length !== 1) throw new CliUsageError("Ambiguous custom model selector; use the complete stored ID");
+  return matches[0]!;
+}
+
+export async function handleModelsCustomRuntimeCommand(
+  sub: "add" | "remove", argv: string[], deps: RuntimeApiDeps = {},
+): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const wantsJson = takeFlag(args, "--json");
+    if (sub === "add") {
+      const input = parseCustomModelAddInput(args);
+      const body = serializeManagementJson(input);
+      const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+      const response = await runtimeRequest("/api/custom-models", { method: "POST", redirect: "error", body }, pinned);
+      const result = addedModel(response, input.provider, input.modelId);
+      return printCatalogResult(result, record(response) ? response.catalogRefresh : undefined, wantsJson,
+        [`Saved custom model ${input.provider}/${input.modelId} (${result.id}).`]);
+    }
+    const confirmed = takeFlag(args, "--yes");
+    if (!confirmed) throw new CliUsageError("Live custom model removal requires --yes");
+    if (args.length !== 1 || !args[0]?.trim() || args[0].startsWith("-")) {
+      throw new CliUsageError("A complete stored ID or provider/model selector is required");
+    }
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    const roster = await runtimeRequest("/api/custom-models", { redirect: "error" }, pinned);
+    const selected = resolveRemoval(roster, args[0].trim());
+    if (selected.id === "." || selected.id === "..") throw new Error("Stored ID is not addressable as a route segment");
+    const response = await runtimeRequest(`/api/custom-models/${encodeURIComponent(selected.id)}`, {
+      method: "DELETE", redirect: "error",
+    }, pinned);
+    if (!record(response) || response.ok !== true) throw new Error("Invalid custom model removal response");
+    return printCatalogResult({ ok: true, ...selected }, response.catalogRefresh, wantsJson,
+      [`Removed custom model ${selected.provider}/${selected.modelId} (${selected.id}).`]);
+  });
+}

package/src/cli/models-order.ts

@@ -0,0 +1,194 @@
+import { isValidProviderName } from "../config/provider-name";
+import { modelDisplayNamesConfigError } from "../config/provider-validation";
+import { isValidModelDiscoveryModelId } from "../providers/model-discovery-limits";
+import { normalizeCatalogDisposition } from "../codex/catalog-refresh-status";
+import { printCatalogResult, runCatalogAction } from "./catalog-command-result";
+import { serializeManagementJson } from "./json-input";
+import {
+  customPickerRows, isModelPickerUsage, isPickerOrderSaved, isPickerOrderSettings,
+  modelPickerOrder, normalizePickerIds, pickerIdentityCoverage,
+  type PickerModelIdentity, type PickerOrderSettings, type ModelPickerUsage,
+} from "./model-picker-ordering";
+import {
+  CliUsageError, RuntimeApiError, printData, runtimeBaseUrl, runtimeRequest,
+  takeFlag, takeOptionWithSyntax, type RuntimeApiDeps,
+} from "./runtime-api";
+
+const ORDER_USAGE = "Usage: ocx models order status|reset|set (--models CSV | --mode default|alphabetical|provider|most-used) [--json]";
+const DISPLAY_USAGE = "Usage: ocx models display-name PROVIDER/MODEL (--set TEXT | --clear) [--json]";
+const SETTINGS = "/api/subagent-models";
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stringList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(item => typeof item === "string");
+}
+function unusable(): never { throw new Error("Invalid model management response"); }
+
+async function readSettings(deps: RuntimeApiDeps): Promise<PickerOrderSettings> {
+  const value = await runtimeRequest(SETTINGS, { redirect: "error" }, deps);
+  if (!isPickerOrderSettings(value) || value.pickerAvailable.some(id => !id.includes("/"))
+    || new Set(value.pickerAvailable).size !== value.pickerAvailable.length) unusable();
+  return { pickerAvailable: value.pickerAvailable, pickerOrder: value.pickerOrder,
+    pickerOrderMode: value.pickerOrderMode, ...(value.chosen === undefined ? {} : { chosen: value.chosen }) };
+}
+async function readIdentities(deps: RuntimeApiDeps): Promise<PickerModelIdentity[]> {
+  const rows = await runtimeRequest("/api/models", { redirect: "error" }, deps);
+  if (!Array.isArray(rows)) unusable();
+  return rows.map(row => {
+    if (!record(row) || typeof row.provider !== "string" || !row.provider.trim()
+      || !isValidModelDiscoveryModelId(row.id) || !isValidModelDiscoveryModelId(row.namespaced)) unusable();
+    return { provider: row.provider, id: row.id, namespaced: row.namespaced };
+  });
+}
+function snapshot(settings: PickerOrderSettings, identities: PickerModelIdentity[]): string {
+  return JSON.stringify([settings, identities]);
+}
+function assertRouted(settings: PickerOrderSettings): void {
+  if (settings.pickerOrder.some(id => !id.includes("/"))) {
+    throw new CliUsageError("Saved order includes native models. Run ocx models order reset before replacing it.");
+  }
+  if (settings.pickerAvailable.length === 0) throw new CliUsageError("No routed picker candidates are available.");
+}
+function manualOrder(csv: string, settings: PickerOrderSettings, identities: PickerModelIdentity[]): string[] {
+  const tokens = csv.split(",").map(id => id.trim());
+  const order = tokens.map(token => {
+    if (!token) throw new CliUsageError("--models cannot contain blank entries", ORDER_USAGE);
+    const result = normalizePickerIds([token], settings.pickerAvailable, identities);
+    if (result.length !== 1) throw new CliUsageError("--models contains an unknown or ambiguous model", ORDER_USAGE);
+    return result[0]!;
+  });
+  if (new Set(order).size !== order.length || order.length !== settings.pickerAvailable.length) {
+    throw new CliUsageError("--models must contain every routed candidate exactly once", ORDER_USAGE);
+  }
+  const draft = customPickerRows(settings, identities);
+  if (!draft) throw new CliUsageError("Featured state or model identities are incomplete. Read status before trying again.");
+  if (!draft.fixed.every((id, index) => order[index] === id)) {
+    throw new CliUsageError("--models must keep the current featured models as its exact leading prefix.");
+  }
+  return order;
+}
+async function readUsage(deps: RuntimeApiDeps): Promise<ModelPickerUsage[]> {
+  const value = await runtimeRequest("/api/usage?range=all&surface=all", { redirect: "error" }, deps);
+  if (!record(value) || (value.usageIncomplete !== undefined && value.usageIncomplete !== false)
+    || !isModelPickerUsage(value.models)) unusable();
+  return value.models;
+}
+function printOrderSave(value: unknown, expected: string[] | null, mode: string | null, wantsJson: boolean): number {
+  if (!record(value) || value.ok !== true || !isPickerOrderSaved(value)
+    || !stringList(value.applied) || (value.force !== null && typeof value.force !== "string")
+    || JSON.stringify(value.pickerOrder) !== JSON.stringify(expected ?? []) || value.pickerOrderMode !== mode) unusable();
+  return printCatalogResult({ ok: true, pickerOrder: value.pickerOrder, pickerOrderMode: value.pickerOrderMode,
+    applied: value.applied, force: value.force }, value.catalogRefresh, wantsJson,
+  ["Picker order saved.", `Order: ${value.pickerOrder.join(", ") || "default"}`]);
+}
+
+export async function handleModelsOrderCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const sub = args.shift();
+    const wantsJson = takeFlag(args, "--json");
+    const csv = takeOptionWithSyntax(args, "--models")?.value;
+    const mode = takeOptionWithSyntax(args, "--mode")?.value;
+    if (args.length || !["status", "reset", "set"].includes(sub ?? "")
+      || (sub !== "set" && (csv !== undefined || mode !== undefined))
+      || (sub === "set" && ((csv === undefined) === (mode === undefined)))
+      || (mode !== undefined && !["default", "alphabetical", "provider", "most-used"].includes(mode))) {
+      throw new CliUsageError("Invalid picker order arguments", ORDER_USAGE);
+    }
+    // Refuse lexical manual-input failures before discovering a target.
+    if (csv !== undefined) {
+      const tokens = csv.split(",").map(id => id.trim());
+      if (tokens.some(id => !id) || new Set(tokens).size !== tokens.length) {
+        throw new CliUsageError("--models requires unique nonblank entries", ORDER_USAGE);
+      }
+    }
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    if (sub === "status") {
+      const settings = await readSettings(pinned);
+      printData(settings, wantsJson, [
+        `Saved mode: ${settings.pickerOrderMode ?? (settings.pickerOrder.length ? "custom" : "default")}`,
+        `Saved order: ${settings.pickerOrder.join(", ") || "default"}`,
+        `Routed candidates: ${settings.pickerAvailable.join(", ") || "none"}`,
+        `Featured: ${settings.chosen === undefined ? "unknown" : settings.chosen.join(", ") || "none"}`,
+      ]);
+      return 0;
+    }
+    let order: string[] | null = null;
+    let savedMode: string | null = null;
+    if (sub !== "reset" && mode !== "default") {
+      const settings = await readSettings(pinned);
+      assertRouted(settings);
+      const identities = await readIdentities(pinned);
+      if (!pickerIdentityCoverage(settings.pickerAvailable, identities)) {
+        throw new CliUsageError("Model identities are incomplete or ambiguous; picker order was not changed.");
+      }
+      if (csv !== undefined) {
+        order = manualOrder(csv, settings, identities);
+        const freshSettings = await readSettings(pinned);
+        const freshIdentities = await readIdentities(pinned);
+        if (snapshot(settings, identities) !== snapshot(freshSettings, freshIdentities)) {
+          throw new RuntimeApiError("Picker state changed", 409, null);
+        }
+      } else {
+        const preset = mode as "alphabetical" | "provider" | "most-used";
+        order = modelPickerOrder(preset, settings.pickerAvailable, preset === "most-used" ? await readUsage(pinned) : [], identities);
+        savedMode = preset;
+      }
+    }
+    const value = await runtimeRequest(SETTINGS, { method: "PUT", redirect: "error",
+      body: serializeManagementJson({ pickerOrder: order, pickerOrderMode: savedMode }) }, pinned);
+    return printOrderSave(value, order, savedMode, wantsJson);
+  });
+}
+
+function displayReceipt(value: unknown, provider: string, modelId: string, label: string | null, partial: boolean): Record<string, unknown> {
+  if (!record(value) || value.provider !== provider || value.modelId !== modelId
+    || value.displayNameOverride !== label || (partial ? value.saved !== true : value.ok !== true)) unusable();
+  const projected: Record<string, unknown> = { ...(partial ? { saved: true } : { ok: true }), provider, modelId,
+    displayNameOverride: value.displayNameOverride };
+  if (partial) {
+    if (normalizeCatalogDisposition(value.catalogRefresh)?.status !== "failed") unusable();
+  } else {
+    if (typeof value.displayName !== "string" || !value.displayName.trim()
+      || typeof value.displayNameSource !== "string"
+      || !["operator", "provider", "fallback"].includes(value.displayNameSource)) unusable();
+    projected.displayName = value.displayName;
+    projected.displayNameSource = value.displayNameSource;
+  }
+  return projected;
+}
+export async function handleModelsDisplayNameCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const selector = args.shift() ?? "";
+    const wantsJson = takeFlag(args, "--json");
+    const set = takeOptionWithSyntax(args, "--set")?.value;
+    const clear = takeFlag(args, "--clear");
+    const slash = selector.indexOf("/");
+    const provider = selector.slice(0, slash), modelId = selector.slice(slash + 1);
+    if (args.length || slash < 1 || !isValidProviderName(provider) || !isValidModelDiscoveryModelId(modelId)
+      || (set !== undefined) === clear) throw new CliUsageError("Invalid display-name arguments", DISPLAY_USAGE);
+    const label = set === undefined ? null : set.trim();
+    if (label !== null && modelDisplayNamesConfigError({ [modelId]: label }) !== null) {
+      throw new CliUsageError("Display name must be a valid nonblank label without slashes or control characters", DISPLAY_USAGE);
+    }
+    const body = serializeManagementJson({ modelId, displayName: label });
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    let value: unknown;
+    let partial = false;
+    try {
+      value = await runtimeRequest(`/api/providers/${encodeURIComponent(provider)}/model-display-names`, {
+        method: "PUT", redirect: "error", body,
+      }, pinned);
+    } catch (error) {
+      if (!(error instanceof RuntimeApiError) || error.status !== 503) throw error;
+      value = error.body;
+      partial = true;
+    }
+    const result = displayReceipt(value, provider, modelId, label, partial);
+    const refresh = (value as Record<string, unknown>).catalogRefresh;
+    return printCatalogResult(result, refresh, wantsJson,
+      [`Display name saved for ${provider}/${modelId}: ${label ?? "override cleared"}.`]);
+  });
+}

package/src/cli/models-runtime-subcommands.ts

@@ -28,6 +28,8 @@ export const MODELS_RUNTIME_SUBCOMMANDS = [
   "new-arrivals",
   "context",
   "shadow",
+  "order",
+  "display-name",
 ] as const;
 
 export type ModelsRuntimeSubcommand = (typeof MODELS_RUNTIME_SUBCOMMANDS)[number];

package/src/cli/models-runtime.ts

@@ -24,6 +24,9 @@ import { MAX_COST4_RATE } from "../usage/expected-prices";
 import { isValidCost4Rate } from "../usage/user-cost-overlays";
 
 const USAGE = `Usage:
+  ocx models display-name <provider/raw-model> (--set <text> | --clear) [--json]
+  ocx models order status|reset [--json]
+  ocx models order set (--models <csv> | --mode <default|alphabetical|provider|most-used>) [--json]
   ocx models live [--provider <name>] [--free-only] [--json]
   ocx models price <provider/model> [--json]
   ocx models set-price <provider/model> --input N --output N [--cache-read N] [--cache-write N] [--json]
@@ -564,6 +567,10 @@ async function shadow(argv: string[], deps: RuntimeApiDeps): Promise<void> {
 }
 
 export async function handleModelsRuntimeCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
+  if (sub === "order" || sub === "display-name") {
+    const { handleModelsOrderCommand, handleModelsDisplayNameCommand } = await import("./models-order");
+    return sub === "order" ? handleModelsOrderCommand(argv, deps) : handleModelsDisplayNameCommand(argv, deps);
+  }
   // The dispatch below and MODELS_RUNTIME_SUBCOMMANDS must name the same set;
   // tests/cli/cli-models-runtime-dispatch.test.ts fails if they drift (#3094).
   if (!isModelsRuntimeSubcommand(sub)) return null;

package/src/cli/models.ts

@@ -8,9 +8,7 @@ import { syncModelsToCodex } from "../codex/sync";
 import { configuredContextWindow } from "../codex/catalog/provider-fetch";
 import { hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
 import {
-  canonicalizeReasoningEfforts,
   configuredReasoningEfforts,
-  isDeclaredReasoningEffort,
   modelRecordValue,
 } from "../reasoning-effort";
 import { encodedModelIdCollides, resolveSlugSelection, routedSlug } from "../providers/slug-codec";
@@ -18,66 +16,19 @@ import { isModelsRuntimeSubcommand } from "./models-runtime-subcommands";
 import { knownModelIdsForProvider } from "../router";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { modelInList, type OcxConfig, type OcxCustomModel } from "../types";
+import type { RuntimeApiDeps } from "./runtime-api";
+import { projectLocalSyncResult, type LocalSyncResult } from "./local-sync-result";
 
-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]";
+export interface ModelsCommandDeps extends RuntimeApiDeps { syncModels?: typeof syncModelsToCodex; }
+
+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>] [--live] [--json]";
+const REMOVE_USAGE = "Usage: ocx models remove <customId|provider/modelId> [--yes] [--live] [--json]";
 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 };
-}
+import { parseReasoningArgs } from "./models-custom-input";
+import { redactSecretArgs } from "./secret-args";
+export { parseReasoningArgs } from "./models-custom-input";
 
 interface ModelEntry {
   provider: string;
@@ -173,29 +124,44 @@ function fail(message: string, usage?: string): never {
 
 function rejectUnexpectedArgs(args: string[], usage: string): void {
   if (args.length === 0) return;
-  const unknown = args.filter(arg => arg.startsWith("-"));
+  const shown = redactSecretArgs(args);
+  const unknown = shown.filter(arg => arg.startsWith("-"));
   fail(
     unknown.length > 0
       ? `Unknown flag(s): ${unknown.join(", ")}`
-      : `Unexpected argument(s): ${args.join(", ")}`,
+      : `Unexpected argument(s): ${shown.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 syncCustomModelsIfLive(config: OcxConfig, deps: ModelsCommandDeps): Promise<LocalSyncResult> {
+  try {
+    const live = await (deps.findLiveProxy ?? findLiveProxy)();
+    if (!live) return { status: "not-attempted", ok: false };
+    return projectLocalSyncResult(await (deps.syncModels ?? syncModelsToCodex)(live.port, config, null));
+  } catch {
+    return { status: "failed", ok: false };
   }
 }
 
-async function handleCustomAdd(args: string[]): Promise<void> {
+function printCustomMutation(action: "added" | "removed", model: OcxCustomModel, sync: LocalSyncResult, wantsJson: boolean): void {
+  const complete = sync.configApplied === true && sync.ok;
+  if (sync.status !== "not-attempted" && (!sync.ok || sync.status === "refused")) process.exitCode = 1;
+  if (wantsJson) {
+    console.log(JSON.stringify({ action,
+      model: action === "added" ? model : { id: model.id, provider: model.provider, modelId: model.modelId },
+      needsSync: !complete, sync }, null, 2));
+    return;
+  }
+  if (sync.warning) console.log(`Warning: ${sync.warning}`);
+  console.log(`${action === "added" ? "Added" : "Removed"} custom model ${routedSlug(model.provider, model.modelId)}${action === "added" ? ` (${model.id})` : ""}.`);
+  if (sync.status === "skipped") console.log("Custom model saved; client sync was skipped by the integration policy.");
+  else if (!complete && sync.status !== "not-attempted") console.log("Custom model saved; client/catalog sync remains incomplete. Inspect the target before retrying.");
+}
+
+async function handleCustomAdd(args: string[], deps: ModelsCommandDeps): Promise<void> {
   const rest = [...args];
+  const wantsJson = consumeFlag(rest, "--json");
   const provider = rest.shift()?.trim() ?? "";
   const modelId = rest.shift()?.trim() ?? "";
   const displayNameValue = consumeFlagValue(rest, "--display-name");
@@ -260,8 +226,8 @@ async function handleCustomAdd(args: string[]): Promise<void> {
   };
   config.customModels = [...existing, entry];
   saveConfig(config);
-  await syncCustomModelsIfLive();
-  console.log(`Added custom model ${slug} (${entry.id}).`);
+  const sync = await syncCustomModelsIfLive(config, deps);
+  printCustomMutation("added", entry, sync, wantsJson);
 }
 
 async function confirmCustomRemoval(model: OcxCustomModel): Promise<boolean> {
@@ -277,12 +243,18 @@ async function confirmCustomRemoval(model: OcxCustomModel): Promise<boolean> {
   }
 }
 
-async function handleCustomRemove(args: string[]): Promise<void> {
+async function handleCustomRemove(args: string[], deps: ModelsCommandDeps): Promise<void> {
   const rest = [...args];
+  const wantsJson = consumeFlag(rest, "--json");
   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);
+  if (wantsJson && !confirmed) {
+    console.error("Error: JSON removal requires --yes; it does not prompt.");
+    process.exitCode = 2;
+    return;
+  }
 
   const config = loadConfig();
   const existing = config.customModels ?? [];
@@ -329,8 +301,8 @@ async function handleCustomRemove(args: string[]): Promise<void> {
   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)}.`);
+  const sync = await syncCustomModelsIfLive(config, deps);
+  printCustomMutation("removed", model, sync, wantsJson);
 }
 
 function customModelCells(model: OcxCustomModel): string[] {
@@ -384,11 +356,12 @@ function handleConfiguredModels(args: string[]): void {
   const providerFilter = consumeFlagValue(restArgs, "--provider");
 
   if (restArgs.length > 0) {
-    const unknown = restArgs.filter(a => a.startsWith("-"));
+    const shown = redactSecretArgs(restArgs);
+    const unknown = shown.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(`Unexpected argument(s): ${shown.join(", ")}`);
     }
     console.error("Usage: ocx models [--provider <name>] [--json]");
     process.exit(1);
@@ -442,14 +415,26 @@ function handleConfiguredModels(args: string[]): void {
   console.log("Note: providers with liveModels may have additional models at runtime.");
 }
 
-export async function handleModels(args: string[]): Promise<void> {
+export async function handleModels(args: string[], deps: ModelsCommandDeps = {}): Promise<void> {
   const [subcommand, ...rest] = args;
+  const live = rest.filter(arg => arg === "--live" || arg.startsWith("--live="));
+  if (live.length) {
+    if (live.length !== 1 || live[0] !== "--live" || (subcommand !== "add" && subcommand !== "remove")) {
+      console.error("Error: --live is a single boolean flag for models add or remove.");
+      process.exitCode = 2;
+      return;
+    }
+    rest.splice(rest.indexOf("--live"), 1);
+    const { handleModelsCustomRuntimeCommand } = await import("./models-custom-runtime");
+    process.exitCode = await handleModelsCustomRuntimeCommand(subcommand, rest, deps);
+    return;
+  }
   if (subcommand === "add") {
-    await handleCustomAdd(rest);
+    await handleCustomAdd(rest, deps);
     return;
   }
   if (subcommand === "remove") {
-    await handleCustomRemove(rest);
+    await handleCustomRemove(rest, deps);
     return;
   }
   if (subcommand === "list-custom") {
@@ -458,7 +443,7 @@ export async function handleModels(args: string[]): Promise<void> {
   }
   if (isModelsRuntimeSubcommand(subcommand)) {
     const { handleModelsRuntimeCommand } = await import("./models-runtime");
-    const code = await handleModelsRuntimeCommand(subcommand!, rest);
+    const code = await handleModelsRuntimeCommand(subcommand!, rest, deps);
     if (code !== null) process.exitCode = code;
     return;
   }