@yansigit/opencodex 2.31.0

package/src/cli/tray-proxy.ts

@@ -0,0 +1,199 @@
+export interface TrayProxyLive { port: number }
+
+export interface TrayProxyServiceState {
+  installed: boolean;
+  startable: boolean;
+  summary: string;
+}
+
+export interface TrayProxyStartIo {
+  findLive: () => Promise<TrayProxyLive | null>;
+  /** Normal Start is idempotent; restart fallback refuses a target that reappeared. */
+  existingIsSuccess?: boolean;
+  diagnoseService: () => TrayProxyServiceState;
+  startService: () => void | Promise<void>;
+  startDirect: () => void | Promise<void>;
+  waitForProxy: () => Promise<TrayProxyLive | null>;
+  info: (message: string) => void;
+  error: (message: string) => void;
+}
+
+export interface ProxyRestartLive {
+  pid: number | null;
+  port: number;
+  hostname?: string;
+  source: "runtime" | "config";
+}
+
+export type ProxyRestartRequestOutcome =
+  | { accepted: true }
+  | { accepted: false; uncertain: boolean; error?: unknown };
+
+export type ProxyRestartResult =
+  | { ok: true; mode: "started" }
+  | { ok: true; mode: "skipped" }
+  | { ok: true; mode: "restarted"; live: ProxyRestartLive }
+  | { ok: false; phase: "start" | "identity" | "request" | "replacement"; error?: unknown };
+
+export type ProxyRestartDiscovery =
+  | { status: "live"; live: ProxyRestartLive }
+  | { status: "absent" }
+  | { status: "uncertain"; error?: unknown };
+
+export interface ProxyRestartDiscoveryIo {
+  findLive: () => Promise<ProxyRestartLive | null>;
+  waitBetweenChecks?: () => Promise<void>;
+  expired?: () => boolean;
+}
+
+export interface ProxyRestartIo {
+  findLive: () => Promise<ProxyRestartDiscovery>;
+  startWhenStopped: () => boolean | "skipped" | Promise<boolean | "skipped">;
+  requestInPlaceRestart: (
+    previous: ProxyRestartLive,
+  ) => ProxyRestartRequestOutcome | Promise<ProxyRestartRequestOutcome>;
+  waitForReplacement: (previous: ProxyRestartLive) => Promise<ProxyRestartLive | null>;
+}
+
+/**
+ * Confirm absence twice before restart is allowed to select a start-only path.
+ * A live target appearing during confirmation is uncertainty, not success: the
+ * caller must not claim it restarted a process it never asked to restart.
+ */
+export async function discoverStableProxyForRestart(
+  io: ProxyRestartDiscoveryIo,
+): Promise<ProxyRestartDiscovery> {
+  let first: ProxyRestartLive | null;
+  try {
+    first = await io.findLive();
+  } catch (error) {
+    return { status: "uncertain", error };
+  }
+  if (first) return { status: "live", live: first };
+  if (io.expired?.()) {
+    return { status: "uncertain", error: new Error("restart_discovery_deadline_expired") };
+  }
+
+  await (io.waitBetweenChecks ?? (() => Bun.sleep(100)))();
+  let second: ProxyRestartLive | null;
+  try {
+    second = await io.findLive();
+  } catch (error) {
+    return { status: "uncertain", error };
+  }
+  if (second) {
+    return {
+      status: "uncertain",
+      error: new Error("restart_target_appeared_during_absence_confirmation"),
+    };
+  }
+  if (io.expired?.()) {
+    return { status: "uncertain", error: new Error("restart_discovery_deadline_expired") };
+  }
+  return { status: "absent" };
+}
+
+export function isProxyReplacement(
+  previous: ProxyRestartLive,
+  candidate: ProxyRestartLive | null,
+): candidate is ProxyRestartLive & { pid: number } {
+  return previous.pid !== null
+    && candidate?.pid !== null
+    && candidate?.pid !== undefined
+    && candidate.source === "runtime"
+    && candidate.port === previous.port
+    && candidate.pid !== previous.pid;
+}
+
+/** Side-effect coordinator for the tray's fixed proxy-start action. */
+export async function runTrayProxyStart(io: TrayProxyStartIo): Promise<boolean> {
+  const live = await io.findLive();
+  if (live) {
+    if (io.existingIsSuccess === false) {
+      io.error("Proxy appeared while restart was confirming absence; no start was attempted.");
+      return false;
+    }
+    io.info(`Proxy already running on port ${live.port}.`);
+    return true;
+  }
+
+  const service = io.diagnoseService();
+  if (service.installed && !service.startable) {
+    io.error(`Cannot start from the tray because the installed service is not viable: ${service.summary}`);
+    io.error("Repair or remove the service before starting a direct proxy.");
+    return false;
+  }
+
+  if (service.startable) await io.startService();
+  else await io.startDirect();
+
+  const started = await io.waitForProxy();
+  if (!started) {
+    io.error("Proxy did not become healthy after the tray start action.");
+    return false;
+  }
+  io.info(`Proxy running on port ${started.port}.`);
+  return true;
+}
+
+/**
+ * Shared restart transaction for both `ocx restart` and the Windows tray.
+ *
+ * A live proxy restarts itself through POST /api/system/restart. That lifecycle owns
+ * drain, supervisor handoff, exact replacement identity, and managed-routing
+ * preservation. Re-implementing restart as `stop` + `start` here races a late service
+ * child and lets ordinary /api/stop restore native routing between the two halves.
+ * When no proxy is live there is nothing to recycle, so restart degrades to the
+ * caller's normal start path.
+ */
+export async function runProxyRestart(io: ProxyRestartIo): Promise<ProxyRestartResult> {
+  let discovery: ProxyRestartDiscovery;
+  try {
+    discovery = await io.findLive();
+  } catch (error) {
+    return { ok: false, phase: "request", error };
+  }
+
+  if (discovery.status === "uncertain") {
+    return { ok: false, phase: "request", error: discovery.error };
+  }
+
+  if (discovery.status === "absent") {
+    try {
+      const started = await io.startWhenStopped();
+      if (started === "skipped") return { ok: true, mode: "skipped" };
+      return started ? { ok: true, mode: "started" } : { ok: false, phase: "start" };
+    } catch (error) {
+      return { ok: false, phase: "start", error };
+    }
+  }
+
+  const previous = discovery.live;
+
+  if (previous.pid === null || previous.source !== "runtime") {
+    return { ok: false, phase: "identity" };
+  }
+
+  let request: ProxyRestartRequestOutcome;
+  try {
+    request = await io.requestInPlaceRestart(previous);
+  } catch (error) {
+    // The request may have reached the proxy before the response connection failed.
+    // Keep observing the original identity; never replay or fall back to stop/start.
+    request = { accepted: false, uncertain: true, error };
+  }
+
+  if (!request.accepted && !request.uncertain) {
+    return { ok: false, phase: "request", error: request.error };
+  }
+
+  try {
+    const replacement = await io.waitForReplacement(previous);
+    if (replacement) return { ok: true, mode: "restarted", live: replacement };
+    return request.accepted
+      ? { ok: false, phase: "replacement" }
+      : { ok: false, phase: "request", error: request.error };
+  } catch (error) {
+    return { ok: false, phase: "replacement", error };
+  }
+}

