@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/provider-result.ts

@@ -0,0 +1,124 @@
+import { normalizeCatalogDisposition } from "../codex/catalog-refresh-status";
+import { CliUsageError, RuntimeApiError, printData, terminalSafeText } from "./runtime-api";
+
+const ERRORS: Readonly<Record<string, string>> = {
+  stale_provider_editor_baseline: "Provider baseline is stale. Read a fresh snapshot and review the changes before applying again.",
+  provider_config_conflict: "Provider configuration changed before the write. Inspect the target before retrying.",
+  provider_config_unavailable: "Provider configuration is unavailable on the target.",
+  invalid_provider_editor_body: "Expected a provider editor document containing only defaultProvider and providers.",
+  invalid_provider_editor_field: "The provider editor document contains a non-editable field.",
+  invalid_provider_editor_config: "The proposed provider configuration is invalid.",
+  invalid_provider_destination: "The target refused a provider destination.",
+  invalid_provider: "The target refused the provider configuration.",
+  invalid_provider_name: "The provider name is invalid.",
+  invalid_default_provider: "The default must name a configured provider.",
+  default_provider_disabled: "A disabled provider cannot be the default.",
+  provider_namespace_conflict: "The provider conflicts with an account namespace.",
+  provider_has_dependent_combos: "A routing combo still depends on this provider. Inspect its dependencies before removal.",
+  last_provider: "The last provider cannot be removed.",
+};
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+
+/** Read only own data values; never invoke response getters or stringify a body. */
+function own(value: unknown, key: string): unknown {
+  if (!record(value)) return undefined;
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && "value" in descriptor ? descriptor.value : undefined;
+}
+
+/** Provider commands return numeric partial outcomes rather than losing them in runCliAction. */
+export async function runProviderAction(action: () => Promise<number | void>): Promise<number> {
+  try {
+    return (await action()) ?? 0;
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      // Domain/input parsers supply static diagnostics; no raw parser/OS error reaches here.
+      console.error(`Error: ${terminalSafeText(error.message)}`);
+      if (error.usage) for (const line of error.usage.split("\n")) console.error(terminalSafeText(line));
+      return 2;
+    }
+    if (error instanceof RuntimeApiError) {
+      const code = own(error.body, "code") ?? own(own(error.body, "error"), "code");
+      const known = typeof code === "string" && Object.hasOwn(ERRORS, code) ? ERRORS[code] : undefined;
+      const fallback = error.status === 404 ? "Provider or management operation was not found on the selected target."
+        : error.status === 409 ? "The target refused a conflicting provider change. Read back before trying again."
+          : error.status === 503 ? "Management API is unavailable. Start the intended proxy; connected clients must make provider changes on their Hub. The write outcome may be unknown."
+            : "The provider request failed. Inspect the selected target before retrying; the write outcome may be unknown.";
+      console.error(`Error: ${known ?? fallback}`);
+      return error.status === 404 ? 4 : error.status === 409 ? 5 : 1;
+    }
+    console.error("Error: Provider operation did not return a usable outcome. Inspect the selected target before retrying; no rollback is implied.");
+    return 1;
+  }
+}
+
+const RECEIPT_FIELDS = new Set([
+  "success", "name", "defaultProvider", "droppedCustomModels", "disabled", "hasApiKey",
+  "xaiResponsesOptInState", "dependentShadowIntercept", "catalogRefresh",
+]);
+
+function invalidReceipt(): never { throw new Error("Invalid provider receipt"); }
+function safeLabel(value: unknown): value is string { return typeof value === "string" && value.length > 0 && value.length <= 4096; }
+
+/** Copy the public receipt vocabulary. Unexpected bodies never become raw CLI output. */
+export function printProviderReceipt(value: unknown, wantsJson: boolean, action: string): number {
+  if (!record(value) || own(value, "success") !== true
+    || Object.keys(value).some(key => !RECEIPT_FIELDS.has(key))) invalidReceipt();
+  const result: Record<string, unknown> = { success: true };
+  for (const key of ["name", "defaultProvider"] as const) {
+    if (!Object.hasOwn(value, key)) continue;
+    const label = own(value, key);
+    if (!safeLabel(label)) invalidReceipt();
+    result[key] = label;
+  }
+  for (const key of ["disabled", "hasApiKey"] as const) {
+    if (!Object.hasOwn(value, key)) continue;
+    const flag = own(value, key);
+    if (typeof flag !== "boolean") invalidReceipt();
+    result[key] = flag;
+  }
+  if (Object.hasOwn(value, "xaiResponsesOptInState")) {
+    const state = own(value, "xaiResponsesOptInState");
+    if (typeof state !== "boolean" && state !== "mixed") invalidReceipt();
+    result.xaiResponsesOptInState = state;
+  }
+  if (Object.hasOwn(value, "droppedCustomModels")) {
+    const count = own(value, "droppedCustomModels");
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) invalidReceipt();
+    result.droppedCustomModels = count;
+  }
+  if (Object.hasOwn(value, "dependentShadowIntercept")) {
+    const shadow = own(value, "dependentShadowIntercept");
+    const model = own(shadow, "model"), enabled = own(shadow, "enabled");
+    if (!record(shadow) || !safeLabel(model) || typeof enabled !== "boolean"
+      || Object.keys(shadow).some(key => key !== "model" && key !== "enabled")) invalidReceipt();
+    result.dependentShadowIntercept = { model, enabled };
+  }
+  let pending = false;
+  let outcome = "No client catalog refresh was requested by this operation.";
+  if (Object.hasOwn(value, "catalogRefresh")) {
+    const raw = own(value, "catalogRefresh");
+    const refresh = raw === null ? null : normalizeCatalogDisposition(raw);
+    if (raw !== null && refresh === null) invalidReceipt();
+    result.catalogRefresh = refresh;
+    if (refresh?.status === "committed") {
+      outcome = refresh.degraded ? "Catalog committed with degraded provider observations." : "Catalog committed.";
+    } else if (refresh && refresh.reason !== "not-requested") {
+      pending = true;
+      outcome = `Configuration saved, but catalog did not converge (${refresh.reason}). Read back before retrying.`;
+    }
+  }
+  const lines = [`${action}: provider configuration saved.`, outcome];
+  if (result.defaultProvider) lines.push(`Default provider: ${result.defaultProvider}`);
+  if (result.droppedCustomModels !== undefined) lines.push(`Removed custom models: ${result.droppedCustomModels}`);
+  if (result.dependentShadowIntercept) {
+    const shadow = result.dependentShadowIntercept as { model: string; enabled: boolean };
+    lines.push(`Shadow-call dependency: ${shadow.model} (enabled: ${shadow.enabled}). Inspect its target.`);
+  }
+  printData(result, wantsJson, lines);
+  return pending ? 1 : 0;
+}

