qlogicagent 2.13.4 → 2.13.5

package/dist/runtime/infra/external-agent-pool.d.ts

@@ -0,0 +1,54 @@
+/**
+ * External-agent process pool (A).
+ *
+ * Keeps spawned external ACP agents (Codex/Claude/etc.) alive and reuses them across chat turns,
+ * instead of the spawn → one turn → kill cycle that paid a full ACP cold-start (several seconds)
+ * on every message. Reuse also gives external agents real multi-turn memory (same ACP session).
+ *
+ * Design (mirrors how VSCode keeps language-server-style agent CLIs resident):
+ *  - One AgentProcessManager + one spawned member per pool key (agentId + cwd + sessionId).
+ *  - The first turn spawns + registers; subsequent turns reuse the live member (sendTask only).
+ *  - A mutable `holder.current` carries the *current* turn's identity so the manager's
+ *    construction-time onNotification can tag live deltas with the right turn (see agents-handler).
+ *  - Idle entries are reaped after IDLE_TTL_MS; the pool is bounded to MAX_POOL by LRU eviction.
+ *  - Busy entries (a turn in flight) are never evicted.
+ */
+import type { AgentProcessManager } from "./agent-process.js";
+/** Mutable per-turn context read by the pooled manager's onNotification callback. */
+export interface PooledTurnCtx {
+    sessionId?: string;
+    turnId?: string;
+    requestId?: string;
+    deltas: string[];
+    streamedAny: boolean;
+}
+export interface PooledAgentEntry {
+    manager: AgentProcessManager;
+    memberId: string;
+    /** Boxed so the manager's onNotification (built before registration) can read the live turn. */
+    holder: {
+        current: PooledTurnCtx | null;
+    };
+    lastUsed: number;
+}
+/** Pool key: same agent + workspace + session ⇒ same resident process (and shared memory). */
+export declare function poolKey(agentId: string, cwd: string, sessionId?: string): string;
+/** Return a live pooled entry for the key, or undefined (evicting a dead one if found). */
+export declare function getAlivePooledAgent(key: string): PooledAgentEntry | undefined;
+/** Register a freshly-spawned entry, evicting any stale same-key entry and enforcing MAX_POOL. */
+export declare function registerPooledAgent(key: string, entry: PooledAgentEntry): void;
+/**
+ * Re-key a pre-warmed entry (spawned before a session existed, under WARM_SESSION) onto the real
+ * session key, so the first turn adopts the warmed process and skips the cold start. Does not
+ * dispose — the same live process is moved. Returns undefined if no live warmed entry exists.
+ */
+export declare function adoptWarmedAgent(warmKey: string, sessionKey: string): PooledAgentEntry | undefined;
+/** Reserved session token for a process pre-warmed before its real session id is known. */
+export declare const WARM_SESSION = "__warm__";
+/** Drop + dispose a single entry (e.g. after a turn errors and the process is suspect). */
+export declare function evictPooledAgent(key: string): void;
+/** Kill + dispose every pooled agent and stop the reaper. Call on agent shutdown. */
+export declare function disposeAllPooledAgents(): void;
+export declare function pooledAgentCount(): number;
+/** Reap idle (non-busy) entries past the TTL. Exposed for deterministic testing. */
+export declare function reapIdlePooledAgents(now: number): void;

package/dist/runtime/infra/external-agent-pool.test.d.ts

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

package/dist/runtime/infra/external-agent-pool.test.js

