qlogicagent 2.13.3 → 2.13.5

package/dist/runtime/infra/acp-usage-tracker.js

@@ -0,0 +1,92 @@
+/**
+ * ACP Usage Tracker — 3-tier token usage tracking for external ACP agents.
+ *
+ * Tier 1: Real-time `usage_update` notifications (preferred).
+ * Tier 2: Per-turn `PromptResponse.usage` fallback.
+ * Tier 3: Graceful degradation — no usage data, no budget enforcement.
+ *
+ * The tracker prevents double-counting when an agent sends both
+ * usage_update notifications AND prompt response usage.
+ */
+// ── AcpUsageTracker ─────────────────────────────────────────
+export class AcpUsageTracker {
+    usage = {
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        cachedReadTokens: 0,
+        thoughtTokens: 0,
+        cost: 0,
+        hasTier1: false,
+        turnCount: 0,
+    };
+    /**
+     * Tier 1: Handle a `usage_update` notification from ACP agent.
+     * Sets the hasTier1 flag to prevent double-counting from Tier 2.
+     */
+    onUsageUpdate(payload) {
+        this.usage.hasTier1 = true;
+        if (typeof payload.inputTokens === "number") {
+            this.usage.inputTokens += payload.inputTokens;
+        }
+        if (typeof payload.outputTokens === "number") {
+            this.usage.outputTokens += payload.outputTokens;
+        }
+        if (typeof payload.totalTokens === "number") {
+            this.usage.totalTokens += payload.totalTokens;
+        }
+        if (typeof payload.cost === "number") {
+            this.usage.cost += payload.cost;
+        }
+    }
+    /**
+     * Tier 2: Handle per-turn usage from PromptResponse.
+     * Only applied if Tier 1 is NOT active (prevents double-counting).
+     */
+    onPromptResponseUsage(usage) {
+        if (!usage)
+            return; // Tier 3: no data, graceful degradation
+        if (this.usage.hasTier1)
+            return; // Tier 1 active, skip Tier 2
+        this.usage.turnCount++;
+        if (typeof usage.inputTokens === "number") {
+            this.usage.inputTokens += usage.inputTokens;
+        }
+        if (typeof usage.outputTokens === "number") {
+            this.usage.outputTokens += usage.outputTokens;
+        }
+        if (typeof usage.totalTokens === "number") {
+            this.usage.totalTokens += usage.totalTokens;
+        }
+        if (typeof usage.cachedReadTokens === "number") {
+            this.usage.cachedReadTokens += usage.cachedReadTokens;
+        }
+        if (typeof usage.thoughtTokens === "number") {
+            this.usage.thoughtTokens += usage.thoughtTokens;
+        }
+    }
+    /** Get the current accumulated usage snapshot. */
+    getUsage() {
+        return { ...this.usage };
+    }
+    /** Reset all counters. */
+    reset() {
+        this.usage = {
+            inputTokens: 0,
+            outputTokens: 0,
+            totalTokens: 0,
+            cachedReadTokens: 0,
+            thoughtTokens: 0,
+            cost: 0,
+            hasTier1: false,
+            turnCount: 0,
+        };
+    }
+    /**
+     * Check whether we have any usage data.
+     * Returns false in Tier 3 (graceful degradation).
+     */
+    hasData() {
+        return this.usage.hasTier1 || this.usage.turnCount > 0;
+    }
+}

package/dist/runtime/infra/agent-catalog.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/infra/agent-catalog.test.js

