@bitkyc08/opencodex 2.28.0 → 2.29.0

package/src/cli/agent.ts

@@ -13,6 +13,13 @@ import {
   type RuntimeApiDeps,
 } from "./runtime-api";
 
+interface WebSearchModelOption {
+  value: string;
+  model: string;
+  backend: "openai" | "anthropic";
+  authSlot?: boolean;
+}
+
 const USAGE = `Usage:
   ocx agent [status] [--json]
   ocx agent injection <status|set> [--model <id|->] [--effort <level|->]
@@ -20,7 +27,7 @@ const USAGE = `Usage:
   ocx agent effort <status|set> [--main <level|->] [--subagent <level|->] [--json]
   ocx agent subagents <status|set|clear> [model,model...] [--json]
   ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
-  ocx agent sidecar <status|web|vision> [--model <id|->] [--backend <openai|anthropic|->]
+  ocx agent sidecar <status|web|vision> [--list] [--model <id|->] [--backend <openai|anthropic|xai|gemini|exa|->]
       [--reasoning <level>] [--max-descriptions <n>] [--json]`;
 
 function clearable(value: string | undefined): string | null | undefined {
@@ -152,6 +159,29 @@ async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     return;
   }
   if (section !== "web" && section !== "vision") throw new CliUsageError("sidecar must be web, vision, or status", USAGE);
+  // --list must be consumed BEFORE rejectArgs sees it. It prints the server's
+  // candidate set — the exact list the GUI picker shows (#2188): the server
+  // computes it once and every surface consumes it, so the CLI cannot drift.
+  const wantsList = takeFlag(args, "--list");
+  if (wantsList) {
+    rejectArgs(args, USAGE);
+    const settings = await runtimeRequest("/api/sidecar-settings", {}, deps) as {
+      webSearchModels?: WebSearchModelOption[];
+      visionModels?: Array<{ value: string; backend?: string; baseline?: boolean }>;
+    };
+    if (section === "web") {
+      const options = settings.webSearchModels ?? [];
+      printData(options, wantsJson, options.length === 0
+        ? ["no runnable web-search sidecar models (log in to ChatGPT or Anthropic)"]
+        : options.map(option => `${option.value} [${option.backend}]${option.authSlot ? " (auth slot)" : ""}`));
+    } else {
+      const options = settings.visionModels ?? [];
+      printData(options, wantsJson, options.length === 0
+        ? ["no eligible vision describers"]
+        : options.map(option => `${option.value}${option.backend ? ` [${option.backend}]` : ""}${option.baseline ? " (baseline)" : ""}`));
+    }
+    return;
+  }
   const model = takeOption(args, "--model");
   const backend = takeOption(args, "--backend");
   const reasoning = takeOption(args, "--reasoning");
@@ -163,6 +193,19 @@ async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   if (reasoning !== undefined) settings.reasoning = reasoning;
   if (maxDescriptionsPerTurn !== undefined) settings.maxDescriptionsPerTurn = maxDescriptionsPerTurn;
   if (Object.keys(settings).length === 0) throw new CliUsageError("at least one sidecar option is required", USAGE);
+  if (section === "web" && model !== undefined && model !== "-") {
+    const offered = await runtimeRequest("/api/sidecar-settings", {}, deps) as {
+      webSearchModels?: WebSearchModelOption[];
+    };
+    const requestedBackend = backend === "-" ? "openai" : backend;
+    const option = offered.webSearchModels?.find(candidate =>
+      (candidate.value === model || candidate.model === model)
+      && (requestedBackend === undefined || candidate.backend === requestedBackend));
+    if (option) {
+      settings.model = option.model;
+      if (backend !== "-") settings.backend = option.backend;
+    }
+  }
   const body = section === "web" ? { webSearch: settings } : { vision: settings };
   const result = await runtimeRequest("/api/sidecar-settings", { method: "PUT", body: JSON.stringify(body) }, deps);
   printData(result, wantsJson, [`${section} sidecar settings updated.`]);

package/src/cli/claude-agent-startup-sync.ts

@@ -0,0 +1,73 @@
+import type { OcxConfig } from "../types";
+import { injectClaudeAgentDefs } from "../claude/agents-inject";
+import { fetchClaudeContextWindows } from "./claude";
+import type { ReadinessGate } from "../server/readiness";
+
+export interface ClaudeAgentStartupSyncDeps {
+  fetchContextWindows?: typeof fetchClaudeContextWindows;
+  injectAgentDefs?: typeof injectClaudeAgentDefs;
+  warn?: (message: string) => void;
+}
+
+/**
+ * Keep the public readiness gate pending until both startup reconciliations have settled.
+ *
+ * The Codex sync remains the authority for ready versus failed. Claude roster repair is
+ * deliberately best-effort (#2200), but readiness must not become observable between the
+ * Codex write and that repair: a service manager could otherwise launch Claude Code against
+ * stale `ocx-*.md` files. A small forwarding gate delays only the successful transition;
+ * terminal Codex failure is still published immediately.
+ */
+export async function reconcileClientStartupBeforeReady<T>(
+  readinessGate: ReadinessGate,
+  syncCodex: (deferredGate: ReadinessGate) => Promise<T>,
+  syncClaudeRoster: () => Promise<unknown>,
+): Promise<T> {
+  let codexReady = false;
+  const deferredGate: ReadinessGate = {
+    getStatus: () => readinessGate.getStatus(),
+    markReady: () => { codexReady = true; },
+    markFailed: () => readinessGate.markFailed(),
+  };
+
+  const result = await syncCodex(deferredGate);
+  await syncClaudeRoster();
+  if (codexReady) readinessGate.markReady();
+  return result;
+}
+
+/**
+ * Reconcile the generated Claude Code roster after the proxy listener is live.
+ *
+ * This belongs to the owning CLI lifecycle rather than `startServer`: the latter is also a
+ * library/test primitive and must not mutate a developer's real `~/.claude` directory merely
+ * because an in-process test server was created. The live Management API supplies the same bounded
+ * context-window map used by `ocx claude`; failure keeps startup available and falls back to an
+ * unmarked roster. Disabled integrations skip discovery and prune verified-owned definitions.
+ */
+export async function syncClaudeAgentDefsAtProxyStartup(
+  config: OcxConfig,
+  port: number,
+  deps: ClaudeAgentStartupSyncDeps = {},
+): Promise<string[] | null> {
+  const inject = deps.injectAgentDefs ?? injectClaudeAgentDefs;
+  const warn = deps.warn ?? (message => console.warn(message));
+
+  try {
+    if (config.claudeCode?.enabled === false || config.claudeCode?.injectAgents === false) {
+      return inject(config, {});
+    }
+
+    let windows: Record<string, number> = {};
+    try {
+      windows = await (deps.fetchContextWindows ?? fetchClaudeContextWindows)(config, port);
+    } catch {
+      // Startup remains best-effort. The next management mutation or `ocx claude` launch can
+      // restore context markers after a transient catalog/Management API failure.
+    }
+    return inject(config, windows);
+  } catch (error) {
+    warn(`⚠ Claude agent definitions could not be synced at proxy startup: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}