@@ -0,0 +1,102 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { adoptWarmedAgent, disposeAllPooledAgents, getAlivePooledAgent, poolKey, pooledAgentCount, reapIdlePooledAgents, registerPooledAgent, } from "./external-agent-pool.js";
+// Minimal fake AgentProcessManager — only the methods the pool touches.
+function fakeManager(alive = true) {
+    return {
+        alive,
+        kill: vi.fn(),
+        dispose: vi.fn(),
+        isAlive: vi.fn(function () { return this.alive; }),
+    };
+}
+function entry(memberId, alive = true, lastUsed = 1000) {
+    const manager = fakeManager(alive);
+    return {
+        manager: manager,
+        memberId,
+        holder: { current: null },
+        lastUsed,
+    };
+}
+afterEach(() => {
+    disposeAllPooledAgents();
+});
+describe("external-agent-pool", () => {
+    it("poolKey separates by agent + workspace + session", () => {
+        expect(poolKey("codex", "/a", "s1")).not.toBe(poolKey("codex", "/a", "s2"));
+        expect(poolKey("codex", "/a", "s1")).not.toBe(poolKey("claude", "/a", "s1"));
+        expect(poolKey("codex", "/a")).toBe(poolKey("codex", "/a", "default"));
+    });
+    it("register + getAlive returns the same live entry (reuse)", () => {
+        const e = entry("m1");
+        registerPooledAgent("k", e);
+        expect(getAlivePooledAgent("k")).toBe(e);
+        expect(pooledAgentCount()).toBe(1);
+    });
+    it("getAlive evicts and disposes a dead entry", () => {
+        const e = entry("m1", false);
+        registerPooledAgent("k", e);
+        expect(getAlivePooledAgent("k")).toBeUndefined();
+        expect(e.manager.kill).toHaveBeenCalledWith("m1");
+        expect(e.manager.dispose).toHaveBeenCalled();
+        expect(pooledAgentCount()).toBe(0);
+    });
+    it("re-registering the same key disposes the previous entry", () => {
+        const a = entry("m1");
+        const b = entry("m2");
+        registerPooledAgent("k", a);
+        registerPooledAgent("k", b);
+        expect(a.manager.kill).toHaveBeenCalled();
+        expect(getAlivePooledAgent("k")).toBe(b);
+    });
+    it("reapIdle disposes idle entries but spares busy ones", () => {
+        const idle = entry("idle", true, 0);
+        const busy = entry("busy", true, 0);
+        busy.holder.current = { deltas: [], streamedAny: false };
+        registerPooledAgent("idle", idle);
+        registerPooledAgent("busy", busy);
+        reapIdlePooledAgents(IDLE_PAST);
+        expect(idle.manager.kill).toHaveBeenCalled();
+        expect(busy.manager.kill).not.toHaveBeenCalled();
+        expect(pooledAgentCount()).toBe(1);
+    });
+    it("enforces the max pool size by evicting the LRU idle entry", () => {
+        // MAX_POOL is 6 → registering a 7th evicts the least-recently-used.
+        const entries = [];
+        for (let i = 0; i < 7; i++) {
+            const e = entry(`m${i}`, true, i); // lastUsed ascending; m0 is LRU
+            entries.push(e);
+            registerPooledAgent(`k${i}`, e);
+        }
+        expect(pooledAgentCount()).toBe(6);
+        expect(entries[0].manager.kill).toHaveBeenCalled(); // LRU evicted
+        expect(getAlivePooledAgent("k0")).toBeUndefined();
+        expect(getAlivePooledAgent("k6")).toBe(entries[6]);
+    });
+    it("adoptWarmedAgent re-keys a live warmed entry onto the session key (warm → first-turn handoff)", () => {
+        const warm = entry("warm-m", true, 0);
+        registerPooledAgent("codex /w __warm__", warm);
+        const adopted = adoptWarmedAgent("codex /w __warm__", "codex /w s1");
+        expect(adopted).toBe(warm);
+        expect(getAlivePooledAgent("codex /w s1")).toBe(warm); // moved to the session key
+        expect(getAlivePooledAgent("codex /w __warm__")).toBeUndefined(); // warm key cleared
+        expect(warm.manager.kill).not.toHaveBeenCalled(); // same live process, not disposed
+    });
+    it("adoptWarmedAgent disposes + returns undefined when the warmed process already died", () => {
+        const dead = entry("dead", false, 0);
+        registerPooledAgent("k __warm__", dead);
+        expect(adoptWarmedAgent("k __warm__", "k s1")).toBeUndefined();
+        expect(dead.manager.kill).toHaveBeenCalled();
+    });
+    it("disposeAll kills everything and resets the pool", () => {
+        const a = entry("m1");
+        const b = entry("m2");
+        registerPooledAgent("k1", a);
+        registerPooledAgent("k2", b);
+        disposeAllPooledAgents();
+        expect(a.manager.dispose).toHaveBeenCalled();
+        expect(b.manager.dispose).toHaveBeenCalled();
+        expect(pooledAgentCount()).toBe(0);
+    });
+});
+const IDLE_PAST = 999_999_999; // far enough past any lastUsed to trip the 10-min TTL

