qlogicagent 2.11.5 → 2.11.7

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/handlers/memory-handler.d.ts

@@ -1,5 +1,5 @@
 /**
- * Memory CRUD + search handlers — extracted from StdioServer.
+ * Memory CRUD + search handlers extracted from StdioServer.
  * Handles: memory.list, memory.read, memory.write, memory.search, memory.delete
  */
 import { type AgentRpcError, type AgentRpcRequest } from "../../protocol/wire/index.js";
@@ -30,15 +30,15 @@ export interface MemoryHandlerHost {
     sendResponse(id: string | number, result?: unknown, error?: AgentRpcError): void;
 }
 export declare function handleMemoryList(this: MemoryHandlerHost, msg: AgentRpcRequest): Promise<void>;
-/** memory.list-files — Returns actual topic files from memdir. */
+/** memory.list-files: returns actual topic files from memdir. */
 export declare function handleMemoryListFiles(this: MemoryHandlerHost, msg: AgentRpcRequest): Promise<void>;
 /**
- * memory.atlas — Returns full L2 vector-memory records (wire-safe, no embedding
+ * memory.atlas: returns full L2 vector-memory records (wire-safe, no embedding
  * blob) plus category roll-ups, for the 3D memory atlas visualization.
  */
 export declare function handleMemoryAtlas(this: MemoryHandlerHost, msg: AgentRpcRequest): Promise<void>;
 /**
- * memory.activity — Daily activity counts + highlights over the recent window,
+ * memory.activity: daily activity counts + highlights over the recent window,
  * powering the atlas timeline ticks and the "memory digest" panel.
  */
 export declare function handleMemoryActivity(this: MemoryHandlerHost, msg: AgentRpcRequest): Promise<void>;
