qlogicagent 2.13.3 → 2.13.5

package/dist/runtime/infra/acp-detector.js

@@ -0,0 +1,862 @@
+/**
+ * ACP Agent Detector — scans PATH for installed ACP-compatible CLI agents.
+ *
+ * Uses `which` (Unix) / `where` (Windows) to locate CLI binaries,
+ * then optionally probes version. Results are cached with TTL.
+ *
+ * Reference: AionUI AcpDetector + ACP_BACKENDS_ALL registry.
+ */
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+// ── Pre-defined ACP Backend Registry ────────────────────────
+export const ACP_BACKENDS = {
+    claude: {
+        id: "claude",
+        name: "Claude Code",
+        cliCommand: "claude-agent-acp",
+        acpArgs: [],
+        authRequired: true,
+        skillsDirs: [".claude/skills"],
+        supportsBaseUrlOverride: true,
+        apiKeyEnvVar: "ANTHROPIC_API_KEY",
+        baseUrlEnvVar: "ANTHROPIC_BASE_URL",
+    },
+    codex: {
+        id: "codex",
+        name: "OpenAI Codex CLI",
+        cliCommand: "codex-acp",
+        // Windows has no OS sandbox (no seatbelt/landlock); codex-acp's default 'read-only' mode stalls
+        // tool exec (the internal Windows sandbox hangs). danger-full-access skips that sandbox so tools
+        // (shell/fs/image/skill) run in codex's own ConPTY. With full-access there is nothing to escalate,
+        // so approval_policy=on-request never fires (verified — codex just runs the command); 'untrusted'
+        // instead asks before every non-trusted command. codex surfaces those via session/request_permission,
+        // which our reverse-RPC host handler turns into a user-facing approval card (verified end-to-end).
+        acpArgs: ["-c", "sandbox_mode=danger-full-access", "-c", "approval_policy=untrusted"],
+        authRequired: true,
+        supportsBaseUrlOverride: true,
+        apiKeyEnvVar: "OPENAI_API_KEY",
+        baseUrlEnvVar: "OPENAI_BASE_URL",
+    },
+    qwen: {
+        id: "qwen",
+        name: "Qwen Code",
+        cliCommand: "qwen",
+        acpArgs: ["--acp", "--experimental-skills"],
+        defaultCliPath: "npx @qwen-code/qwen-code",
+        authRequired: true,
+        skillsDirs: [".qwen/skills"],
+        supportsBaseUrlOverride: true,
+        apiKeyEnvVar: "DASHSCOPE_API_KEY",
+    },
+    kimi: {
+        id: "kimi",
+        name: "Kimi CLI",
+        cliCommand: "kimi",
+        acpArgs: ["acp"],
+        // kimi-cli authenticates via a Kimi account OAuth flow (`kimi login`), not an env API key
+        // (no MOONSHOT_API_KEY support in the agentic CLI — verified against `kimi --help`).
+        authRequired: true,
+        skillsDirs: [".kimi/skills"],
+        supportsBaseUrlOverride: false,
+    },
+    opencode: {
+        id: "opencode",
+        name: "OpenCode",
+        cliCommand: "opencode",
+        acpArgs: ["acp"],
+        authRequired: false,
+        skillsDirs: [".opencode/skills"],
+        supportsBaseUrlOverride: true,
+    },
+    cursor: {
+        id: "cursor",
+        name: "Cursor Agent",
+        cliCommand: "cursor-agent",
+        acpArgs: ["acp"],
+        authRequired: true,
+        skillsDirs: [".cursor/skills"],
+        supportsBaseUrlOverride: false,
+    },
+    hermes: {
+        id: "hermes",
+        name: "Hermes Agent",
+        cliCommand: "hermes",
+        // NousResearch Hermes speaks standard ACP via `hermes acp` (HermesACPAgent, built on the
+        // official `acp` Python SDK). Verified on a real machine: the initialize handshake returns
+        // agentCapabilities + authMethods (id "hermes-setup"), then session/new fails with
+        // "No LLM provider configured" until setup runs — i.e. a clean auth boundary like gemini/qwen.
+        acpArgs: ["acp"],
+        // Needs a one-time provider/model setup (`hermes acp --setup`) before it can serve a turn.
+        authRequired: true,
+        supportsBaseUrlOverride: true,
+    },
+    copilot: {
+        id: "copilot",
+        name: "GitHub Copilot",
+        cliCommand: "copilot",
+        acpArgs: ["--acp"],
+        authRequired: true,
+        supportsBaseUrlOverride: false,
+    },
+    codebuddy: {
+        id: "codebuddy",
+        name: "CodeBuddy",
+        cliCommand: "codebuddy",
+        acpArgs: ["--acp"],
+        authRequired: true,
+        skillsDirs: [".codebuddy/skills"],
+        supportsBaseUrlOverride: true,
+    },
+    kiro: {
+        id: "kiro",
+        name: "Kiro CLI",
+        cliCommand: "kiro-cli",
+        acpArgs: ["acp"],
+        authRequired: true,
+        supportsBaseUrlOverride: true,
+    },
+    snow: {
+        id: "snow",
+        name: "Snow",
+        cliCommand: "snow",
+        acpArgs: ["--acp"],
+        authRequired: true,
+        supportsBaseUrlOverride: true,
+    },
+    qoder: {
+        id: "qoder",
+        name: "Qoder",
+        cliCommand: "qodercli",
+        acpArgs: ["--acp"],
+        authRequired: true,
+        supportsBaseUrlOverride: true,
+    },
+    gemini: {
+        id: "gemini",
+        name: "Gemini CLI",
+        cliCommand: "gemini",
+        // Gemini CLI gates ACP behind the experimental flag (matches vscode-acp); plain --acp is
+        // not recognised by the gemini binary.
+        acpArgs: ["--experimental-acp"],
+        defaultCliPath: "npx @google/gemini-cli",
+        authRequired: true,
+        supportsBaseUrlOverride: false,
+        apiKeyEnvVar: "GEMINI_API_KEY",
+    },
+    glm: {
+        id: "glm",
+        name: "GLM Agent",
+        cliCommand: "glm-acp-agent",
+        acpArgs: [],
+        defaultCliPath: "npx glm-acp-agent",
+        authRequired: true,
+        supportsBaseUrlOverride: true,
+        apiKeyEnvVar: "Z_AI_API_KEY",
+    },
+    cline: {
+        id: "cline",
+        name: "Cline",
+        cliCommand: "cline",
+        acpArgs: ["--acp"],
+        defaultCliPath: "npx cline",
+        authRequired: true,
+        supportsBaseUrlOverride: true,
+    },
+    nova: {
+        id: "nova",
+        name: "Nova",
+        cliCommand: "nova",
+        acpArgs: ["acp"],
+        defaultCliPath: "npx @compass-ai/nova",
+        authRequired: true,
+        supportsBaseUrlOverride: true,
+    },
+    openclaw: {
+        id: "openclaw",
+        name: "OpenClaw",
+        cliCommand: "openclaw",
+        // OpenClaw is a host PLATFORM, not a thin agent. The bare `openclaw acp` command runs an
+        // "ACP bridge backed by the Gateway" (there is no `serve`/`--acp` subcommand — verified on a
+        // real machine). It proxies to a running openclaw Gateway, so it needs a valid ~/.openclaw
+        // config + a live Gateway (--url/--token/--session) before it can serve. Advanced entry only.
+        acpArgs: ["acp"],
+        authRequired: true,
+        supportsBaseUrlOverride: true,
+        apiKeyEnvVar: "OPENCLAW_API_KEY",
+        baseUrlEnvVar: "OPENCLAW_BASE_URL",
+    },
+};
+export const AGENT_CATALOG_IDS = [
+    "claude", "codex", "gemini", "copilot",
+    "cursor", "qwen", "kimi", "glm",
+    "opencode", "kiro", "qoder",
+    "openclaw", "hermes",
+];
+const CATALOG_META = {
+    claude: { brandId: "claude", category: "coding", integration: "acp", keySource: "llmrouter", authMode: "key",
+        install: { npm: "npm i -g @agentclientprotocol/claude-agent-acp", cliCommand: "claude-agent-acp", docsUrl: "https://github.com/agentclientprotocol/claude-agent-acp" } },
+    codex: { brandId: "codex", category: "coding", integration: "acp", keySource: "llmrouter", authMode: "key",
+        install: { npm: "npm i -g @zed-industries/codex-acp", cliCommand: "codex-acp", verifyCmd: "codex-acp --help", docsUrl: "https://github.com/zed-industries/codex-acp" } },
+    gemini: { brandId: "gemini", category: "coding", integration: "acp", keySource: "direct", authMode: "key",
+        install: { npm: "npm i -g @google/gemini-cli", cliCommand: "gemini", docsUrl: "https://github.com/google-gemini/gemini-cli" } },
+    copilot: { brandId: "copilot", category: "coding", integration: "acp", keySource: "none", authMode: "oauth", note: "默认需 GitHub 账号(也支持 BYOK 自带 key,后续可接入免登录注入)",
+        install: { npm: "npm i -g @github/copilot", cliCommand: "copilot", docsUrl: "https://docs.github.com/copilot/concepts/agents/about-copilot-cli" } },
+    cursor: { brandId: "cursor", category: "coding", integration: "acp", keySource: "none", authMode: "oauth", note: "需 Cursor 账号",
+        install: { curl: "curl https://cursor.com/install -fsS | bash", cliCommand: "cursor-agent", docsUrl: "https://cursor.com/cli" } },
+    qwen: { brandId: "qwen", category: "coding", integration: "acp", keySource: "direct", authMode: "key",
+        install: { npm: "npm i -g @qwen-code/qwen-code", cliCommand: "qwen", docsUrl: "https://github.com/QwenLM/qwen-code" } },
+    kimi: { brandId: "kimi", category: "coding", integration: "acp", keySource: "none", authMode: "oauth", note: "需 Kimi 账号(在终端运行 kimi login 登录)",
+        install: { pip: "uv tool install kimi-cli", cliCommand: "kimi", docsUrl: "https://github.com/MoonshotAI/kimi-cli" } },
+    glm: { brandId: "glm", category: "coding", integration: "acp", keySource: "direct", authMode: "key",
+        install: { npm: "npm i -g glm-acp-agent", cliCommand: "glm-acp-agent", docsUrl: "https://github.com/stefandevo/glm-acp-agent" } },
+    opencode: { brandId: "opencode", category: "coding", integration: "acp", keySource: "direct", authMode: "key",
+        install: { npm: "npm i -g opencode-ai", cliCommand: "opencode", docsUrl: "https://opencode.ai/docs" } },
+    kiro: { brandId: "kiro", category: "coding", integration: "acp", keySource: "direct", authMode: "key",
+        install: { cliCommand: "kiro-cli", docsUrl: "https://kiro.dev/docs" } },
+    qoder: { brandId: "qoder", category: "coding", integration: "acp", keySource: "direct", authMode: "key",
+        install: { npm: "npm i -g @qoder-ai/qodercli", cliCommand: "qodercli", docsUrl: "https://docs.qoder.com/cli/acp" } },
+    // 助理 (assistant): popular personal desktop agents.
+    openclaw: { brandId: "openclaw", category: "assistant", integration: "acp", keySource: "direct", authMode: "key", note: "高级:需自备运行中的 openclaw Gateway + 有效 ~/.openclaw 配置(openclaw acp = 挂在 Gateway 上的 ACP 桥)",
+        install: { npm: "npm i -g openclaw", cliCommand: "openclaw", docsUrl: "https://github.com/openclaw/openclaw" } },
+    hermes: { brandId: "hermes", category: "assistant", integration: "acp", keySource: "none", authMode: "oauth", note: "首次需在终端运行 hermes acp --setup 配置 provider/model",
+        install: { pip: "uv tool install hermes-agent[acp] --python 3.13", cliCommand: "hermes", docsUrl: "https://github.com/NousResearch/hermes-agent" } },
+};
+/** Merged catalog entry (base ACP config + grid/install metadata) for one id. */
+export function getCatalogEntry(id) {
+    const base = ACP_BACKENDS[id];
+    if (!base)
+        return undefined;
+    return CATALOG_META[id] ? { ...base, ...CATALOG_META[id] } : base;
+}
+/** Ordered curated catalog: base ACP config merged with grid/install metadata. */
+export function getAgentCatalog() {
+    return AGENT_CATALOG_IDS.map((id) => {
+        const entry = getCatalogEntry(id);
+        if (!entry)
+            throw new Error(`Agent catalog entry "${id}" has no backend definition`);
+        return entry;
+    });
+}
+// ── Internal sub-agent role descriptors ─────────────────────
+const INTERNAL_ROLES = ["general", "explore", "plan", "code", "research", "verify"];
+function buildInternalAgentDescriptors() {
+    return INTERNAL_ROLES.map((role) => ({
+        id: `qlogicagent-${role}`,
+        name: `qlogicagent (${role})`,
+        category: "sub-agent",
+        protocol: "internal",
+        status: "available",
+        authRequired: false,
+        hasConfig: true,
+        supportsBaseUrlOverride: true,
+        capabilities: {
+            supportsMcp: false,
+            supportsResume: true,
+            supportsUsageUpdate: true,
+        },
+    }));
+}
+// ── CLI Detection ───────────────────────────────────────────
+const isWindows = platform() === "win32";
+const NPM_LATEST_TTL_MS = 5 * 60_000;
+let npmGlobalRootCache;
+const npmLatestVersionCache = new Map();
+/** Locate a CLI binary using which (Unix) or where (Windows). */
+function whichSync(command) {
+    try {
+        const cmd = isWindows ? `where ${command}` : `which ${command}`;
+        const result = execSync(cmd, {
+            encoding: "utf8",
+            timeout: 5_000,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        // `where` on Windows may return multiple lines; take the first
+        const firstLine = result.split(/\r?\n/)[0]?.trim();
+        return firstLine || null;
+    }
+    catch {
+        return null;
+    }
+}
+function compareSemverDesc(a, b) {
+    const parse = (value) => {
+        const match = value.match(/^(\d+)\.(\d+)\.(\d+)/);
+        return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : [0, 0, 0];
+    };
+    const av = parse(a);
+    const bv = parse(b);
+    for (let i = 0; i < 3; i += 1) {
+        if (av[i] !== bv[i])
+            return bv[i] - av[i];
+    }
+    return b.localeCompare(a);
+}
+export function resolveWindowsCopilotLoader() {
+    if (!isWindows)
+        return null;
+    const roots = [
+        process.env.COPILOT_CACHE_HOME ? join(process.env.COPILOT_CACHE_HOME, "pkg", "win32-x64") : null,
+        process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "copilot", "pkg", "win32-x64") : null,
+        process.env.COPILOT_HOME ? join(process.env.COPILOT_HOME, "pkg", "win32-x64") : null,
+        join(homedir(), ".copilot", "pkg", "win32-x64"),
+    ].filter((value) => Boolean(value));
+    for (const root of roots) {
+        try {
+            const versions = readdirSync(root, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => entry.name)
+                .sort(compareSemverDesc);
+            for (const version of versions) {
+                const loader = join(root, version, "npm-loader.js");
+                if (existsSync(loader) && probeVersion(loader))
+                    return loader;
+            }
+        }
+        catch {
+            // Keep scanning other cache roots.
+        }
+    }
+    return null;
+}
+function resolveBackendCli(backend) {
+    if (backend.id === "copilot") {
+        return resolveWindowsCopilotLoader() ?? whichSync(backend.cliCommand);
+    }
+    return whichSync(backend.cliCommand);
+}
+function runNpm(args, timeout) {
+    return execFileSync(isWindows ? "cmd.exe" : "npm", isWindows ? ["/d", "/s", "/c", "npm", ...args] : args, {
+        encoding: "utf8",
+        timeout,
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+function normalizePackageSpecifier(specifier) {
+    const raw = specifier.trim().replace(/^["']|["']$/g, "");
+    if (!raw || raw.startsWith("-"))
+        return null;
+    if (raw.startsWith("@")) {
+        const versionAt = raw.indexOf("@", 1);
+        return versionAt > 0 ? raw.slice(0, versionAt) : raw;
+    }
+    const versionAt = raw.indexOf("@");
+    return versionAt > 0 ? raw.slice(0, versionAt) : raw;
+}
+export function getNpmInstallPackageName(command) {
+    if (!command)
+        return null;
+    const parts = command.trim().split(/\s+/).filter(Boolean);
+    if (parts[0] !== "npm" && parts[0] !== "npm.cmd")
+        return null;
+    const installIndex = parts.findIndex((part) => part === "i" || part === "install" || part === "add");
+    if (installIndex < 0)
+        return null;
+    for (let i = installIndex + 1; i < parts.length; i += 1) {
+        const part = parts[i];
+        if (part === "-g" || part === "--global")
+            continue;
+        if (part.startsWith("--") && !part.includes("=")) {
+            i += 1;
+            continue;
+        }
+        if (part.startsWith("-"))
+            continue;
+        return normalizePackageSpecifier(part);
+    }
+    return null;
+}
+function cleanSemver(value) {
+    if (!value)
+        return null;
+    const match = value.trim().match(/v?(\d+\.\d+\.\d+(?:[-+][\w.-]+)?|\d+\.\d+(?:[-+][\w.-]+)?)/);
+    return match?.[1] ?? null;
+}
+export function compareSemverVersions(a, b) {
+    const parse = (value) => {
+        const cleaned = cleanSemver(value) ?? value;
+        const [core, pre = ""] = cleaned.replace(/^v/, "").split("-", 2);
+        const nums = core.split(".").map((part) => Number.parseInt(part, 10) || 0);
+        while (nums.length < 3)
+            nums.push(0);
+        return { nums, pre };
+    };
+    const av = parse(a);
+    const bv = parse(b);
+    for (let i = 0; i < 3; i += 1) {
+        if (av.nums[i] !== bv.nums[i])
+            return av.nums[i] - bv.nums[i];
+    }
+    if (av.pre === bv.pre)
+        return 0;
+    if (!av.pre)
+        return 1;
+    if (!bv.pre)
+        return -1;
+    return av.pre.localeCompare(bv.pre);
+}
+export function isVersionNewer(latest, current) {
+    if (!latest || !current)
+        return false;
+    return compareSemverVersions(latest, current) > 0;
+}
+function getNpmGlobalRoot() {
+    if (npmGlobalRootCache !== undefined)
+        return npmGlobalRootCache;
+    try {
+        npmGlobalRootCache = runNpm(["root", "-g"], 3_000) || null;
+    }
+    catch {
+        npmGlobalRootCache = null;
+    }
+    return npmGlobalRootCache;
+}
+export function readGlobalNpmPackageVersion(packageName) {
+    if (!packageName)
+        return null;
+    const root = getNpmGlobalRoot();
+    if (!root)
+        return null;
+    const packageJson = join(root, ...packageName.split("/"), "package.json");
+    try {
+        const parsed = JSON.parse(readFileSync(packageJson, "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function fetchNpmLatestPackageVersion(packageName) {
+    if (!packageName)
+        return null;
+    const cached = npmLatestVersionCache.get(packageName);
+    if (cached && Date.now() - cached.timestamp < NPM_LATEST_TTL_MS)
+        return cached.version;
+    let version = null;
+    try {
+        const raw = runNpm(["view", packageName, "version", "--json"], 5_000);
+        const parsed = raw ? JSON.parse(raw) : null;
+        version = typeof parsed === "string" ? parsed : cleanSemver(raw);
+    }
+    catch {
+        version = null;
+    }
+    npmLatestVersionCache.set(packageName, { timestamp: Date.now(), version });
+    return version;
+}
+export function resolveInstalledNpmPackageVersionFromInstall(install) {
+    const packageName = getNpmInstallPackageName(install?.npm);
+    return readGlobalNpmPackageVersion(packageName);
+}
+export function getCatalogPackageVersionInfo(entry, detectedVersion) {
+    const packageName = getNpmInstallPackageName(entry.install?.npm);
+    const packageVersion = readGlobalNpmPackageVersion(packageName);
+    const installedVersion = packageVersion ?? cleanSemver(detectedVersion) ?? detectedVersion ?? undefined;
+    if (!packageName || !installedVersion)
+        return { installedVersion, updateAvailable: false };
+    const latestVersion = fetchNpmLatestPackageVersion(packageName) ?? undefined;
+    return {
+        packageName,
+        installedVersion,
+        latestVersion,
+        updateAvailable: isVersionNewer(latestVersion, installedVersion),
+    };
+}
+/** Try to extract version from a CLI (best-effort). */
+function probeVersion(cliPath) {
+    try {
+        const command = cliPath.endsWith("npm-loader.js")
+            ? `"${process.execPath}" "${cliPath}" version`
+            : `"${cliPath}" version`;
+        const result = execSync(command, {
+            encoding: "utf8",
+            timeout: 5_000,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        // Extract version-like pattern
+        const match = result.match(/(\d+\.\d+[\w.-]*)/);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function normalizeWindowsAcpCommand(cliPath, args) {
+    if (!isWindows)
+        return { cliPath, acpArgs: args };
+    if (cliPath.endsWith("npm-loader.js")) {
+        const hasNoAutoUpdate = args.includes("--no-auto-update");
+        return {
+            cliPath: process.execPath,
+            acpArgs: [cliPath, ...args, ...(hasNoAutoUpdate ? [] : ["--no-auto-update"])],
+        };
+    }
+    // .bin shim (.cmd/.ps1/extensionless) -> resolve the real entry .js and run it under node,
+    // so Node's piped stdin reaches the agent (powershell -File swallows piped stdin).
+    const entry = resolveNpmBinEntry(cliPath);
+    if (entry) {
+        return { cliPath: process.execPath, acpArgs: [entry, ...args] };
+    }
+    return { cliPath, acpArgs: args };
+}
+/**
+ * Resolve an npm `.bin` shim (or its extensionless base) to the real JS entry it launches.
+ * npm-generated shims (.cmd/.ps1/sh) all reference the same target relative to the shim dir,
+ * e.g. a quoted `node_modules/<scope>/<pkg>/bin/<name>.js` path. We read the shim text,
+ * extract that `node_modules/.../*.js` tail, and resolve it against the shim's directory.
+ * Returns an absolute entry path, or null if it cannot be resolved.
+ */
+function resolveNpmBinEntry(shimPath) {
+    // Strip a known shim extension to get the base, then probe the concrete shim files.
+    const base = shimPath.replace(/\.(cmd|ps1|exe)$/i, "");
+    const candidates = [`${base}.cmd`, `${base}.ps1`, base];
+    for (const candidate of candidates) {
+        if (!existsSync(candidate))
+            continue;
+        let text;
+        try {
+            text = readFileSync(candidate, "utf8");
+        }
+        catch {
+            continue;
+        }
+        // Match the quoted entry path the shim launches: a `.js` token containing `node_modules`.
+        const match = text.match(/["']?[^"'\s]*?(node_modules[\\/][^"'\s]*?\.js)["']?/i);
+        if (!match)
+            continue;
+        const rel = match[1].replace(/\\/g, "/");
+        const entry = join(dirname(base), rel);
+        if (existsSync(entry))
+            return entry;
+    }
+    return null;
+}
+const CACHE_TTL_MS = 60_000; // 1 minute
+/**
+ * Build the spawn env for an external ACP backend.
+ *
+ * Maps the agent-config's portable `apiKey`/`baseUrl` onto the backend-declared
+ * environment-variable names (`apiKeyEnvVar`/`baseUrlEnvVar`) so a user who only
+ * configures an API key + base URL (e.g. via agents.setConfig) actually drives the
+ * underlying CLI with a third-party OpenAI/Anthropic-compatible gateway — no official
+ * account login required. Without this mapping the backends declared the env-var names
+ * but nothing ever populated them.
+ *
+ * Precedence (lowest → highest), so explicit user input always wins:
+ *   1. backend.env            (static backend defaults)
+ *   2. mapped apiKey/baseUrl  (config.apiKey → backend.apiKeyEnvVar, etc.)
+ *   3. customConfig.env       (raw env the user hand-entered)
+ *
+ * Injection is conditional: the apiKey/baseUrl mapping only fires when the backend
+ * actually declares the corresponding envVar name (so we never invent a var the CLI
+ * does not read). Returns undefined when there is nothing to inject, preserving the
+ * prior `env?: undefined` behavior for un-configured backends.
+ */
+export function buildBackendEnv(backend, customConfig, autoEnv) {
+    const merged = {};
+    // 1. Static backend defaults (lowest precedence).
+    if (backend?.env)
+        Object.assign(merged, backend.env);
+    // 1.5. Catalog login-free key injection (below explicit user config, so a user
+    //      override always wins, but above static defaults).
+    if (autoEnv)
+        Object.assign(merged, autoEnv);
+    // 2. Map portable apiKey/baseUrl onto the backend-declared env-var names.
+    if (backend?.apiKeyEnvVar && customConfig?.apiKey) {
+        merged[backend.apiKeyEnvVar] = customConfig.apiKey;
+    }
+    if (backend?.baseUrlEnvVar && customConfig?.baseUrl) {
+        merged[backend.baseUrlEnvVar] = customConfig.baseUrl;
+    }
+    // 3. Raw user-supplied env wins over the mapped values (highest precedence).
+    if (customConfig?.env)
+        Object.assign(merged, customConfig.env);
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/** Agents drivable via the OpenAI-compatible env (OPENAI_API_KEY/OPENAI_BASE_URL/OPENAI_MODEL),
+ *  so the host's active model can be passed through to them. */
+const OPENAI_COMPAT_AGENTS = new Set(["codex", "qwen", "opencode"]);
+/**
+ * Resolve the login-free key env for a catalog agent from the unified key sources.
+ * "set key once in our system → all agents" — the user never logs into each CLI.
+ *   - authMode "oauth" / keySource "none" → {} (no bypass; account required)
+ *   - keySource "llmrouter" → gateway sk-qllm + gateway baseUrl (agent calls our gateway)
+ *   - keySource "direct"    → the user's provider key (agent calls the provider directly)
+ * Only emits env vars the backend actually declares (apiKeyEnvVar / baseUrlEnvVar).
+ */
+export function resolveCatalogKeyEnv(entry, sources) {
+    const env = {};
+    if (!entry || entry.authMode === "oauth" || entry.keySource === "none")
+        return env;
+    const { apiKeyEnvVar, baseUrlEnvVar } = entry;
+    if (entry.keySource === "llmrouter") {
+        if (apiKeyEnvVar && sources.llmrouterKey)
+            env[apiKeyEnvVar] = sources.llmrouterKey;
+        const baseUrl = sources.getLlmrouterBaseUrl?.(entry.id, entry) ?? sources.llmrouterBaseUrl;
+        if (baseUrlEnvVar && baseUrl)
+            env[baseUrlEnvVar] = baseUrl;
+        if (OPENAI_COMPAT_AGENTS.has(entry.id) && sources.llmrouterModel)
+            env.OPENAI_MODEL = sources.llmrouterModel;
+    }
+    else if (entry.keySource === "direct") {
+        const key = sources.getDirectKey?.(entry.id);
+        if (apiKeyEnvVar && key)
+            env[apiKeyEnvVar] = key;
+        // direct agents call their own official endpoint — no base URL override needed.
+    }
+    // Model passthrough (透传): when no provider key resolved above, drive OpenAI-compatible agents
+    // (codex/qwen/opencode) with the host's active model (deepseek/volcengine) via OPENAI_*. This is
+    // how the configured model flows to spawned teammates with no per-agent login. qlogicagent
+    // participants instead read the shared owner-profile settings.json (see buildSelfDescriptor).
+    if (Object.keys(env).length === 0 && sources.passthroughModel?.apiKey && OPENAI_COMPAT_AGENTS.has(entry.id)) {
+        const m = sources.passthroughModel;
+        env.OPENAI_API_KEY = m.apiKey;
+        if (m.baseUrl)
+            env.OPENAI_BASE_URL = m.baseUrl;
+        if (m.model)
+            env.OPENAI_MODEL = m.model;
+    }
+    return env;
+}
+function appendLlmrouterAcpArgs(entry, args, autoEnv, sources) {
+    if (entry?.id !== "codex" || entry.keySource !== "llmrouter" || !autoEnv.OPENAI_API_KEY)
+        return args;
+    if (args.some((arg) => arg.includes("model_provider") || arg.includes("model_providers.")))
+        return args;
+    const baseUrl = autoEnv.OPENAI_BASE_URL;
+    const model = sources.llmrouterModel || autoEnv.OPENAI_MODEL || "deepseek-v4-flash";
+    if (!baseUrl)
+        return args;
+    return [
+        ...args,
+        "-c", "model_providers.llmrouter.name=llmrouter",
+        "-c", `model_providers.llmrouter.base_url=${baseUrl}`,
+        "-c", "model_providers.llmrouter.wire_api=responses",
+        "-c", "model_providers.llmrouter.env_key=OPENAI_API_KEY",
+        "-c", "model_provider=llmrouter",
+        "-c", `model=${model}`,
+    ];
+}
+export class AcpDetector {
+    cache = null;
+    configStore = null;
+    keySources = {};
+    /**
+     * Provide the config store data so detector can populate `hasConfig` field
+     * and include user-registered custom agents.
+     */
+    setConfigStore(data) {
+        this.configStore = data;
+    }
+    /** Wire the unified key sources for login-free catalog injection. */
+    setKeySources(sources) {
+        this.keySources = sources;
+    }
+    /**
+     * Scan for installed ACP agent CLIs.
+     * @param force - Clear cache and re-scan.
+     */
+    scan(force = false) {
+        if (!force && this.cache && Date.now() - this.cache.timestamp < CACHE_TTL_MS) {
+            return this.cache.agents;
+        }
+        const agents = [];
+        // 1. Known ACP backends (external agents exposed to UI)
+        for (const backend of Object.values(ACP_BACKENDS)) {
+            agents.push(this.detectBackend(backend));
+        }
+        // 3. User-registered custom agents
+        if (this.configStore?.customAgents) {
+            for (const custom of Object.values(this.configStore.customAgents)) {
+                agents.push(this.detectCustomAgent(custom));
+            }
+        }
+        this.cache = { agents, timestamp: Date.now() };
+        return agents;
+    }
+    /** Return cached results without IO. */
+    list() {
+        if (this.cache)
+            return this.cache.agents;
+        return this.scan();
+    }
+    /** Clear the detection cache. */
+    clearCache() {
+        this.cache = null;
+    }
+    detectBackend(backend) {
+        const cliPath = resolveBackendCli(backend);
+        const hasConfig = this.hasAgentConfig(backend.id);
+        if (!cliPath) {
+            return {
+                id: backend.id,
+                name: backend.name,
+                category: "teammate",
+                protocol: "acp",
+                status: "not_installed",
+                authRequired: backend.authRequired,
+                hasConfig,
+                supportsBaseUrlOverride: backend.supportsBaseUrlOverride,
+                capabilities: {
+                    supportsMcp: true,
+                    supportsResume: false,
+                    supportsUsageUpdate: backend.id === "claude" || backend.id === "codex",
+                    skillsDirs: backend.skillsDirs,
+                },
+            };
+        }
+        const catalogEntry = getCatalogEntry(backend.id);
+        const version = probeVersion(cliPath) ?? resolveInstalledNpmPackageVersionFromInstall(catalogEntry?.install);
+        if (backend.id === "copilot" && !version) {
+            return {
+                id: backend.id,
+                name: backend.name,
+                category: "teammate",
+                protocol: "acp",
+                status: "not_installed",
+                authRequired: backend.authRequired,
+                hasConfig,
+                supportsBaseUrlOverride: backend.supportsBaseUrlOverride,
+                capabilities: {
+                    supportsMcp: true,
+                    supportsResume: false,
+                    supportsUsageUpdate: false,
+                    skillsDirs: backend.skillsDirs,
+                },
+            };
+        }
+        return {
+            id: backend.id,
+            name: backend.name,
+            category: "teammate",
+            protocol: "acp",
+            status: "available",
+            cliPath,
+            version: version ?? undefined,
+            authRequired: backend.authRequired,
+            hasConfig,
+            supportsBaseUrlOverride: backend.supportsBaseUrlOverride,
+            capabilities: {
+                supportsMcp: true,
+                supportsResume: backend.id === "claude" || backend.id === "goose" || backend.id === "copilot",
+                supportsUsageUpdate: backend.id === "claude" || backend.id === "codex" || backend.id === "copilot",
+                skillsDirs: backend.skillsDirs,
+            },
+        };
+    }
+    detectCustomAgent(custom) {
+        const cliPath = whichSync(custom.cliCommand);
+        const hasConfig = this.hasAgentConfig(custom.id);
+        return {
+            id: custom.id,
+            name: custom.name,
+            category: "teammate",
+            protocol: "acp",
+            status: cliPath ? "available" : "not_installed",
+            cliPath: cliPath ?? undefined,
+            authRequired: custom.authRequired ?? false,
+            hasConfig,
+            supportsBaseUrlOverride: custom.supportsBaseUrlOverride ?? false,
+            capabilities: {
+                supportsMcp: true,
+                supportsResume: false,
+                supportsUsageUpdate: false,
+                skillsDirs: custom.skillsDirs,
+            },
+        };
+    }
+    hasAgentConfig(agentId) {
+        if (!this.configStore)
+            return false;
+        const cfg = this.configStore.agents[agentId];
+        return !!(cfg?.apiKey || cfg?.baseUrl || cfg?.customCliPath);
+    }
+    /**
+     * Descriptor for qlogicagent participating in Solo/Product as a self-hosted ACP agent.
+     *
+     * qlogicagent's own CLI speaks ACP by default (cli/main.ts: ACP server unless --no-acp), so a
+     * participant is just another `node <cli.js>` process. The child reads the SAME owner-profile
+     * settings.json (model-registry), so it runs with the configured provider (deepseek / volcengine /
+     * llmrouter) — that is how the configured model "passes through" to every qlogicagent instance,
+     * with no per-agent key. We forward the owner-profile + llmrouter env so the child resolves its
+     * model identically to this (host) process. This lets Solo run N independent qlogicagent sessions
+     * in parallel (each its own worktree) — the core "多个 qlogicagent = 多会话并行" use case.
+     */
+    buildSelfDescriptor() {
+        const PASSTHROUGH_ENV = [
+            "QLOGIC_LLMROUTER_USER_ID", // ← resolveActiveOwnerUserId() priority 1
+            "QLOGIC_IMPLICIT_OWNER_ID", // ← priority 2 (owner profile → same settings.json keys)
+            "QLOGIC_DEVICE_ID", // ← priority 3 (oc_<deviceId>)
+            "QLOGICAGENT_HOME", // base dot-dir
+            "QLOGIC_LLMROUTER_BASE_URL",
+            "QLOGIC_LLMROUTER_ACCESS_TOKEN",
+        ];
+        const env = {};
+        for (const k of PASSTHROUGH_ENV) {
+            const v = process.env[k];
+            if (v)
+                env[k] = v;
+        }
+        return {
+            id: "qlogicagent",
+            cliPath: process.execPath,
+            acpArgs: [process.argv[1] ?? ""],
+            env: Object.keys(env).length > 0 ? env : undefined,
+            protocol: "acp",
+        };
+    }
+    /**
+     * Build an ExternalAgentDescriptor suitable for AgentProcessManager.spawn().
+     * Returns null if the agent is not available.
+     */
+    buildExternalDescriptor(agentId) {
+        // qlogicagent participates as a self-hosted ACP agent (not an installed external CLI).
+        if (agentId === "qlogicagent") {
+            return this.buildSelfDescriptor();
+        }
+        const desc = this.list().find((a) => a.id === agentId);
+        if (!desc || desc.protocol !== "acp" || desc.status !== "available" || !desc.cliPath) {
+            return null;
+        }
+        // Use the merged catalog entry (base + keySource/authMode/env) so login-free
+        // injection knows how to source the key.
+        const backend = getCatalogEntry(agentId) ?? ACP_BACKENDS[agentId];
+        const customConfig = this.configStore?.agents[agentId];
+        const command = customConfig?.customCliPath
+            ? { cliPath: customConfig.customCliPath, acpArgs: customConfig?.customArgs ?? backend?.acpArgs ?? [] }
+            : normalizeWindowsAcpCommand(desc.cliPath, customConfig?.customArgs ?? backend?.acpArgs ?? []);
+        const autoEnv = resolveCatalogKeyEnv(backend, this.keySources);
+        const acpArgs = customConfig?.customArgs?.length
+            ? command.acpArgs
+            : appendLlmrouterAcpArgs(backend, command.acpArgs, autoEnv, this.keySources);
+        return {
+            id: agentId,
+            cliPath: command.cliPath,
+            acpArgs,
+            env: buildBackendEnv(backend, customConfig, autoEnv),
+            protocol: "acp",
+        };
+    }
+    /**
+     * Whether an agent is ready to compete in Solo/Product: installed/available AND configured.
+     * qlogicagent self-resolves from the owner profile (always ready). External agents need a usable
+     * ACP descriptor (installed) and, for key-auth backends, the key env resolved (configured by the
+     * user on the welcome page). Used by the 启动 pre-check so a race never starts with an agent that
+     * would fail its turn ("No LLM provider"/auth). Does NOT verify the key is *valid* — that's only
+     * known at runtime.
+     */
+    isAgentReady(agentId) {
+        if (agentId === "qlogicagent")
+            return true;
+        const desc = this.buildExternalDescriptor(agentId);
+        if (!desc)
+            return false; // not installed / not ACP-available
+        const backend = getCatalogEntry(agentId) ?? ACP_BACKENDS[agentId];
+        // Key-auth backend (non-oauth) must have its key env resolved (login-free inject or user config).
+        if (backend?.apiKeyEnvVar && backend.authMode !== "oauth") {
+            return !!desc.env?.[backend.apiKeyEnvVar];
+        }
+        return true; // oauth/keyless backend — installed is enough
+    }
+}