package/src/cli/dispatch.ts

@@ -204,8 +204,9 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   sync: async deps => {
     const restartCodex = deps.args.slice(1).includes("--restart-codex");
+    const live = await deps.findLiveProxy();
     const synced = await syncModelsToCodex(
-      (await deps.findLiveProxy())?.port,
+      live?.port,
       undefined,
       undefined,
       undefined,
@@ -229,6 +230,28 @@ const commandRunners: Record<string, CommandRunner> = {
     if (synced.catalogWritten || synced.cacheSynced) {
       afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
     }
+    // `ocx sync` is a direct CLI path; it does not call the management
+    // `/api/sync` route. Refresh the already-connected MCode block here too,
+    // after Codex has published the catalog that supplies its capabilities.
+    if (synced.status !== "refused" && live) {
+      try {
+        const config = deps.loadConfig();
+        const { refreshOwnedIntegration } = await import("../integrations/owned-refresh");
+        const result = await refreshOwnedIntegration({
+          clientId: "mcode",
+          models: async () => {
+            const { loadExportModels } = await import("../server/management/model-rows");
+            return loadExportModels(config);
+          },
+          config,
+          port: live.port,
+        });
+        if (result?.changed) console.log("MCode integration refreshed from the current catalog.");
+        else if (result?.reason) console.warn(`MCode integration was not refreshed: ${result.reason}`);
+      } catch (error) {
+        console.warn(`MCode integration was not refreshed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
     return code;
   },
   v2: async deps => {

package/src/cli/ensure-desired-integrations.ts

@@ -0,0 +1,152 @@
+/**
+ * Align Grok and Claude Desktop files with the durable switches during `ocx ensure`.
+ *
+ * handleEnsure used to load config once, then health-probe / model-sync / spawn,
+ * and only afterwards mutate ~/.grok/config.toml and the Desktop library from
+ * that snapshot. An OFF→ON flip in that window stripped a freshly enabled fence
+ * or deleted a freshly applied Desktop profile; ON→OFF rewrote the files the
+ * user had just turned off. Re-read persisted desired state immediately before
+ * each external-file mutation, and use that current config for sync inputs.
+ */
+import { loadConfig } from "../config";
+import { stripGrokConfig, type GrokInjectResult } from "../grok/inject";
+import { removeDesktop3pStandardPivot } from "../claude/desktop-3p";
+import {
+  claudeDesktopIntegrationEnabled,
+  shouldSyncGrokOnStart,
+} from "../codex/desired-state";
+import type { OcxConfig } from "../types";
+
+export function grokSyncFailureMessage(err: unknown): string {
+  const detail = err instanceof Error ? err.message : String(err);
+  return `Grok Build config sync failed: ${detail}. `
+    + "~/.grok/config.toml may still point at a previous proxy port — "
+    + "run 'ocx ensure' (or apply from the dashboard's Grok page) to repoint it.";
+}
+
+export interface EnsureDesiredIntegrationsDeps {
+  loadConfig: () => OcxConfig;
+  stripGrokConfig: typeof stripGrokConfig;
+  syncGrokConfig: (
+    port: number,
+    config: OcxConfig,
+    opts?: { hostname?: string },
+  ) => Promise<GrokInjectResult>;
+  removeDesktop3pStandardPivot: typeof removeDesktop3pStandardPivot;
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+}
+
+async function defaultSyncGrokConfig(
+  port: number,
+  config: OcxConfig,
+  opts: { hostname?: string } = {},
+): Promise<GrokInjectResult> {
+  const { syncGrokConfig } = await import("../grok/sync");
+  return syncGrokConfig(port, config, opts);
+}
+
+const productionDeps: EnsureDesiredIntegrationsDeps = {
+  loadConfig,
+  stripGrokConfig,
+  syncGrokConfig: defaultSyncGrokConfig,
+  removeDesktop3pStandardPivot,
+};
+
+function io(deps: EnsureDesiredIntegrationsDeps): {
+  log: (message: string) => void;
+  error: (message: string) => void;
+} {
+  return {
+    log: deps.log ?? (message => console.log(message)),
+    error: deps.error ?? (message => console.error(message)),
+  };
+}
+
+/**
+ * Keep ~/.grok/config.toml aligned with the durable Grok switch.
+ *
+ * `handleStart` already gates inject on `shouldSyncGrokOnStart`. `ocx ensure`
+ * used to call `syncGrokConfig` unconditionally, so a dashboard/update/restart
+ * path that lands in ensure rewrote the fence while the switch stayed OFF.
+ * When the switch is OFF, strip any leftover managed block instead of injecting.
+ */
+export async function ensureGrokFenceMatchesDesired(
+  port: number,
+  opts: { hostname?: string } = {},
+  deps: EnsureDesiredIntegrationsDeps = productionDeps,
+): Promise<void> {
+  const config = deps.loadConfig();
+  const { log, error } = io(deps);
+  if (!shouldSyncGrokOnStart(config)) {
+    try {
+      const grok = deps.stripGrokConfig();
+      if (grok.changed) log(`   ↩️  ${grok.message}`);
+      else if (!grok.ok) error(`⚠️  ${grok.message}`);
+    } catch (err) {
+      error(`⚠️  ${grokSyncFailureMessage(err)}`);
+    }
+    return;
+  }
+  try {
+    const hostname = opts.hostname ?? config.hostname;
+    const g = await deps.syncGrokConfig(
+      port,
+      config,
+      hostname !== undefined ? { hostname } : {},
+    );
+    if (g.changed) log("   + Grok Build config updated (~/.grok/config.toml)");
+    else if (!g.ok) error(`⚠️  ${g.message}`);
+  } catch (err) {
+    error(`⚠️  ${grokSyncFailureMessage(err)}`);
+  }
+}
+
+/**
+ * When Claude Desktop is durably OFF, clear any leftover owned gateway profile.
+ * ensure/update used to leave Claude-3p residue in place after a failed disable
+ * (drifted fingerprint), so the Integrations card kept looking applied/stale.
+ */
+export function ensureClaudeDesktopMatchesDesired(
+  deps: EnsureDesiredIntegrationsDeps = productionDeps,
+): void {
+  const config = deps.loadConfig();
+  const { log, error } = io(deps);
+  if (claudeDesktopIntegrationEnabled(config)) return;
+  try {
+    const removed = deps.removeDesktop3pStandardPivot({
+      appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null,
+    });
+    if (removed.ok && removed.changed) {
+      log("   ↩️  Claude Desktop integration residue removed.");
+    } else if (!removed.ok) {
+      error(`⚠️  Claude Desktop cleanup skipped: ${removed.reason ?? removed.kind}.`);
+    }
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    error(`⚠️  Claude Desktop cleanup failed: ${detail}.`);
+  }
+}
+
+export type EnsureDesiredIntegrationsBranch =
+  | { kind: "live"; hostname?: string }
+  | { kind: "spawned" };
+
+/**
+ * Reconcile the two external integration files after either ensure race window.
+ * Only the live proxy's observed bind host crosses this boundary; persisted
+ * config is deliberately loaded inside each mutation helper.
+ */
+export async function reconcileEnsureDesiredIntegrations(
+  port: number,
+  branch: EnsureDesiredIntegrationsBranch,
+  deps: EnsureDesiredIntegrationsDeps = productionDeps,
+): Promise<void> {
+  const liveHost = branch.kind === "live" ? branch.hostname : undefined;
+  await ensureGrokFenceMatchesDesired(
+    port,
+    liveHost ? { hostname: liveHost } : {},
+    deps,
+  );
+  ensureClaudeDesktopMatchesDesired(deps);
+}

package/src/cli/help.ts

@@ -60,7 +60,7 @@ Usage:
   ocx memory [--json]         Alias of ocx observe memory
   ocx api-key <sub>           Alias of ocx access key
   ocx access <sub>            External API keys and endpoint information
-  ocx export --client <id>    Print a client config wired to the running proxy (10 clients)
+  ocx export --client <id>    Print a client config wired to the running proxy (11 clients)
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, and updates

package/src/cli/index.ts

@@ -54,7 +54,18 @@ import { maybeShowStarPrompt } from "./star-prompt";
 import { scheduleCatalogPrewarm } from "./catalog-prewarm";
 import { maybeShowUpdatePrompt } from "../update/notify";
 import { syncModelsToCodex } from "../codex/sync";
-import { setIntegrationEnabled, shouldSyncCodexOnStart, shouldSyncGrokOnStart, syncCodexOnStartIfEnabled } from "../codex/desired-state";
+import {
+  shouldSyncGrokOnStart,
+  syncCodexOnStartIfEnabled,
+} from "../codex/desired-state";
+import {
+  reconcileClientStartupBeforeReady,
+  syncClaudeAgentDefsAtProxyStartup,
+} from "./claude-agent-startup-sync";
+import {
+  grokSyncFailureMessage,
+  reconcileEnsureDesiredIntegrations,
+} from "./ensure-desired-integrations";
 
 /**
  * A failed shell-hook reconcile is not cosmetic: a stale hook keeps sourcing
@@ -116,21 +127,6 @@ async function waitForProxy(timeoutMs = 8_000): Promise<LiveProxy | null> {
   return null;
 }
 
-/**
- * A Grok fence sync that throws is best-effort by design — it must never block startup.
- * Reporting nothing, however, is what lets a STALE fence survive: `~/.grok/config.toml`
- * keeps naming whatever port the last successful sync wrote, and once that listener is
- * gone every grok turn retries against a refused connection while our own log stays
- * silent (2026-07-27 field report: 8 entries pinned to a dead 127.0.0.1:4179).
- * So say what failed and name the single command that repairs it.
- */
-function grokSyncFailureMessage(err: unknown): string {
-  const detail = err instanceof Error ? err.message : String(err);
-  return `Grok Build config sync failed: ${detail}. `
-    + "~/.grok/config.toml may still point at a previous proxy port — "
-    + "run 'ocx ensure' (or apply from the dashboard's Grok page) to repoint it.";
-}
-
 /** Argv for detached `start`, optionally hard-pinning the listen port. */
 function startArgv(port?: number): string[] {
   const args = ["start"];
@@ -381,14 +377,18 @@ async function handleStart(options: { block?: boolean } = {}) {
   // The hook is useful only for an installed Claude Code CLI. Reconcile instead of
   // appending unconditionally so stale OpenCodex-owned hooks are removed as well.
   reportShellHookFailure(reconcileShellHook(systemEnv.injected));
-
   await maybeShowStarPrompt(); // once-only Yes/No GitHub-star prompt on first interactive start
-  // Post-startup sync drives the readiness gate AND the #1046 stale app-server
-  // warning. `syncCodexOnStartIfEnabled` respects the Codex integration toggle
-  // (OFF → no sync) and reports whether anything was written; the readiness gate
-  // observes the real sync outcome (ok/warning) so /readyz never advertises a
-  // half-synced proxy as ready while /healthz stays live.
-  const startupSync = await syncCodexOnStartIfEnabled(port, config, undefined, readinessGate);
+  // Codex sync owns the ready/failed verdict, but its successful transition is
+  // deferred until the best-effort Claude roster reconciliation settles. This
+  // keeps /readyz closed across both startup writes without making an optional
+  // Claude integration failure prevent the proxy from starting.
+  const startupSync = await reconcileClientStartupBeforeReady(
+    readinessGate,
+    gate => syncCodexOnStartIfEnabled(port, config, undefined, gate),
+    () => systemEnv.injected
+      ? Promise.resolve(null)
+      : syncClaudeAgentDefsAtProxyStartup(config, port),
+  );
   if (!startupSync.ran) console.log("   Codex integration OFF; startup left Codex native.");
   // #1046: one warning per startup, after BOTH writes. The server's cache
   // invalidation happens first and the catalog sync second, so the mtime is only
@@ -469,14 +469,15 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
       // Ensure env file exists for already-running proxy (may have been deleted or pre-dates this feature).
       const systemEnv = await injectSystemEnv(live.port, config).catch(() => ({ injected: false }));
       reportShellHookFailure(reconcileShellHook(systemEnv.injected));
+      if (!systemEnv.injected) await syncClaudeAgentDefsAtProxyStartup(config, live.port);
       // Refresh the Grok Build fence too (same contract as start). live.hostname is the
       // hostname the running proxy actually bound — config.hostname may have drifted.
-      try {
-        const { syncGrokConfig } = await import("../grok/sync");
-        const g = await syncGrokConfig(live.port, config, live.hostname ? { hostname: live.hostname } : {});
-        if (g.changed) console.log("   + Grok Build config updated (~/.grok/config.toml)");
-        else if (!g.ok) console.error(`⚠️  ${g.message}`);
-      } catch (err) { console.error(`⚠️  ${grokSyncFailureMessage(err)}`); }
+      // The reconciler re-reads immediately before each client-file mutation; only
+      // the live proxy's observed bind host is safe to carry across this boundary.
+      await reconcileEnsureDesiredIntegrations(
+        live.port,
+        { kind: "live", hostname: live.hostname },
+      );
       console.log(`✅ Proxy running on port ${live.port}`);
       return true;
     }
@@ -496,15 +497,12 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
     process.exitCode = 1;
     return false;
   }
-  // Deterministic fence guarantee: the spawned child injects late in its own startup, but
-  // this parent returns as soon as /healthz responds — inject here too (idempotent block
-  // replace) so `ocx ensure` never returns without the Grok fence in place.
-  try {
-    const { syncGrokConfig } = await import("../grok/sync");
-    const g = await syncGrokConfig(port, config, config.hostname ? { hostname: config.hostname } : {});
-    if (g.changed) console.log("   + Grok Build config updated (~/.grok/config.toml)");
-    else if (!g.ok) console.error(`⚠️  ${g.message}`);
-  } catch (err) { console.error(`⚠️  ${grokSyncFailureMessage(err)}`); }
+  // Deterministic fence guarantee when the durable switch is ON: the spawned child
+  // injects late in its own startup, but this parent returns as soon as /healthz
+  // responds — align here too so `ocx ensure` never returns with a stale ON/OFF mismatch.
+  // Persisted state is loaded inside each mutation after waitForProxy, so a
+  // toggle while the child starts wins over the pre-spawn snapshot.
+  await reconcileEnsureDesiredIntegrations(port, { kind: "spawned" });
   // Always sync the LIVE port: after a fallback-port start, config.port still names the
   // busy preferred port — syncing that would point Codex at a dead listener.
   const synced = await syncModelsToCodex(port).catch(e => {
@@ -512,6 +510,10 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
     return null;
   });
   if (synced?.status === "skipped") console.log("   Codex integration OFF; startup left Codex native.");
+  // The child opens /healthz before its best-effort roster reconcile. Await the same idempotent
+  // operation in the parent so `ocx ensure` cannot report success while stale ocx-*.md files are
+  // still observable. Always use the live port, including fallback-port starts.
+  await syncClaudeAgentDefsAtProxyStartup(config, port);
   console.log(`✅ Proxy running on port ${port}`);
   return true;
 }

package/src/cli/integrations.ts

@@ -18,7 +18,7 @@ const CLAUDE_USAGE = `Usage:
       [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>]
       [--compact-window <tokens|default>] [--inject-agents <on|off>]
       [--small-fast-model <id|->] [--model-map <from=to,from=to|->]
-      [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|->]
+      [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->]
       [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]`;
 
 const GROK_USAGE = `Usage:

package/src/cli/registry.ts

@@ -216,8 +216,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "api-key", usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
   {
     name: "export",
-    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode) wired to the running proxy.",
+    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent) wired to the running proxy.",
     details: [
       "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
       "--out <path> writes the native config there and refuses to replace an existing file without --force.",