@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

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/opencode.ts

@@ -39,6 +39,7 @@ import type {
   OpencodeProviderBlocks,
   OpencodeV2ProviderBlock,
 } from "../clients/config-export";
+import type { EffectiveModelExportMetadata } from "../clients/config-export/contracts";
 import { filterCatalogVisibleModels, visibleNativeSlugs } from "../codex/catalog";
 import { commandInvocation } from "../lib/win-exec";
 import { configuredAdminToken, opencodeCatalogToken } from "../lib/admin-secrets";
@@ -106,12 +107,30 @@ export interface OpencodeProxyModelRow {
   contextWindow?: number;
   /** Authoritative output limit (CatalogModel.maxOutputTokens); optional. */
   maxOutputTokens?: number;
+  /** Authoritative input ceiling (CatalogModel.maxInputTokens); optional. */
+  maxInputTokens?: number;
+  /**
+   * Derived on the hub from known evidence; absent means unknown, never a negative. An
+   * explicit `false` from the hub is evidence too and is carried through unchanged.
+   */
+  supportsTools?: boolean;
+  supportsReasoning?: boolean;
+  supportsReasoningSummaries?: boolean;
   /** Declared input modalities from `/api/models`; carried into opencode model capabilities. */
   inputModalities?: string[];
   /** Declared effort ladder from `/api/models`; carried into opencode model variants. */
   reasoningEfforts?: string[];
   /** Declared default effort from `/api/models`. */
   defaultReasoningEffort?: string;
+  /**
+   * Effective export metadata `/api/models` attaches to every row it produces. Custom row
+   * fields are the operator's stored overrides, so this object is the authoritative
+   * projection a client consumes; routed and native rows carry their declared default in it
+   * because the row-level default is the picker's preference order. When present, an absent
+   * field inside means "no declared value" — never "fall back to the row" — and every field
+   * below still works for rows without it (older hubs, hand-built rows).
+   */
+  exportMetadata?: EffectiveModelExportMetadata;
 }
 
 const PROJECT_CONFIG_FILENAMES = ["opencode.json", "opencode.jsonc"] as const;
@@ -324,6 +343,12 @@ export async function fetchOpencodeProxyModels(
 /**
  * Visible OpenCode catalog entries from proxy /api/models rows. Disabled rows are omitted;
  * native rows are omitted in Codex Direct mode.
+ *
+ * Custom rows carry their effective projection in `exportMetadata`; when it is present it
+ * wins over the row's own fields, which for a custom row are the operator's stored overrides
+ * rather than the resolved capabilities. Routed/native projections also distinguish declared
+ * defaults from picker preferences; older hubs without the field retain their row values. The empty-vs-undefined ladder distinction
+ * survives: a row declaring `reasoningEfforts: []` exports `[]`, not an absent key.
  */
 export function opencodeCatalogFromProxyRows(
   rows: readonly OpencodeProxyModelRow[],
@@ -343,24 +368,43 @@ export function opencodeCatalogFromProxyRows(
       && !visibleRouted.has(row)) continue;
     if (seen.has(namespaced)) continue;
     seen.add(namespaced);
+    const effective = row.exportMetadata;
+    const maxTokens = effective?.maxTokens ?? row.maxOutputTokens;
+    const maxInputTokens = effective?.maxInputTokens ?? row.maxInputTokens;
+    const inputModalities = effective?.inputModalities ?? row.inputModalities;
+    const reasoningEfforts = effective?.reasoningEfforts ?? row.reasoningEfforts;
+    // The projection is the authority on the default: when it exists, an absent default means
+    // NO declared default, and falling back to the row would reintroduce the picker's
+    // synthetic medium/low value. Rows without one (older hubs, hand-built rows) keep the
+    // row's own value.
+    const defaultReasoningEffort = effective !== undefined
+      ? effective.defaultReasoningEffort
+      : row.defaultReasoningEffort;
+    const supportsTools = effective?.supportsTools ?? row.supportsTools;
+    const supportsReasoning = effective?.supportsReasoning ?? row.supportsReasoning;
+    const supportsReasoningSummaries = effective?.supportsReasoningSummaries ?? row.supportsReasoningSummaries;
     catalog.push({
       namespaced,
       native: row.native === true,
       provider: row.provider,
       id: row.id,
-      contextWindow: row.contextWindow,
-      ...(typeof row.maxOutputTokens === "number" ? { maxTokens: row.maxOutputTokens } : {}),
+      contextWindow: effective?.contextWindow ?? row.contextWindow,
+      ...(typeof maxTokens === "number" ? { maxTokens } : {}),
+      ...(typeof maxInputTokens === "number" ? { maxInputTokens } : {}),
       displayName: row.displayNameSource === "fallback" ? undefined : row.displayName,
-      ...(Array.isArray(row.inputModalities) && row.inputModalities.length > 0
-        ? { inputModalities: [...row.inputModalities] }
+      ...(Array.isArray(inputModalities) && inputModalities.length > 0
+        ? { inputModalities: [...inputModalities] }
         : {}),
       ...(typeof row.fastRowAvailable === "boolean" ? { fastRowAvailable: row.fastRowAvailable } : {}),
-      ...(Array.isArray(row.reasoningEfforts) && row.reasoningEfforts.length > 0
-        ? { reasoningEfforts: [...row.reasoningEfforts] }
-        : {}),
-      ...(typeof row.defaultReasoningEffort === "string" && row.defaultReasoningEffort.length > 0
-        ? { defaultReasoningEffort: row.defaultReasoningEffort }
+      // `[]` is a declaration, not an absence: an explicit no-rungs ladder stays empty here.
+      ...(Array.isArray(reasoningEfforts) ? { reasoningEfforts: [...reasoningEfforts] } : {}),
+      ...(typeof defaultReasoningEffort === "string" && defaultReasoningEffort.length > 0
+        ? { defaultReasoningEffort }
         : {}),
+      // An explicit false survives the hop; only derivation is true-or-nothing.
+      ...(typeof supportsTools === "boolean" ? { supportsTools } : {}),
+      ...(typeof supportsReasoning === "boolean" ? { supportsReasoning } : {}),
+      ...(typeof supportsReasoningSummaries === "boolean" ? { supportsReasoningSummaries } : {}),
     });
   }
   return catalog;
@@ -377,7 +421,7 @@ export function isOpencodeRuntimeConfigError(
 
 /**
  * Merge inherited `OPENCODE_CONFIG_CONTENT` and override only our own blocks:
- * `provider.opencodex` (V1) and `providers.opencodex` (V2, the one carrying variants).
+ * `provider.opencodex` (V1 maps) and `providers.opencodex` (native V2 arrays).
  * When no inline layer is present, emit the minimal runtime object for this launcher.
  */
 export function mergeOpencodeRuntimeConfig(

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