@dotobokuri/fleet-console 1.37.0 → 1.38.0

package/dist/fleet-plugins/terminal/routes.mjs

@@ -26,18 +26,18 @@ var __export = (target, all) => {
 function definePlugin(definition) {
   return definition;
 }
-function registerRouter(ctx, path47, handler) {
-  ctx.registerRouter(normalizePath(path47), handler);
+function registerRouter(ctx, path48, handler) {
+  ctx.registerRouter(normalizePath(path48), handler);
 }
-function registerWsHandler(ctx, path47, handler) {
-  ctx.registerWsHandler(normalizePath(path47), handler);
+function registerWsHandler(ctx, path48, handler) {
+  ctx.registerWsHandler(normalizePath(path48), handler);
 }
 function registerLaunchCatalog(ctx, provider) {
   return ctx.host.operations.registerLaunchCatalog(ctx.pluginId, provider);
 }
-function normalizePath(path47) {
-  if (path47.length === 0 || path47 === "/") return "/";
-  return path47;
+function normalizePath(path48) {
+  if (path48.length === 0 || path48 === "/") return "/";
+  return path48;
 }
 var FLEET_DATA_DIR_NAME = ".fleet";
 function getFleetDataDir() {
@@ -1650,10 +1650,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path47) {
-  if (!path47)
+function getElementAtPath(obj, path48) {
+  if (!path48)
     return obj;
-  return path47.reduce((acc, key) => acc?.[key], obj);
+  return path48.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -2062,11 +2062,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path47, issues) {
+function prefixIssues(path48, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path47);
+    iss.path.unshift(path48);
     return iss;
   });
 }
@@ -2213,16 +2213,16 @@ function flattenError(error51, mapper = (issue3) => issue3.message) {
 }
 function formatError(error51, mapper = (issue3) => issue3.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error52, path47 = []) => {
+  const processError = (error52, path48 = []) => {
     for (const issue3 of error52.issues) {
       if (issue3.code === "invalid_union" && issue3.errors.length) {
-        issue3.errors.map((issues) => processError({ issues }, [...path47, ...issue3.path]));
+        issue3.errors.map((issues) => processError({ issues }, [...path48, ...issue3.path]));
       } else if (issue3.code === "invalid_key") {
-        processError({ issues: issue3.issues }, [...path47, ...issue3.path]);
+        processError({ issues: issue3.issues }, [...path48, ...issue3.path]);
       } else if (issue3.code === "invalid_element") {
-        processError({ issues: issue3.issues }, [...path47, ...issue3.path]);
+        processError({ issues: issue3.issues }, [...path48, ...issue3.path]);
       } else {
-        const fullpath = [...path47, ...issue3.path];
+        const fullpath = [...path48, ...issue3.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue3));
         } else {
@@ -2249,17 +2249,17 @@ function formatError(error51, mapper = (issue3) => issue3.message) {
 }
 function treeifyError(error51, mapper = (issue3) => issue3.message) {
   const result = { errors: [] };
-  const processError = (error52, path47 = []) => {
+  const processError = (error52, path48 = []) => {
     var _a3, _b;
     for (const issue3 of error52.issues) {
       if (issue3.code === "invalid_union" && issue3.errors.length) {
-        issue3.errors.map((issues) => processError({ issues }, [...path47, ...issue3.path]));
+        issue3.errors.map((issues) => processError({ issues }, [...path48, ...issue3.path]));
       } else if (issue3.code === "invalid_key") {
-        processError({ issues: issue3.issues }, [...path47, ...issue3.path]);
+        processError({ issues: issue3.issues }, [...path48, ...issue3.path]);
       } else if (issue3.code === "invalid_element") {
-        processError({ issues: issue3.issues }, [...path47, ...issue3.path]);
+        processError({ issues: issue3.issues }, [...path48, ...issue3.path]);
       } else {
-        const fullpath = [...path47, ...issue3.path];
+        const fullpath = [...path48, ...issue3.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue3));
           continue;
@@ -2291,8 +2291,8 @@ function treeifyError(error51, mapper = (issue3) => issue3.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path47 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path47) {
+  const path48 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path48) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -14956,13 +14956,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path47 = ref.slice(1).split("/").filter(Boolean);
-  if (path47.length === 0) {
+  const path48 = ref.slice(1).split("/").filter(Boolean);
+  if (path48.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path47[0] === defsKey) {
-    const key = path47[1];
+  if (path48[0] === defsKey) {
+    const key = path48[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -31419,7 +31419,7 @@ function engineExecuteOneShot(opts) {
         model: opts.model,
         promptIdleTimeout: opts.promptIdleTimeout,
         effort
-      }, opts.connectSystemPrompt, opts.authEnvResolver, mcpSetup?.mcpServers));
+      }, opts.connectSystemPrompt, opts.authEnvResolver, opts.agentCliLaunchResolver, mcpSetup?.mcpServers));
       if (opts.resumeSessionId) connectOpts.sessionId = opts.resumeSessionId;
       const connectResult = await raceAbort(raceProviderFailure(client2.connect(connectOpts)), opts.signal);
       await raceProviderFailure(applyResolvedEffort(client2, opts.cliType, model, effort));
@@ -31596,7 +31596,7 @@ async function setupExecutorMcp(cwd, signal, scopeId, reservedIds = [], serverBi
     throw error51;
   }
 }
-async function buildConnectOptions(cli, cwd, overrides, systemPrompt, authEnvResolver, mcpServers) {
+async function buildConnectOptions(cli, cwd, overrides, systemPrompt, authEnvResolver, agentCliLaunchResolver, mcpServers) {
   const options = { cwd, cli, autoApprove: true, clientInfo: CLIENT_INFO, timeout: 0, strictMcp: true, archiveSessionOnDisconnect: true };
   if (overrides.model) options.model = overrides.model;
   if (overrides.effort) options.effort = overrides.effort;
@@ -31607,7 +31607,14 @@ async function buildConnectOptions(cli, cwd, overrides, systemPrompt, authEnvRes
     ...overrides.model ? { model: overrides.model } : {},
     ...overrides.effort ? { effort: overrides.effort } : {}
   });
-  if (Object.keys(env).length) options.env = env;
+  const launch = await agentCliLaunchResolver?.(cli, {
+    env,
+    ...overrides.model ? { model: overrides.model } : {},
+    ...overrides.effort ? { effort: overrides.effort } : {}
+  });
+  if (launch?.cliPath) options.cliPath = launch.cliPath;
+  const mergedEnv = launch?.env ? { ...env, ...launch.env } : env;
+  if (Object.keys(mergedEnv).length) options.env = mergedEnv;
   return options;
 }
 function assertAuthEnvResolver(value) {
@@ -31964,6 +31971,7 @@ async function launchTaskForceJob(options) {
     const handle = executeOneShot({
       scopeId: carrierId,
       authEnvResolver: deps.authEnvResolver,
+      agentCliLaunchResolver: deps.agentCliLaunchResolver,
       reservedExternalMcpServerIds: deps.reservedExternalMcpServerIds,
       cliType,
       request,
@@ -32463,6 +32471,7 @@ function buildCarrierDispatchToolSpec(registry3, deps, services) {
       const handle = executeOneShot({
         scopeId: carrierId,
         authEnvResolver: deps.authEnvResolver,
+        agentCliLaunchResolver: deps.agentCliLaunchResolver,
         reservedExternalMcpServerIds: deps.reservedExternalMcpServerIds,
         cliType: trackModelInfo.cliType,
         request,
@@ -32889,6 +32898,7 @@ function createCarrierRuntime() {
   const registry3 = createCarrierRegistry();
   const dispatchContexts = new DispatchContextRegistry();
   const inFlight = /* @__PURE__ */ new Set();
+  let agentCliLaunchResolver;
   let accepting = true;
   const admission = {
     get accepting() {
@@ -32917,12 +32927,23 @@ function createCarrierRuntime() {
     dispatchServices,
     dispatch: boundDispatch,
     buildDispatchToolSpec(deps) {
-      return boundDispatch.buildToolSpecs(deps);
+      return boundDispatch.buildToolSpecs({
+        ...deps,
+        // host가 lifecycle 생성 뒤 resolver를 주입해도 이미 등록된 단일 dispatch 도구가
+        // 실행 직전 최신 resolver를 읽도록 runtime 소유 closure로 연결한다.
+        agentCliLaunchResolver: async (cli, context) => {
+          const resolver = agentCliLaunchResolver ?? deps.agentCliLaunchResolver;
+          return resolver ? resolver(cli, context) : {};
+        }
+      });
     },
     jobs: boundCarrierJobs,
     personas: personas_exports,
     store: { initStore },
     stream: boundStream,
+    setAgentCliLaunchResolver(resolver) {
+      agentCliLaunchResolver = resolver;
+    },
     trackInFlight: dispatchServices.trackInFlight,
     async cleanup() {
       accepting = false;
@@ -32930,6 +32951,7 @@ function createCarrierRuntime() {
       await Promise.allSettled(tasks.map((task) => task.cancel()));
       await Promise.allSettled(tasks.map((task) => task.completion));
       inFlight.clear();
+      agentCliLaunchResolver = void 0;
       dispatchContexts.dispose();
     },
     registerCarrierDefaults() {
@@ -42898,10 +42920,10 @@ function createShellTerminalLaunchResolver(deps = {}) {
   const env = deps.env ?? process4.env;
   const homedir2 = deps.homedir ?? DEFAULT_TERMINAL_CWD_FALLBACK;
   const platform = deps.platform ?? process4.platform;
-  return async (selectedCwd) => {
+  return async (selectedCwd, context) => {
     const cwd = selectedCwd || baseCwd || homedir2();
     const shell = resolveWindowsLaunchBinary(resolveUserShell(env, platform), [], env, platform, "user shell");
-    return { bin: shell.bin, args: shell.args, cwd, env: buildShellLaunchEnv(env), terminalName: TERMINAL_TERM };
+    return { bin: shell.bin, args: shell.args, cwd, env: buildShellLaunchEnv(env, context?.colorScheme), terminalName: TERMINAL_TERM };
   };
 }
 function startTerminalShell(launch, size) {
@@ -42959,10 +42981,13 @@ function resolveWindowsLaunchBinary(bin, args, env, platform, label) {
   }
   return { bin: resolved.bin, args: [...resolved.prefixArgs, ...args] };
 }
-function buildShellLaunchEnv(env) {
+function buildShellLaunchEnv(env, colorScheme) {
   return {
     ...stripConsoleInternalEnv(env),
-    TERM: TERMINAL_TERM
+    TERM: TERMINAL_TERM,
+    // COLORFGBG는 배경을 질의하지 않는 CLI/TUI를 위한 고전적 극성 힌트다("fg;bg" ANSI 인덱스).
+    // 값이 없으면 변수 자체를 싣지 않아 사용자 셸 환경의 기존 값을 훼손하지 않는다.
+    ...colorScheme ? { COLORFGBG: colorScheme === "light" ? "0;15" : "15;0" } : {}
   };
 }
 
@@ -43166,7 +43191,8 @@ function createTerminalSessionManager(deps) {
       ...context.theaterId ? { theaterId: context.theaterId } : {},
       ...context.kind ? { kind: context.kind } : {},
       ...context.cliId ? { cliId: context.cliId } : {},
-      ...context.resumeSessionId ? { resumeSessionId: context.resumeSessionId } : {}
+      ...context.resumeSessionId ? { resumeSessionId: context.resumeSessionId } : {},
+      ...context.colorScheme ? { colorScheme: context.colorScheme } : {}
     });
     let pty;
     let ptyFds = [];
@@ -43659,41 +43685,198 @@ function hashablePath(entry) {
   if (!filePath || filePath.includes("\n")) return null;
   return filePath;
 }
+var AGENT_CLI_PATHS_STORAGE_KEY = "agent-cli-paths";
+var AGENT_CLI_COMMANDS = ["claude", "codex", "opencode", "cursor-agent"];
+var OVERRIDE_ENV_BY_COMMAND = {
+  claude: "CLAUDE_BIN",
+  codex: "CODEX_BIN",
+  "cursor-agent": "CURSOR_AGENT_BIN"
+};
+var agentCliPathsWriteTail = Promise.resolve();
+function createAgentCliPathStore(storage, pluginId) {
+  return {
+    read: async () => normalizeAgentCliPaths(
+      await storage.readJson(pluginId, AGENT_CLI_PATHS_STORAGE_KEY)
+    ),
+    writePath: (cliCommand, executablePath) => serializeAgentCliPathsWrite(async () => {
+      const current = normalizeAgentCliPaths(await storage.readJson(pluginId, AGENT_CLI_PATHS_STORAGE_KEY));
+      const paths = { ...current.paths };
+      const normalized = executablePath ?? "";
+      if (normalized.length === 0) delete paths[cliCommand];
+      else paths[cliCommand] = normalized;
+      const next = { version: 1, paths };
+      await storage.writeJson(pluginId, AGENT_CLI_PATHS_STORAGE_KEY, next);
+      return next;
+    })
+  };
+}
+function serializeAgentCliPathsWrite(write) {
+  const result = agentCliPathsWriteTail.then(write);
+  agentCliPathsWriteTail = result.then(
+    () => void 0,
+    () => void 0
+  );
+  return result;
+}
+function normalizeAgentCliPaths(value) {
+  if (!isRecord4(value) || value.version !== 1 || !isRecord4(value.paths)) {
+    return { version: 1, paths: {} };
+  }
+  const paths = {};
+  for (const command of AGENT_CLI_COMMANDS) {
+    const candidate = value.paths[command];
+    if (typeof candidate === "string" && candidate.length > 0) paths[command] = candidate;
+  }
+  return { version: 1, paths };
+}
+function resolveAgentCliBinary(options) {
+  const platform = options.platform ?? process.platform;
+  const envName = OVERRIDE_ENV_BY_COMMAND[options.cliCommand];
+  const envOverride = envName ? options.env[envName]?.trim() : void 0;
+  if (envOverride) {
+    const searchedPathEntries2 = path30__default.isAbsolute(envOverride) ? [] : readPathEntries(options.env, platform);
+    const resolved2 = resolveBinarySafely(envOverride, options.env, platform);
+    if (!resolved2) {
+      return { resolved: void 0, source: "env", error: "path_not_found", launchPath: envOverride, searchedPathEntries: searchedPathEntries2 };
+    }
+    const error52 = validateResolvedFile(resolved2, platform);
+    return { resolved: error52 ? void 0 : resolved2, source: "env", error: error52, launchPath: envOverride, searchedPathEntries: searchedPathEntries2 };
+  }
+  const userPath = options.userPaths[options.cliCommand];
+  if (userPath) {
+    const checked = resolveConfiguredPath(userPath, options.env, platform);
+    return { ...checked, source: "user", launchPath: userPath, searchedPathEntries: [] };
+  }
+  const searchedPathEntries = readPathEntries(options.env, platform);
+  const resolved = resolveBinarySafely(options.cliCommand, options.env, platform);
+  if (!resolved) return { resolved: void 0, source: null, error: null, launchPath: void 0, searchedPathEntries };
+  const error51 = validateResolvedFile(resolved, platform);
+  return {
+    resolved: error51 ? void 0 : resolved,
+    source: error51 ? null : "path",
+    error: error51,
+    launchPath: void 0,
+    searchedPathEntries
+  };
+}
+function validateUserAgentCliPath(executablePath, env, platform = process.platform) {
+  const checked = resolveConfiguredPath(executablePath, env, platform);
+  return { ...checked, source: "user", launchPath: executablePath, searchedPathEntries: [] };
+}
+function agentCliCommandForId(cliId) {
+  if (cliId === "claude" || cliId === "claude-kimi") return "claude";
+  if (cliId === "codex") return "codex";
+  if (cliId === "opencode-go") return "opencode";
+  if (cliId === "cursor") return "cursor-agent";
+  return null;
+}
+function applyAgentCliPathEnvOverlay(env, cliId, userPaths) {
+  const cliCommand = agentCliCommandForId(cliId);
+  if (!cliCommand) return env;
+  const envName = OVERRIDE_ENV_BY_COMMAND[cliCommand];
+  const userPath = userPaths[cliCommand];
+  if (!envName || !userPath || (env[envName]?.trim().length ?? 0) > 0) return env;
+  return { ...env, [envName]: userPath };
+}
+function buildAgentCliClientEnvOverlay(env, cliId, userPaths) {
+  const cliCommand = agentCliCommandForId(cliId);
+  if (cliCommand !== "claude") return void 0;
+  const userPath = userPaths[cliCommand];
+  if (!userPath || (env.CLAUDE_BIN?.trim().length ?? 0) > 0) return void 0;
+  return { CLAUDE_BIN: userPath };
+}
+function createCarrierAgentCliLaunchResolver(readAgentCliPaths, baseEnv = process.env) {
+  return async (cliId, context) => {
+    const userPaths = await readAgentCliPaths();
+    const cliCommand = agentCliCommandForId(cliId);
+    if (!cliCommand) throw new Error("agent_cli_unavailable");
+    const effectiveEnv = { ...baseEnv, ...context.env };
+    const resolution = resolveAgentCliBinary({ cliCommand, env: effectiveEnv, userPaths });
+    if (!resolution.resolved) throw new Error("agent_cli_unavailable");
+    const env = buildAgentCliClientEnvOverlay(effectiveEnv, cliId, userPaths);
+    return {
+      cliPath: resolution.launchPath,
+      ...env ? { env } : {}
+    };
+  };
+}
+function resolveConfiguredPath(executablePath, env, platform) {
+  if (executablePath.includes("\0") || executablePath.startsWith("~") || !path30__default.isAbsolute(executablePath)) {
+    return { resolved: void 0, error: "path_not_absolute" };
+  }
+  let stats;
+  try {
+    stats = fs11__default.statSync(executablePath);
+  } catch {
+    return { resolved: void 0, error: "path_not_found" };
+  }
+  if (!stats.isFile()) return { resolved: void 0, error: "path_not_file" };
+  if (platform !== "win32") {
+    try {
+      fs11__default.accessSync(executablePath, fs11__default.constants.X_OK);
+    } catch {
+      return { resolved: void 0, error: "path_not_executable" };
+    }
+  }
+  const resolved = resolveBinarySafely(executablePath, env, platform);
+  return resolved ? { resolved, error: null } : { resolved: void 0, error: "path_not_executable" };
+}
+function resolveBinarySafely(command, env, platform) {
+  try {
+    return resolvePathBinary(command, env, { platform });
+  } catch {
+    return void 0;
+  }
+}
+function validateResolvedFile(resolved, platform) {
+  const resolvedPath = platform === "win32" && resolved.prefixArgs[3] === "call" ? resolved.prefixArgs[4]?.trim() ?? resolved.bin : resolved.bin;
+  try {
+    const stats = fs11__default.statSync(resolvedPath);
+    if (!stats.isFile()) return "path_not_file";
+    if (platform !== "win32") fs11__default.accessSync(resolvedPath, fs11__default.constants.X_OK);
+    return null;
+  } catch (error51) {
+    if (isNodeError2(error51) && error51.code === "EACCES") return "path_not_executable";
+    return "path_not_found";
+  }
+}
+function readPathEntries(env, platform) {
+  const value = platform === "win32" ? env.Path ?? env.PATH ?? "" : env.PATH ?? "";
+  const separator = platform === "win32" ? ";" : path30__default.delimiter;
+  return value.split(separator).filter((entry) => entry.length > 0);
+}
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNodeError2(error51) {
+  return error51 instanceof Error && "code" in error51;
+}
+
+// ../fleet-plugins/terminal/server/agent-api/agent-cli-detect.ts
 var BINARY_DISPLAY_NAMES = {
   claude: "Claude Code",
   codex: "Codex CLI",
   opencode: "OpenCode",
   "cursor-agent": "Cursor Agent"
 };
-var OVERRIDE_ENV_BY_COMMAND = {
-  claude: "CLAUDE_BIN",
-  codex: "CODEX_BIN",
-  "cursor-agent": "CURSOR_AGENT_BIN"
-};
 var VERSION_PROBE_TIMEOUT_MS = 5e3;
 var SEMVER_PATTERN = /(\d+\.\d+\.\d+)/;
 function createAgentCliDetector(deps) {
   return {
     detect: async () => {
       const commands = distinctBinaryCommands();
-      return Promise.all(commands.map((command) => detectOne(command, deps)));
+      const userPaths = await (deps.readUserPaths?.() ?? Promise.resolve({}));
+      return Promise.all(commands.map((command) => detectOne(command, userPaths, deps)));
     }
   };
 }
-function createDefaultAgentCliDetector() {
+function createDefaultAgentCliDetector(readUserPaths = async () => ({}), env = process.env) {
   return createAgentCliDetector({
-    resolve: (command) => resolveCommandWithOverride(command, process.env),
+    env,
+    readUserPaths,
     runVersion: (bin, args) => execFileVersion(bin, args)
   });
 }
-function resolveCommandWithOverride(command, env) {
-  const overrideName = OVERRIDE_ENV_BY_COMMAND[command];
-  const override = overrideName ? env[overrideName] : void 0;
-  if (override && override.trim().length > 0) {
-    return resolvePathBinary(override, env);
-  }
-  return resolvePathBinary(command, env);
-}
 function distinctBinaryCommands() {
   const seen = /* @__PURE__ */ new Set();
   const commands = [];
@@ -43705,12 +43888,13 @@ function distinctBinaryCommands() {
   }
   return commands;
 }
-async function detectOne(command, deps) {
-  const resolved = deps.resolve(command);
+async function detectOne(command, userPaths, deps) {
+  const customResolution = deps.resolve?.(command, userPaths);
+  const resolved = deps.resolve ? toResolvedBinary(customResolution) : resolveAgentCliBinary({ cliCommand: command, env: deps.env ?? process.env, userPaths }).resolved;
   const available = resolved !== void 0;
   let version2 = null;
   if (resolved) {
-    version2 = await probeVersionSafe(resolved, deps);
+    version2 = await probeAgentCliVersion(resolved, deps.runVersion);
   }
   return {
     id: command,
@@ -43719,14 +43903,26 @@ async function detectOne(command, deps) {
     version: version2
   };
 }
-async function probeVersionSafe(resolved, deps) {
+function toResolvedBinary(resolution) {
+  if (!resolution) return void 0;
+  return "resolved" in resolution ? resolution.resolved : resolution;
+}
+async function probeAgentCliVersion(resolved, runVersion = execFileVersion) {
   try {
-    const output = await deps.runVersion(resolved.bin, [...resolved.prefixArgs, "--version"]);
+    const output = await runVersion(resolved.bin, [...resolved.prefixArgs, "--version"]);
     return output.match(SEMVER_PATTERN)?.[1] ?? null;
   } catch {
     return null;
   }
 }
+async function validateAgentCliPathForSave(executablePath, env = process.env, runVersion = execFileVersion) {
+  const resolution = validateUserAgentCliPath(executablePath, env);
+  if (resolution.error || !resolution.resolved) {
+    return { error: resolution.error ?? "path_not_found", version: null };
+  }
+  const version2 = await probeAgentCliVersion(resolution.resolved, runVersion);
+  return version2 ? { error: null, version: version2 } : { error: "probe_failed", version: null };
+}
 function execFileVersion(bin, args) {
   return new Promise((resolve3, reject) => {
     execFile(
@@ -44063,7 +44259,10 @@ function createAgentTerminalLaunchResolver(deps = {}) {
     const cwd = selectedCwd || baseCwd || homedir2();
     const testLaunch = globalThis.__fleetTerminalLaunch;
     if (testLaunch) return testLaunch(cwd, context);
-    const launchEnv = buildLaunchEnv(env, cwd, context?.sessionId);
+    let launchEnv = buildLaunchEnv(env, cwd, context?.sessionId, context?.colorScheme);
+    if (deps.readAgentCliPaths) {
+      launchEnv = applyAgentCliPathEnvOverlay(launchEnv, context?.cliId, await deps.readAgentCliPaths());
+    }
     const override = parseTerminalCommand(env.FLEET_TERMINAL_CMD);
     if (override) {
       const resolvedOverride = resolveWindowsLaunchBinary2(
@@ -44209,11 +44408,13 @@ function parseTerminalCommand(command) {
   if (!bin) return null;
   return { bin, args };
 }
-function buildLaunchEnv(env, cwd, sessionId) {
+function buildLaunchEnv(env, cwd, sessionId, colorScheme) {
   return {
     ...stripConsoleInternalEnv(env),
     ...sessionId ? { FLEET_CONSOLE_SESSION_ID: sessionId, INIT_CWD: cwd, PWD: cwd } : {},
-    TERM: TERMINAL_TERM2
+    TERM: TERMINAL_TERM2,
+    // 배경을 질의하지 않는 agent CLI를 위한 고전적 테마 극성 힌트 — spawn 시점 값에 고정된다.
+    ...colorScheme ? { COLORFGBG: colorScheme === "light" ? "0;15" : "15;0" } : {}
   };
 }
 function resolveOptionalPackage(id) {
@@ -45163,6 +45364,8 @@ function buildAgentPlanToolRegistrations(dataDir) {
 }
 function createAgentApi(ctx, terminalRuntime, deps) {
   const wikiToolSpecs = createTerminalWikiToolSpecs(ctx.host.paths.fleetDataDir);
+  const agentCliPathStore = createAgentCliPathStore(ctx.host.storage, ctx.pluginId);
+  const readAgentCliPaths = async () => (await agentCliPathStore.read()).paths;
   const runtime = createFleetAgentRuntimeLifecycle({
     authService: deps.authService,
     dataDir: ctx.host.paths.fleetDataDir,
@@ -45174,11 +45377,12 @@ function createAgentApi(ctx, terminalRuntime, deps) {
     wikiToolSpecs,
     ...buildAgentPlanToolRegistrations(ctx.host.paths.fleetDataDir)
   });
+  runtime.carrierRuntime.setAgentCliLaunchResolver(createCarrierAgentCliLaunchResolver(readAgentCliPaths));
   const observability = createConsoleObservabilityStore({
     canonicalizeTheaterPath: ctx.host.paths.canonicalizeTheaterPath,
     workspaceHash: ctx.host.paths.workspaceHash
   });
-  const detector = createDefaultAgentCliDetector();
+  const detector = createDefaultAgentCliDetector(readAgentCliPaths);
   const pendingRuntimeSessions = /* @__PURE__ */ new Map();
   const identityRefreshes = /* @__PURE__ */ new Map();
   const jobOriginById = /* @__PURE__ */ new Map();
@@ -45187,6 +45391,7 @@ function createAgentApi(ctx, terminalRuntime, deps) {
     agentRuntime: runtime,
     dataDir: ctx.host.paths.fleetDataDir,
     infraServices: deps,
+    readAgentCliPaths,
     resolveServerBindings: (launchContext) => {
       const operationId = launchContext?.operationId;
       if (!operationId) return void 0;
@@ -45284,23 +45489,49 @@ function createAgentApi(ctx, terminalRuntime, deps) {
     registerCleanup: (cleanup2) => ctx.host.lifecycle.registerCleanup(cleanup2)
   });
   async function handle({ req, res, pathname }) {
-    const path47 = pathname.slice(`${ctx.basePath}/agent`.length) || "/";
-    if (path47 === "/state") {
+    const path48 = pathname.slice(`${ctx.basePath}/agent`.length) || "/";
+    if (path48 === "/state") {
       if (req.method !== "GET") return methodNotAllowed2(res);
       ctx.host.http.writeJson(res, 200, { agentClis: await buildAgentCliLaunchMetadata() });
       return true;
     }
-    if (path47 === "/agent-cli/state") {
+    if (path48 === "/agent-cli/state") {
       if (req.method !== "GET") return methodNotAllowed2(res);
       ctx.host.http.writeJson(res, 200, { clis: await detector.detect() });
       return true;
     }
-    if (path47 === "/tenants") {
+    if (path48 === "/agent-cli/diagnostics") {
+      if (req.method !== "GET") return methodNotAllowed2(res);
+      if (!ctx.host.security.isTerminalAuthorized(req)) return unauthorized(res);
+      ctx.host.http.writeJson(res, 200, await buildAgentCliDiagnostics());
+      return true;
+    }
+    if (path48 === "/agent-cli/path") {
+      if (req.method !== "PUT") return methodNotAllowed2(res);
+      if (!ctx.host.security.isTerminalAuthorized(req)) return unauthorized(res);
+      const body = await ctx.host.http.readJsonBody(req);
+      if (!body || typeof body.cliCommand !== "string" || !AGENT_CLI_COMMANDS.includes(body.cliCommand) || body.path !== null && typeof body.path !== "string") {
+        ctx.host.http.writeJson(res, 400, { error: "path_not_absolute" });
+        return true;
+      }
+      const executablePath = body.path ?? "";
+      if (executablePath.length > 0) {
+        const validation = await validateAgentCliPathForSave(executablePath, process4.env);
+        if (validation.error) {
+          ctx.host.http.writeJson(res, 400, { error: validation.error });
+          return true;
+        }
+      }
+      await agentCliPathStore.writePath(body.cliCommand, executablePath);
+      ctx.host.http.writeJson(res, 200, { ok: true });
+      return true;
+    }
+    if (path48 === "/tenants") {
       if (req.method !== "GET") return methodNotAllowed2(res);
       ctx.host.http.writeJson(res, 200, { tenants: observability.listWorkspaces() });
       return true;
     }
-    if (path47 === "/jobs") {
+    if (path48 === "/jobs") {
       if (req.method !== "GET") return methodNotAllowed2(res);
       const requestedTenantId = new URL(req.url ?? "/", "http://127.0.0.1").searchParams.get("tenant");
       const visible = requestedTenantId ? observability.listWorkspaces().filter((workspace) => workspace.tenantId === requestedTenantId) : observability.listWorkspaces();
@@ -45311,7 +45542,7 @@ function createAgentApi(ctx, terminalRuntime, deps) {
       ctx.host.http.writeJson(res, 200, { tenants: visible.map((workspace) => ({ tenantId: workspace.tenantId, tenantLabel: workspace.tenantLabel, jobs: observability.listJobs(workspace.tenantId), truncation: observability.getTruncation(workspace.tenantId) })) });
       return true;
     }
-    if (path47 === "/events") {
+    if (path48 === "/events") {
       if (req.method !== "GET") return methodNotAllowed2(res);
       const requestedTenantId = new URL(req.url ?? "/", "http://127.0.0.1").searchParams.get("tenant");
       const visible = requestedTenantId ? observability.listWorkspaces().filter((workspace) => workspace.tenantId === requestedTenantId) : observability.listWorkspaces();
@@ -45322,11 +45553,11 @@ function createAgentApi(ctx, terminalRuntime, deps) {
       writeAggregateObserverEvents(req, res, visible, observability, (tenantId) => observability.getWorkspace(tenantId), { subscribeAll: true });
       return true;
     }
-    if (path47 === "/sessions") return handleSessions(req, res);
-    if (path47 === "/capture") return handleCapture(req, res, "");
-    const sessionMatch = path47.match(/^\/sessions\/([^/]+)(?:\/([^/]+))?$/);
+    if (path48 === "/sessions") return handleSessions(req, res);
+    if (path48 === "/capture") return handleCapture(req, res, "");
+    const sessionMatch = path48.match(/^\/sessions\/([^/]+)(?:\/([^/]+))?$/);
     if (sessionMatch) return handleSessionItem(req, res, decodeURIComponent(sessionMatch[1] ?? ""), sessionMatch[2] ?? "");
-    if (path47 === "/ticket") {
+    if (path48 === "/ticket") {
       if (req.method !== "POST") return methodNotAllowed2(res);
       if (!ctx.host.security.isTerminalAuthorized(req)) {
         ctx.host.http.writeJson(res, 401, { error: "Unauthorized" });
@@ -45351,6 +45582,7 @@ function createAgentApi(ctx, terminalRuntime, deps) {
         ctx.host.http.writeJson(res, 404, { error: "theater_not_found" });
         return true;
       }
+      const colorScheme = body?.colorScheme === "light" || body?.colorScheme === "dark" ? body.colorScheme : void 0;
       ctx.host.http.writeJson(res, 200, terminalRuntime.issueTicket({
         cwd,
         sessionId: operation.id,
@@ -45358,7 +45590,8 @@ function createAgentApi(ctx, terminalRuntime, deps) {
         operationType: operation.type,
         pluginId: operation.pluginId,
         theaterId: operation.theaterId,
-        cliId: readPayloadString(operation.payload, "cliId") ?? void 0
+        cliId: readPayloadString(operation.payload, "cliId") ?? void 0,
+        ...colorScheme ? { colorScheme } : {}
       }));
       return true;
     }
@@ -45599,6 +45832,20 @@ function createAgentApi(ctx, terminalRuntime, deps) {
     const authStatuses = await getAgentCliAuthStatuses(deps.authService);
     return combineAgentCliLaunchMetadata(metadata, detected, authStatuses);
   }
+  async function buildAgentCliDiagnostics() {
+    const userPaths = await readAgentCliPaths();
+    return {
+      entries: AGENT_CLI_COMMANDS.map((cliCommand) => {
+        const resolution = resolveAgentCliBinary({ cliCommand, env: process4.env, userPaths });
+        return {
+          cliCommand,
+          configuredPath: userPaths[cliCommand] ?? null,
+          resolutionSource: resolution.source,
+          searchedPathEntries: resolution.searchedPathEntries
+        };
+      })
+    };
+  }
   async function buildLaunchKinds() {
     const metadata = await buildAgentCliLaunchMetadata();
     return buildAgentCliLaunchKinds(metadata, AGENT_OPERATION_TYPE);
@@ -46380,7 +46627,7 @@ var AnalystSession = class {
     }
     this.bridge(client2);
     try {
-      await client2.connect({ cwd: this.options.cwd, model: this.options.model, effort: this.options.effort, autoApprove: true, fsAccess: false, yoloMode: true, strictMcp: this.options.cliId === "claude" || this.options.cliId === "claude-kimi", systemPrompt: resolveAnalystSystemPrompt(this.options.language), mcpServers: [{ type: "http", name: ANALYST_MCP_SERVER, url: url2, headers: [{ name: "Authorization", value: `Bearer ${this.token}` }] }] });
+      await client2.connect({ cwd: this.options.cwd, cliPath: this.options.cliPath, env: this.options.env ? { ...this.options.env } : void 0, model: this.options.model, effort: this.options.effort, autoApprove: true, fsAccess: false, yoloMode: true, strictMcp: this.options.cliId === "claude" || this.options.cliId === "claude-kimi", systemPrompt: resolveAnalystSystemPrompt(this.options.language), mcpServers: [{ type: "http", name: ANALYST_MCP_SERVER, url: url2, headers: [{ name: "Authorization", value: `Bearer ${this.token}` }] }] });
     } catch (error51) {
       if (this.disposed) await (this.disposeFlight ?? Promise.resolve());
       else await client2.disconnect().catch(() => void 0);
@@ -46669,7 +46916,7 @@ function analysisError(code, message) {
   return { error: { code, message } };
 }
 function isAnalysisSelection(catalog, value) {
-  if (!isRecord4(value) || !hasExactKeys(value, ["cliId", "model", "effort", "language"]) || typeof value.cliId !== "string" || typeof value.model !== "string" || value.effort !== void 0 && typeof value.effort !== "string" || value.language !== void 0 && value.language !== "en" && value.language !== "ko") return false;
+  if (!isRecord5(value) || !hasExactKeys(value, ["cliId", "model", "effort", "language"]) || typeof value.cliId !== "string" || typeof value.model !== "string" || value.effort !== void 0 && typeof value.effort !== "string" || value.language !== void 0 && value.language !== "en" && value.language !== "ko") return false;
   const cli = catalog.clis.find((candidate) => candidate.cliId === value.cliId);
   if (!cli?.available) return false;
   const model = cli.models.find((candidate) => candidate.id === value.model);
@@ -46678,9 +46925,9 @@ function isAnalysisSelection(catalog, value) {
   return typeof value.effort === "string" && value.effort.length > 0 && model.effortLevels.includes(value.effort);
 }
 function isMessageBody(value) {
-  return isRecord4(value) && hasExactKeys(value, ["text"]) && typeof value.text === "string" && value.text.trim().length > 0;
+  return isRecord5(value) && hasExactKeys(value, ["text"]) && typeof value.text === "string" && value.text.trim().length > 0;
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function hasExactKeys(value, keys) {
@@ -46699,7 +46946,9 @@ var ARTIFACT_CANVAS_STYLE_PROPERTIES = /* @__PURE__ */ new Set(["background-colo
 var ARTIFACT_BODY_CANVAS_STYLE_PROPERTIES = /* @__PURE__ */ new Set([...ARTIFACT_CANVAS_STYLE_PROPERTIES, "margin"]);
 function registerAnalysisRoutes(ctx, deps = {}) {
   const registry3 = new AnalysisRegistry();
-  const detect = deps.detect ?? createDefaultAgentCliDetector().detect;
+  const env = deps.env ?? process.env;
+  const readAgentCliPaths = deps.readAgentCliPaths;
+  const detect = deps.detect ?? createDefaultAgentCliDetector(readAgentCliPaths ?? (async () => ({})), env).detect;
   const modelsFor = deps.modelsFor ?? getProviderModels;
   const readCapture = deps.readCapture ?? readProviderSessionCapture;
   const createSession = deps.createSession ?? ((options) => new AnalystSession(options));
@@ -46711,14 +46960,14 @@ function registerAnalysisRoutes(ctx, deps = {}) {
       writeError(ctx, res, 403, ANALYSIS_ERROR_CODES.catalogInvalid, "Analysis request is not accepted by this host.");
       return true;
     }
-    const path47 = pathname.slice(`${ctx.basePath}/analysis`.length) || "/";
-    if (path47 === "/catalog") return handleCatalog(ctx, req, res, catalog);
-    if (path47 === "/stream") return handleGlobalStream(ctx, req, res, registry3);
-    const artifactMatch = path47.match(/^\/artifacts\/([^/]+)$/);
+    const path48 = pathname.slice(`${ctx.basePath}/analysis`.length) || "/";
+    if (path48 === "/catalog") return handleCatalog(ctx, req, res, catalog);
+    if (path48 === "/stream") return handleGlobalStream(ctx, req, res, registry3);
+    const artifactMatch = path48.match(/^\/artifacts\/([^/]+)$/);
     if (artifactMatch) return handleArtifact(ctx, req, res, decodeURIComponent(artifactMatch[1] ?? ""), registry3);
-    const clearArtifactsMatch = path47.match(/^\/([^/]+)\/artifacts$/);
+    const clearArtifactsMatch = path48.match(/^\/([^/]+)\/artifacts$/);
     if (clearArtifactsMatch) return handleClearArtifacts(ctx, req, res, decodeURIComponent(clearArtifactsMatch[1] ?? ""), registry3);
-    const match = path47.match(/^\/([^/]+)\/(ready|start|message|stream|stop)$/);
+    const match = path48.match(/^\/([^/]+)\/(ready|start|message|stream|stop)$/);
     if (!match) return false;
     const operationId = decodeURIComponent(match[1] ?? "");
     const action = match[2] ?? "";
@@ -46732,7 +46981,7 @@ function registerAnalysisRoutes(ctx, deps = {}) {
       const deletionMarker = { operationId, deleted: false };
       inFlightStartDeletionMarkers.add(deletionMarker);
       try {
-        return await handleStart(ctx, req, res, operation, registry3, catalog, readCapture, createSession, deletionMarker);
+        return await handleStart(ctx, req, res, operation, registry3, catalog, readCapture, createSession, readAgentCliPaths, env, deletionMarker);
       } finally {
         inFlightStartDeletionMarkers.delete(deletionMarker);
       }
@@ -47014,7 +47263,7 @@ async function handleReady(ctx, req, res, operation, readCapture) {
   }
   return true;
 }
-async function handleStart(ctx, req, res, operation, registry3, catalog, readCapture, createSession, deletionMarker) {
+async function handleStart(ctx, req, res, operation, registry3, catalog, readCapture, createSession, readAgentCliPaths, env, deletionMarker) {
   if (req.method !== "POST") return methodNotAllowed(ctx, res);
   if (!isJsonRequest2(req)) return unsupportedMediaType(ctx, res);
   const body = await ctx.host.http.readJsonBody(req);
@@ -47043,7 +47292,27 @@ async function handleStart(ctx, req, res, operation, registry3, catalog, readCap
     return true;
   }
   try {
-    const result = await registry3.start(operation.id, (onEvent) => createSession({ cliId: body.cliId, model: body.model, effort: body.effort || void 0, language: body.language, cwd, capturePath: transcriptPath, onEvent: (event) => onEvent(toBrowserEvent(event)) }));
+    let launchOptions = {};
+    if (readAgentCliPaths) {
+      const userPaths = await readAgentCliPaths();
+      const cliCommand = agentCliCommandForId(body.cliId);
+      const resolution = cliCommand ? resolveAgentCliBinary({ cliCommand, env, userPaths }) : null;
+      if (!resolution?.resolved) throw new Error("analysis_cli_unavailable");
+      launchOptions = {
+        cliPath: resolution.launchPath,
+        env: buildAgentCliClientEnvOverlay(env, body.cliId, userPaths)
+      };
+    }
+    const result = await registry3.start(operation.id, (onEvent) => createSession({
+      cliId: body.cliId,
+      ...launchOptions,
+      model: body.model,
+      effort: body.effort || void 0,
+      language: body.language,
+      cwd,
+      capturePath: transcriptPath,
+      onEvent: (event) => onEvent(toBrowserEvent(event))
+    }));
     if (result === "exists") writeError(ctx, res, 409, ANALYSIS_ERROR_CODES.sessionExists, "Analysis session already exists.");
     else if (result === "stopped") writeError(ctx, res, 404, ANALYSIS_ERROR_CODES.sessionNotFound, "Analysis session was stopped before it started.");
     else ctx.host.http.writeJson(res, 200, { started: true });
@@ -47615,6 +47884,7 @@ function registerGlobalShellRoutes(ctx, runtime) {
       ctx.host.http.writeJson(res, 503, { error: "Terminal session capacity exhausted" });
       return true;
     }
+    const colorScheme = body?.colorScheme === "light" || body?.colorScheme === "dark" ? body.colorScheme : void 0;
     ctx.host.http.writeJson(res, 200, runtime.issueTicket({
       cwd: theaterPath,
       sessionId: operationId,
@@ -47622,7 +47892,8 @@ function registerGlobalShellRoutes(ctx, runtime) {
       operationType: GLOBAL_SHELL_OPERATION_TYPE,
       pluginId: ctx.pluginId,
       theaterId,
-      kind: "shell"
+      kind: "shell",
+      ...colorScheme ? { colorScheme } : {}
     }));
     return true;
   });
@@ -47650,8 +47921,8 @@ function registerTerminalModelAuthRoutes(ctx, deps) {
 }
 function createTerminalModelAuthRouter(ctx, deps) {
   return async function handleTerminalModelAuthRoute({ req, res, pathname }) {
-    const path47 = pathname.slice(`${ctx.basePath}/model-auth`.length) || "/";
-    if (path47 === "/state") {
+    const path48 = pathname.slice(`${ctx.basePath}/model-auth`.length) || "/";
+    if (path48 === "/state") {
       if (req.method !== "GET") {
         ctx.host.http.writeJson(res, 405, { error: "Method not allowed" });
         return true;
@@ -47659,7 +47930,7 @@ function createTerminalModelAuthRouter(ctx, deps) {
       ctx.host.http.writeJson(res, 200, await buildModelAuthState(deps.authService));
       return true;
     }
-    const cli = parseProviderPath(path47);
+    const cli = parseProviderPath(path48);
     if (!cli) return false;
     if (cli !== "claude-kimi") {
       ctx.host.http.writeJson(res, 404, { error: "provider_not_found" });
@@ -47726,8 +47997,8 @@ async function writeMutationState2(ctx, res, deps) {
 async function findProvider(deps) {
   return (await buildModelAuthState(deps.authService)).providers[0] ?? null;
 }
-function parseProviderPath(path47) {
-  const parts = path47.split("/").filter(Boolean);
+function parseProviderPath(path48) {
+  const parts = path48.split("/").filter(Boolean);
   if (parts.length !== 2 || parts[0] !== "providers") return null;
   try {
     return decodeURIComponent(parts[1] ?? "");
@@ -47796,6 +48067,7 @@ function registerShellRoutes(ctx, runtime) {
       ctx.host.http.writeJson(res, 503, { error: "Terminal session capacity exhausted" });
       return true;
     }
+    const colorScheme = body?.colorScheme === "light" || body?.colorScheme === "dark" ? body.colorScheme : void 0;
     ctx.host.http.writeJson(res, 200, runtime.issueTicket({
       cwd: theaterPath,
       sessionId: operationId,
@@ -47803,7 +48075,8 @@ function registerShellRoutes(ctx, runtime) {
       operationType: operation.type,
       pluginId: operation.pluginId,
       theaterId: operation.theaterId,
-      kind: "shell"
+      kind: "shell",
+      ...colorScheme ? { colorScheme } : {}
     }));
     return true;
   });
@@ -47880,7 +48153,10 @@ var routes_default = definePlugin({
     registerTerminalSettingsRoutes(ctx, { globalOptionsService: infraServices.globalOptionsService });
     registerTerminalModelAuthRoutes(ctx, { authService: infraServices.authService });
     registerCarrierSettingsRoutes(ctx, { registry: carrierRegistry });
-    registerAnalysisRoutes(ctx);
+    const agentCliPathStore = createAgentCliPathStore(ctx.host.storage, ctx.pluginId);
+    registerAnalysisRoutes(ctx, {
+      readAgentCliPaths: async () => (await agentCliPathStore.read()).paths
+    });
     const agentLaunchKinds = registerAgentRoutes(ctx, runtime, {
       authService: infraServices.authService,
       globalOptionsService: infraServices.globalOptionsService