qlogicagent 2.11.4 → 2.11.6

package/dist/types/cli/handlers/agents-handler.d.ts

@@ -7,7 +7,7 @@
 import { type AgentRpcError, type AgentRpcRequest } from "../../protocol/wire/index.js";
 import { AgentProcessManager } from "../../runtime/infra/agent-process.js";
 import type { AgentConfigStore } from "../../runtime/infra/agent-config-store.js";
-import type { AcpDetector } from "../../runtime/infra/acp-detector.js";
+import { type AcpDetector } from "../../runtime/infra/acp-detector.js";
 export interface AgentsHandlerHost {
     acpDetector: AcpDetector;
     soloProcessManager: AgentProcessManager | null;
@@ -17,9 +17,24 @@ export interface AgentsHandlerHost {
     handleMcpToolCall?(memberId: string, tool: string, args: Record<string, unknown>): Promise<unknown>;
     log?(message: string): void;
     sendResponse(id: string | number, result?: unknown, error?: AgentRpcError): void;
+    sendNotification?(method: string, params: Record<string, unknown>): void;
 }
+/** Resolve a pending external-agent approval with the user's decision (delivered by the gateway). */
+export declare function handleAgentsApprovalResponse(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
 export declare function handleAgentsScan(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
 export declare function handleAgentsList(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/**
+ * Curated Discover-Agent catalog (12 agents) merged with live install status, for the
+ * discover grid. Status comes from the detector; install carries the official command
+ * summary + source for the confirm dialog (no secrets).
+ */
+export declare function handleAgentsCatalog(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/**
+ * One-click install a catalog agent by id. Runs ONLY the official command from the
+ * catalog manifest (never a free-form command), streaming progress via the
+ * agent.install.progress notification, then refreshes detection. Returns the outcome.
+ */
+export declare function handleAgentsInstall(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
 export declare function handleAgentsConfig(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
 export declare function handleAgentsSetConfig(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
 export declare function handleAgentsGetConfig(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
@@ -31,4 +46,6 @@ export declare function handleAgentsProcesses(this: AgentsHandlerHost, msg: Agen
 export declare function handleAgentsKill(this: AgentsHandlerHost, msg: AgentRpcRequest): void;
 export declare function handleAgentsGetLog(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
 export declare function handleAgentsTestConnection(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
+/** Pre-warm an external agent's process (on agent-select) so the first message skips the cold start. */
+export declare function handleAgentsWarm(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
 export declare function handleAgentsPrompt(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;

package/dist/types/cli/tool-bootstrap.d.ts

@@ -12,6 +12,8 @@ export interface SandboxPermissionSnapshot {
     mode: PermissionMode;
     workdir: string;
     allowedDirs: string[];
+    /** cut7c: current turn is an untrusted community-skill turn → tighten the sandbox. */
+    communityTurn: boolean;
 }
 /** Wire the OS-sandbox permission source (live rule-engine snapshot), or null to clear. */
 export declare function setSandboxPermissionSource(source: (() => SandboxPermissionSnapshot | undefined) | null): void;

package/dist/types/protocol/wire/acp-agent-management.d.ts

@@ -30,6 +30,33 @@ export interface AcpBackendConfig {
     apiKeyEnvVar?: string;
     /** Environment variable name for the base URL. */
     baseUrlEnvVar?: string;
+    /** Official-logo key for AgentBrandIcon. */
+    brandId?: string;
+    /** Real-world usage scenario for grouping in the discover UI (not a capability tag). */
+    category?: "coding" | "writing" | "design" | "creative" | "research";
+    /** How the agent is driven in-app: "acp" via the ACP adapter, "custom" via a dedicated adapter (e.g. Trae). */
+    integration?: "acp" | "custom";
+    /** Where the injected key comes from: gateway-issued (llmrouter), the user's direct third-party key, or none (OAuth). */
+    keySource?: "llmrouter" | "direct" | "none";
+    /** Auth model: "key" = login-free key injection; "oauth" = no key bypass, user account required. */
+    authMode?: "key" | "oauth";
+    /** One-click install spec (official commands per platform). */
+    install?: AgentInstallSpec;
+    /** Short UI note (e.g. "需 GitHub 账号", "非 ACP,自定义适配器驱动"). */
+    note?: string;
+}
+/** Official install commands for the one-click installer (no self-hosted CDN — runs upstream). */
+export interface AgentInstallSpec {
+    npm?: string;
+    brew?: string;
+    curl?: string;
+    pip?: string;
+    /** Executable name after install (probe target). */
+    cliCommand: string;
+    /** Probe command (default `<cliCommand> --version`). */
+    verifyCmd?: string;
+    /** Official docs / source URL (shown in the install confirmation). */
+    docsUrl: string;
 }
 /**
  * Extended descriptor for external agents,

package/dist/types/protocol/wire/notification-payloads.d.ts

@@ -387,6 +387,99 @@ export interface AgentsErrorNotification {
     error: string;
     retriesLeft: number;
 }
+/** One-click install progress (state transitions + streamed log lines + final result). */
+export interface AgentInstallProgressNotification {
+    agentId: string;
+    event: {
+        type: "state";
+        state: "installing" | "verifying" | "installed" | "failed";
+    } | {
+        type: "log";
+        stream: "stdout" | "stderr";
+        chunk: string;
+    } | {
+        type: "done";
+        ok: boolean;
+        error?: string;
+    };
+}
+/**
+ * Live streaming chunk from an EXTERNAL agent's prompt turn (agents.prompt). Echoes the gateway's
+ * turn identity (sessionId/turnId/requestId passed in agents.prompt params) so the gateway can
+ * re-emit it on the same turn.delta path the main agent uses — no separate frontend handling.
+ */
+export interface AgentsPromptDeltaNotification {
+    agentId: string;
+    sessionId?: string;
+    turnId?: string;
+    requestId?: string;
+    text: string;
+    /** When true this chunk is the agent's reasoning/thinking (→ turn.reasoning_delta), not reply text. */
+    reasoning?: boolean;
+}
+/**
+ * Live tool-call lifecycle from an EXTERNAL agent's prompt turn — same echo-the-turn-identity
+ * mechanism as AgentsPromptDeltaNotification, so the gateway re-emits it on the main
+ * turn.tool_call / turn.tool_result path and the UI shows external tools running, no extra handling.
+ */
+export interface AgentsPromptToolNotification {
+    agentId: string;
+    sessionId?: string;
+    turnId?: string;
+    requestId?: string;
+    event: {
+        kind: "call";
+        callId: string;
+        name: string;
+        arguments?: string;
+        inputSummary?: string;
+    } | {
+        kind: "result";
+        callId: string;
+        name: string;
+        ok: boolean;
+        outputPreview?: string;
+        error?: string;
+    };
+}
+/**
+ * Plan/task update from an EXTERNAL agent's prompt turn (ACP plan steps). The gateway maps the
+ * steps onto the main turn.task_updated path so the UI shows the agent's plan as a task list.
+ */
+export interface AgentsPromptPlanNotification {
+    agentId: string;
+    sessionId?: string;
+    turnId?: string;
+    requestId?: string;
+    steps: Array<{
+        content?: string;
+        title?: string;
+        status?: string;
+        priority?: string;
+    }>;
+}
+/**
+ * Interactive permission request from an EXTERNAL agent's prompt turn. Echoes the gateway's turn
+ * identity so the gateway re-emits it on the main turn.approval_request path → the UI shows an
+ * approval card; the user's decision returns via the agents.approvalResponse RPC.
+ */
+export interface AgentsPromptApprovalNotification {
+    agentId: string;
+    sessionId?: string;
+    turnId?: string;
+    requestId?: string;
+    approvalId: string;
+    callId?: string;
+    toolName: string;
+    arguments?: string;
+    message?: string;
+    category?: string;
+    options?: Array<{
+        optionId: string;
+        name?: string;
+        kind?: string;
+    }>;
+}
 /** Solo agent progress. */
 export interface SoloProgressNotification {
     soloId: string;
@@ -761,6 +854,11 @@ export interface NotificationMethodMap {
     "pong": PongNotification;
     "agents.status": AgentsStatusNotification;
     "agents.error": AgentsErrorNotification;
+    "agent.install.progress": AgentInstallProgressNotification;
+    "agents.prompt.delta": AgentsPromptDeltaNotification;
+    "agents.prompt.tool": AgentsPromptToolNotification;
+    "agents.prompt.approval": AgentsPromptApprovalNotification;
+    "agents.prompt.plan": AgentsPromptPlanNotification;
     "solo.progress": SoloProgressNotification;
     "solo.evaluation": SoloEvaluationNotification;
     "solo.agentDelta": SoloAgentDeltaNotification;

package/dist/types/runtime/infra/acp-detector.d.ts

@@ -8,6 +8,11 @@
  */
 import type { AcpBackendConfig, AgentDescriptor, AgentConfigStoreData } from "../../protocol/wire/acp-agent-management.js";
 export declare const ACP_BACKENDS: Record<string, AcpBackendConfig>;
+export declare const AGENT_CATALOG_IDS: readonly ["claude", "codex", "gemini", "copilot", "cursor", "qwen", "kimi", "glm", "opencode", "kiro", "qoder", "auggie", "trae"];
+/** Merged catalog entry (base ACP/Trae config + grid/install metadata) for one id. */
+export declare function getCatalogEntry(id: string): AcpBackendConfig | undefined;
+/** Ordered curated catalog: base ACP config (or Trae base) merged with grid/install metadata. */
+export declare function getAgentCatalog(): AcpBackendConfig[];
 export declare function resolveWindowsCopilotLoader(): string | null;
 export declare function normalizeWindowsAcpCommand(cliPath: string, args: string[]): {
     cliPath: string;
@@ -33,15 +38,38 @@ export declare function normalizeWindowsAcpCommand(cliPath: string, args: string
  * does not read). Returns undefined when there is nothing to inject, preserving the
  * prior `env?: undefined` behavior for un-configured backends.
  */
-export declare function buildBackendEnv(backend: AcpBackendConfig | undefined, customConfig: import("../../protocol/wire/acp-agent-management.js").AgentConfig | undefined): Record<string, string> | undefined;
+export declare function buildBackendEnv(backend: AcpBackendConfig | undefined, customConfig: import("../../protocol/wire/acp-agent-management.js").AgentConfig | undefined, autoEnv?: Record<string, string>): Record<string, string> | undefined;
+/** Unified key sources for login-free catalog injection (wired by the runtime). */
+export interface CatalogKeySources {
+    /** Gateway-issued inference key (sk-qllm) for keySource:"llmrouter". */
+    llmrouterKey?: string;
+    /** Base URL an llmrouter-routed agent should call (our gateway endpoint). */
+    llmrouterBaseUrl?: string;
+    /** Resolve a provider's direct third-party key for keySource:"direct". */
+    getDirectKey?: (providerId: string) => string | null | undefined;
+}
+/**
+ * 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 declare function resolveCatalogKeyEnv(entry: AcpBackendConfig | undefined, sources: CatalogKeySources): Record<string, string>;
 export declare class AcpDetector {
     private cache;
     private configStore;
+    private keySources;
     /**
      * Provide the config store data so detector can populate `hasConfig` field
      * and include user-registered custom agents.
      */
     setConfigStore(data: AgentConfigStoreData): void;
+    /** Wire the unified key sources for login-free catalog injection. */
+    setKeySources(sources: CatalogKeySources): void;
+    /** Login-free key env for a catalog agent (used by non-ACP adapters, e.g. Trae). */
+    getCatalogKeyEnv(agentId: string): Record<string, string>;
     /**
      * Scan for installed ACP agent CLIs.
      * @param force - Clear cache and re-scan.

package/dist/types/runtime/infra/acp-host-handler.d.ts

@@ -1,6 +1,14 @@
 import type { AcpHostRequestHandler } from "./acp-protocol-adapter.js";
 interface HostHandlerOpts {
     cwd: string;
+    /**
+     * Optional interactive permission resolver. When provided, session/request_permission is routed
+     * here (forwarded to the user) instead of auto-allowing. Returning a chosen optionId responds to
+     * the external agent. If omitted, permissions auto-allow (host-trust baseline for sub-agents).
+     */
+    requestPermission?: (params: Record<string, unknown>) => Promise<{
+        optionId: string;
+    }>;
 }
 /**
  * Host-side reverse-RPC handler for an EXTERNAL ACP agent (codex/copilot/…).
@@ -12,7 +20,7 @@ interface HostHandlerOpts {
  * disposeAll().
  *
  * Terminal response shapes align with the official ACP schema
- * (@zed-industries/agent-client-protocol):
+ * (@agentclientprotocol/sdk):
  *   - createTerminal       -> { terminalId }
  *   - terminalOutput       -> { output, truncated, exitStatus: {exitCode, signal} | null }
  *   - waitForTerminalExit  -> { exitCode, signal }

package/dist/types/runtime/infra/acp-protocol-adapter.d.ts

@@ -1,25 +1,25 @@
 /**
- * ACP Protocol Adapter — translates between qlogicagent's internal JSON-RPC
- * protocol and the ACP (Agent-Client Protocol) wire format.
+ * ACP Protocol Adapter — a thin wrapper over the official @agentclientprotocol/sdk
+ * `ClientSideConnection`. qlogicagent is the ACP *client* (host); spawned external
+ * agents (codex-acp, claude-agent-acp, openclaw, …) are the ACP *agents*.
  *
- * Aligned with @agentclientprotocol/sdk v0.18.2 (PROTOCOL_VERSION = 1).
- * Reference: AionUI ClientSideConnection, @agentclientprotocol/sdk.
+ * The SDK owns the wire protocol entirely: JSON-RPC 2.0 / NDJSON framing, request↔response
+ * correlation, and the reverse-RPC dispatch. This module owns only the three concerns the SDK
+ * leaves to the host:
+ *   1. bridging a Node ChildProcess's stdio to the SDK's web-stream transport (ndJsonStream)
+ *   2. mapping our loose `AcpHostRequestHandler` onto the typed SDK `Client` interface
+ *   3. translating SDK `session/update` notifications into qlogicagent's internal `turn.*` methods
  *
- * ACP = JSON-RPC 2.0 over NDJSON stdio:
- *   HOST → AGENT (requests):
- *     initialize, session/new, session/prompt, session/close, session/resume
- *   AGENT → HOST (notifications):
- *     session/update — carries { sessionId, update: { sessionUpdate: "...", ...payload } }
- *   AGENT → HOST (requests, host must respond):
- *     fs/read_text_file, fs/write_text_file, session/request_permission,
- *     session/elicitation, terminal/create, terminal/output, terminal/release,
- *     terminal/wait_for_exit, terminal/kill
+ * Extension capabilities (clientCapabilities.qlogicagent) are forwarded verbatim — the SDK does
+ * not strip outgoing params (validation runs only on the receiving side), so openclaw interop is
+ * preserved.
  */
 import type { ChildProcess } from "node:child_process";
 import type { AcpInitializeResult, AcpSessionResult, AcpPromptResponse, McpServerConfig } from "../../protocol/wire/acp-agent-management.js";
 /**
  * Handler for agent→host requests (fs, terminal, permission, elicitation).
- * Host implementations should implement the methods they support.
+ * Host implementations should implement the methods they support. This is intentionally loose
+ * (Record-typed) — {@link AcpProtocolAdapter} bridges it onto the SDK's strongly-typed Client.
  */
 export interface AcpHostRequestHandler {
     /** Read a text file from the host filesystem. */
@@ -33,8 +33,10 @@ export interface AcpHostRequestHandler {
         path: string;
         content: string;
     }): Promise<Record<string, unknown> | undefined>;
-    /** Request permission for a tool call (return selected option). */
-    requestPermission?(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Request permission for a tool call. Returns the chosen option id (host responsibility). */
+    requestPermission?(params: Record<string, unknown>): Promise<{
+        optionId: string;
+    }>;
     /** Elicitation request (ask user for input). */
     elicitation?(params: Record<string, unknown>): Promise<Record<string, unknown>>;
     /** Create a terminal session. */
@@ -55,73 +57,90 @@ export interface TranslatedNotification {
     method: string;
     params: Record<string, unknown>;
 }
+/** An auth method an agent advertises when it needs the user to log in (subset of ACP shape). */
+export interface AcpAuthMethod {
+    id?: string;
+    name?: string;
+    description?: string;
+}
+/**
+ * Thrown when an agent rejects session setup because the user must authenticate first — e.g. kimi
+ * returns -32000 "Authentication required" with a `kimi login` authMethod. Carries the agent's
+ * advertised authMethods and `retryable = false`, so the spawn layer surfaces it immediately (a
+ * missing login never heals by retrying) with an actionable message instead of a generic failure.
+ */
+export declare class AcpAuthRequiredError extends Error {
+    readonly retryable: false;
+    readonly authMethods: AcpAuthMethod[];
+    constructor(message: string, authMethods: AcpAuthMethod[]);
+}
+/**
+ * Recognise the ACP "authentication required" failure (by code -32000, an authMethods payload, or
+ * message text) and convert it to an {@link AcpAuthRequiredError} whose message tells the user how
+ * to log in (from the agent's own authMethod description). Returns null for any other error.
+ */
+export declare function asAuthRequiredError(err: unknown): AcpAuthRequiredError | null;
 export declare class AcpProtocolAdapter {
-    private pendingRpcs;
-    private rl;
+    private conn;
     private child;
     private onNotification;
     private hostHandler;
     /**
      * Attach to a child process's stdio for ACP communication.
-     * Must be called before any RPC methods.
+     * Constructs the official ClientSideConnection over the child's stdin/stdout. The connection's
+     * read loop starts immediately, so incoming notifications + reverse-RPC are live after this call.
      *
      * @param child The spawned ACP agent process
-     * @param onNotification Callback for agent notifications (session/update, etc.)
+     * @param onNotification Callback for agent notifications (raw method + params; caller translates)
      * @param hostHandler Optional handler for agent→host requests (fs, terminal, permission)
      */
     attach(child: ChildProcess, onNotification?: (method: string, params: unknown) => void, hostHandler?: AcpHostRequestHandler): void;
     /**
-     * Handle an incoming JSON-RPC request from the agent (reverse-RPC).
-     * Agent calls host for fs operations, terminal, permissions, etc.
+     * Build the SDK Client implementation (agent→host reverse-RPC) from our loose host handler.
+     * Re-reads this.hostHandler / this.onNotification on each call so detach() takes effect.
      */
-    private handleAgentRequest;
-    /** Detach from the child process. */
+    private buildClient;
+    /** Detach from the child process. The SDK read loop ends when the child's stdout closes. */
     detach(): void;
-    /** Send a raw JSON-RPC request and await response. */
-    sendRpc(child: ChildProcess, method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+    private requireConn;
+    /** Race a connection call against a timeout; optionally run a side effect (e.g. cancel) on timeout. */
+    private withTimeout;
     /**
-     * Perform ACP initialize handshake.
-     * Sends standard clientInfo + clientCapabilities (aligned with SDK).
+     * Perform the ACP initialize handshake. Sends standard clientInfo + clientCapabilities plus the
+     * qlogicagent extension capability (forwarded verbatim by the SDK).
      */
-    initialize(child: ChildProcess): Promise<AcpInitializeResult>;
+    initialize(_child?: ChildProcess): Promise<AcpInitializeResult>;
     /**
-     * Create an ACP session.
-     * Official SDK params: { cwd, mcpServers, additionalDirectories? }
-     * Optionally injects system prompt as extension field.
+     * Create an ACP session (session/new). A non-standard systemPrompt is forwarded under `_meta`
+     * (the ACP extension mechanism) so it survives validation on the agent side.
      */
-    createSession(child: ChildProcess, options: {
+    createSession(_child: ChildProcess, options: {
         cwd: string;
         mcpServers?: McpServerConfig[];
         additionalDirectories?: string[];
         systemPrompt?: string;
     }): Promise<AcpSessionResult>;
     /**
-     * Send a prompt to a running ACP session.
-     * Official SDK params: { sessionId, prompt: ContentBlock[], messageId? }
-     * Official SDK response: { stopReason, usage?, userMessageId? }
-     *
-     * Note: Actual content is delivered via session/update notifications DURING
-     * the prompt execution. The response only signals completion.
+     * Send a prompt to a running ACP session (session/prompt). Content streams back via session/update
+     * notifications during execution; the response carries only { stopReason, usage? }. On timeout the
+     * turn is cancelled (session/cancel) so the agent stops cleanly.
      */
-    sendPrompt(child: ChildProcess, sessionId: string, content: string, timeoutMs?: number): Promise<AcpPromptResponse>;
+    sendPrompt(_child: ChildProcess, sessionId: string, content: string, timeoutMs?: number): Promise<AcpPromptResponse>;
     /**
-     * Resume an existing ACP session (loadSession capability).
-     * Official SDK method: session/load (same schema as session/new + sessionId).
+     * Resume an existing ACP session (session/load — replays history via notifications).
+     * Only valid when the agent advertised the loadSession capability.
      */
-    resumeSession(child: ChildProcess, sessionId: string, options?: {
+    resumeSession(_child: ChildProcess, sessionId: string, options?: {
         cwd?: string;
         mcpServers?: McpServerConfig[];
     }): Promise<AcpSessionResult>;
-    /**
-     * Close an ACP session.
-     */
-    closeSession(child: ChildProcess, sessionId: string): Promise<void>;
     /**
      * Translate an ACP notification into qlogicagent's internal format.
      * Returns null if the notification is not translatable (handled separately).
      *
-     * Standard ACP: agent sends "session/update" notification with
-     *   params: { sessionId, update: { sessionUpdate: "<type>", ...payload } }
+     * Standard ACP: agent sends "session/update" with params { sessionId, update: { sessionUpdate, … } }.
+     * Used by both the external-agent path (this adapter) and the internal/builtin agent path, so it
+     * stays a pure static function decoupled from the connection.
      */
     static translateNotification(method: string, params: unknown): TranslatedNotification | null;
 }

package/dist/types/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/types/runtime/infra/agent-process.d.ts

@@ -101,6 +101,14 @@ export interface AgentProcessCallbacks {
     onExit?: (memberId: string, code: number | null, signal: string | null) => void;
     /** Called when MCP bridge server proxies a tool call from an external agent. */
     onMcpToolCall?: (memberId: string, tool: string, args: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Called when an external agent requests permission (ACP session/request_permission). When set,
+     * it drives interactive approval (forward to user, await decision) instead of the auto-allow
+     * host-trust baseline; resolve with the chosen optionId.
+     */
+    onPermissionRequest?: (memberId: string, params: Record<string, unknown>) => Promise<{
+        optionId: string;
+    }>;
     /** Logger. */
     log?: {
         info(msg: string): void;
@@ -243,6 +251,8 @@ export declare class AgentProcessManager {
     getHandle(memberId: string): AgentProcessHandle | undefined;
     /** Get all handles. */
     getAllHandles(): AgentProcessHandle[];
+    /** Whether a member's process is still spawned and usable (for pool reuse across turns). */
+    isAlive(memberId: string): boolean;
     /** Get usage tracker for an ACP agent (returns null for internal agents). */
     getUsageTracker(memberId: string): AcpUsageTracker | null;
     /**

package/dist/types/runtime/infra/external-agent-approvals.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pending interactive-approval registry for EXTERNAL agents.
+ *
+ * When a spawned external agent (Codex/Claude/…) asks for permission (ACP session/request_permission),
+ * the host handler forwards the request to the frontend and parks the ACP response here until the user
+ * decides. The gateway delivers the decision via the agents.approvalResponse RPC, which resolves the
+ * matching pending promise so the host handler can return the chosen optionId to the external agent.
+ *
+ * This is the qlogicagent-side mirror of the gateway adapter's pendingPermissionRequests map.
+ */
+/**
+ * Park an approval until the user decides. Resolves with the chosen optionId, or null on timeout
+ * (the caller then applies a safe default). Idempotent per approvalId — a duplicate replaces the old.
+ */
+export declare function awaitApprovalDecision(approvalId: string, timeoutMs: number): Promise<string | null>;
+/** Deliver the user's decision. Returns false if no approval was pending for this id (no-op). */
+export declare function resolveApprovalDecision(approvalId: string, optionId: string): boolean;
+/** Cancel all pending approvals (e.g. on shutdown) — resolves them as null so awaiters unblock. */
+export declare function cancelAllApprovals(): void;
+export declare function pendingApprovalCount(): number;
+export interface ApprovalForwardDeps {
+    agentId: string;
+    /** Current streaming turn identity (read fresh each call, since members are reused across turns). */
+    turnContext: () => {
+        sessionId?: string;
+        turnId?: string;
+        requestId?: string;
+    } | null;
+    /** Emit the forward notification to the gateway (→ turn.approval_request → UI card). */
+    sendNotification?: (method: string, params: Record<string, unknown>) => void;
+    timeoutMs?: number;
+}
+/**
+ * Drive one interactive approval for an external agent: forward the ACP session/request_permission
+ * to the user (agents.prompt.approval), await the decision, and return the chosen optionId. Falls
+ * back to a reject option if there's no streaming turn context or the user doesn't decide in time.
+ * Pure + injectable so the bidirectional loop is unit-testable without a live agent.
+ */
+export declare function forwardExternalApproval(params: Record<string, unknown>, deps: ApprovalForwardDeps): Promise<{
+    optionId: string;
+}>;

package/dist/types/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;