package/dist/runtime/infra/file-watcher.d.ts

@@ -0,0 +1,72 @@
+/**
+ * File Watcher — CC filesystem change tracking parity.
+ *
+ * Fires hook events when files in the project change:
+ *   - file.changed (created/modified/deleted)
+ *   - cwd.changed (working directory switch)
+ *
+ * Uses Node.js fs.watch for project-level file monitoring.
+ * Does NOT use chokidar or other heavyweight watchers —
+ * this is a lightweight change-awareness system.
+ *
+ * Watched paths:
+ *   - .qlogicagent/settings.json → permission hot-reload
+ *   - INSTRUCTIONS.md / .qlogicagent/INSTRUCTIONS.md → instruction re-load
+ *   - configurable additional patterns
+ *
+ * Reference: claude-code file-watcher usage throughout lifecycle
+ */
+import type { HookRegistry } from "../../contracts/hooks.js";
+export interface FileWatcherDeps {
+    /** Project root directory (base for relative paths) */
+    projectRoot: string;
+    /** Session ID for hook context */
+    sessionId: string;
+    /** Hook registry for file.changed / cwd.changed events */
+    hooks: HookRegistry;
+    /** Logger */
+    log?: (msg: string) => void;
+    /** Callback to reset instruction cache when instructions change (injected, decoupled from prompt/) */
+    onInstructionCacheReset?: () => void;
+}
+export type ChangeType = "created" | "modified" | "deleted";
+export interface FileChangeEvent {
+    filePath: string;
+    changeType: ChangeType;
+    relativePath: string;
+}
+export declare class FileWatcher {
+    private watchers;
+    private deps;
+    private debounceTimers;
+    private _cwd;
+    constructor(deps: FileWatcherDeps);
+    get cwd(): string;
+    /**
+     * Start watching files.
+     * Watches each path in WATCHED_PATHS that exists on disk.
+     */
+    start(): Promise<void>;
+    /**
+     * Watch a single path. If it's a directory, watches recursively.
+     */
+    private watchPath;
+    /**
+     * Handle a file change event (debounced).
+     */
+    private handleChange;
+    /**
+     * Update the current working directory.
+     * Fires cwd.changed hook if the directory actually changed.
+     */
+    setCwd(newCwd: string): void;
+    /**
+     * Stop all watchers.
+     */
+    stop(): void;
+}
+/**
+ * Create and start a file watcher.
+ * Returns the watcher instance (call .stop() to clean up).
+ */
+export declare function createFileWatcher(deps: FileWatcherDeps): Promise<FileWatcher>;

package/dist/runtime/infra/file-watcher.js