@@ -0,0 +1,174 @@
+import { describe, expect, it } from "vitest";
+import { getAgentCatalog, AGENT_CATALOG_IDS, compareSemverVersions, getNpmInstallPackageName, isVersionNewer, } from "./acp-detector.js";
+describe("agent catalog (Discover-Agent manifest)", () => {
+    const catalog = getAgentCatalog();
+    it("returns the 13 curated agents in order", () => {
+        expect(catalog).toHaveLength(13);
+        expect(catalog.map((e) => e.id)).toEqual([...AGENT_CATALOG_IDS]);
+    });
+    it("every entry carries the grid metadata", () => {
+        for (const e of catalog) {
+            expect(e.name, e.id).toBeTruthy();
+            expect(e.brandId, e.id).toBeTruthy();
+            expect(["coding", "writing", "design", "creative", "research", "assistant"], e.id).toContain(e.category);
+            expect(["acp", "custom"], e.id).toContain(e.integration);
+            expect(["key", "oauth"], e.id).toContain(e.authMode);
+        }
+    });
+    it("every entry has an installable spec (command name + source + ≥1 platform command)", () => {
+        for (const e of catalog) {
+            const install = e.install;
+            expect(install, e.id).toBeTruthy();
+            expect(install.cliCommand, e.id).toBeTruthy();
+            expect(install.docsUrl, e.id).toMatch(/^https?:\/\//);
+            // at least one install channel, OR docsUrl-only for manual (kiro has no scripted command yet)
+            const channels = [install.npm, install.brew, install.curl, install.pip].filter(Boolean);
+            expect(channels.length >= 1 || !!install.docsUrl, e.id).toBe(true);
+        }
+    });
+    it("OAuth agents inject no key (keySource none); key agents have a source", () => {
+        for (const e of catalog) {
+            if (e.authMode === "oauth") {
+                expect(e.keySource, e.id).toBe("none");
+            }
+            else {
+                expect(e.keySource, e.id).not.toBe("none");
+            }
+        }
+    });
+    it("every curated agent is ACP (no non-ACP custom entries)", () => {
+        expect(catalog.every((e) => e.integration === "acp")).toBe(true);
+        expect(catalog.filter((e) => e.integration === "acp").length).toBe(13);
+    });
+    it("the 助理 (assistant) category holds openclaw + hermes (personal desktop ACP agents)", () => {
+        const assistants = catalog.filter((e) => e.category === "assistant").map((e) => e.id);
+        expect(assistants).toEqual(["openclaw", "hermes"]);
+        const openclaw = catalog.find((e) => e.id === "openclaw");
+        expect(openclaw.integration).toBe("acp");
+        expect(openclaw.install.npm).toContain("openclaw");
+        const hermes = catalog.find((e) => e.id === "hermes");
+        expect(hermes.integration).toBe("acp");
+        expect(hermes.install.pip).toContain("hermes-agent");
+    });
+});
+// Locks in the corrections verified against the npm/PyPI registry in T7 — regressing any of
+// these silently breaks detection (wrong binary) or login-free injection (wrong env var).
+describe("agent catalog — T7 registry-verified facts", () => {
+    const byId = (id) => getAgentCatalog().find((e) => e.id === id);
+    it("qwen detects the real `qwen` binary (npm bin is qwen, not qwen-code)", () => {
+        const qwen = byId("qwen");
+        expect(qwen.cliCommand).toBe("qwen");
+        expect(qwen.install.cliCommand).toBe("qwen");
+        expect(qwen.install.npm).toContain("@qwen-code/qwen-code");
+    });
+    it("glm uses the Z_AI_API_KEY env var and the stefandevo repo", () => {
+        const glm = byId("glm");
+        expect(glm.apiKeyEnvVar).toBe("Z_AI_API_KEY");
+        expect(glm.install.docsUrl).toContain("stefandevo/glm-acp-agent");
+    });
+    it("kimi installs from PyPI (uv/pip), not npm, and authenticates via Kimi account (kimi login), not an env key", () => {
+        const kimi = byId("kimi");
+        expect(kimi.install.npm).toBeUndefined();
+        expect(kimi.install.pip).toMatch(/kimi-cli/);
+        // kimi-cli uses an OAuth `kimi login` flow, not MOONSHOT_API_KEY — so no injectable key env.
+        expect(kimi.authMode).toBe("oauth");
+        expect(kimi.keySource).toBe("none");
+        expect(kimi.apiKeyEnvVar).toBeFalsy();
+    });
+    // Login-free injection only fires when an entry declares apiKeyEnvVar (resolveCatalogKeyEnv).
+    // This locks the set we verified end-to-end; agents without one fall back to the per-agent
+    // settings panel (multi-provider/unverified: opencode/kiro/qoder). See NOTE(T7).
+    it("ACP install provides the binary detection looks for (install.cliCommand === cliCommand)", () => {
+        // Catches the bug class where install fetches package A (binary X) but the detector scans for
+        // binary Y, so a freshly-installed agent is never detected. e.g. codex must install
+        // @zed-industries/codex-acp (bin codex-acp), the official Zed ACP adapter — not @openai/codex.
+        for (const e of getAgentCatalog()) {
+            if (e.integration !== "acp")
+                continue;
+            if (!e.install?.cliCommand)
+                continue;
+            expect(e.install.cliCommand, e.id).toBe(e.cliCommand);
+        }
+    });
+    it("codex uses the official Zed ACP adapter (@zed-industries/codex-acp)", () => {
+        const codex = getAgentCatalog().find((e) => e.id === "codex");
+        expect(codex.cliCommand).toBe("codex-acp");
+        expect(codex.install.npm).toContain("@zed-industries/codex-acp");
+    });
+    it("codex enables interactive approval (approval_policy=untrusted, not never)", () => {
+        // Now that the reverse-RPC permission flow can answer codex's request_permission, we let codex
+        // ask before high-risk steps instead of auto-running everything. sandbox_mode stays full-access
+        // (the Windows sandbox hangs otherwise); under full-access 'on-request' never escalates, so
+        // 'untrusted' (ask before every non-trusted command) is the only policy that surfaces a card.
+        const codex = getAgentCatalog().find((e) => e.id === "codex");
+        const args = codex.acpArgs.join(" ");
+        expect(args).toContain("approval_policy=untrusted");
+        expect(args).not.toContain("approval_policy=never");
+        expect(args).toContain("sandbox_mode=danger-full-access");
+    });
+    it("助理 agents use their real ACP entry: hermes via `hermes acp` (PyPI [acp] extra + Python<3.14), openclaw via the Gateway-backed `acp` bridge", () => {
+        // Both were verified by a real-machine ACP handshake. hermes: NousResearch Hermes speaks
+        // standard ACP via `hermes acp`, but the base PyPI package omits the ACP adapter deps (needs
+        // the [acp] extra) and requires-python is "<3.14,>=3.11" (so pin Python). The npm `hermes-agent`
+        // wrapper pip-installs onto the default Python → fails on 3.14, hence pip (uv), not npm.
+        const hermes = byId("hermes");
+        expect(hermes.acpArgs).toEqual(["acp"]);
+        expect(hermes.install.npm).toBeUndefined();
+        expect(hermes.install.pip).toContain("hermes-agent[acp]");
+        expect(hermes.install.pip).toContain("--python 3.13");
+        expect(hermes.authMode).toBe("oauth");
+        expect(hermes.keySource).toBe("none");
+        // openclaw: a host platform whose bare `acp` command is the Gateway-backed ACP bridge — there
+        // is no `serve`/`--acp` subcommand. It needs a running openclaw Gateway + valid config.
+        const openclaw = byId("openclaw");
+        expect(openclaw.acpArgs).toEqual(["acp"]);
+        expect(openclaw.acpArgs).not.toContain("--acp");
+    });
+    it("claude uses the canonical claude-agent-acp scope (@agentclientprotocol, not the deprecated @zed-industries)", () => {
+        // claude-agent-acp (Claude Agent SDK) succeeded claude-code-acp (Claude Code SDK), and then the
+        // package itself was renamed @zed-industries/claude-agent-acp → @agentclientprotocol/claude-agent-acp
+        // (the old scope is npm-deprecated). Stay on the maintained scope so installs keep getting updates.
+        const claude = getAgentCatalog().find((e) => e.id === "claude");
+        expect(claude.cliCommand).toBe("claude-agent-acp");
+        expect(claude.install.npm).toContain("@agentclientprotocol/claude-agent-acp");
+        expect(claude.install.npm).not.toContain("@zed-industries");
+        expect(claude.install.docsUrl).toContain("agentclientprotocol/claude-agent-acp");
+    });
+    it("codex verifies installation with help because codex-acp exposes no version flag", () => {
+        const codex = getAgentCatalog().find((e) => e.id === "codex");
+        expect(codex.install.verifyCmd).toBe("codex-acp --help");
+    });
+    it("gemini gates ACP behind --experimental-acp (the flag the gemini binary actually accepts)", () => {
+        const gemini = getAgentCatalog().find((e) => e.id === "gemini");
+        expect(gemini.acpArgs).toContain("--experimental-acp");
+        expect(gemini.acpArgs).not.toContain("--acp");
+    });
+    it("the verified login-free set declares a single-key env var; OAuth agents declare none", () => {
+        const injectable = new Set(["claude", "codex", "gemini", "qwen", "glm"]);
+        for (const e of getAgentCatalog()) {
+            if (injectable.has(e.id)) {
+                expect(e.apiKeyEnvVar, e.id).toBeTruthy();
+                expect(e.authMode, e.id).toBe("key");
+                expect(e.keySource, e.id).not.toBe("none");
+            }
+            if (e.authMode === "oauth") {
+                expect(e.apiKeyEnvVar, e.id).toBeFalsy();
+                expect(e.keySource, e.id).toBe("none");
+            }
+        }
+    });
+});
+describe("agent catalog npm version helpers", () => {
+    it("extracts npm package names from global install commands", () => {
+        expect(getNpmInstallPackageName("npm i -g @zed-industries/codex-acp")).toBe("@zed-industries/codex-acp");
+        expect(getNpmInstallPackageName("npm install --global opencode-ai --registry https://x")).toBe("opencode-ai");
+        expect(getNpmInstallPackageName("npm i -g pkg@1.2.3")).toBe("pkg");
+        expect(getNpmInstallPackageName("uv tool install kimi-cli")).toBeNull();
+    });
+    it("compares semver values for update badges", () => {
+        expect(compareSemverVersions("0.16.1", "0.16.0")).toBeGreaterThan(0);
+        expect(compareSemverVersions("1.0.0", "1.0.0-beta.1")).toBeGreaterThan(0);
+        expect(isVersionNewer("0.16.1", "0.16.0")).toBe(true);
+        expect(isVersionNewer("0.16.0", "0.16.1")).toBe(false);
+    });
+});

package/dist/runtime/infra/agent-config-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Agent Config Store — persistent per-agent configuration with project + global fallback.
+ *
+ * Storage paths:
+ *   - Project-level: `<cwd>/.qlogicagent/agent-configs.json`
+ *   - User-level:    `~/.qlogicagent/profiles/<owner>/agent-configs.json`
+ *
+ * Merge strategy: project-level overrides take precedence.
+ * Sensitive fields (apiKey) use file permissions 0o600 on Unix.
+ */
+import type { AgentConfig, AgentConfigStoreData, CustomAgentDef } from "../../protocol/wire/acp-agent-management.js";
+export declare class AgentConfigStore {
+    private data;
+    private cwd;
+    constructor(cwd?: string);
+    /** Load config from disk. Project-level merges on top of user-level. */
+    load(): Promise<void>;
+    /** Get the full store data (for AcpDetector.setConfigStore). */
+    getData(): AgentConfigStoreData;
+    getAgentConfig(agentId: string): AgentConfig | null;
+    setAgentConfig(agentId: string, config: AgentConfig): Promise<void>;
+    removeAgentConfig(agentId: string): Promise<void>;
+    getGatewayUrl(): string | undefined;
+    setGatewayUrl(url: string): Promise<void>;
+    registerCustomAgent(def: CustomAgentDef): Promise<void>;
+    unregisterCustomAgent(agentId: string): Promise<void>;
+    getCustomAgents(): Record<string, CustomAgentDef>;
+    /** Save to user-level config. Restricts permissions for sensitive data. */
+    private save;
+}

package/dist/runtime/infra/agent-config-store.js

@@ -0,0 +1,115 @@
+/**
+ * Agent Config Store — persistent per-agent configuration with project + global fallback.
+ *
+ * Storage paths:
+ *   - Project-level: `<cwd>/.qlogicagent/agent-configs.json`
+ *   - User-level:    `~/.qlogicagent/profiles/<owner>/agent-configs.json`
+ *
+ * Merge strategy: project-level overrides take precedence.
+ * Sensitive fields (apiKey) use file permissions 0o600 on Unix.
+ */
+import { join } from "node:path";
+import { chmod } from "node:fs/promises";
+import { getOwnerProfileDir, getProjectAgentDir } from "./agent-paths.js";
+import { readJsonFile, writeJsonFile } from "./disk-storage.js";
+// ── Config File Name ────────────────────────────────────────
+const CONFIG_FILENAME = "agent-configs.json";
+function getUserConfigPath() {
+    return join(getOwnerProfileDir(), CONFIG_FILENAME);
+}
+function getProjectConfigPath(cwd) {
+    return join(getProjectAgentDir(cwd), CONFIG_FILENAME);
+}
+// ── Default Empty Store ─────────────────────────────────────
+function createEmptyStore() {
+    return { agents: {} };
+}
+// ── AgentConfigStore ────────────────────────────────────────
+export class AgentConfigStore {
+    data = createEmptyStore();
+    cwd;
+    constructor(cwd) {
+        this.cwd = cwd;
+    }
+    /** Load config from disk. Project-level merges on top of user-level. */
+    async load() {
+        const userStore = await readJsonFile(getUserConfigPath());
+        const projStore = this.cwd
+            ? await readJsonFile(getProjectConfigPath(this.cwd))
+            : undefined;
+        // Start with user-level
+        const merged = {
+            gatewayUrl: userStore?.gatewayUrl,
+            agents: { ...userStore?.agents },
+            customAgents: { ...userStore?.customAgents },
+        };
+        // Project-level overrides
+        if (projStore) {
+            if (projStore.gatewayUrl)
+                merged.gatewayUrl = projStore.gatewayUrl;
+            for (const [id, cfg] of Object.entries(projStore.agents ?? {})) {
+                merged.agents[id] = { ...merged.agents[id], ...cfg };
+            }
+            for (const [id, def] of Object.entries(projStore.customAgents ?? {})) {
+                merged.customAgents ??= {};
+                merged.customAgents[id] = def;
+            }
+        }
+        this.data = merged;
+    }
+    /** Get the full store data (for AcpDetector.setConfigStore). */
+    getData() {
+        return this.data;
+    }
+    // ── Per-agent Config ──────────────────────────────────────
+    getAgentConfig(agentId) {
+        return this.data.agents[agentId] ?? null;
+    }
+    async setAgentConfig(agentId, config) {
+        this.data.agents[agentId] = {
+            ...this.data.agents[agentId],
+            ...config,
+        };
+        await this.save();
+    }
+    async removeAgentConfig(agentId) {
+        delete this.data.agents[agentId];
+        await this.save();
+    }
+    // ── Gateway URL ───────────────────────────────────────────
+    getGatewayUrl() {
+        return this.data.gatewayUrl;
+    }
+    async setGatewayUrl(url) {
+        this.data.gatewayUrl = url;
+        await this.save();
+    }
+    // ── Custom Agents ─────────────────────────────────────────
+    async registerCustomAgent(def) {
+        this.data.customAgents ??= {};
+        this.data.customAgents[def.id] = def;
+        await this.save();
+    }
+    async unregisterCustomAgent(agentId) {
+        if (this.data.customAgents) {
+            delete this.data.customAgents[agentId];
+            await this.save();
+        }
+    }
+    getCustomAgents() {
+        return { ...this.data.customAgents };
+    }
+    // ── Persistence ───────────────────────────────────────────
+    /** Save to user-level config. Restricts permissions for sensitive data. */
+    async save() {
+        const filePath = getUserConfigPath();
+        await writeJsonFile(filePath, this.data);
+        // Restrict permissions on Unix (API keys are sensitive)
+        try {
+            await chmod(filePath, 0o600);
+        }
+        catch {
+            // Windows doesn't support chmod — acceptable
+        }
+    }
+}

package/dist/runtime/infra/agent-install-runner.d.ts

@@ -0,0 +1,57 @@
+import type { AgentInstallSpec } from "../../protocol/wire/acp-agent-management.js";
+export type InstallEvent = {
+    type: "state";
+    state: "installing" | "verifying" | "installed" | "failed";
+} | {
+    type: "log";
+    stream: "stdout" | "stderr";
+    chunk: string;
+} | {
+    type: "done";
+    ok: boolean;
+    error?: string;
+};
+/** A child process shaped like node's, so tests can inject a fake. */
+export interface InstallProc {
+    stdout?: {
+        on(ev: "data", cb: (c: Buffer | string) => void): void;
+    } | null;
+    stderr?: {
+        on(ev: "data", cb: (c: Buffer | string) => void): void;
+    } | null;
+    on(ev: "close", cb: (code: number | null) => void): void;
+    on(ev: "error", cb: (err: Error) => void): void;
+}
+export type InstallSpawn = (command: string, shell: boolean) => InstallProc;
+/**
+ * Choose the best official install command for the current platform.
+ * Preference: brew (macOS only) → npm → pip → curl (POSIX shell only). Returns the raw
+ * command + whether it must run through a shell (curl pipelines / shell metachars).
+ */
+export declare function pickInstallCommand(install: AgentInstallSpec, platform: NodeJS.Platform): {
+    command: string;
+    shell: boolean;
+} | null;
+/**
+ * Inject a package-registry mirror into an install command, for users behind slow or blocked public
+ * registries (e.g. PyPI / npm from mainland China, where the default index frequently times out).
+ *
+ * Opt-in via `mirror`: "cn" applies curated China mirrors per package manager; off (undefined) by
+ * default so other users are unaffected. Only rewrites a command that hasn't already pinned a
+ * registry/index, and never touches brew/curl. Returns the command unchanged when not applicable.
+ */
+export declare function applyInstallMirror(command: string, mirror: string | undefined): string;
+/** Default spawner: split into argv (or run via shell for pipelines). */
+export declare const defaultInstallSpawn: InstallSpawn;
+/**
+ * Run an install spec end-to-end, streaming progress via onEvent. Emits state →
+ * log(s) → (verify) → done. Resolves with the final outcome.
+ */
+export declare function runAgentInstall(install: AgentInstallSpec, onEvent: (e: InstallEvent) => void, opts?: {
+    platform?: NodeJS.Platform;
+    spawnImpl?: InstallSpawn;
+    mirror?: string;
+}): Promise<{
+    ok: boolean;
+    error?: string;
+}>;

package/dist/runtime/infra/agent-install-runner.js

@@ -0,0 +1,123 @@
+/**
+ * One-click agent installer.
+ *
+ * SECURITY: the only commands ever run are the official install commands declared in a
+ * catalog entry's AgentInstallSpec (npm/brew/curl/pip). Callers pass a catalog entry
+ * (resolved by agentId) — never a free-form command — so there is no injection vector.
+ * The command + source are shown to the user for confirmation before this runs.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+const SHELL_META = /[|&;><$`(){}]/;
+/**
+ * Choose the best official install command for the current platform.
+ * Preference: brew (macOS only) → npm → pip → curl (POSIX shell only). Returns the raw
+ * command + whether it must run through a shell (curl pipelines / shell metachars).
+ */
+export function pickInstallCommand(install, platform) {
+    const isWin = platform === "win32";
+    const isMac = platform === "darwin";
+    const candidates = isMac
+        ? [install.brew, install.npm, install.pip, install.curl]
+        : [install.npm, install.pip, install.brew, install.curl];
+    for (const raw of candidates) {
+        if (!raw)
+            continue;
+        const shell = SHELL_META.test(raw);
+        // curl|bash style scripts need a POSIX shell — skip on Windows.
+        if (shell && isWin)
+            continue;
+        // brew only exists on macOS.
+        if (raw.startsWith("brew ") && !isMac)
+            continue;
+        return { command: raw, shell };
+    }
+    return null;
+}
+/**
+ * Inject a package-registry mirror into an install command, for users behind slow or blocked public
+ * registries (e.g. PyPI / npm from mainland China, where the default index frequently times out).
+ *
+ * Opt-in via `mirror`: "cn" applies curated China mirrors per package manager; off (undefined) by
+ * default so other users are unaffected. Only rewrites a command that hasn't already pinned a
+ * registry/index, and never touches brew/curl. Returns the command unchanged when not applicable.
+ */
+export function applyInstallMirror(command, mirror) {
+    if (mirror !== "cn")
+        return command;
+    const c = command.trim();
+    if (/^npm\b/.test(c) && !/(?:^|\s)--registry(?:\s|=)/.test(c)) {
+        return `${c} --registry https://registry.npmmirror.com`;
+    }
+    if (/^uv\b/.test(c) && !/(?:^|\s)--(?:default-)?index(?:-url)?(?:\s|=)/.test(c)) {
+        return `${c} --default-index https://pypi.tuna.tsinghua.edu.cn/simple`;
+    }
+    if (/^(?:pipx|pip3?|python -m pip)\b/.test(c) && !/(?:^|\s)--index-url(?:\s|=)/.test(c)) {
+        return `${c} --index-url https://pypi.tuna.tsinghua.edu.cn/simple`;
+    }
+    return c;
+}
+function runOne(command, shell, spawnImpl, onEvent) {
+    return new Promise((resolve) => {
+        let proc;
+        try {
+            proc = spawnImpl(command, shell);
+        }
+        catch (err) {
+            onEvent({ type: "log", stream: "stderr", chunk: err instanceof Error ? err.message : String(err) });
+            resolve(1);
+            return;
+        }
+        proc.stdout?.on("data", (c) => onEvent({ type: "log", stream: "stdout", chunk: c.toString() }));
+        proc.stderr?.on("data", (c) => onEvent({ type: "log", stream: "stderr", chunk: c.toString() }));
+        proc.on("error", (err) => {
+            onEvent({ type: "log", stream: "stderr", chunk: err.message });
+            resolve(1);
+        });
+        proc.on("close", (code) => resolve(code));
+    });
+}
+/** Default spawner: split into argv (or run via shell for pipelines). */
+export const defaultInstallSpawn = (command, shell) => {
+    if (shell) {
+        return nodeSpawn(command, { shell: true, stdio: ["ignore", "pipe", "pipe"] });
+    }
+    const parts = command.split(/\s+/).filter(Boolean);
+    return nodeSpawn(parts[0], parts.slice(1), { stdio: ["ignore", "pipe", "pipe"] });
+};
+/**
+ * Run an install spec end-to-end, streaming progress via onEvent. Emits state →
+ * log(s) → (verify) → done. Resolves with the final outcome.
+ */
+export async function runAgentInstall(install, onEvent, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const spawnImpl = opts.spawnImpl ?? defaultInstallSpawn;
+    const picked = pickInstallCommand(install, platform);
+    if (!picked) {
+        const error = `No install command available for ${platform}`;
+        onEvent({ type: "state", state: "failed" });
+        onEvent({ type: "done", ok: false, error });
+        return { ok: false, error };
+    }
+    const command = applyInstallMirror(picked.command, opts.mirror);
+    onEvent({ type: "state", state: "installing" });
+    const code = await runOne(command, picked.shell, spawnImpl, onEvent);
+    if (code !== 0) {
+        const error = `Install command exited with code ${code}`;
+        onEvent({ type: "state", state: "failed" });
+        onEvent({ type: "done", ok: false, error });
+        return { ok: false, error };
+    }
+    // Verify the CLI is now runnable.
+    const verify = install.verifyCmd ?? `${install.cliCommand} --version`;
+    onEvent({ type: "state", state: "verifying" });
+    const verifyCode = await runOne(verify, SHELL_META.test(verify), spawnImpl, onEvent);
+    if (verifyCode !== 0) {
+        const error = `Installed but verification failed (${install.cliCommand})`;
+        onEvent({ type: "state", state: "failed" });
+        onEvent({ type: "done", ok: false, error });
+        return { ok: false, error };
+    }
+    onEvent({ type: "state", state: "installed" });
+    onEvent({ type: "done", ok: true });
+    return { ok: true };
+}

package/dist/runtime/infra/agent-install-runner.test.d.ts

@@ -0,0 +1 @@
+export {};