@@ -51,11 +51,11 @@ export declare function handleMemorySearch(this: MemoryHandlerHost, msg: AgentRp
 export declare function handleMemoryDelete(this: MemoryHandlerHost, msg: AgentRpcRequest): Promise<void>;
 export declare function handleMemoryUpdate(this: MemoryHandlerHost, msg: AgentRpcRequest): Promise<void>;
 /**
- * memory.attachment.adopt — persist an uploaded素材 into the long-term-memory
+ * memory.attachment.adopt: persist an uploaded attachment into the long-term-memory
  * attachment store from a transient source URL (the gateway's temp MediaStore).
  * The attachment is an orphan until linked to a memory at consolidate time.
  */
 export declare function handleMemoryAttachmentAdopt(this: MemoryHandlerHost, msg: AgentRpcRequest): Promise<void>;
-/** memory.attachment.locate — resolve an attachment id to its on-disk path (for serving). */
+/** memory.attachment.locate: resolve an attachment id to its on-disk path (for serving). */
 export declare function handleMemoryAttachmentLocate(this: MemoryHandlerHost, msg: AgentRpcRequest): Promise<void>;
 export {};

package/dist/types/cli/memory-coordinator.d.ts

@@ -32,5 +32,6 @@ export interface RegisterMemoryToolDeps {
     memoryProvider: MemoryToolProvider | null;
     memoryUserId: string;
     toolCatalog: ToolCatalog;
+    sendNotification?: (method: string, params: Record<string, unknown>) => void;
 }
 export declare function registerMemoryTool(deps: RegisterMemoryToolDeps): void;

package/dist/types/cli/runtime-hook-bootstrap.d.ts

@@ -24,6 +24,7 @@ export interface RuntimeHookBootstrapDeps {
         transport: LLMTransport;
         apiKey: string;
     };
+    sendNotification?(method: string, params: Record<string, unknown>): void;
 }
 export interface RuntimeHookBootstrapResult {
     hooks: HookRegistry;

package/dist/types/orchestration/product-worktree.d.ts

@@ -5,7 +5,6 @@
 export declare function findGitRoot(cwd: string): Promise<string | null>;
 /** Create an isolated git worktree. Returns the worktree path. */
 export declare function createWorktree(gitRoot: string, name: string, baseBranch?: string): Promise<string>;
-/** Get a git diff stat from a worktree. */
 export declare function getWorktreeDiff(worktreePath: string): Promise<string>;
 /** Remove a git worktree. */
 export declare function removeWorktree(gitRoot: string, path: string): Promise<void>;

package/dist/types/orchestration/solo-evaluator.d.ts

@@ -70,6 +70,11 @@ export declare class SoloEvaluator {
      * The user chooses which agent in the session performs the evaluation comparison.
      */
     triggerEvaluation(soloId: string, evaluatorAgentId: string, evaluatorIndex?: number): Promise<SoloEvaluation>;
+    /** Map a spawned member back to its solo run + UI column id (for live delta forwarding). */
+    getMemberContext(memberId: string): {
+        soloId: string;
+        displayId: string;
+    } | null;
     /** Get the current status of a solo session. */
     getStatus(soloId: string): SoloStatus | null;
     /** Cancel a running solo session. Kill all agents and clean up worktrees. */

package/dist/types/protocol/methods.d.ts

@@ -594,8 +594,6 @@ export interface MemorySearchParams {
     query: string;
     /** Max results (default 10). */
     limit?: number;
-    /** Filter by userId (defaults to current session user). */
-    userId?: string;
 }
 export interface MemorySearchResult {
     results: Array<{

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" | "assistant";
+    /** How the agent is driven in-app: "acp" via the ACP adapter, "custom" via a dedicated non-ACP adapter. */
+    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/gateway-rpc.d.ts

@@ -56,7 +56,6 @@ export interface MemoryCandidateWire {
     reason?: string;
 }
 export interface MemoryTextMutationParams {
-    userId?: string;
     text?: string;
     category?: string;
     importance?: number;
@@ -583,7 +582,6 @@ export interface GatewayRpcMethodMap {
     };
     "memory.atlas": {
         params: {
-            userId?: string;
             pageSize?: number;
             windowStartAt?: number;
             windowEndAt?: number;
@@ -650,7 +648,6 @@ export interface GatewayRpcMethodMap {
     };
     "memory.activity": {
         params: {
-            userId?: string;
             days?: number;
         };
         result: {
@@ -669,7 +666,6 @@ export interface GatewayRpcMethodMap {
     };
     "memory.observe": {
         params: {
-            userId?: string;
             text: string;
             category?: string;
             importance?: number;
@@ -708,7 +704,6 @@ export interface GatewayRpcMethodMap {
     };
     "memory.update": {
         params: {
-            userId?: string;
             id: string;
             text?: string;
             category?: string;
@@ -724,7 +719,6 @@ export interface GatewayRpcMethodMap {
     };
     "memory.attachment.adopt": {
         params: {
-            userId?: string;
             tempUrl: string;
             filename?: string;
             mimeType?: string;

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", "openclaw", "hermes"];
+/** Merged catalog entry (base ACP config + grid/install metadata) for one id. */
+export declare function getCatalogEntry(id: string): AcpBackendConfig | undefined;
+/** Ordered curated catalog: base ACP config 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,44 @@ 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;
+    /** The host's active text-generation model (deepseek / volcengine / …) to "pass through" to
+     *  OpenAI-compatible spawned agents (codex/qwen/opencode) that resolve no key of their own — so
+     *  they run on the configured key+baseUrl+model with zero per-agent credentials. */
+    passthroughModel?: {
+        apiKey: string;
+        baseUrl?: string;
+        model?: string;
+    };
+}
+/**
+ * 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;
     /**
      * Scan for installed ACP agent CLIs.
      * @param force - Clear cache and re-scan.
@@ -54,6 +88,18 @@ export declare class AcpDetector {
     private detectBackend;
     private detectCustomAgent;
     private hasAgentConfig;
+    /**
+     * 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.
+     */
+    private buildSelfDescriptor;
     /**
      * Build an ExternalAgentDescriptor suitable for AgentProcessManager.spawn().
      * Returns null if the agent is not available.

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, fallbackAuthMethods?: AcpAuthMethod[]): 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;
 }