@@ -0,0 +1,154 @@
+/**
+ * File Watcher — CC filesystem change tracking parity.
+ *
+ * Fires hook events when files in the project change:
+ *   - file.changed (created/modified/deleted)
+ *   - cwd.changed (working directory switch)
+ *
+ * Uses Node.js fs.watch for project-level file monitoring.
+ * Does NOT use chokidar or other heavyweight watchers —
+ * this is a lightweight change-awareness system.
+ *
+ * Watched paths:
+ *   - .qlogicagent/settings.json → permission hot-reload
+ *   - INSTRUCTIONS.md / .qlogicagent/INSTRUCTIONS.md → instruction re-load
+ *   - configurable additional patterns
+ *
+ * Reference: claude-code file-watcher usage throughout lifecycle
+ */
+import { watch } from "node:fs";
+import { stat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { AGENT_DOT_DIR } from "./agent-paths.js";
+// ── Watched Files ──────────────────────────────────────────
+/** Files/patterns to watch relative to project root */
+const WATCHED_PATHS = [
+    `${AGENT_DOT_DIR}/settings.json`,
+    "INSTRUCTIONS.md",
+    `${AGENT_DOT_DIR}/INSTRUCTIONS.md`,
+    "INSTRUCTIONS.local.md",
+    `${AGENT_DOT_DIR}/rules`,
+];
+/** File change patterns that trigger instruction cache invalidation */
+const INSTRUCTION_PATTERNS = [
+    "INSTRUCTIONS.md",
+    "INSTRUCTIONS.local.md",
+    `${AGENT_DOT_DIR}/rules`,
+];
+// ── File Watcher ───────────────────────────────────────────
+export class FileWatcher {
+    watchers = new Map();
+    deps;
+    debounceTimers = new Map();
+    _cwd;
+    constructor(deps) {
+        this.deps = deps;
+        this._cwd = deps.projectRoot;
+    }
+    get cwd() { return this._cwd; }
+    /**
+     * Start watching files.
+     * Watches each path in WATCHED_PATHS that exists on disk.
+     */
+    async start() {
+        for (const relPath of WATCHED_PATHS) {
+            const absPath = join(this.deps.projectRoot, relPath);
+            this.watchPath(absPath, relPath);
+        }
+        this.deps.log?.(`file-watcher: watching ${this.watchers.size} paths`);
+    }
+    /**
+     * Watch a single path. If it's a directory, watches recursively.
+     */
+    watchPath(absPath, relPath) {
+        if (this.watchers.has(absPath))
+            return;
+        try {
+            const watcher = watch(absPath, { persistent: false, recursive: relPath.includes("/") ? false : undefined }, (eventType, filename) => {
+                const changedFile = filename ? join(absPath, filename) : absPath;
+                this.handleChange(changedFile, eventType === "rename" ? "created" : "modified");
+            });
+            watcher.on("error", () => {
+                // File/dir may have been deleted — remove watcher silently
+                this.watchers.delete(absPath);
+            });
+            this.watchers.set(absPath, watcher);
+        }
+        catch {
+            // Path doesn't exist yet — that's OK
+        }
+    }
+    /**
+     * Handle a file change event (debounced).
+     */
+    handleChange(filePath, changeType) {
+        // Debounce: 300ms
+        const existing = this.debounceTimers.get(filePath);
+        if (existing)
+            clearTimeout(existing);
+        this.debounceTimers.set(filePath, setTimeout(async () => {
+            this.debounceTimers.delete(filePath);
+            // Determine actual change type
+            let actualType = changeType;
+            try {
+                await stat(filePath);
+            }
+            catch {
+                actualType = "deleted";
+            }
+            const relativePath = relative(this.deps.projectRoot, filePath);
+            this.deps.log?.(`file-watcher: ${actualType} ${relativePath}`);
+            // Fire hook
+            this.deps.hooks.invoke("file.changed", {
+                sessionId: this.deps.sessionId,
+                filePath,
+                changeType: actualType,
+            }).catch(() => { });
+            // Invalidate instruction cache if instruction file changed
+            const isInstructionFile = INSTRUCTION_PATTERNS.some(p => relativePath.includes(p) || filePath.includes(p));
+            if (isInstructionFile) {
+                this.deps.onInstructionCacheReset?.();
+            }
+        }, 300));
+    }
+    /**
+     * Update the current working directory.
+     * Fires cwd.changed hook if the directory actually changed.
+     */
+    setCwd(newCwd) {
+        const resolved = resolve(newCwd);
+        if (resolved === this._cwd)
+            return;
+        const oldCwd = this._cwd;
+        this._cwd = resolved;
+        this.deps.hooks.invoke("cwd.changed", {
+            sessionId: this.deps.sessionId,
+            oldCwd,
+            newCwd: resolved,
+        }).catch(() => { });
+        // Instruction cache depends on cwd
+        this.deps.onInstructionCacheReset?.();
+    }
+    /**
+     * Stop all watchers.
+     */
+    stop() {
+        for (const [, watcher] of this.watchers) {
+            watcher.close();
+        }
+        this.watchers.clear();
+        for (const [, timer] of this.debounceTimers) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+    }
+}
+/**
+ * Create and start a file watcher.
+ * Returns the watcher instance (call .stop() to clean up).
+ */
+export async function createFileWatcher(deps) {
+    const watcher = new FileWatcher(deps);
+    await watcher.start();
+    return watcher;
+}

package/dist/runtime/infra/index.d.ts

@@ -0,0 +1,19 @@
+export { AGENT_DOT_DIR, getUserAgentHome, getUserCredentialsPath, getUserPluginsDir, getUserSkillsDir, getUserSettingsPath, getUserCacheDir, getUserDebugLogsDir, getUserPluginCacheDir, getUserMcpConfigPath, getUserMarketplaceConfigPath, getUserWorkflowsDir, getProjectAgentDir, getProjectWorkflowsDir, getProjectPluginsDir, getProjectSkillManifestPath, getProjectSettingsPath, getProjectInstructionsPath, getProjectRulesDir, getGitRootHooksDir, } from "./agent-paths.js";
+export { getBudgetContinuationMessage } from "./token-budget.js";
+export { type SecureStorage, saveApiKey, loadApiKey } from "./secure-storage.js";
+export { ProjectInstructionsStore, type InstructionFile } from "./project-instructions-store.js";
+export { createFileWatcher, FileWatcher } from "./file-watcher.js";
+export { TaskStore } from "./task-runtime.js";
+export { createWorktreeBackend } from "./worktree-backend.js";
+export { registerCleanup, runCleanupFunctions } from "./cleanup-registry.js";
+export { atomicWriteFile, readJsonFile, writeJsonFile, } from "./disk-storage.js";
+export { AcpDetector, ACP_BACKENDS } from "./acp-detector.js";
+export { AcpProtocolAdapter, type TranslatedNotification, type AcpHostRequestHandler } from "./acp-protocol-adapter.js";
+export { AcpUsageTracker, type AccumulatedUsage } from "./acp-usage-tracker.js";
+export { AgentConfigStore } from "./agent-config-store.js";
+export { ModelIdTranslator } from "./model-id-translator.js";
+export { SkillInjector } from "./skill-injector.js";
+export { ACP_FAULT_LEVEL, type AcpFaultLevel, buildLlmEnvForTeammate } from "./agent-process.js";
+export { McpBridge, MCP_BRIDGE_TOOLS } from "./mcp-bridge.js";
+export type { AgentCategory, AgentProtocol, AgentStatus, AcpBackendConfig, AgentDescriptor, ExternalAgentDescriptor, CustomAgentDef, AgentConfig, AgentConfigStoreData, AgentCapabilities, AcpInitializeResult, AcpSessionResult, AcpPromptResponse, AcpPromptResponseUsage, AcpStopReason, AcpUsageUpdatePayload, McpServerConfig, AgentsScanParams, AgentsConfigParams, AgentsSetConfigParams, AgentsGetConfigParams, AgentsRemoveConfigParams, AgentsSetGatewayParams, SoloState, SoloAgentState, SoloAgentResult, SoloEvaluation, SoloStatus, SoloStartParams, SoloIdParams, SoloSelectParams, ProductPhase, ProductInstanceState, ProductTaskStatus, ProductBudget, ProductInstanceDef, ProductTaskDef, ProductCreateParams, ProductIdParams, ProductInstanceStatus, ProductTaskState, ProductStatus, ProductSummary, AgentsGetGatewayResult, AgentsListConfiguredItem, AgentsProcessInfo, AgentsKillParams, AgentsGetLogParams, AgentsGetLogResult, AgentsTestConnectionParams, AgentsTestConnectionResult, SoloDeleteParams, ProductDeleteParams, AgentSource, } from "../../protocol/wire/acp-agent-management.js";
+export type { AgentsStatusNotification, AgentsErrorNotification, SoloProgressNotification, SoloEvaluationNotification, SoloAgentDeltaNotification, ProductTaskStartedNotification, ProductTaskCompletedNotification, ProductTaskFailedNotification, ProductCheckpointedNotification, ProductBudgetWarningNotification, ProductCompletedNotification, } from "../../protocol/notifications.js";

package/dist/runtime/infra/index.js

@@ -0,0 +1,19 @@
+// runtime/infra — infrastructure subsystem
+export { AGENT_DOT_DIR, getUserAgentHome, getUserCredentialsPath, getUserPluginsDir, getUserSkillsDir, getUserSettingsPath, getUserCacheDir, getUserDebugLogsDir, getUserPluginCacheDir, getUserMcpConfigPath, getUserMarketplaceConfigPath, getUserWorkflowsDir, getProjectAgentDir, getProjectWorkflowsDir, getProjectPluginsDir, getProjectSkillManifestPath, getProjectSettingsPath, getProjectInstructionsPath, getProjectRulesDir, getGitRootHooksDir, } from "./agent-paths.js";
+export { getBudgetContinuationMessage } from "./token-budget.js";
+export { saveApiKey, loadApiKey } from "./secure-storage.js";
+export { ProjectInstructionsStore } from "./project-instructions-store.js";
+export { createFileWatcher, FileWatcher } from "./file-watcher.js";
+export { TaskStore } from "./task-runtime.js";
+export { createWorktreeBackend } from "./worktree-backend.js";
+export { registerCleanup, runCleanupFunctions } from "./cleanup-registry.js";
+export { atomicWriteFile, readJsonFile, writeJsonFile, } from "./disk-storage.js";
+// ── ACP Agent Management ────────────────────────────────────
+export { AcpDetector, ACP_BACKENDS } from "./acp-detector.js";
+export { AcpProtocolAdapter } from "./acp-protocol-adapter.js";
+export { AcpUsageTracker } from "./acp-usage-tracker.js";
+export { AgentConfigStore } from "./agent-config-store.js";
+export { ModelIdTranslator } from "./model-id-translator.js";
+export { SkillInjector } from "./skill-injector.js";
+export { ACP_FAULT_LEVEL, buildLlmEnvForTeammate } from "./agent-process.js";
+export { McpBridge, MCP_BRIDGE_TOOLS } from "./mcp-bridge.js";

package/dist/runtime/infra/key-injection.test.d.ts

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

package/dist/runtime/infra/key-injection.test.js

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { resolveCatalogKeyEnv, buildBackendEnv, getCatalogEntry } from "./acp-detector.js";
+describe("resolveCatalogKeyEnv (login-free catalog key injection)", () => {
+    it("llmrouter agents get the gateway key + base URL", () => {
+        const env = resolveCatalogKeyEnv(getCatalogEntry("claude"), {
+            llmrouterKey: "sk-qllm-abc",
+            llmrouterBaseUrl: "https://gw.example/anthropic",
+        });
+        expect(env.ANTHROPIC_API_KEY).toBe("sk-qllm-abc");
+        expect(env.ANTHROPIC_BASE_URL).toBe("https://gw.example/anthropic");
+    });
+    it("llmrouter agents can resolve protocol-specific base URLs", () => {
+        const codex = resolveCatalogKeyEnv(getCatalogEntry("codex"), {
+            llmrouterKey: "sk-qllm-abc",
+            llmrouterModel: "deepseek-v4-flash",
+            getLlmrouterBaseUrl: (id) => (id === "codex" ? "https://gw.example/v1" : "https://gw.example"),
+        });
+        expect(codex.OPENAI_API_KEY).toBe("sk-qllm-abc");
+        expect(codex.OPENAI_BASE_URL).toBe("https://gw.example/v1");
+        expect(codex.OPENAI_MODEL).toBe("deepseek-v4-flash");
+        const claude = resolveCatalogKeyEnv(getCatalogEntry("claude"), {
+            llmrouterKey: "sk-qllm-abc",
+            llmrouterModel: "deepseek-v4-flash",
+            getLlmrouterBaseUrl: (id) => (id === "codex" ? "https://gw.example/v1" : "https://gw.example"),
+        });
+        expect(claude.ANTHROPIC_API_KEY).toBe("sk-qllm-abc");
+        expect(claude.ANTHROPIC_BASE_URL).toBe("https://gw.example");
+    });
+    it("direct agents get the user's provider key, no base override", () => {
+        const env = resolveCatalogKeyEnv(getCatalogEntry("qwen"), {
+            getDirectKey: (id) => (id === "qwen" ? "dk-qwen-123" : null),
+        });
+        expect(env.DASHSCOPE_API_KEY).toBe("dk-qwen-123");
+    });
+    it("direct agents with no available key inject nothing", () => {
+        const env = resolveCatalogKeyEnv(getCatalogEntry("qwen"), { getDirectKey: () => null });
+        expect(env).toEqual({});
+    });
+    it("OAuth agents are never injected (account required)", () => {
+        const env = resolveCatalogKeyEnv(getCatalogEntry("copilot"), {
+            llmrouterKey: "sk-qllm-abc",
+            llmrouterBaseUrl: "https://gw",
+            getDirectKey: () => "anything",
+        });
+        expect(env).toEqual({});
+    });
+    it("undefined / non-catalog entries inject nothing", () => {
+        expect(resolveCatalogKeyEnv(undefined, { llmrouterKey: "x" })).toEqual({});
+    });
+});
+describe("model passthrough (透传 host's active model to OpenAI-compatible agents)", () => {
+    const passthroughModel = { apiKey: "sk-deepseek-xyz", baseUrl: "https://api.deepseek.com", model: "deepseek-chat" };
+    it("drives codex (no llmrouter key) with the active model via OPENAI_*", () => {
+        const env = resolveCatalogKeyEnv(getCatalogEntry("codex"), { passthroughModel });
+        expect(env.OPENAI_API_KEY).toBe("sk-deepseek-xyz");
+        expect(env.OPENAI_BASE_URL).toBe("https://api.deepseek.com");
+        expect(env.OPENAI_MODEL).toBe("deepseek-chat");
+    });
+    it("drives qwen (no direct key) with the active model via OPENAI_*", () => {
+        const env = resolveCatalogKeyEnv(getCatalogEntry("qwen"), { getDirectKey: () => null, passthroughModel });
+        expect(env.OPENAI_API_KEY).toBe("sk-deepseek-xyz");
+        expect(env.OPENAI_BASE_URL).toBe("https://api.deepseek.com");
+    });
+    it("does NOT passthrough when the agent already resolved its own key", () => {
+        const env = resolveCatalogKeyEnv(getCatalogEntry("codex"), { llmrouterKey: "sk-qllm-real", passthroughModel });
+        expect(env.OPENAI_API_KEY).toBe("sk-qllm-real"); // llmrouter wins; passthrough skipped
+    });
+    it("does NOT passthrough to non-OpenAI-compatible agents (e.g. claude)", () => {
+        const env = resolveCatalogKeyEnv(getCatalogEntry("claude"), { passthroughModel });
+        expect(env).toEqual({}); // claude uses ANTHROPIC_*, not the OpenAI passthrough
+    });
+});
+describe("buildBackendEnv autoEnv layering", () => {
+    const claude = getCatalogEntry("claude");
+    it("applies auto (login-free) env when there's no user override", () => {
+        const env = buildBackendEnv(claude, undefined, {
+            ANTHROPIC_API_KEY: "sk-auto",
+            ANTHROPIC_BASE_URL: "https://gw",
+        });
+        expect(env?.ANTHROPIC_API_KEY).toBe("sk-auto");
+        expect(env?.ANTHROPIC_BASE_URL).toBe("https://gw");
+    });
+    it("an explicit user config wins over the auto key", () => {
+        const env = buildBackendEnv(claude, { apiKey: "sk-user" }, { ANTHROPIC_API_KEY: "sk-auto", ANTHROPIC_BASE_URL: "https://gw" });
+        expect(env?.ANTHROPIC_API_KEY).toBe("sk-user"); // user override beats auto
+        expect(env?.ANTHROPIC_BASE_URL).toBe("https://gw"); // auto kept where no override
+    });
+});

package/dist/runtime/infra/key-pool.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Key Pool — commercial-grade multi-key load balancing per provider.
+ *
+ * Supports: weighted-round-robin, least-busy, random strategies.
+ * Features: RPM/TPM sliding window, failure cooldown, health detection, auto-failover.
+ *
+ * Runtime state (inFlight, counters, health) is in-memory only — resets on restart.
+ * Persistent config (keys, weights, strategy) is managed by the caller (settings.json).
+ */
+export type LoadBalanceStrategy = "weighted-round-robin" | "least-busy" | "random";
+export type KeyHealthStatus = "healthy" | "degraded" | "cooldown" | "disabled";
+/** Persistent key config (saved to settings.json). */
+export interface KeyConfig {
+    id: string;
+    key: string;
+    label?: string;
+    weight: number;
+    enabled: boolean;
+}
+/** Persistent provider pool config (saved to settings.json). */
+export interface ProviderPoolConfig {
+    providerId: string;
+    baseUrl?: string;
+    strategy: LoadBalanceStrategy;
+    keys: KeyConfig[];
+    rateLimit?: {
+        rpm?: number;
+        tpm?: number;
+    };
+}
+/** Acquired key handle — caller must call release() when done. */
+export interface KeyHandle {
+    keyId: string;
+    apiKey: string;
+    providerId: string;
+    release: (result: KeyReleaseResult) => void;
+}
+export interface KeyReleaseResult {
+    success: boolean;
+    tokens?: number;
+    errorCode?: number;
+    retryAfter?: number;
+}
+/** Full status for a single key (config + runtime). */
+export interface KeyStatus extends KeyConfig {
+    inFlight: number;
+    totalRequests: number;
+    totalTokens: number;
+    lastUsedAt: number;
+    lastErrorAt: number;
+    consecutiveErrors: number;
+    cooldownUntil: number;
+    healthStatus: KeyHealthStatus;
+}
+/** Full status for a provider pool. */
+export interface PoolStatus {
+    providerId: string;
+    baseUrl?: string;
+    strategy: LoadBalanceStrategy;
+    rateLimit?: {
+        rpm?: number;
+        tpm?: number;
+    };
+    keys: KeyStatus[];
+}
+export declare class KeyPool {
+    private pools;
+    private runtimeStates;
+    constructor(configs?: ProviderPoolConfig[]);
+    /**
+     * Acquire the next available key for a provider.
+     * Returns a KeyHandle with release() that MUST be called when the request completes.
+     * Returns null if no healthy key is available.
+     */
+    acquireKey(providerId: string): KeyHandle | null;
+    /**
+     * Release a key after request completion. Updates health/stats.
+     */
+    private releaseKey;
+    addProvider(providerId: string, opts?: {
+        baseUrl?: string;
+        strategy?: LoadBalanceStrategy;
+        rateLimit?: {
+            rpm?: number;
+            tpm?: number;
+        };
+    }): void;
+    removeProvider(providerId: string): void;
+    addKey(providerId: string, key: string, opts?: {
+        id?: string;
+        label?: string;
+        weight?: number;
+        enabled?: boolean;
+    }): string;
+    removeKey(keyId: string): boolean;
+    getKeyById(keyId: string): string | null;
+    updateKey(keyId: string, updates: Partial<Pick<KeyConfig, "label" | "weight" | "enabled">>): boolean;
+    /** Explicitly set a key's health status (e.g. after background validation). */
+    setKeyHealth(keyId: string, status: KeyHealthStatus): void;
+    setStrategy(providerId: string, strategy: LoadBalanceStrategy): void;
+    setRateLimit(providerId: string, rateLimit: {
+        rpm?: number;
+        tpm?: number;
+    }): void;
+    getPoolStatus(providerId: string): PoolStatus | null;
+    getAllStatus(): PoolStatus[];
+    getProviderIds(): string[];
+    hasProvider(providerId: string): boolean;
+    hasAvailableKey(providerId: string): boolean;
+    /** Export persistent config (for saving to settings.json). */
+    exportConfig(): ProviderPoolConfig[];
+    /** Reload from config (e.g., after settings.json changes on disk). */
+    reloadConfig(configs: ProviderPoolConfig[]): void;
+    private createInitialState;
+    private getHealthyCandidates;
+    private selectByStrategy;
+    private weightedRandom;
+    private leastBusy;
+    private pruneWindow;
+    private pruneTokenWindow;
+    private buildPoolStatus;
+}