@iislee/opencodex 2.11.0

package/src/cli/agent-driven.ts

@@ -0,0 +1,70 @@
+/**
+ * Detects whether this process was started by a coding agent rather than typed
+ * by a person.
+ *
+ * Agent harnesses run `ocx` on the user's behalf and answer prompts from their
+ * own logic, which means a consent question would be decided by the agent
+ * instead of the account owner. Prompts that act on the user's identity check
+ * this and defer instead: they stay silent so the question reaches the human on
+ * a later hand-typed run.
+ *
+ * Detection is env-var based and deliberately conservative — a false positive
+ * only postpones a prompt, while a false negative would let an agent answer for
+ * the user.
+ */
+
+/**
+ * Env vars set by agent harnesses and CI runners inside the shell they spawn.
+ *
+ * The list errs wide on purpose. A harness that is missed here is a harness
+ * whose model answers a consent question with the user's GitHub identity, which
+ * is the failure this module exists to prevent; a harness matched by mistake
+ * only postpones a prompt to the user's next hand-typed run.
+ */
+const AGENT_ENV_VARS = [
+  // Claude Code
+  "CLAUDECODE",
+  "CLAUDE_CODE_ENTRYPOINT",
+  "CLAUDE_CODE_SSE_PORT",
+  // Codex CLI / App / SDK. `CODEX_HOME` is deliberately NOT here: users export it
+  // from their own shell profile, so matching it would suppress the prompt for a
+  // person who is sitting right there.
+  "CODEX_THREAD_ID",
+  "CODEX_SHELL",
+  "CODEX_CI",
+  "CODEX_SANDBOX",
+  "CODEX_SANDBOX_NETWORK_DISABLED",
+  // Cursor
+  "CURSOR_TRACE_ID",
+  "CURSOR_SESSION_TOKEN",
+  "CURSOR_AGENT",
+  // Other coding agents
+  "AIDER_CHAT",
+  "OPENCODE_BIN_PATH",
+  "GEMINI_CLI",
+  // Generic runners and hosted environments that are never a person at a keyboard
+  "REPL_ID",
+  "CI",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "BUILDKITE",
+  "JENKINS_URL",
+  "TEAMCITY_VERSION",
+  "CODESPACES",
+] as const;
+
+/**
+ * True when an agent or automated runner is driving this process. Reads the
+ * environment on every call so tests and long-lived processes see current state.
+ */
+export function isAgentDriven(env: NodeJS.ProcessEnv = process.env): boolean {
+  return AGENT_ENV_VARS.some(name => (env[name] ?? "").trim() !== "");
+}
+
+/**
+ * The env-var names that mark this process as agent-driven. Empty for a real
+ * hand-typed run. Callers that refuse an action use it to name the reason.
+ */
+export function agentDrivenMarkers(env: NodeJS.ProcessEnv = process.env): string[] {
+  return AGENT_ENV_VARS.filter(name => (env[name] ?? "").trim() !== "");
+}

package/src/cli/agent.ts

