@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/observe-stream.ts

@@ -0,0 +1,142 @@
+/** Bounded, serial observation of fixed management read surfaces. */
+import { readBoundedResponseBytes } from "../lib/bounded-body";
+import { runningProxyUpdateHeaders } from "../oauth/login-cli";
+import { findLiveProxy, type LiveProxy } from "../server/proxy-liveness";
+import { runtimeBaseUrl, type RuntimeApiDeps } from "./runtime-api";
+
+const POLL_MS = 1_000;
+const REQUEST_MS = 10_000;
+const RESPONSE_BYTES = 32 * 1024 * 1024;
+type ObservationPath = "/api/logs" | "/api/debug/injection-logs" | "/api/companion/settings" | "/api/usage";
+
+export interface ObserveStreamDeps extends RuntimeApiDeps {
+  signal?: AbortSignal;
+  /** Reduced timings for isolated tests only; never command-line options. */
+  pollIntervalMs?: number;
+  requestTimeoutMs?: number;
+}
+
+export class ObservationError extends Error {}
+
+function reduced(value: number | undefined, ceiling: number): number {
+  return value !== undefined && Number.isFinite(value) && value > 0 && value <= ceiling ? value : ceiling;
+}
+
+function interrupted<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const abort = () => { cleanup(); reject(signal.reason); };
+    const cleanup = () => signal.removeEventListener("abort", abort);
+    signal.addEventListener("abort", abort, { once: true });
+    work.then(value => { cleanup(); resolve(value); }, error => { cleanup(); reject(error); });
+    if (signal.aborted) abort();
+  });
+}
+
+function waitForPoll(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); };
+    const abort = () => { cleanup(); reject(signal.reason); };
+    const timer = setTimeout(() => { cleanup(); resolve(); }, ms);
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+  });
+}
+
+function identity(live: LiveProxy | undefined): string {
+  return JSON.stringify(live ? [live.pid, live.port, live.hostname, live.role] : null);
+}
+
+export interface ObserveStream {
+  signal: AbortSignal;
+  get(path: ObservationPath, query: URLSearchParams): Promise<unknown>;
+  wait(): Promise<void>;
+}
+
+export interface ObservationContext {
+  kind: "follow" | "snapshot";
+  limitOption?: "--limit" | "--scan-limit";
+}
+
+/** Each invocation owns its signals, in-flight request and pinned runtime identity. */
+export async function withObserveStream(
+  deps: ObserveStreamDeps,
+  run: (stream: ObserveStream) => Promise<void | number>,
+  context: ObservationContext = { kind: "follow", limitOption: "--limit" },
+): Promise<number> {
+  const retry = context.kind === "follow" ? "restart follow" : "retry the command";
+  const controller = new AbortController();
+  let exit = 0;
+  const stop = (code: number) => {
+    if (controller.signal.aborted) return;
+    exit = code;
+    controller.abort();
+  };
+  const onInt = () => stop(130);
+  const onTerm = () => stop(143);
+  process.on("SIGINT", onInt);
+  process.on("SIGTERM", onTerm);
+  deps.signal?.addEventListener("abort", onInt, { once: true });
+  if (deps.signal?.aborted) onInt();
+  let pinned: { origin: string; identity: string } | undefined;
+  const signal = controller.signal;
+  const timeoutMs = reduced(deps.requestTimeoutMs, REQUEST_MS);
+  const get = async (path: ObservationPath, query: URLSearchParams): Promise<unknown> => {
+    signal.throwIfAborted();
+    let live: LiveProxy | undefined;
+    const origin = await interrupted(runtimeBaseUrl({ ...deps, findLiveProxy: async () => {
+      const found = await (deps.findLiveProxy ?? findLiveProxy)();
+      live = found ? { ...found } : undefined;
+      // Snapshot recovery comes from our observed target, never arbitrary transport text.
+      if (context.kind === "snapshot") {
+        if (!found) throw new ObservationError("Proxy is not running. Start it with: ocx start");
+        if (found.role === "client") throw new ObservationError("This listener runs in the client role and has no management API. Run this command on its serving hub, or open the hub dashboard.");
+      }
+      return found;
+    } }), signal);
+    signal.throwIfAborted();
+    const current = { origin, identity: identity(live) };
+    if (pinned && (pinned.origin !== current.origin || pinned.identity !== current.identity)) {
+      throw new ObservationError(`The runtime changed. ${context.kind === "follow" ? "Restart follow" : "Retry the command"} to observe the current runtime.`);
+    }
+    pinned = current;
+    const request = new AbortController();
+    const abort = () => request.abort();
+    signal.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(abort, timeoutMs);
+    try {
+      signal.throwIfAborted();
+      const responsePromise = (deps.fetchImpl ?? fetch)(`${origin}${path}?${query}`, {
+        method: "GET", headers: runningProxyUpdateHeaders(), credentials: "omit", redirect: "error", signal: request.signal,
+      });
+      // A test transport or late fetch may settle after abort. Release its body too.
+      void responsePromise.then(response => {
+        if (request.signal.aborted) void response.body?.cancel().catch(() => {});
+      }, () => {});
+      const response = await interrupted(responsePromise, request.signal);
+      const result = await readBoundedResponseBytes(response, { maxBytes: RESPONSE_BYTES, signal: request.signal });
+      signal.throwIfAborted();
+      request.signal.throwIfAborted();
+      if (result.oversized) throw new ObservationError(`The observation window exceeds 32 MiB. ${context.limitOption ? `Reduce ${context.limitOption} and ${retry}` : "Check the runtime response size and retry the command"}.`);
+      if (!response.ok) throw new ObservationError(`The observation request was refused. Check runtime access and ${retry}.`);
+      return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.bytes));
+    } finally {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", abort);
+      request.abort();
+    }
+  };
+  try {
+    signal.throwIfAborted();
+    const result = await run({ signal, get, wait: () => waitForPoll(reduced(deps.pollIntervalMs, POLL_MS), signal) });
+    return exit || result || 0;
+  } catch (error) {
+    if (exit) return exit;
+    console.error(`Error: ${error instanceof ObservationError ? error.message : `Observation failed or timed out. Check the runtime and ${retry}.`}`);
+    return 1;
+  } finally {
+    controller.abort();
+    process.removeListener("SIGINT", onInt);
+    process.removeListener("SIGTERM", onTerm);
+    deps.signal?.removeEventListener("abort", onInt);
+  }
+}