package/src/cli/provider-runtime.ts

@@ -12,6 +12,8 @@ import {
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import { takeProviderEditSettings } from "./provider-settings";
+import { printProviderReceipt, runProviderAction } from "./provider-result";
 import { providerQuotaLine } from "./account-extended";
 import { pinSponsorRows } from "../providers/sponsor-order";
 import type { ProviderQuotaReportDto } from "./account-api";
@@ -42,7 +44,7 @@ const USAGE = `Usage:
       [--api-key-transport <x-api-key|bearer|->]
       [--headers <json>] [--enabled <on|off>] [--live-models <on|off>]
       [--retain-models <id,id|->] [--model <id> --text-only]
-      [--xai-chat <on|off>]
+      [--xai-chat <on|off>] [--upstream-http-version <http1.1|->] [--fast <on|off>] [--context-window <tokens|->]
       [--allow-private-network <on|off>] [--model-context-tier <model=default|long_context>] [--json]
   ocx provider test <name> [--json]
   ocx provider quota [--refresh] [--json]
@@ -56,12 +58,12 @@ function cleared(value: string | undefined): string | undefined {
   return value === "-" ? "" : value;
 }
 
-async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+async function edit(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   const args = [...argv];
   const name = args.shift()?.trim();
   if (!name) throw new CliUsageError("provider name is required", USAGE);
   const wantsJson = takeFlag(args, "--json");
-  const patch: Record<string, unknown> = {};
+  const patch: Record<string, unknown> = takeProviderEditSettings(args);
   const adapter = takeOption(args, "--adapter");
   const baseUrl = takeOption(args, "--base-url");
   const defaultModel = cleared(takeOption(args, "--default-model"));
@@ -139,13 +141,13 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   if (allowPrivateNetwork !== undefined) patch.allowPrivateNetwork = allowPrivateNetwork;
   if (Object.keys(patch).length === 0) throw new CliUsageError("at least one edit option is required", USAGE);
   const result = await runtimeRequest(`/api/providers?name=${encodeURIComponent(name)}`, {
-    method: "PATCH",
+    method: "PATCH", redirect: "error",
     body: JSON.stringify(patch),
   }, deps);
-  printData(result, wantsJson, [`Updated provider ${name}.`]);
+  return printProviderReceipt(result, wantsJson, "Provider edit");
 }
 
-async function testProvider(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+async function testProvider(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   const args = [...argv];
   const name = args.shift()?.trim();
   const wantsJson = takeFlag(args, "--json");
@@ -159,7 +161,7 @@ async function testProvider(argv: string[], deps: RuntimeApiDeps): Promise<void>
       `${name}: not applicable`,
       "Static catalog; no live model-discovery endpoint to test.",
     ]);
-    return;
+    return 0;
   }
   const ok = result.ok === true;
   printData(result, wantsJson, [
@@ -167,7 +169,7 @@ async function testProvider(argv: string[], deps: RuntimeApiDeps): Promise<void>
     String(result.message ?? result.error ?? "No detail"),
     `Latency: ${String(result.latencyMs ?? "?")} ms`,
   ]);
-  if (!ok) process.exitCode = 1;
+  return ok ? 0 : 1;
 }
 
 async function quota(argv: string[], deps: RuntimeApiDeps): Promise<void> {
@@ -310,9 +312,8 @@ async function keychain(argv: string[], deps: RuntimeApiDeps): Promise<void> {
 }
 
 export async function handleProviderRuntimeCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
-  const handlers: Record<string, (args: string[], deps: RuntimeApiDeps) => Promise<void>> = {
-    edit,
-    update: edit,
+  if (sub === "edit" || sub === "update") return runProviderAction(() => edit(argv, deps));
+  const handlers: Record<string, (args: string[], deps: RuntimeApiDeps) => Promise<number | void>> = {
     test: testProvider,
     quota,
     resets,
@@ -323,7 +324,9 @@ export async function handleProviderRuntimeCommand(sub: string, argv: string[],
   };
   const handler = handlers[sub];
   if (!handler) return null;
-  return runCliAction(() => handler(argv, deps));
+  let outcome: number | void = 0;
+  const exit = await runCliAction(async () => { outcome = await handler(argv, deps); });
+  return exit || outcome || 0;
 }
 
 export const PROVIDER_RUNTIME_USAGE = USAGE;

package/src/cli/provider-settings.ts

@@ -0,0 +1,143 @@
+import { isValidProviderName } from "../config/provider-name";
+import { requestPacingConfigError } from "../config/schema/leaf-validators";
+import { readJsonInput, serializeManagementJson } from "./json-input";
+import { printProviderReceipt, runProviderAction } from "./provider-result";
+import {
+  CliUsageError, RuntimeApiError, printData, runtimeBaseUrl, runtimeRequest,
+  takeFlag, takeOptionWithSyntax, type RuntimeApiDeps,
+} from "./runtime-api";
+
+const PACING_USAGE = "Usage: ocx provider pacing <name> [--file <FILE|-> | --enabled <on|off> --rpm <number> --min-interval-ms <integer> --max-concurrent <integer>] [--json]";
+
+function onOff(value: string, flag: string): boolean {
+  if (value !== "on" && value !== "off") throw new CliUsageError(`${flag} must be on or off`);
+  return value === "on";
+}
+
+function positiveInteger(value: string, flag: string): number {
+  const number = Number(value);
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(number) || number <= 0) {
+    throw new CliUsageError(`${flag} must be a positive safe integer`);
+  }
+  return number;
+}
+
+/** Consume only the additional edit options; the existing edit parser owns all others. */
+export function takeProviderEditSettings(args: string[]): Record<string, unknown> {
+  const patch: Record<string, unknown> = {};
+  const version = takeOptionWithSyntax(args, "--upstream-http-version")?.value;
+  const fast = takeOptionWithSyntax(args, "--fast")?.value;
+  const context = takeOptionWithSyntax(args, "--context-window")?.value;
+  if (version !== undefined) {
+    if (version !== "http1.1" && version !== "-") {
+      throw new CliUsageError("--upstream-http-version must be http1.1 or -");
+    }
+    patch.upstreamHttpVersion = version === "-" ? null : version;
+  }
+  if (fast !== undefined) patch.fastEnabled = onOff(fast, "--fast");
+  if (context !== undefined) patch.contextWindow = context === "-" ? null : positiveInteger(context, "--context-window");
+  return patch;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validRules(value: unknown): value is Record<string, unknown> {
+  return record(value) && requestPacingConfigError(value) === null;
+}
+
+function takePacingScalars(args: string[]): Record<string, unknown> {
+  const patch: Record<string, unknown> = {};
+  const enabled = takeOptionWithSyntax(args, "--enabled")?.value;
+  const rpm = takeOptionWithSyntax(args, "--rpm")?.value;
+  const interval = takeOptionWithSyntax(args, "--min-interval-ms")?.value;
+  const concurrent = takeOptionWithSyntax(args, "--max-concurrent")?.value;
+  if (enabled !== undefined) patch.enabled = onOff(enabled, "--enabled");
+  if (rpm !== undefined) {
+    const number = Number(rpm);
+    if (!rpm.trim() || !Number.isFinite(number)) throw new CliUsageError("--rpm must be a finite number");
+    patch.requestsPerMinute = number;
+  }
+  if (interval !== undefined) patch.minIntervalMs = positiveInteger(interval, "--min-interval-ms");
+  if (concurrent !== undefined) patch.maxConcurrentRequests = positiveInteger(concurrent, "--max-concurrent");
+  // Validate numeric bounds before target resolution; enabling alone may use stored rules.
+  if (!validRules({ ...patch, enabled: false })) throw new CliUsageError("Invalid pacing limits", PACING_USAGE);
+  return patch;
+}
+
+async function configuredRules(name: string, deps: RuntimeApiDeps): Promise<Record<string, unknown> | null> {
+  const config = await runtimeRequest("/api/config", { redirect: "error" }, deps);
+  if (!record(config) || !record(config.providers)) throw new Error("Invalid provider configuration response");
+  if (!Object.hasOwn(config.providers, name)) throw new RuntimeApiError("Provider not found", 404, null);
+  const provider = config.providers[name];
+  if (!record(provider)) throw new Error("Invalid provider configuration response");
+  if (!Object.hasOwn(provider, "requestPacing")) return null;
+  if (!validRules(provider.requestPacing)) throw new Error("Invalid stored pacing rules");
+  return provider.requestPacing;
+}
+
+function pacingStatus(value: unknown, name: string): Record<string, unknown> {
+  const keys = ["provider", "enabled", "queued", "nextSlotInMs", "inFlight", "lastStartedAt", "lastModelId"];
+  if (!record(value) || Object.keys(value).some(key => !keys.includes(key))
+    || value.provider !== name || typeof value.enabled !== "boolean") {
+    throw new Error("Invalid pacing status response");
+  }
+  for (const key of ["queued", "nextSlotInMs", "inFlight", "lastStartedAt"]) {
+    if ((key === "inFlight" || key === "lastStartedAt") && !Object.hasOwn(value, key)) continue;
+    const number = value[key];
+    if (typeof number !== "number" || !Number.isFinite(number) || number < 0
+      || (key !== "lastStartedAt" && !Number.isSafeInteger(number))) {
+      throw new Error("Invalid pacing status response");
+    }
+  }
+  if (Object.hasOwn(value, "lastModelId") && typeof value.lastModelId !== "string") {
+    throw new Error("Invalid pacing status response");
+  }
+  return value;
+}
+
+export async function handleProviderPacingCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runProviderAction(async () => {
+    const args = [...argv];
+    const name = args.shift()?.trim();
+    if (!name || !isValidProviderName(name)) throw new CliUsageError("A valid provider name is required", PACING_USAGE);
+    const wantsJson = takeFlag(args, "--json");
+    const file = takeOptionWithSyntax(args, "--file")?.value;
+    const scalars = takePacingScalars(args);
+    if (args.length) throw new CliUsageError("Unexpected pacing argument(s)", PACING_USAGE);
+    const editing = Object.keys(scalars).length > 0;
+    if (file !== undefined && editing) throw new CliUsageError("--file cannot be combined with pacing scalar options", PACING_USAGE);
+    let fileBody: string | undefined;
+    if (file !== undefined) {
+      const rules = await readJsonInput(file, deps, "Pacing JSON input");
+      if (!validRules(rules)) throw new CliUsageError("Invalid pacing rules", PACING_USAGE);
+      fileBody = serializeManagementJson({ requestPacing: rules });
+    }
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    if (fileBody !== undefined || editing) {
+      let body = fileBody;
+      if (body === undefined) {
+        const observed = await configuredRules(name, pinned);
+        const rules = { ...(observed ?? { enabled: false }), ...scalars };
+        if (!validRules(rules)) throw new CliUsageError("Invalid resulting pacing rules", PACING_USAGE);
+        // PATCH replaces the observed block, including its model rules. This is not CAS.
+        body = serializeManagementJson({ requestPacing: rules });
+      }
+      const result = await runtimeRequest(`/api/providers?name=${encodeURIComponent(name)}`, {
+        method: "PATCH", redirect: "error", body,
+      }, pinned);
+      return printProviderReceipt(result, wantsJson, "Updated provider pacing");
+    }
+    const rules = await configuredRules(name, pinned);
+    const status = pacingStatus(await runtimeRequest(`/api/provider-request-pacing?name=${encodeURIComponent(name)}`, {
+      redirect: "error",
+    }, pinned), name);
+    printData({ provider: name, rules, status }, wantsJson, [
+      `${name}: ${rules === null ? "no pacing rules configured" : rules.enabled ? "pacing rules enabled" : "pacing rules disabled"}`,
+      ...(rules === null ? [] : [JSON.stringify(rules)]),
+      `Runtime: ${status.enabled ? "enabled" : "disabled"}; queued: ${status.queued}; next slot: ${status.nextSlotInMs} ms`,
+    ]);
+    return 0;
+  });
+}

package/src/cli/provider.ts

@@ -8,7 +8,7 @@
  *   show <name>   Show provider config details (secrets masked)
  *   set-default <name>  Change the default provider
  */
-import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
+import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate } from "../config";
 import { apiKeyTransportConfigError, modelCapabilitiesConfigError, mergeModelCapabilities } from "../config/provider-validation";
 import { hasHelpFlag, printSubcommandUsage } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
@@ -19,6 +19,16 @@ import { findLiveProxy } from "../server/proxy-liveness";
 import { syncModelsToCodex } from "../codex/sync";
 import { codexAccountNamespaceProviderCollisionError } from "../codex/account-namespace-match";
 import { modelSelectionGuidance, modelSelectionNextSteps } from "./model-selection-guidance";
+import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers-destination";
+import { providerRelativeSendPathConfigError } from "../config/provider-relative-send-path";
+import type { RuntimeApiDeps } from "./runtime-api";
+import { redactSecretArgs } from "./secret-args";
+import { projectLocalSyncResult, type LocalSyncResult } from "./local-sync-result";
+import { providerManagementConfigError } from "../server/auth-cors";
+
+export interface ProviderCommandDeps extends RuntimeApiDeps {
+  syncModels?: typeof syncModelsToCodex;
+}
 
 // ---------------------------------------------------------------------------
 // Arg helpers
@@ -42,11 +52,13 @@ function consumeFlagValue(args: string[], flag: string): string | undefined {
 /** Reject any leftover args (unknown flags or trailing values). */
 function rejectUnknownArgs(args: string[], usage: string): void {
   if (args.length === 0) return;
-  const unknown = args.filter(a => a.startsWith("-"));
+  const shown = redactSecretArgs(args);
+  // Flags plus redaction markers only: a stray positional may be a credential operand.
+  const unknown = shown.filter(a => a.startsWith("-") || a === "<redacted>");
   if (unknown.length > 0) {
     console.error(`Unknown flag(s): ${unknown.join(", ")}`);
   } else {
-    console.error(`Unexpected argument(s): ${args.join(", ")}`);
+    console.error(`Unexpected argument(s): ${shown.join(", ")}`);
   }
   console.error(usage);
   process.exit(1);
@@ -70,6 +82,16 @@ function validateAndSave(config: ReturnType<typeof loadConfig>): void {
     console.error(`Error: defaultProvider "${config.defaultProvider}" does not exist in providers. Aborting.`);
     process.exit(1);
   }
+  const result = validateConfigCandidate(config);
+  if (!result.ok) {
+    console.error(`Error: ${result.error}`);
+    if (result.error.includes("set allowPrivateNetwork:true")) {
+      console.error("For an intentionally local provider, add --allow-private-network.");
+    } else {
+      console.error("Nothing was saved. Fix the setting named above; if this command did not set it, run ocx config validate and repair it with ocx config set/unset.");
+    }
+    process.exit(1);
+  }
   saveConfig(config);
 }
 
@@ -139,9 +161,9 @@ function handleList(args: string[]): void {
 // provider add
 // ---------------------------------------------------------------------------
 
-const ADD_USAGE = "Usage: ocx provider add <name> [--adapter <adapter>] [--base-url <url>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <model>] [--model <id> --text-only] [--google-tool-schema-policy <compatible|reject-lossy>] [--allow-private-network] [--set-default] [--force] [--json] [--sync]";
+const ADD_USAGE = "Usage: ocx provider add <name> [--adapter <adapter>] [--base-url <url>] [--responses-path <path>] [--auth-mode <key|forward|oauth|local>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <model>] [--model <id> --text-only] [--google-tool-schema-policy <compatible|reject-lossy>] [--allow-private-network] [--set-default] [--force] [--json] [--sync | --live]";
 
-async function handleAdd(args: string[]): Promise<void> {
+async function handleAdd(args: string[], deps: ProviderCommandDeps): Promise<void> {
   const name = args[0];
   if (!name || name.startsWith("-")) {
     console.error(ADD_USAGE);
@@ -164,6 +186,8 @@ async function handleAdd(args: string[]): Promise<void> {
   const adapter = consumeFlagValue(restArgs, "--adapter");
   const baseUrl = consumeFlagValue(restArgs, "--base-url");
   const defaultModel = consumeFlagValue(restArgs, "--default-model");
+  const responsesPath = consumeFlagValue(restArgs, "--responses-path");
+  const authMode = consumeFlagValue(restArgs, "--auth-mode");
   const googleToolSchemaPolicy = consumeFlagValue(restArgs, "--google-tool-schema-policy");
   const textOnly = consumeFlag(restArgs, "--text-only");
   const capabilityModel = consumeFlagValue(restArgs, "--model");
@@ -173,6 +197,12 @@ async function handleAdd(args: string[]): Promise<void> {
     process.exit(1);
   }
 
+  const pathError = providerRelativeSendPathConfigError("responsesPath", responsesPath);
+  if (pathError || (authMode !== undefined && !["key", "forward", "oauth", "local"].includes(authMode))) {
+    console.error(pathError ? `Error: ${pathError}.` : "Error: --auth-mode must be key, forward, oauth, or local.");
+    process.exit(1);
+  }
+
   const config = loadConfig();
 
   const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, name);
@@ -192,9 +222,9 @@ async function handleAdd(args: string[]): Promise<void> {
   if (registryEntry) {
     provConfig = providerConfigSeed(registryEntry);
     if (apiKey) {
-      if (registryEntry.authKind === "forward") {
+      if ((authMode ?? registryEntry.authKind) === "forward") {
         console.warn(`Warning: provider "${name}" uses ChatGPT login (forward auth); --api-key is ignored.`);
-      } else if (registryEntry.authKind === "oauth") {
+      } else if ((authMode ?? registryEntry.authKind) === "oauth") {
         console.warn(`Warning: provider "${name}" uses OAuth auth; --api-key is ignored. Run: ocx login ${name}`);
       } else {
         provConfig.apiKey = apiKey;
@@ -217,6 +247,15 @@ async function handleAdd(args: string[]): Promise<void> {
     };
   }
 
+  if (responsesPath !== undefined) provConfig.responsesPath = responsesPath;
+  if (authMode !== undefined) provConfig.authMode = authMode as OcxProviderConfig["authMode"];
+  if (name === "openai" && (authMode !== undefined || responsesPath !== undefined)
+    && !isCanonicalOpenAiForwardProvider(provConfig)) {
+    console.error("Error: Canonical OpenAI must keep its built-in forward destination and authentication. Use a separate provider name for a custom endpoint.");
+    process.exitCode = 2;
+    return;
+  }
+
   if (apiKeyTransport !== undefined) {
     if (apiKeyTransport !== "x-api-key" && apiKeyTransport !== "bearer") {
       console.error('Error: --api-key-transport must be "x-api-key" or "bearer".');
@@ -259,9 +298,6 @@ async function handleAdd(args: string[]): Promise<void> {
     if (error) { console.error(`Error: ${error}.`); process.exit(1); }
     provConfig.modelCapabilities = mergeModelCapabilities(provConfig.modelCapabilities, declaration);
   }
-  const { initializeProviderModelSelection } = await import("../providers/initial-model-selection");
-  initializeProviderModelSelection(name, provConfig, existingProvider, config);
-  config.providers[name] = provConfig;
   // A --force overwrite rotates the key/endpoint but must not drop a
   // user-configured price overlay (same rule as the /api/providers path and
   // the login paths); there is no explicit clear/replace flag yet.
@@ -269,10 +305,38 @@ async function handleAdd(args: string[]): Promise<void> {
     provConfig.modelCosts = existingProvider.modelCosts;
   }
   if (allowPrivateNetwork) provConfig.allowPrivateNetwork = true;
+  // New auth/path overrides use the management owner's completed-row contract.
+  // Validate overrides before registration state changes; the full candidate is
+  // validated again by validateAndSave for every local save.
+  if ((authMode !== undefined || responsesPath !== undefined)
+    && providerManagementConfigError(name, provConfig)) {
+    console.error("Error: Invalid provider configuration. Authentication, destination and provider options must satisfy the provider's management rules.");
+    process.exitCode = 2;
+    return;
+  }
+  const { initializeProviderModelSelection } = await import("../providers/initial-model-selection");
+  initializeProviderModelSelection(name, provConfig, existingProvider, config);
+  config.providers[name] = provConfig;
   if (setDefault) config.defaultProvider = name;
 
   validateAndSave(config);
 
+  let sync: LocalSyncResult | undefined;
+  if (wantsSync) {
+    try {
+      const live = await (deps.findLiveProxy ?? findLiveProxy)();
+      if (!live) sync = { status: "not-running", ok: false };
+      else {
+        const result = await (deps.syncModels ?? syncModelsToCodex)(live.port, config, null);
+        sync = projectLocalSyncResult(result);
+      }
+    } catch {
+      // Dependency errors can contain keys, paths or request details. Keep a fixed outcome.
+      sync = { status: "failed", ok: false };
+    }
+    if (!sync.ok || sync.status === "refused") process.exitCode = 1;
+  }
+  const synced = sync?.status === "applied" && sync.ok;
   if (wantsJson) {
     console.log(JSON.stringify({
       action: "added",
@@ -283,26 +347,13 @@ async function handleAdd(args: string[]): Promise<void> {
       defaultModel: provConfig.defaultModel ?? null,
       isDefault: config.defaultProvider === name,
       source: registryEntry ? "registry" : "custom",
-      needsSync: true,
+      needsSync: !synced,
+      ...(sync ? { sync } : {}),
     }, null, 2));
     return;
   }
 
-  let codexSyncSkipped = false;
-  if (wantsSync) {
-    const live = await findLiveProxy();
-    if (live) {
-      const synced = await syncModelsToCodex(live.port).catch(e => {
-        console.error(`Warning: sync failed: ${e instanceof Error ? e.message : String(e)}`);
-        return null;
-      });
-      if (synced?.status === "skipped") {
-        codexSyncSkipped = true;
-        console.log("Provider saved; Codex integration is OFF, so Codex sync was skipped.");
-      }
-    }
-  }
-
+  if (sync?.warning) console.log(`   Warning: ${sync.warning}`);
   const registryLabel = registryEntry ? ` (${registryEntry.label})` : "";
   console.log(`✅ Provider "${name}"${registryLabel} added.`);
   for (const line of modelSelectionGuidance(name)) console.log(line);
@@ -315,10 +366,15 @@ async function handleAdd(args: string[]): Promise<void> {
     console.log(`   Set API key with: ocx provider add ${name} --api-key <key> --force`);
     console.log(`   Or set env var: ${envKey}`);
   }
-  if (wantsSync && !codexSyncSkipped) {
-    console.log(`   Models synced to Codex.`);
-  } else {
-    console.log(`   Apply to Codex: ocx sync`);
+  if (synced) console.log("   Models synced to Codex.");
+  else {
+    if (sync) {
+      console.log(sync.configApplied && !sync.ok
+        ? "   Provider saved; sync remains incomplete despite config injection."
+        : `   Provider saved; client sync outcome: ${sync.status}.`);
+      if (sync.catalog && !sync.catalog.converged) console.log("   Model catalog did not converge; inspect the target before retrying.");
+    }
+    console.log("   Apply to Codex: ocx sync");
   }
 }
 
@@ -473,7 +529,7 @@ function handleSetDefault(args: string[]): void {
 // ---------------------------------------------------------------------------
 
 
-export async function handleProviderCommand(args: string[]): Promise<void> {
+export async function handleProviderCommand(args: string[], deps: ProviderCommandDeps = {}): Promise<void> {
   const sub = args[0];
 
   if (!sub || sub === "help" || hasHelpFlag(args)) {
@@ -482,13 +538,35 @@ export async function handleProviderCommand(args: string[]): Promise<void> {
   }
 
   const subArgs = args.slice(1);
+  const liveArgs = subArgs.filter(arg => arg === "--live" || arg.startsWith("--live="));
+  if (liveArgs.length) {
+    if (liveArgs.length !== 1 || liveArgs[0] !== "--live" || !["add", "remove", "set-default"].includes(sub)) {
+      console.error("Error: --live is a single boolean flag for provider add, remove, or set-default.");
+      process.exitCode = 2;
+      return;
+    }
+    subArgs.splice(subArgs.indexOf("--live"), 1);
+    const { handleProviderLifecycleRuntimeCommand } = await import("./provider-lifecycle-runtime");
+    process.exitCode = await handleProviderLifecycleRuntimeCommand(sub as "add" | "remove" | "set-default", subArgs, deps);
+    return;
+  }
+  if (sub === "snapshot" || sub === "apply") {
+    const { handleProviderBatchCommand } = await import("./provider-batch");
+    process.exitCode = await handleProviderBatchCommand(sub, subArgs, deps);
+    return;
+  }
+  if (sub === "pacing") {
+    const { handleProviderPacingCommand } = await import("./provider-settings");
+    process.exitCode = await handleProviderPacingCommand(subArgs, deps);
+    return;
+  }
 
   switch (sub) {
     case "list":
       handleList(subArgs);
       break;
     case "add":
-      await handleAdd(subArgs);
+      await handleAdd(subArgs, deps);
       break;
     case "remove":
       handleRemove(subArgs);
@@ -501,12 +579,12 @@ export async function handleProviderCommand(args: string[]): Promise<void> {
       break;
     default: {
       const { handleProviderRuntimeCommand } = await import("./provider-runtime");
-      const code = await handleProviderRuntimeCommand(sub, subArgs);
+      const code = await handleProviderRuntimeCommand(sub, subArgs, deps);
       if (code !== null) {
         process.exitCode = code;
         break;
       }
-      console.error(`Unknown provider subcommand: ${sub}`);
+      console.error(`Unknown provider subcommand: ${redactSecretArgs([sub ?? ""])[0]}`);
       printSubcommandUsage("provider", undefined, { write: console.error });
       process.exit(1);
     }