package/src/cli/v2.ts

@@ -0,0 +1,268 @@
+/**
+ * `ocx v2 status|on|off` — toggle/report the codex `multi_agent_v2` feature that
+ * controls the multi-agent surface (v1 vs v2 collab mode).
+ *
+ * Contract:
+ *  - config.toml writes go through the official `codex features enable|disable`
+ *    CLI only (format-preserving TOML edit stays upstream-owned).
+ *  - after a successful flip the catalog is RESYNCED so model metadata stays fresh.
+ *  - flips preserve the active thread limit while moving it between the v1/v2
+ *    config keys, with byte-for-byte rollback when the feature command fails.
+ *  - nothing in the catalog build path calls this module; no auto-flip exists.
+ */
+import { execFileSync } from "node:child_process";
+import { dirname } from "node:path";
+import { activeCodexConfigPath, getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMultiAgentModeHintText, transitionMultiAgentV2 } from "../codex/features";
+
+import { commandInvocation, type SpawnInvocation } from "../lib/win-exec";
+import { loadConfig, saveConfig } from "../config";
+import { resolveAndPersistCodexRuntime, type ResolveCodexRuntimeDeps } from "../codex/runtime";
+
+export interface V2CliDeps {
+  execFile?: (file: string, args: string[], options?: SpawnInvocation["options"]) => void;
+  isEnabled?: typeof isMultiAgentV2Enabled;
+  hasMaxThreads?: typeof hasAgentsMaxThreads;
+  sync?: (port?: number) => Promise<unknown>;
+  log?: Pick<Console, "log" | "error">;
+}
+
+export type CodexFeaturesInvocationDeps =
+  & Parameters<typeof commandInvocation>[3]
+  & Pick<ResolveCodexRuntimeDeps, "existsSync" | "execFileSync" | "configDir" | "readFileSync">;
+
+/**
+ * Shared invocation for `codex features enable|disable <feature>` — the single
+ * source of truth for the CLI and the management API fallback. Windows npm installs
+ * expose `codex` as a `.cmd` shim, which needs the win-exec launcher
+ * (devlog 260715_cross_platform_audit/020). Upstream `codex features` validates
+ * the key against the installed build's feature registry, so an old Codex will
+ * fail loudly instead of silently writing an unknown flag.
+ */
+export function codexFeaturesInvocation(
+  action: "enable" | "disable",
+  feature: string = "multi_agent_v2",
+  platform: NodeJS.Platform = process.platform,
+  deps: CodexFeaturesInvocationDeps = {},
+): SpawnInvocation {
+  const command = resolveAndPersistCodexRuntime({
+    env: deps.env ?? process.env,
+    platform,
+    existsSync: deps.existsSync,
+    execFileSync: deps.execFileSync,
+    configDir: deps.configDir,
+    readFileSync: deps.readFileSync,
+  }).runtime.command || "codex";
+  return commandInvocation(command, ["features", action, feature], platform, deps);
+}
+
+/**
+ * Run `codex features <action> <feature>` synchronously - the management API
+ * fallback when no deps toggle is injected. Shares the invocation builder and
+ * the bounded timeout/stdio options so every production toggle path behaves
+ * identically.
+ */
+export function runCodexFeaturesCommand(
+  action: "enable" | "disable",
+  feature: string = "multi_agent_v2",
+): void {
+  const inv = codexFeaturesInvocation(action, feature);
+  execFileSync(inv.file, inv.args,
+    {
+      stdio: ["ignore", "pipe", "pipe"], timeout: 15_000, windowsHide: true, encoding: "utf8",
+      // The reader resolves $CODEX_HOME at call time (including the WSL Windows-home
+      // detection); force the same home on the child so it never toggles a different
+      // config than the one the postcondition re-reads.
+      env: { ...process.env, CODEX_HOME: dirname(activeCodexConfigPath()) },
+      ...inv.options,
+    });
+}
+
+function runCodexFeatures(action: "enable" | "disable", deps: V2CliDeps): void {
+  if (deps.execFile) {
+    const inv = codexFeaturesInvocation(action);
+    deps.execFile(inv.file, inv.args, inv.options);
+    return;
+  }
+  runCodexFeaturesCommand(action);
+}
+
+export function v2StatusLine(enabled: boolean): string {
+  return enabled
+    ? "multi_agent_v2: ON — v2 multi-agent surface active"
+    : "multi_agent_v2: OFF — v1 multi-agent surface (default install)";
+}
+
+export function multiAgentModeLine(mode: string): string {
+  switch (mode) {
+    case "v1": return "multi_agent_mode: v1 — ALL models forced to v1 surface (upstream pins overridden)";
+    case "v2": return "multi_agent_mode: v2 — ALL models forced to v2 surface (upstream pins overridden)";
+    default: return "multi_agent_mode: default — upstream model pins respected (sol/terra=v2, luna=v1, rest=codex flag)";
+  }
+}
+
+export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: () => Promise<number | undefined>): Promise<number> {
+  const log = deps.log ?? console;
+  const isEnabled = deps.isEnabled ?? isMultiAgentV2Enabled;
+  const hasMaxThreads = deps.hasMaxThreads ?? hasAgentsMaxThreads;
+  const verb = (args[0] ?? "status").trim().toLowerCase();
+
+  if (verb === "status") {
+    log.log(v2StatusLine(isEnabled()));
+    const cfg = loadConfig();
+    log.log(multiAgentModeLine(cfg.multiAgentMode ?? "default"));
+    log.log(cfg.keepNativeChatGptOnV1 === true
+      ? "keep_native_chatgpt_on_v1: ON — ChatGPT-native rows stay v1 when mode is v2"
+      : "keep_native_chatgpt_on_v1: OFF");
+    const threads = getLogicalMaxThreads();
+    log.log(`max_threads: ${threads ?? "(unset — codex default)"}`);
+    const v2Active = isEnabled();
+    const agentsEnabled = getAgentsEnabled();
+    log.log(`agents.enabled: ${agentsEnabled === null ? "(unset — upstream default true)" : agentsEnabled}`);
+    const maxDepth = getAgentsMaxDepth();
+    // max_depth is V1-only upstream; say so whenever V2 is active so the number
+    // cannot be misread as an effective V2 limit.
+    log.log(`agents.max_depth: ${maxDepth ?? "(unset — upstream default 1)"}${v2Active ? " (V1-only — ignored while multi_agent_v2 is enabled)" : ""}`);
+    const instructions = getSubagentDeveloperInstructions();
+    log.log(`subagent_developer_instructions: ${instructions === null ? "(unset — children inherit)" : instructions === "" ? '"" (clears inherited instructions)' : JSON.stringify(instructions)}`);
+    const modeHint = getMultiAgentModeHintText();
+    log.log(`multi_agent_mode_hint_text: ${modeHint === null ? "(unset — effort-derived policy: ultra=proactive, else explicit)" : JSON.stringify(modeHint)}`);
+    if (isEnabled() && hasMaxThreads()) {
+      log.log("WARNING: [agents] max_threads is set — codex refuses to start while multi_agent_v2 is enabled. Remove it from config.toml (concurrency lives in features.multi_agent_v2.max_concurrent_threads_per_session).");
+    }
+    return 0;
+  }
+  if (verb === "mode-hint") {
+    const value = args[1];
+    if (value === undefined) {
+      log.error("v2 mode-hint: pass the hint text, or --clear to unset it.");
+      return 1;
+    }
+    if (value === "--clear") {
+      const result = setMultiAgentModeHintText(null);
+      if (!result.ok) {
+        log.error(`v2 mode-hint: ${result.error}`);
+        return 1;
+      }
+      log.log(result.changed
+        ? "multi_agent_mode_hint_text cleared — effort-derived policy resumes (new sessions)."
+        : "multi_agent_mode_hint_text already unset — nothing to do.");
+      return 0;
+    }
+    // `--clear` is the only reserved token; hints are otherwise arbitrary
+    // nonblank text and may legitimately begin with a hyphen.
+    if (value.trim().length === 0) {
+      log.error("v2 mode-hint: pass the hint text, or --clear to unset it.");
+      return 1;
+    }
+    const result = setMultiAgentModeHintText(value);
+    if (!result.ok) {
+      log.error(`v2 mode-hint: ${result.error}`);
+      return 1;
+    }
+    log.log(result.changed
+      ? `multi_agent_mode_hint_text set (new sessions).`
+      : "multi_agent_mode_hint_text already set — nothing to do.");
+    return 0;
+  }
+  if (verb === "threads") {
+    const value = Number((args[1] ?? "").trim());
+    if (!Number.isInteger(value) || value < 1) {
+      log.error("v2 threads: pass an integer >= 1 (features.multi_agent_v2.max_concurrent_threads_per_session)");
+      return 1;
+    }
+    const enabled = isEnabled();
+    const result = transitionMultiAgentV2(enabled, next => runCodexFeatures(next ? "enable" : "disable", deps), { threadLimit: value });
+    if (!result.ok) { log.error(`v2 threads: ${result.error}`); return 1; }
+    log.log(result.changed
+      ? `max_threads = ${value} (${enabled ? "v2" : "v1"}) — applies to new sessions.`
+      : `max_threads already ${value} — nothing to do.`);
+    return 0;
+  }
+  if (verb === "mode") {
+    const modeArg = (args[1] ?? "").trim().toLowerCase();
+    if (modeArg !== "v1" && modeArg !== "default" && modeArg !== "v2") {
+      log.error("v2 mode: expected v1|default|v2");
+      return 1;
+    }
+    const cfg = loadConfig();
+    if (modeArg !== "default") {
+      const target = modeArg === "v2";
+      const transition = transitionMultiAgentV2(target, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
+      if (!transition.ok) {
+        log.error(`multi-agent mode transition failed: ${transition.error}`);
+        return 1;
+      }
+    }
+    if (modeArg === "default") delete cfg.multiAgentMode;
+    else cfg.multiAgentMode = modeArg as "v1" | "v2";
+    saveConfig(cfg);
+    try {
+      const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
+      await sync(findPort ? await findPort() : undefined);
+    } catch (err) {
+      log.error(`catalog resync failed: ${err instanceof Error ? err.message : String(err)} — run 'ocx sync' manually.`);
+      return 1;
+    }
+    log.log(multiAgentModeLine(modeArg));
+    log.log("Applies to NEW sessions; running sessions keep their pinned multi-agent version.");
+    return 0;
+  }
+  if (verb === "keep-native-v1") {
+    const flag = (args[1] ?? "").trim().toLowerCase();
+    if (flag !== "on" && flag !== "off") {
+      log.error("v2 keep-native-v1: expected on|off");
+      return 1;
+    }
+    const cfg = loadConfig();
+    const next = flag === "on";
+    const already = cfg.keepNativeChatGptOnV1 === true === next;
+    if (next) cfg.keepNativeChatGptOnV1 = true;
+    else delete cfg.keepNativeChatGptOnV1;
+    saveConfig(cfg);
+    try {
+      const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
+      await sync(findPort ? await findPort() : undefined);
+    } catch (err) {
+      log.error(`catalog resync failed: ${err instanceof Error ? err.message : String(err)} — run 'ocx sync' manually.`);
+      return 1;
+    }
+    if (already) {
+      log.log(next
+        ? "keep_native_chatgpt_on_v1 already ON — catalog re-synced."
+        : "keep_native_chatgpt_on_v1 already OFF — catalog re-synced.");
+      return 0;
+    }
+    log.log(next
+      ? "keep_native_chatgpt_on_v1: ON — ChatGPT-native rows stay v1 when mode is v2 (new sessions)."
+      : "keep_native_chatgpt_on_v1: OFF — ChatGPT-native rows follow v1/base/v2 (new sessions).");
+    return 0;
+  }
+  if (verb !== "on" && verb !== "off") {
+    log.error(`v2: unknown verb '${verb}' (expected status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>)`);
+    return 1;
+  }
+
+  const want = verb === "on";
+  const transition = transitionMultiAgentV2(want, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
+  if (!transition.ok) {
+    log.error(`codex features ${want ? "enable" : "disable"} multi_agent_v2 failed: ${transition.error}`);
+    return 1;
+  }
+  if (!transition.changed) {
+    log.log(`multi_agent_v2 already ${want ? "ON" : "OFF"} — nothing to do.`);
+    return 0;
+  }
+
+  // Resync catalog so multi-agent surface metadata stays fresh in both the
+  // on-disk catalog and models_cache.json after the toggle flip.
+  try {
+    const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
+    await sync(findPort ? await findPort() : undefined);
+  } catch (err) {
+    log.error(`catalog resync failed (flag IS flipped): ${err instanceof Error ? err.message : String(err)} — run 'ocx sync' manually.`);
+    return 1;
+  }
+  log.log(v2StatusLine(want));
+  log.log("Applies to NEW sessions; running sessions keep their pinned multi-agent version. Restart the Codex app (or wait out its picker cache) to see the ladder change.");
+  return 0;
+}

package/src/cli.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+// Compatibility stub for the pre-restructure entrypoint path.
+//
+// Before the src/ restructure the CLI lived at src/cli.ts, and durable launchers
+// (codex shim wrappers, installed service definitions) baked that absolute path
+// into their command lines. Users who upgrade in place with a bare
+// `npm install -g @yansigit/opencodex` (instead of `ocx update`, which repairs the
+// shim/service) would otherwise be stranded on a dead path. Keep this stub for at
+// least one release cycle after the restructure ships.
+import "./cli/index.ts";