@@ -0,0 +1,184 @@
+import {
+  CliUsageError,
+  csv,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  summaryLines,
+  takeBooleanOption,
+  takeFlag,
+  takeIntegerOption,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx agent [status] [--json]
+  ocx agent injection <status|set> [--model <id|->] [--effort <level|->]
+      [--prompt <text|->] [--guidance <on|off>] [--json]
+  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|->]
+      [--reasoning <level>] [--max-descriptions <n>] [--json]`;
+
+function clearable(value: string | undefined): string | null | undefined {
+  return value === "-" ? null : value;
+}
+
+async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const [v2, injection, caps, subagents, fallback, sidecars] = await Promise.all([
+    runtimeRequest("/api/v2", {}, deps),
+    runtimeRequest("/api/injection-model", {}, deps),
+    runtimeRequest("/api/effort-caps", {}, deps),
+    runtimeRequest("/api/subagent-models", {}, deps),
+    runtimeRequest("/api/subagent-model-fallback", {}, deps),
+    runtimeRequest("/api/sidecar-settings", {}, deps),
+  ]);
+  const result = { v2, injection, caps, subagents, fallback, sidecars };
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function injection(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/injection-model", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (action !== "set") throw new CliUsageError(`unknown injection action ${action}`, USAGE);
+  const model = clearable(takeOption(args, "--model"));
+  const effort = clearable(takeOption(args, "--effort"));
+  const prompt = clearable(takeOption(args, "--prompt"));
+  const guidance = takeBooleanOption(args, "--guidance");
+  rejectArgs(args, USAGE);
+  const body: Record<string, unknown> = {};
+  if (model !== undefined) body.model = model;
+  if (effort !== undefined) body.effort = effort;
+  if (prompt !== undefined) body.prompt = prompt;
+  if (guidance !== undefined) body.multiAgentGuidanceEnabled = guidance;
+  if (Object.keys(body).length === 0) throw new CliUsageError("at least one injection option is required", USAGE);
+  const result = await runtimeRequest("/api/injection-model", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Agent injection settings updated."]);
+}
+
+async function effort(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/effort-caps", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (action !== "set") throw new CliUsageError(`unknown effort action ${action}`, USAGE);
+  const main = clearable(takeOption(args, "--main"));
+  const subagent = clearable(takeOption(args, "--subagent"));
+  rejectArgs(args, USAGE);
+  const body: Record<string, unknown> = {};
+  if (main !== undefined) body.effortCap = main;
+  if (subagent !== undefined) body.subagentEffortCap = subagent;
+  if (Object.keys(body).length === 0) throw new CliUsageError("--main and/or --subagent is required", USAGE);
+  const result = await runtimeRequest("/api/effort-caps", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Agent effort caps updated."]);
+}
+
+async function subagents(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/subagent-models", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  let models: string[];
+  if (action === "clear") models = [];
+  else if (action === "set") {
+    const raw = args.shift();
+    if (!raw) throw new CliUsageError("comma-separated subagent models are required", USAGE);
+    models = csv(raw) ?? [];
+  } else throw new CliUsageError(`unknown subagents action ${action}`, USAGE);
+  rejectArgs(args, USAGE);
+  if (models.length > 5) throw new CliUsageError("at most 5 subagent models are allowed", USAGE);
+  const result = await runtimeRequest("/api/subagent-models", { method: "PUT", body: JSON.stringify({ models }) }, deps);
+  printData(result, wantsJson, [`Subagent roster: ${models.join(", ") || "cleared"}`]);
+}
+
+async function fallback(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/subagent-model-fallback", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  const body: Record<string, unknown> = {};
+  if (action === "clear") body.models = [];
+  else if (action === "set") {
+    const raw = args[0] && !args[0].startsWith("--") ? args.shift() : undefined;
+    if (raw) body.models = csv(raw) ?? [];
+  } else throw new CliUsageError(`unknown fallback action ${action}`, USAGE);
+  const pollMs = takeIntegerOption(args, "--poll-ms", { min: 5_000 });
+  if (pollMs !== undefined) {
+    if (pollMs > 600_000) throw new CliUsageError("--poll-ms must be <= 600000", USAGE);
+    body.pollMs = pollMs;
+  }
+  rejectArgs(args, USAGE);
+  if (Object.keys(body).length === 0) throw new CliUsageError("models and/or --poll-ms is required", USAGE);
+  const result = await runtimeRequest("/api/subagent-model-fallback", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["Subagent fallback settings updated."]);
+}
+
+async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const section = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (section === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/sidecar-settings", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (section !== "web" && section !== "vision") throw new CliUsageError("sidecar must be web, vision, or status", USAGE);
+  const model = takeOption(args, "--model");
+  const backend = takeOption(args, "--backend");
+  const reasoning = takeOption(args, "--reasoning");
+  const maxDescriptionsPerTurn = takeIntegerOption(args, "--max-descriptions", { min: 1 });
+  rejectArgs(args, USAGE);
+  const settings: Record<string, unknown> = {};
+  if (model !== undefined) settings.model = model === "-" ? "" : model;
+  if (backend !== undefined) settings.backend = backend === "-" ? null : backend;
+  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);
+  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.`]);
+}
+
+export async function handleAgentCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "status", ...rest] = argv;
+    if (sub === "status") await status(rest, deps);
+    else if (sub === "injection" || sub === "guidance") await injection(rest, deps);
+    else if (sub === "effort") await effort(rest, deps);
+    else if (sub === "subagents" || sub === "roster") await subagents(rest, deps);
+    else if (sub === "fallback") await fallback(rest, deps);
+    else if (sub === "sidecar") await sidecar(rest, deps);
+    else throw new CliUsageError(`unknown agent command ${sub}`, USAGE);
+  });
+}
+
+export const AGENT_USAGE = USAGE;

package/src/cli/catalog-prewarm.ts

@@ -0,0 +1,27 @@
+import type { OcxConfig } from "../types";
+
+type GatherRoutedModels = (config: OcxConfig) => Promise<unknown>;
+
+export type CatalogPrewarmDeps = {
+  loadConfig?: () => OcxConfig;
+  importCatalog?: () => Promise<{ gatherRoutedModels: GatherRoutedModels }>;
+};
+
+/**
+ * After the listen port is bound, kick off live provider discovery so the first
+ * GUI /v1/models and syncModelsToCodex share one gather flight instead of racing
+ * duplicate upstream /models fetches.
+ */
+export function scheduleCatalogPrewarm(deps: CatalogPrewarmDeps = {}): void {
+  void Promise.resolve()
+    .then(async () => {
+      const load = deps.loadConfig ?? (await import("../config")).loadConfig;
+      const { gatherRoutedModels } = await (deps.importCatalog?.() ?? import("../codex/catalog"));
+      return gatherRoutedModels(load());
+    })
+    .catch(error => {
+      if (error && typeof error === "object" && (error as { code?: unknown }).code === "catalog_busy") {
+        console.warn("[catalog] startup discovery skipped: catalog gather is busy");
+      }
+    });
+}