package/src/cli/observe.ts

@@ -1,5 +1,6 @@
 import {
   CliUsageError,
+  RuntimeApiError,
   printData,
   rejectArgs,
   runCliAction,
@@ -8,10 +9,16 @@ import {
   takeFlag,
   takeIntegerOption,
   takeOption,
+  takeOptionWithSyntax,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import { followLogs } from "./log-follow";
+import { handleLogFilterCommand } from "./log-view-filter";
+import { followInjection } from "./injection-follow";
+import type { ObserveStreamDeps } from "./observe-stream";
 import { formatUsageReport } from "./usage-report";
-import { USAGE_RANGES, USAGE_SURFACES, type UsageSummary } from "../usage/summary";
+import { selectUsageModelView, takeUsageSearchOption } from "./usage-model-search";
+import { USAGE_RANGES, USAGE_SURFACES, type UsageSummary, type UsageFilterEcho } from "../usage/summary";
 import { parseUsageTimeWindow, type UsageTimeWindow } from "../usage/time-range";
 import { redactSecretString } from "../lib/redact";
 import { readClientConnectionState, sameClientConnectionOwner } from "../client/state";
@@ -21,18 +28,19 @@ import type { HubUsageReport } from "../remote/hub-usage";
 
 const USAGE = `Usage:
   ocx observe logs [--provider <name>] [--model <id>] [--status <code>]
-      [--conversation <id>] [--account <label>] [--limit <n>] [--follow] [--json|--jsonl]
+      [--conversation <id>] [--account <label>] [--limit <n>] [--follow] [--json|--jsonl] [--events]
   ocx logs explain <request-id> [--json]
+  ocx logs filter [selectors] [--scan-limit <1..2000>] [--limit <1..2000>] [--json|--jsonl]
   ocx logs rebuild-index
   ocx logs index-status
   ocx observe usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>]
       [--since <epoch-ms|ISO-datetime>] [--until <epoch-ms|ISO-datetime>]
-      [--provider <name>] [--model <id>] [--json]
+      [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--json]
   ocx observe storage [codex-logs [status|protect|unprotect|repair|compact] [--mode <compat|quiet>]] [--json]
   ocx observe memory [--json]
   ocx observe debug [--json]
   ocx observe claude-inbound [--limit <n>] [--json]
-  ocx observe injection [--limit <n>] [--json]`;
+  ocx observe injection [--limit <n>] [--follow [--jsonl]] [--json]`;
 
 type LogEntry = Record<string, unknown> & { id?: string | number; timestamp?: string; provider?: string; model?: string; status?: number };
 
@@ -77,10 +85,11 @@ function formatLog(row: LogEntry): string {
 }
 
 /** Read or follow request logs while preserving raw JSON and JSONL output. */
-async function logs(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+async function logs(argv: string[], deps: ObserveStreamDeps): Promise<number> {
   const args = [...argv];
   const wantsJson = takeFlag(args, "--json");
-  const wantsJsonl = takeFlag(args, "--jsonl");
+  const wantsEvents = takeFlag(args, "--events");
+  const wantsJsonl = takeFlag(args, "--jsonl") || wantsEvents;
   const follow = takeFlag(args, "--follow") || takeFlag(args, "-f");
   const provider = takeOption(args, "--provider");
   const model = takeOption(args, "--model");
@@ -97,24 +106,19 @@ async function logs(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   if (follow && wantsJson) {
     throw new CliUsageError("--follow cannot be combined with --json; use --jsonl for streaming JSONL", USAGE);
   }
-  let seen = new Set<string>();
-  do {
-    const data = await runtimeRequest(`/api/logs${query({ provider, model, status, conversationId, account, limit })}`, {}, deps);
-    const rows = logRows(data);
-    if (!follow && wantsJson) printData(data, true);
-    else {
-      for (const row of rows) {
-        const key = String(row.id ?? `${row.timestamp}:${row.provider}:${row.model}:${row.status}`);
-        if (follow && seen.has(key)) continue;
-        if (wantsJsonl) console.log(JSON.stringify(row));
-        else console.log(formatLog(row));
-        seen.add(key);
-      }
-    }
-    if (!follow) return;
-    if (seen.size > 5_000) seen = new Set([...seen].slice(-2_500));
-    await Bun.sleep(1_000);
-  } while (true);
+  if (wantsEvents && !follow) throw new CliUsageError("--events requires --follow", USAGE);
+  const params = { provider, model, status, conversationId, account, limit };
+  if (follow) {
+    if (limit > 2000) throw new CliUsageError("--limit must be between 1 and 2000 for follow", USAGE);
+    return followLogs({ query: new URLSearchParams(query(params)), limit, jsonl: wantsJsonl, events: wantsEvents, formatRow: formatLog }, deps);
+  }
+  const data = await runtimeRequest(`/api/logs${query(params)}`, {}, deps);
+  if (wantsJson) printData(data, true);
+  else for (const row of logRows(data)) {
+    if (wantsJsonl) console.log(JSON.stringify(row));
+    else console.log(formatLog(row));
+  }
+  return 0;
 }
 
 async function explain(argv: string[], deps: RuntimeApiDeps): Promise<void> {
@@ -163,6 +167,7 @@ async function indexStatus(argv: string[], deps: RuntimeApiDeps): Promise<void>
 
 async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
+  const search = takeUsageSearchOption(args);
   const wantsJson = takeFlag(args, "--json");
   const range = takeOption(args, "--range") ?? "30d";
   const surface = takeOption(args, "--surface") ?? "all";
@@ -170,6 +175,9 @@ async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const model = takeOption(args, "--model");
   const since = takeOption(args, "--since");
   const until = takeOption(args, "--until");
+  const rawKeyId = takeOptionWithSyntax(args, "--api-key-id")?.value;
+  const apiKeyId = rawKeyId?.trim();
+  if (apiKeyId !== undefined && !apiKeyId) throw new CliUsageError("--api-key-id must not be blank", USAGE);
   let window: UsageTimeWindow | undefined;
   try {
     window = parseUsageTimeWindow(since, until);
@@ -184,13 +192,14 @@ async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     throw new CliUsageError(`--surface must be one of ${USAGE_SURFACES.join(", ")}`, USAGE);
   }
   rejectArgs(args.map(redactSecretString), USAGE);
-  const suffix = query({ range, surface, provider, model, since: window?.since, until: window?.until });
+  const suffix = query({ range, surface, provider, model, apiKeyId, since: window?.since, until: window?.until });
   const connection = readClientConnectionState();
-  let result: UsageSummary | HubUsageReport;
+  let result: (UsageSummary & { filter?: UsageFilterEcho }) | HubUsageReport;
   if (connection.kind === "invalid" || connection.kind === "mismatched") {
     throw new Error(`Client usage unavailable: ${connection.reason}`);
   }
   if (connection.kind === "connected") {
+    if (apiKeyId !== undefined) throw new CliUsageError("--api-key-id is unavailable on connected clients; run on the hub for a selected key, or omit it for this client's usage", USAGE);
     const token = readServiceApiTokenState();
     if (token.kind !== "present" || token.fingerprint !== connection.value.tokenFingerprint) {
       throw new Error("Client usage unavailable: the enrolled data key is missing or changed; repair the client connection");
@@ -206,7 +215,18 @@ async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
       throw new Error("Client connection changed while reading usage; retry for the current connection");
     }
   } else {
-    result = await runtimeRequest<UsageSummary>(`/api/usage${suffix}`, {}, deps);
+    if (apiKeyId === undefined) result = await runtimeRequest<UsageSummary>(`/api/usage${suffix}`, {}, deps);
+    else {
+      try {
+        result = await runtimeRequest<UsageSummary & { filter?: UsageFilterEcho }>(`/api/usage${suffix}`, { redirect: "error", credentials: "omit" }, deps);
+      } catch (error) {
+        if (error instanceof RuntimeApiError && error.code === "proxy_not_running") throw error;
+        throw new Error("Key-scoped usage could not be read. Check runtime access and retry.");
+      }
+      if (result?.filter?.apiKeyId !== apiKeyId) {
+        throw new Error("The server did not confirm the requested API key scope. Upgrade and restart the proxy, then retry.");
+      }
+    }
   }
   // Older daemons ignore custom bounds and return successful preset reports.
   if (window && (result?.customWindow !== true || result.since !== window.since || result.until !== window.until)) {
@@ -216,8 +236,10 @@ async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   // the call, so passing formatUsageReport(...) inline would run the human
   // renderer during --json and let its assumptions affect a path that is meant
   // to bypass it entirely.
-  if (wantsJson) printData(result, true);
-  else printData(result, false, formatUsageReport(result as Parameters<typeof formatUsageReport>[0]));
+  const view = search === undefined ? undefined : selectUsageModelView(result, search);
+  const displayed = view ?? result;
+  if (wantsJson) printData(displayed, true);
+  else printData(displayed, false, formatUsageReport(displayed as Parameters<typeof formatUsageReport>[0], view ? { modelView: view.modelView } : undefined));
 }
 
 async function simple(path: string, argv: string[], deps: RuntimeApiDeps): Promise<void> {
@@ -265,24 +287,43 @@ async function storage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, summaryLines(result));
 }
 
-export async function handleObserveCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
-  return runCliAction(async () => {
+async function injection(argv: string[], deps: ObserveStreamDeps): Promise<number> {
+  const args = [...argv];
+  const follow = takeFlag(args, "--follow");
+  const jsonl = takeFlag(args, "--jsonl");
+  if (!follow) {
+    if (jsonl) throw new CliUsageError("--jsonl requires --follow for injection logs", USAGE);
+    await simple("/api/debug/injection-logs", args, deps);
+    return 0;
+  }
+  if (takeFlag(args, "--json")) throw new CliUsageError("--follow cannot be combined with --json; use --jsonl", USAGE);
+  const limit = takeIntegerOption(args, "--limit", { min: 1 }) ?? 500;
+  if (limit > 2000) throw new CliUsageError("--limit must be between 1 and 2000 for follow", USAGE);
+  rejectArgs(args, USAGE);
+  return followInjection(limit, jsonl, deps);
+}
+
+export async function handleObserveCommand(argv: string[], deps: ObserveStreamDeps = {}): Promise<number> {
+  let streamExit = 0;
+  const exit = await runCliAction(async () => {
     const [sub = "logs", ...rest] = argv;
     if (sub === "logs") {
       const action = rest[0];
-      if (action === "explain") await explain(rest.slice(1), deps);
+      if (action === "filter") streamExit = await handleLogFilterCommand(rest.slice(1), deps, formatLog);
+      else if (action === "explain") await explain(rest.slice(1), deps);
       else if (action === "rebuild-index") await rebuildIndex(rest.slice(1), deps);
       else if (action === "index-status") await indexStatus(rest.slice(1), deps);
-      else await logs(rest, deps);
+      else streamExit = await logs(rest, deps);
     }
     else if (sub === "usage") await usage(rest, deps);
     else if (sub === "storage") await storage(rest, deps);
     else if (sub === "memory") await simple("/api/system/memory", rest, deps);
     else if (sub === "debug") await simple("/api/debug", rest, deps);
     else if (sub === "claude-inbound") await simple("/api/claude/inbound-debug", rest, deps);
-    else if (sub === "injection") await simple("/api/debug/injection-logs", rest, deps);
+    else if (sub === "injection") streamExit = await injection(rest, deps);
     else throw new CliUsageError(`unknown observe command ${sub}`, USAGE);
   });
+  return exit || streamExit;
 }
 
 export const OBSERVE_USAGE = USAGE;

package/src/cli/provider-batch.ts

@@ -0,0 +1,77 @@
+import { parseProviderEditorConfigDTO } from "../server/auth-cors";
+import { readJsonInput, serializeManagementJson } from "./json-input";
+import { printProviderReceipt, runProviderAction } from "./provider-result";
+import {
+  CliUsageError, printData, runtimeBaseUrl, runtimeRequest, takeFlag,
+  takeOptionWithSyntax, type RuntimeApiDeps,
+} from "./runtime-api";
+
+function record(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function editorInput(value: unknown) {
+  const parsed = parseProviderEditorConfigDTO(value);
+  if (!parsed.ok) throw new CliUsageError("Provider batch input must be an editable provider snapshot without secret, derived or unknown fields.");
+  return parsed.value;
+}
+
+async function snapshot(wantsJson: boolean, deps: RuntimeApiDeps): Promise<number> {
+  const baseUrl = await runtimeBaseUrl(deps);
+  const fetched = await runtimeRequest("/api/config", { method: "GET", redirect: "error" }, { ...deps, baseUrl });
+  if (!record(fetched) || !record(fetched.providers)) throw new Error("Invalid provider snapshot response.");
+  const entries = Object.entries(fetched.providers).map(([name, provider]) => {
+    if (!record(provider)) throw new Error("Invalid provider snapshot response.");
+    // These are the four dashboard decorations, not editor fields. Any other
+    // unexpected field must reach the canonical parser and fail closed.
+    const { hasApiKey, hasHeaders, xaiResponsesOptInState, initialModelSelection, ...editable } = provider;
+    return [name, editable] as const;
+  });
+  const parsed = parseProviderEditorConfigDTO({
+    defaultProvider: fetched.defaultProvider,
+    providers: Object.fromEntries(entries),
+  });
+  if (!parsed.ok) throw new Error("Invalid provider snapshot response.");
+  printData(parsed.value, wantsJson);
+  return 0;
+}
+
+async function apply(args: string[], wantsJson: boolean, deps: RuntimeApiDeps): Promise<number> {
+  const baselinePath = takeOptionWithSyntax(args, "--baseline")?.value;
+  const nextPath = takeOptionWithSyntax(args, "--file")?.value;
+  const confirmed = takeFlag(args, "--yes");
+  if (args.length || !baselinePath?.trim() || !nextPath?.trim()) {
+    throw new CliUsageError("Provider apply requires --baseline FILE and --file FILE, with optional --yes and --json.");
+  }
+  if (baselinePath === "-" && nextPath === "-") {
+    throw new CliUsageError("Provider apply accepts at most one stdin source.");
+  }
+  // Parse both documents as supplied: normalizing a public baseline would
+  // change the server's CAS comparison and can discard unseen private data.
+  const baseline = editorInput(await readJsonInput(baselinePath, deps, "Provider baseline"));
+  const next = editorInput(await readJsonInput(nextPath, deps, "Provider next snapshot"));
+  if (!confirmed && Object.keys(baseline.providers).some(name => !Object.hasOwn(next.providers, name))) {
+    throw new CliUsageError("Provider removals or renames require --yes. Batch apply does not perform single-provider DELETE OAuth account cleanup.");
+  }
+  const body = serializeManagementJson({ baseline, next });
+  const baseUrl = await runtimeBaseUrl(deps);
+  const result = await runtimeRequest("/api/providers", {
+    method: "PUT", redirect: "error", headers: { "content-type": "application/json" }, body,
+  }, { ...deps, baseUrl });
+  return printProviderReceipt(result, wantsJson, "Provider batch");
+}
+
+/** Public editor snapshots and one server-authoritative compare-and-swap. */
+export async function handleProviderBatchCommand(
+  sub: "snapshot" | "apply", args: string[], deps: RuntimeApiDeps = {},
+): Promise<number> {
+  return runProviderAction(async () => {
+    const argv = [...args];
+    const wantsJson = takeFlag(argv, "--json");
+    if (sub === "apply") return apply(argv, wantsJson, deps);
+    if (argv.length) throw new CliUsageError("Provider snapshot accepts only --json.");
+    return snapshot(wantsJson, deps);
+  });
+}

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