@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/provider-lifecycle-runtime.ts

@@ -0,0 +1,170 @@
+/** Explicit live lifecycle writes; the server remains the persistence authority. */
+import { isValidProviderName } from "../config/provider-name";
+import { providerRelativeSendPathConfigError } from "../config/provider-relative-send-path";
+import { modelCapabilitiesConfigError, providerBaseUrlConfigError } from "../config/provider-validation";
+import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers-destination";
+import { parseProviderEditorConfigDTO, providerManagementConfigError } from "../server/auth-cors";
+import type { OcxProviderConfig } from "../types";
+import { printProviderReceipt, runProviderAction } from "./provider-result";
+import { serializeManagementJson } from "./json-input";
+import {
+  CliUsageError, runtimeBaseUrl, runtimeRequest, takeFlag, takeOptionWithSyntax,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx provider add <name> --live [--adapter <id>] [--base-url <url>]
+      [--api-key <key>] [--api-key-transport <x-api-key|bearer>]
+      [--auth-mode <key|forward|oauth|local>] [--responses-path <path>]
+      [--default-model <id>] [--model <id> --text-only]
+      [--google-tool-schema-policy <compatible|reject-lossy>]
+      [--allow-private-network] [--set-default] [--force] [--json]
+  ocx provider set-default <name> --live [--json]
+  ocx provider remove <name> --live --yes [--json]
+Add checks the target roster before writing; a concurrent change can still win the upsert race.
+--force permits overwriting an observed provider. --sync is not supported with --live.
+Remove uses server default reassignment, dependency checks and account/custom-model cleanup.`;
+const AUTH_MODES = new Set(["key", "forward", "oauth", "local"]);
+const OPTION_FIELDS = {
+  "--adapter": "adapter", "--base-url": "baseUrl", "--api-key": "apiKey",
+  "--api-key-transport": "apiKeyTransport", "--auth-mode": "authMode",
+  "--responses-path": "responsesPath", "--default-model": "defaultModel",
+  "--google-tool-schema-policy": "googleToolSchemaPolicy",
+} as const;
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function invalid(message: string): never { throw new CliUsageError(message, USAGE); }
+function flag(args: string[], name: string): boolean {
+  if (args.filter(arg => arg === name).length > 1) invalid("An option was given more than once.");
+  return takeFlag(args, name);
+}
+function checkExplicitFields(fields: Record<string, unknown>): void {
+  if (typeof fields.baseUrl === "string" && providerBaseUrlConfigError(fields.baseUrl)) invalid("Invalid provider base URL.");
+  if (providerRelativeSendPathConfigError("responsesPath", fields.responsesPath)) invalid("Invalid responses path.");
+  if (fields.authMode !== undefined && !AUTH_MODES.has(String(fields.authMode))) invalid("Invalid auth mode.");
+  if (fields.apiKeyTransport !== undefined && !["x-api-key", "bearer"].includes(String(fields.apiKeyTransport))) invalid("Invalid API key transport.");
+  if (fields.googleToolSchemaPolicy !== undefined && !["compatible", "reject-lossy"].includes(String(fields.googleToolSchemaPolicy))) invalid("Invalid Google tool schema policy.");
+}
+function parseAdd(args: string[]) {
+  const force = flag(args, "--force");
+  const setDefault = flag(args, "--set-default");
+  const allowPrivateNetwork = flag(args, "--allow-private-network");
+  const textOnly = flag(args, "--text-only");
+  const model = takeOptionWithSyntax(args, "--model")?.value;
+  const fields: Record<string, unknown> = {};
+  for (const [option, field] of Object.entries(OPTION_FIELDS)) {
+    const value = takeOptionWithSyntax(args, option)?.value;
+    if (value !== undefined) {
+      if (!value.trim()) invalid("Provider options require nonempty values.");
+      fields[field] = value;
+    }
+  }
+  if (allowPrivateNetwork) fields.allowPrivateNetwork = true;
+  if (args.length) invalid("Unexpected provider argument or option.");
+  if (model !== undefined && !textOnly) invalid("--model requires --text-only.");
+  if (model !== undefined && modelCapabilitiesConfigError({ [model]: { inputModalities: ["text"] } })) invalid("Invalid model capability selection.");
+  checkExplicitFields(fields);
+  return { force, setDefault, fields, textOnly, model };
+}
+
+function presetSeed(name: string, payload: unknown): Record<string, unknown> | undefined {
+  if (!record(payload) || !Array.isArray(payload.providers)
+    || payload.providers.some(row => !record(row) || typeof row.id !== "string")) {
+    throw new Error("Invalid provider preset response.");
+  }
+  const matches = payload.providers.filter(row => row.id === name);
+  if (matches.length > 1) throw new Error("Ambiguous provider preset response.");
+  const preset = matches[0] as Record<string, unknown> | undefined;
+  if (!preset) return undefined;
+  // The target catalog's custom row is a form placeholder, not a provider seed.
+  if (name === "custom" && preset.baseUrl === "") return undefined;
+  if (name === "openai") {
+    const seed = preset.provider;
+    if (!record(seed) || typeof seed.baseUrl !== "string"
+      || !isCanonicalOpenAiForwardProvider(seed as unknown as OcxProviderConfig)
+      || !["pool", "direct"].includes(String(seed.codexAccountMode))
+      || Object.hasOwn(seed, "allowPrivateNetwork")
+      || !parseProviderEditorConfigDTO({ defaultProvider: name, providers: { [name]: seed } }).ok
+      || providerRelativeSendPathConfigError("responsesPath", seed.responsesPath)) {
+      throw new Error("Invalid canonical provider preset.");
+    }
+    // Use the selected target's seed verbatim, never a local registry fallback.
+    return structuredClone(seed);
+  }
+  if (typeof preset.adapter !== "string" || !preset.adapter.trim()
+    || typeof preset.baseUrl !== "string" || providerBaseUrlConfigError(preset.baseUrl)
+    || typeof preset.auth !== "string" || !AUTH_MODES.has(preset.auth)) {
+    throw new Error("Invalid provider preset.");
+  }
+  const seed: Record<string, unknown> = { adapter: preset.adapter, baseUrl: preset.baseUrl, authMode: preset.auth };
+  for (const field of ["responsesPath", "chatCompletionsPath", "defaultModel"] as const) {
+    if (preset[field] !== undefined) {
+      if (typeof preset[field] !== "string" || !preset[field].trim()) throw new Error("Invalid provider preset.");
+      seed[field] = preset[field];
+    }
+  }
+  return seed;
+}
+
+async function add(name: string, options: ReturnType<typeof parseAdd>, wantsJson: boolean, deps: RuntimeApiDeps): Promise<number> {
+  const roster = await runtimeRequest<unknown>("/api/providers", { redirect: "error" }, deps);
+  if (!Array.isArray(roster) || roster.some(row => !record(row) || typeof row.name !== "string" || !isValidProviderName(row.name))) {
+    throw new Error("Invalid provider roster response.");
+  }
+  if (!options.force && roster.some(row => row.name === name)) {
+    console.error("Provider already exists on this target. Use --force to permit overwrite.");
+    return 5;
+  }
+  const presets = await runtimeRequest("/api/provider-presets", { redirect: "error" }, deps);
+  const seed = presetSeed(name, presets);
+  if (!seed && (name === "openai" || !options.fields.adapter || !options.fields.baseUrl)) {
+    throw new Error("Target preset unavailable. Custom providers require --adapter and --base-url.");
+  }
+  const provider = { ...seed, ...options.fields };
+  if (provider.googleToolSchemaPolicy !== undefined && provider.adapter !== "google") {
+    invalid("--google-tool-schema-policy requires the google adapter.");
+  }
+  if (provider.apiKey !== undefined && provider.authMode !== undefined && provider.authMode !== "key") {
+    invalid("--api-key requires key authentication; use the provider login workflow for account authentication.");
+  }
+  if (options.textOnly) {
+    const model = options.model ?? provider.defaultModel;
+    if (typeof model !== "string") invalid("--text-only requires --model or a default model.");
+    const capabilities = { [model]: { inputModalities: ["text"] } };
+    if (modelCapabilitiesConfigError(capabilities)) invalid("Invalid model capability selection.");
+    provider.modelCapabilities = capabilities;
+  }
+  if (name !== "openai" && providerManagementConfigError(name, provider)) invalid("Invalid provider configuration.");
+  const result = await runtimeRequest("/api/providers", {
+    method: "POST", redirect: "error",
+    body: serializeManagementJson({ name, provider, ...(options.setDefault ? { setDefault: true } : {}) }),
+  }, deps);
+  return printProviderReceipt(result, wantsJson, "added");
+}
+
+export async function handleProviderLifecycleRuntimeCommand(
+  sub: "add" | "remove" | "set-default", argv: string[], deps: RuntimeApiDeps = {},
+): Promise<number> {
+  return runProviderAction(async () => {
+    const args = [...argv];
+    const wantsJson = flag(args, "--json");
+    const name = args.shift();
+    if (!name || !isValidProviderName(name)) invalid("A valid provider name is required.");
+    const options = sub === "add" ? parseAdd(args) : undefined;
+    const yes = sub === "remove" ? flag(args, "--yes") : false;
+    if (args.length) invalid("Unexpected provider argument or option.");
+    if (sub === "remove" && !yes) invalid("Live removal requires --yes.");
+    if (name === "openai" && options && (Object.keys(options.fields).length || options.textOnly)) {
+      invalid("Canonical OpenAI uses the target preset unchanged; add flags cannot override its seed.");
+    }
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    if (options) return add(name, options, wantsJson, pinned);
+    const result = await runtimeRequest(`/api/providers?name=${encodeURIComponent(name)}`, {
+      method: sub === "remove" ? "DELETE" : "PATCH", redirect: "error",
+      ...(sub === "set-default" ? { body: JSON.stringify({ setDefault: true }) } : {}),
+    }, pinned);
+    return printProviderReceipt(result, wantsJson, sub === "remove" ? "removed" : "set-default");
+  });
+}

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;
+  });
+}