package/src/cli/claude-desktop.ts

@@ -0,0 +1,188 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadConfig, saveConfigPreservingClaudeCode } from "../config";
+import {
+  DESKTOP_FAMILIES,
+  moveDesktopRoute,
+  parseDesktopProfile,
+  setDesktopFamilyDefault,
+  type DesktopFamily,
+  type DesktopProfile,
+} from "../claude/desktop-profile";
+import { writeDesktop3pConfig, type Desktop3pConfigMode, parseDesktop3pModeArgs } from "../claude/desktop-3p";
+import { filterCatalogVisibleModels, desktopVisibleNativeSlugs } from "../codex/catalog";
+import { buildClaudeDesktopState, fetchAllModels } from "../server/management-api";
+import { findLiveProxy } from "../server/proxy-liveness";
+import { runtimeRequest } from "./runtime-api";
+
+function isFamily(value: string | undefined): value is DesktopFamily {
+  return !!value && (DESKTOP_FAMILIES as readonly string[]).includes(value);
+}
+
+function printDesktopHelp(): void {
+  console.log(`Usage:
+  ocx claude desktop [apply] [--static|--hybrid|--discovery-only]
+  ocx claude desktop show [--json]
+  ocx claude desktop move <provider/model> <opus|fable|sonnet|haiku> [--default]
+  ocx claude desktop default <family> <provider/model|none>
+  ocx claude desktop export <path|->
+  ocx claude desktop import <path> [--apply]`);
+}
+
+export interface ApplyProfileDeps {
+  findLiveProxyImpl?: typeof findLiveProxy;
+  postApplyImpl?: (
+    mode: Desktop3pConfigMode,
+    profile: DesktopProfile,
+  ) => Promise<{ ok?: boolean; path?: string; error?: string }>;
+}
+
+export async function applyProfile(
+  profile: DesktopProfile,
+  mode: Desktop3pConfigMode,
+  deps: ApplyProfileDeps = {},
+): Promise<{ ok: boolean; path: string; reason?: string }> {
+  const config = loadConfig();
+  const state = await buildClaudeDesktopState(config, profile);
+  config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: state.profile };
+  saveConfigPreservingClaudeCode(config);
+  const live = await (deps.findLiveProxyImpl ?? findLiveProxy)();
+  if (live) {
+    // #859: the Desktop alias reverse-map is process-local. Applying through the
+    // serving process installs the map there; a local-only write leaves the
+    // daemon unable to decode aliases, and the provider rejects them (400).
+    const post = deps.postApplyImpl ?? (async (m: Desktop3pConfigMode, p: DesktopProfile) =>
+      runtimeRequest<{ ok?: boolean; path?: string; error?: string }>(
+        "/api/claude-desktop/apply",
+        // The daemon's config may be older than what we just saved, so the
+        // profile travels with the request instead of being re-read there.
+        { method: "POST", body: JSON.stringify({ mode: m, profile: p }) },
+      ));
+    try {
+      const applied = await post(mode, state.profile);
+      if (applied.ok === false) return { ok: false, path: applied.path ?? "", reason: applied.error ?? "daemon apply failed" };
+      return { ok: true, path: applied.path ?? "" };
+    } catch (error) {
+      return { ok: false, path: "", reason: error instanceof Error ? error.message : String(error) };
+    }
+  }
+  const allModels = await fetchAllModels(config);
+  const routed = filterCatalogVisibleModels(allModels, config).map(model => ({
+    provider: model.provider,
+    id: model.id,
+    contextWindow: model.contextWindow,
+  }));
+  const result = writeDesktop3pConfig(
+    config.port ?? 10100,
+    [...desktopVisibleNativeSlugs(config)],
+    routed,
+    config.apiKeys?.[0]?.key,
+    mode,
+    state.profile,
+  );
+  return { ok: result.written, path: result.path, reason: result.reason };
+}
+
+export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProfileDeps = {}): Promise<number> {
+  const command = argv[0];
+  if (command === "help" || command === "--help" || command === "-h") {
+    printDesktopHelp();
+    return 0;
+  }
+
+  // Legacy mode flags remain apply aliases and are parsed before subcommands.
+  const legacyFlags = argv.filter(arg => ["--static", "--hybrid", "--discovery-only"].includes(arg));
+  const applyInvocation = argv.length === 0 || command === "apply" || legacyFlags.length > 0;
+  if (applyInvocation) {
+    const nonMode = argv.filter(arg => !["apply", "--static", "--hybrid", "--discovery-only"].includes(arg));
+    if (nonMode.length > 0) {
+      console.error(`알 수 없는 인자: ${nonMode.join(" ")}`);
+      return 1;
+    }
+    const parsedMode = parseDesktop3pModeArgs(legacyFlags);
+    if ("error" in parsedMode) { console.error(parsedMode.error); return 1; }
+    try {
+      const config = loadConfig();
+      const state = await buildClaudeDesktopState(config);
+      const result = await applyProfile(state.profile, parsedMode.mode, deps);
+      if (!result.ok) {
+        console.error(`설정 적용 실패: ${result.reason ?? "unknown error"}`);
+        console.error("프로필은 저장되었지만 Claude Desktop 설정 파일에는 반영되지 않았습니다. 프록시 상태를 확인한 뒤 다시 적용해 주세요.");
+        return 1;
+      }
+      console.log(`Claude Desktop 설정을 적용했습니다: ${result.path}`);
+      console.log("Claude Desktop을 완전히 종료한 뒤 다시 열어 주세요.");
+      return 0;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      return 1;
+    }
+  }
+
+  try {
+    const config = loadConfig();
+    const state = await buildClaudeDesktopState(config);
+    if (command === "show") {
+      if (argv.length > 2 || (argv[1] && argv[1] !== "--json")) throw new Error("Usage: ocx claude desktop show [--json]");
+      if (argv[1] === "--json") console.log(JSON.stringify(state));
+      else {
+        for (const family of DESKTOP_FAMILIES) {
+          console.log(`${family.toUpperCase()}${state.profile.defaults[family] ? ` (default: ${state.profile.defaults[family]})` : ""}`);
+          for (const model of state.models.filter(item => item.assignment.family === family)) {
+            console.log(`  ${model.available ? "•" : "○"} ${model.route} -> ${model.assignment.alias}${model.available ? "" : " (unavailable)"}`);
+          }
+        }
+      }
+      return 0;
+    }
+    if (command === "move") {
+      const [, route, familyRaw, ...flags] = argv;
+      if (!route || !isFamily(familyRaw) || flags.some(flag => flag !== "--default")) throw new Error("Usage: ocx claude desktop move <route> <family> [--default]");
+      if (!state.models.some(model => model.route === route && model.available)) throw new Error(`현재 사용할 수 없는 모델입니다: ${route}`);
+      const profile = moveDesktopRoute(state.profile, route, familyRaw, flags.includes("--default"));
+      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: profile };
+      saveConfigPreservingClaudeCode(config);
+      console.log(`${route} 모델을 ${familyRaw} 그룹으로 옮겼습니다.`);
+      return 0;
+    }
+    if (command === "default") {
+      const [, familyRaw, routeRaw] = argv;
+      if (!isFamily(familyRaw) || !routeRaw || argv.length !== 3) throw new Error("Usage: ocx claude desktop default <family> <route|none>");
+      const route = routeRaw === "none" ? null : routeRaw;
+      if (route && !state.models.some(model => model.route === route && model.available)) throw new Error(`현재 사용할 수 없는 모델입니다: ${route}`);
+      const profile = setDesktopFamilyDefault(state.profile, familyRaw, route);
+      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: profile };
+      saveConfigPreservingClaudeCode(config);
+      console.log(`${familyRaw} 기본 모델을 ${route ?? "없음"}으로 지정했습니다.`);
+      return 0;
+    }
+    if (command === "export") {
+      const target = argv[1];
+      if (!target || argv.length !== 2) throw new Error("Usage: ocx claude desktop export <path|->");
+      const json = JSON.stringify(state.profile, null, 2) + "\n";
+      if (target === "-") process.stdout.write(json);
+      else writeFileSync(resolve(target), json, { encoding: "utf8", mode: 0o600 });
+      return 0;
+    }
+    if (command === "import") {
+      const source = argv[1];
+      const flags = argv.slice(2);
+      if (!source || flags.some(flag => flag !== "--apply")) throw new Error("Usage: ocx claude desktop import <path> [--apply]");
+      const profile = parseDesktopProfile(JSON.parse(readFileSync(resolve(source), "utf8")));
+      const reconciled = (await buildClaudeDesktopState(config, profile)).profile;
+      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: reconciled };
+      saveConfigPreservingClaudeCode(config);
+      if (flags.includes("--apply")) {
+        const result = await applyProfile(reconciled, "static", deps);
+        if (!result.ok) { console.error(`프로필은 저장했지만 Desktop 적용에 실패했습니다: ${result.reason ?? "unknown error"}`); return 1; }
+      }
+      console.log("Claude Desktop 프로필을 가져왔습니다.");
+      return 0;
+    }
+    printDesktopHelp();
+    return 1;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}