@armadra/agent 0.10.0 → 0.12.0

package/dist/cli/compose-agents.js

@@ -18,6 +18,8 @@ import { AgentCatalog } from "../agents/catalog.js";
 import { agentSources, discoverAgents } from "../agents/discover.js";
 import { NO_AGENT_PROBE_ENV, SessionExternalAgents, registerExternalAgents, } from "../agents/external.js";
 import { hostRunnersOf } from "../host/api-impl.js";
+import { isCoordinatorPreset } from "../tools/presets.js";
+import { COORDINATOR_WAIT_MAX_MS, bindTaskCtlWaitCap } from "../tools/task-ctl.js";
 import { bindTaskAgents, bindTaskBackground } from "../tools/task.js";
 import { resolveTaskBackground } from "../agent/subagent-background.js";
 import { msg } from "../i18n/index.js";
@@ -62,6 +64,9 @@ export function subagentEnvironment(deps, catalog) {
     // [W7-B1] 缺省后台与自动转后台（配置键 W7-B2 登记于 config/types-w5.ts）
     const sub = config.subagents;
     env.background = resolveTaskBackground(sub?.background, deps.assembly.unattended === true);
+    // [#242] 协调者不阻塞：缺省后台，不受 subagents.background / -p 影响（调用参数与类型定义仍优先）
+    if (isCoordinatorPreset(config))
+        env.background = true;
     const after = sub?.autoBackgroundAfterMs;
     if (typeof after === "number" && after > 0)
         env.autoBackgroundAfterMs = after;
@@ -120,5 +125,8 @@ export function createSubagentsFactory(deps) {
     bindTaskAgents(task, catalog);
     const env = subagentEnvironment(deps, catalog);
     bindTaskBackground(task, env.background === true);
+    // [#242] 协调者预设：task_ctl wait 超时封顶（task 与 task_ctl 同进退）
+    if (isCoordinatorPreset(deps.assembly.config))
+        bindTaskCtlWaitCap(deps.assembly.tools.get("task_ctl"), COORDINATOR_WAIT_MAX_MS);
     return ({ core }) => (core.depth > 0 ? undefined : createSubagentExtension(core, env, wiring));
 }

package/dist/cli/compose.d.ts

@@ -30,6 +30,7 @@ import type { Rule } from "../permissions/types.js";
 import { type SandboxCapability } from "../codemode/capability.js";
 import { type BashSandbox } from "../sandbox/bash.js";
 import { PresetToolRegistry } from "../tools/presets.js";
+import type { WebFetchOptions } from "../tools/web/fetch.js";
 import type { MemoryRuntime } from "../memory/runtime.js";
 import type { ToolDefinition, ToolRegistryApi } from "../tools/types.js";
 import { type ComposeState, type LogFn } from "./compose-session.js";
@@ -57,6 +58,8 @@ export interface ComposeOptions {
     apis?: ApiRegistry;
     /** SDK 追加的工具（来源 sdk，总在活动集里）。 */
     extraTools?: ToolDefinition[];
+    /** 测试注入：web_fetch 的解析与请求（不出网）。 */
+    webFetch?: WebFetchOptions;
     /** 缺省 DEFAULT_TOOL_FACTORIES。 */
     toolFactories?: readonly ToolFactory[];
     /**

package/dist/cli/compose.js

@@ -88,6 +88,7 @@ export function createTools(input, options, state) {
     };
     const builtins = builtinTools({
         bash,
+        ...(options.webFetch !== undefined ? { webFetch: options.webFetch } : {}),
         read: {
             supportsImages: (ctx) => modelAcceptsImages(state, ctx.model),
             imageOptions: (ctx) => imageFitOptionsFor(state.providers, ctx.model, input.config.images),

package/dist/drivers/acp/client.d.ts

@@ -14,13 +14,29 @@
  * - `elicitation/create` 交给 `onElicitation`；给了它 `initialize` 才声明 `clientCapabilities.elicitation`，
  *   没给时线路与旧版相同（不声明，Agent 发来的请求回 method not found）。`cancel(sessionId)`、连接关闭时
  *   挂起的 elicitation 一律回 `{ action: "cancel" }`；ama 从不替人填表。
+ * - `elicitation/complete`（Agent → 客户端通知，URL 型 elicitation 在带外完成）交给 `onElicitationComplete`；给了它
+ *   `initialize` 声明 `elicitation: { form: {}, url: {} }`（只给 `onElicitation` 时仍是 `{}`，与旧版相同）。同一
+ *   `elicitationId` 若还挂着（处理器没答），它的 `signal` 随之 abort、答 `{ action: "cancel" }`，宿主据此收掉卡片。
+ *   表单字段含字符串多选（`type: "array"`）与带标题的 `oneOf` / `anyOf`，答复 `content` 里多选是字符串数组；
+ *   {@link multiSelectOptions} / {@link singleSelectOptions} 把两种写法收成统一的 `{ const, title }` 列表。
+ * - 会话管理：`listSessions(cwd?, cursor?, signal?)` 发 `session/list`（要 Agent 声明 `sessionCapabilities.list`，见
+ *   `supportsList`），`listAllSessions` 跟 `nextCursor` 翻页取全；`closeSession(sessionId, signal?)` 发 `session/close`
+ *   （`supportsClose`），按规范等同先取消：该会话挂起的权限请求答 `cancelled`、elicitation 答 `cancel`，再发请求。
+ *   没声明能力的 Agent 会答 -32601，开会话遇 -32000 同样原样抛出（{@link isAuthRequiredError}）。
  * - `setConfigOption(sessionId, configId, value)` 发 `session/set_config_option`；开会话答的 `configOptions`
  *   原样交回。`initialize` 声明 `clientCapabilities.session.configOptions: {}`（只认 select，不声明 boolean）；
- *   不声明 `auth.terminal`（ama 作客户端没有可借给 Agent 的交互终端）。[ACP-D]
+ *   `auth.terminal` 缺省不声明（ama 作客户端没有可借给 Agent 的交互终端），见下 `authTerminal`。[ACP-D]
+ * - 认证：`authenticate(methodId)` 发 `authenticate`（agent 型方法）、`logout()` 发 `logout`（Agent 声明
+ *   `auth.logout` 才可用，见 `supportsLogout`）；terminal 型方法规范禁止经 `authenticate`，已知是 terminal 型时本地
+ *   拒绝（-32602），宿主自己在终端里跑 `args` / `env`。构造参数 `authTerminal: true` 才在 `initialize` 声明
+ *   `clientCapabilities.auth.terminal`（宿主有交互终端可借；Agent 据此才给 terminal 型方法），缺省线路与旧版相同。
+ *   开会话遇 -32000（auth_required）用 {@link isAuthRequiredError} 判断，`authMethods` 保留 id / name / description / type
+ *   / args / env 原样。
  * - 线路两侧开 `$/cancel_request`：本端请求的 `signal` abort 时通知 Agent；Agent 撤回挂起的
  *   `session/request_permission` / `elicitation/create` 时处理器的 `signal` abort，回 cancelled / cancel。[ACP-D]
  */
-import { type AcpAgentCapabilities, type AcpAuthMethod, type AcpContentBlock, type AcpElicitationParams, type AcpElicitationResult, type AcpImplementationInfo, type AcpInitializeResult, type AcpListSessionsResult, type AcpLoadSessionResult, type AcpNewSessionResult, type AcpPromptResult, type AcpRequestPermissionParams, type AcpRequestPermissionResult, type AcpSessionNotification, type AcpSessionOptions, type AcpSetConfigOptionResult } from "./types.js";
+import { RpcError } from "../jsonrpc.js";
+import { type AcpAgentCapabilities, type AcpAuthMethod, type AcpAuthenticateResult, type AcpLogoutResult, type AcpCompleteElicitationParams, type AcpContentBlock, type AcpElicitationParams, type AcpElicitationResult, type AcpImplementationInfo, type AcpInitializeResult, type AcpListSessionsResult, type AcpCloseSessionResult, type AcpSessionInfo, type AcpLoadSessionResult, type AcpNewSessionResult, type AcpPromptResult, type AcpRequestPermissionParams, type AcpRequestPermissionResult, type AcpSessionNotification, type AcpSessionOptions, type AcpSetConfigOptionResult } from "./types.js";
 export interface AcpClientHandlers {
     onUpdate?(notification: AcpSessionNotification): void;
     /** `signal`：该会话被 cancel、连接关闭时 abort（此时应尽快回 cancelled）。 */
@@ -30,6 +46,11 @@ export interface AcpClientHandlers {
      * `signal`：该会话被 cancel、连接关闭时 abort（此时回 `{ action: "cancel" }`，不必再答）。
      */
     onElicitation?(params: AcpElicitationParams, signal: AbortSignal): Promise<AcpElicitationResult>;
+    /**
+     * `elicitation/complete`：URL 型 elicitation 已在带外完成（`params.elicitationId` 对应此前
+     * `elicitation/create` 的同名字段），宿主据此收掉对应卡片。给了它，`initialize` 才声明 `elicitation.url`。
+     */
+    onElicitationComplete?(params: AcpCompleteElicitationParams): void;
     /**
      * `terminal/*`（create / output / wait_for_exit / kill / release）：宿主替 Agent 起终端。给了它才声明
      * `clientCapabilities.terminal: true` 并把这些请求交给它；`method` 是完整方法名，`params` 原样交回，返回值即
@@ -43,7 +64,14 @@ export interface AcpClientOptions extends AcpClientHandlers {
     input: NodeJS.ReadableStream;
     output: NodeJS.WritableStream;
     clientInfo?: AcpImplementationInfo;
+    /**
+     * 宿主能在交互终端里复现 Agent 的启动命令：声明 `clientCapabilities.auth.terminal`，Agent 才会在
+     * `authMethods` 里给 terminal 型方法。缺省不声明。
+     */
+    authTerminal?: boolean;
 }
+/** 错误是 ACP 的 auth_required（-32000）：开会话或发提示前需要先认证 / 登录。 */
+export declare function isAuthRequiredError(error: unknown): error is RpcError;
 /** 无人值守的回答：首个 reject_once，没有就 cancelled。 */
 export declare function unattendedOutcome(params: AcpRequestPermissionParams): AcpRequestPermissionResult;
 export declare class AcpClient {
@@ -53,19 +81,25 @@ export declare class AcpClient {
      * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
      * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
      * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`；
-     * - `terminal`：构造参数 `onTerminal` 接 `terminal/*`。
+     * - `terminal`：构造参数 `onTerminal` 接 `terminal/*`；
+     * - `auth`：`authenticate` / `logout`、构造参数 `authTerminal`、`isAuthRequiredError`；
+     * - `elicitationComplete`：构造参数 `onElicitationComplete` 接 `elicitation/complete`，表单字段含多选与 `oneOf`。
      */
     static readonly features: {
         readonly mcpServers: true;
         readonly elicitation: true;
         readonly configOptions: true;
         readonly terminal: true;
+        readonly auth: true;
+        readonly elicitationComplete: true;
     };
     private readonly peer;
     /** sessionId → 挂起权限请求的取消器。 */
     private readonly pendingPermissions;
     /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
     private readonly pendingElicitations;
+    /** elicitationId → 挂起 elicitation 的取消器（`elicitation/complete` 用）。 */
+    private readonly elicitationsById;
     private initResult;
     constructor(options: AcpClientOptions);
     get closed(): Promise<void>;
@@ -79,14 +113,27 @@ export declare class AcpClient {
     supportsLoad(): boolean;
     supportsList(): boolean;
     supportsClose(): boolean;
+    /** Agent 声明了 `auth.logout`（存在即支持）。 */
+    supportsLogout(): boolean;
     supportsImages(): boolean;
+    /**
+     * 用 agent 型认证方法登录（`methodId` 取自 `authMethods`）。terminal 型方法不经 `authenticate`：已知是
+     * terminal 型时抛 -32602，由宿主在终端里跑该方法的 `args` / `env`。失败的错误码原样抛出。
+     */
+    authenticate(methodId: string, signal?: AbortSignal): Promise<AcpAuthenticateResult>;
+    /** 登出当前账号；Agent 没声明 `auth.logout`（见 `supportsLogout`）时会答 method not found。 */
+    logout(signal?: AbortSignal): Promise<AcpLogoutResult>;
     newSession(cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpNewSessionResult>;
     /** 不回放历史（优先，R13：v2 计划取消 load）。 */
     resumeSession(sessionId: string, cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpLoadSessionResult>;
     /** 回放历史（以 session/update 通知）。 */
     loadSession(sessionId: string, cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpLoadSessionResult>;
-    listSessions(cwd?: string, cursor?: string): Promise<AcpListSessionsResult>;
-    closeSession(sessionId: string): Promise<unknown>;
+    /** 一页会话；`cwd` 过滤（绝对路径），`cursor` 取自上一页的 `nextCursor`。 */
+    listSessions(cwd?: string, cursor?: string, signal?: AbortSignal): Promise<AcpListSessionsResult>;
+    /** 跟 `nextCursor` 翻页取全（`maxPages` 防对端游标不终止，缺省 100 页）。 */
+    listAllSessions(cwd?: string, signal?: AbortSignal, maxPages?: number): Promise<AcpSessionInfo[]>;
+    /** 关闭会话：规范要求 Agent 先取消进行中的工作，所以本端先把该会话挂起的请求收掉。 */
+    closeSession(sessionId: string, signal?: AbortSignal): Promise<AcpCloseSessionResult>;
     prompt(sessionId: string, prompt: AcpContentBlock[], signal?: AbortSignal): Promise<AcpPromptResult>;
     setMode(sessionId: string, modeId: string): Promise<unknown>;
     /** 改一个会话配置项（如模型）；答复是全部配置项的新状态。 */
@@ -96,4 +143,6 @@ export declare class AcpClient {
     close(): void;
     private onRequest;
     private onElicitation;
+    /** 通知没有答复：参数不对就忽略；还挂着的同 id elicitation 先收掉，再交给宿主。 */
+    private onElicitationComplete;
 }

package/dist/drivers/acp/client.js

@@ -14,14 +14,33 @@
  * - `elicitation/create` 交给 `onElicitation`；给了它 `initialize` 才声明 `clientCapabilities.elicitation`，
  *   没给时线路与旧版相同（不声明，Agent 发来的请求回 method not found）。`cancel(sessionId)`、连接关闭时
  *   挂起的 elicitation 一律回 `{ action: "cancel" }`；ama 从不替人填表。
+ * - `elicitation/complete`（Agent → 客户端通知，URL 型 elicitation 在带外完成）交给 `onElicitationComplete`；给了它
+ *   `initialize` 声明 `elicitation: { form: {}, url: {} }`（只给 `onElicitation` 时仍是 `{}`，与旧版相同）。同一
+ *   `elicitationId` 若还挂着（处理器没答），它的 `signal` 随之 abort、答 `{ action: "cancel" }`，宿主据此收掉卡片。
+ *   表单字段含字符串多选（`type: "array"`）与带标题的 `oneOf` / `anyOf`，答复 `content` 里多选是字符串数组；
+ *   {@link multiSelectOptions} / {@link singleSelectOptions} 把两种写法收成统一的 `{ const, title }` 列表。
+ * - 会话管理：`listSessions(cwd?, cursor?, signal?)` 发 `session/list`（要 Agent 声明 `sessionCapabilities.list`，见
+ *   `supportsList`），`listAllSessions` 跟 `nextCursor` 翻页取全；`closeSession(sessionId, signal?)` 发 `session/close`
+ *   （`supportsClose`），按规范等同先取消：该会话挂起的权限请求答 `cancelled`、elicitation 答 `cancel`，再发请求。
+ *   没声明能力的 Agent 会答 -32601，开会话遇 -32000 同样原样抛出（{@link isAuthRequiredError}）。
  * - `setConfigOption(sessionId, configId, value)` 发 `session/set_config_option`；开会话答的 `configOptions`
  *   原样交回。`initialize` 声明 `clientCapabilities.session.configOptions: {}`（只认 select，不声明 boolean）；
- *   不声明 `auth.terminal`（ama 作客户端没有可借给 Agent 的交互终端）。[ACP-D]
+ *   `auth.terminal` 缺省不声明（ama 作客户端没有可借给 Agent 的交互终端），见下 `authTerminal`。[ACP-D]
+ * - 认证：`authenticate(methodId)` 发 `authenticate`（agent 型方法）、`logout()` 发 `logout`（Agent 声明
+ *   `auth.logout` 才可用，见 `supportsLogout`）；terminal 型方法规范禁止经 `authenticate`，已知是 terminal 型时本地
+ *   拒绝（-32602），宿主自己在终端里跑 `args` / `env`。构造参数 `authTerminal: true` 才在 `initialize` 声明
+ *   `clientCapabilities.auth.terminal`（宿主有交互终端可借；Agent 据此才给 terminal 型方法），缺省线路与旧版相同。
+ *   开会话遇 -32000（auth_required）用 {@link isAuthRequiredError} 判断，`authMethods` 保留 id / name / description / type
+ *   / args / env 原样。
  * - 线路两侧开 `$/cancel_request`：本端请求的 `signal` abort 时通知 Agent；Agent 撤回挂起的
  *   `session/request_permission` / `elicitation/create` 时处理器的 `signal` abort，回 cancelled / cancel。[ACP-D]
  */
 import { JsonRpcPeer, RpcError } from "../jsonrpc.js";
-import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./types.js";
+import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, isTerminalAuthMethod, } from "./types.js";
+/** 错误是 ACP 的 auth_required（-32000）：开会话或发提示前需要先认证 / 登录。 */
+export function isAuthRequiredError(error) {
+    return error instanceof RpcError && error.code === RPC_ERRORS.authRequired;
+}
 /** 开会话参数里的 `mcpServers`：拷一份，缺省空数组。 */
 function mcpServersOf(options) {
     return [...(options?.mcpServers ?? [])];
@@ -52,14 +71,25 @@ export class AcpClient {
      * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
      * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
      * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`；
-     * - `terminal`：构造参数 `onTerminal` 接 `terminal/*`。
+     * - `terminal`：构造参数 `onTerminal` 接 `terminal/*`；
+     * - `auth`：`authenticate` / `logout`、构造参数 `authTerminal`、`isAuthRequiredError`；
+     * - `elicitationComplete`：构造参数 `onElicitationComplete` 接 `elicitation/complete`，表单字段含多选与 `oneOf`。
      */
-    static features = { mcpServers: true, elicitation: true, configOptions: true, terminal: true };
+    static features = {
+        mcpServers: true,
+        elicitation: true,
+        configOptions: true,
+        terminal: true,
+        auth: true,
+        elicitationComplete: true,
+    };
     peer;
     /** sessionId → 挂起权限请求的取消器。 */
     pendingPermissions = new Map();
     /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
     pendingElicitations = new Map();
+    /** elicitationId → 挂起 elicitation 的取消器（`elicitation/complete` 用）。 */
+    elicitationsById = new Map();
     initResult;
     constructor(options) {
         this.options = options;
@@ -71,6 +101,8 @@ export class AcpClient {
             onNotification: (method, params) => {
                 if (method === ACP_METHODS.sessionUpdate)
                     options.onUpdate?.(params);
+                else if (method === ACP_METHODS.elicitationComplete)
+                    this.onElicitationComplete(params);
             },
             onClose: () => {
                 for (const set of this.pendingPermissions.values())
@@ -109,7 +141,12 @@ export class AcpClient {
                 fs: { readTextFile: false, writeTextFile: false },
                 terminal: this.options.onTerminal !== undefined,
                 session: { configOptions: {} },
-                ...(this.options.onElicitation !== undefined ? { elicitation: {} } : {}),
+                ...(this.options.authTerminal === true ? { auth: { terminal: true } } : {}),
+                ...(this.options.onElicitation !== undefined || this.options.onElicitationComplete
+                    ? {
+                        elicitation: this.options.onElicitationComplete !== undefined ? { form: {}, url: {} } : {},
+                    }
+                    : {}),
             },
             ...(this.options.clientInfo !== undefined ? { clientInfo: this.options.clientInfo } : {}),
         }, signal);
@@ -130,9 +167,27 @@ export class AcpClient {
     supportsClose() {
         return this.agentCapabilities.sessionCapabilities?.close != null;
     }
+    /** Agent 声明了 `auth.logout`（存在即支持）。 */
+    supportsLogout() {
+        return this.agentCapabilities.auth?.logout != null;
+    }
     supportsImages() {
         return this.agentCapabilities.promptCapabilities?.image === true;
     }
+    /**
+     * 用 agent 型认证方法登录（`methodId` 取自 `authMethods`）。terminal 型方法不经 `authenticate`：已知是
+     * terminal 型时抛 -32602，由宿主在终端里跑该方法的 `args` / `env`。失败的错误码原样抛出。
+     */
+    async authenticate(methodId, signal) {
+        const known = this.authMethods.find((method) => method.id === methodId);
+        if (known !== undefined && isTerminalAuthMethod(known))
+            throw new RpcError(RPC_ERRORS.invalidParams, `auth method ${methodId} is a terminal method: run it in a terminal, not through authenticate`);
+        return this.peer.request(ACP_METHODS.authenticate, { methodId }, signal);
+    }
+    /** 登出当前账号；Agent 没声明 `auth.logout`（见 `supportsLogout`）时会答 method not found。 */
+    logout(signal) {
+        return this.peer.request(ACP_METHODS.logout, {}, signal);
+    }
     newSession(cwd, signal, options) {
         return this.peer.request(ACP_METHODS.sessionNew, { cwd, mcpServers: mcpServersOf(options) }, signal);
     }
@@ -144,14 +199,33 @@ export class AcpClient {
     loadSession(sessionId, cwd, signal, options) {
         return this.peer.request(ACP_METHODS.sessionLoad, { sessionId, cwd, mcpServers: mcpServersOf(options) }, signal);
     }
-    listSessions(cwd, cursor) {
+    /** 一页会话；`cwd` 过滤（绝对路径），`cursor` 取自上一页的 `nextCursor`。 */
+    listSessions(cwd, cursor, signal) {
         return this.peer.request(ACP_METHODS.sessionList, {
             ...(cwd !== undefined ? { cwd } : {}),
             ...(cursor !== undefined ? { cursor } : {}),
-        });
+        }, signal);
+    }
+    /** 跟 `nextCursor` 翻页取全（`maxPages` 防对端游标不终止，缺省 100 页）。 */
+    async listAllSessions(cwd, signal, maxPages = 100) {
+        const sessions = [];
+        let cursor;
+        for (let page = 0; page < maxPages; page++) {
+            const result = await this.listSessions(cwd, cursor, signal);
+            sessions.push(...(result.sessions ?? []));
+            if (typeof result.nextCursor !== "string" || result.nextCursor === "")
+                break;
+            cursor = result.nextCursor;
+        }
+        return sessions;
     }
-    closeSession(sessionId) {
-        return this.peer.request(ACP_METHODS.sessionClose, { sessionId });
+    /** 关闭会话：规范要求 Agent 先取消进行中的工作，所以本端先把该会话挂起的请求收掉。 */
+    closeSession(sessionId, signal) {
+        for (const controller of this.pendingPermissions.get(sessionId) ?? [])
+            controller.abort();
+        for (const controller of this.pendingElicitations.get(sessionId) ?? [])
+            controller.abort();
+        return this.peer.request(ACP_METHODS.sessionClose, { sessionId }, signal);
     }
     prompt(sessionId, prompt, signal) {
         return this.peer.request(ACP_METHODS.sessionPrompt, { sessionId, prompt }, signal);
@@ -225,6 +299,9 @@ export class AcpClient {
         const set = this.pendingElicitations.get(key) ?? new Set();
         set.add(controller);
         this.pendingElicitations.set(key, set);
+        const id = typeof request.elicitationId === "string" ? request.elicitationId : undefined;
+        if (id !== undefined)
+            this.elicitationsById.set(id, controller);
         const signal = AbortSignal.any([controller.signal, connection]);
         try {
             const answer = await Promise.race([
@@ -243,6 +320,16 @@ export class AcpClient {
         }
         finally {
             set.delete(controller);
+            if (id !== undefined && this.elicitationsById.get(id) === controller)
+                this.elicitationsById.delete(id);
         }
     }
+    /** 通知没有答复：参数不对就忽略；还挂着的同 id elicitation 先收掉，再交给宿主。 */
+    onElicitationComplete(params) {
+        const id = params?.elicitationId;
+        if (typeof id !== "string")
+            return;
+        this.elicitationsById.get(id)?.abort();
+        this.options.onElicitationComplete?.(params);
+    }
 }

package/dist/drivers/acp/types.d.ts

@@ -14,8 +14,10 @@ export declare const ACP_PROTOCOL_VERSION: 1;
 /** 方法名（客户端 → Agent 的请求 / 通知，Agent → 客户端的请求 / 通知）。 */
 export declare const ACP_METHODS: {
     readonly initialize: "initialize";
-    /** ama 不实现（只给 terminal 型认证方法，规范要求这类方法不经 authenticate）。 */
+    /** 客户端 → Agent：agent 型认证方法经它完成；terminal 型不经它（规范）。 */
     readonly authenticate: "authenticate";
+    /** 客户端 → Agent：登出当前账号（Agent 声明 `agentCapabilities.auth.logout` 才可用）。 */
+    readonly logout: "logout";
     readonly sessionNew: "session/new";
     readonly sessionLoad: "session/load";
     readonly sessionResume: "session/resume";
@@ -28,6 +30,8 @@ export declare const ACP_METHODS: {
     readonly sessionUpdate: "session/update";
     readonly requestPermission: "session/request_permission";
     readonly elicitationCreate: "elicitation/create";
+    /** Agent → 客户端通知：URL 型 elicitation 已在带外完成。 */
+    readonly elicitationComplete: "elicitation/complete";
     /** 协议级取消（双向通知，`requestId` 指对端发来的、尚未答复的请求）。 */
     readonly cancelRequest: "$/cancel_request";
 };
@@ -93,6 +97,7 @@ export interface AcpClientCapabilities {
         } | null;
     } | null;
     /** `terminal: true`：客户端能替 Agent 起终端跑 terminal 型认证方法。 */
+    /** 能在交互终端里复现 Agent 的启动命令；声明后 Agent 才会给 terminal 型认证方法。 */
     auth?: {
         terminal?: boolean;
     };
@@ -144,6 +149,19 @@ export type AcpAuthMethod = {
 export interface AcpAuthenticateParams {
     methodId: string;
 }
+/** `authenticate` / `logout` 的答复：规范里只有 `_meta`。 */
+export type AcpAuthenticateResult = {
+    _meta?: Record<string, unknown> | null;
+};
+export type AcpLogoutResult = {
+    _meta?: Record<string, unknown> | null;
+};
+/** terminal 型认证方法（客户端在终端里跑 `<agent 命令> <args…>`，带 `env`）。 */
+export type AcpTerminalAuthMethod = Extract<AcpAuthMethod, {
+    type: "terminal";
+}>;
+/** 是 terminal 型认证方法：这类方法不经 `authenticate`。 */
+export declare function isTerminalAuthMethod(method: AcpAuthMethod): method is AcpTerminalAuthMethod;
 export interface AcpInitializeResult {
     protocolVersion: number;
     agentCapabilities?: AcpAgentCapabilities;
@@ -234,14 +252,23 @@ export interface AcpSetConfigOptionParams {
 export interface AcpSetConfigOptionResult {
     configOptions?: AcpSessionConfigOption[] | null;
 }
-/** 表单里的一个字段：扁平的原始类型，规范只允许这几种。 */
+/** 带标题的枚举项（`oneOf` / `anyOf` 里的一项）：`const` 是提交的值，`title` 是显示名。 */
+export interface AcpEnumOption {
+    const: string;
+    title: string;
+}
+/** 表单里的一个字段：扁平的原始类型或字符串多选，规范只允许这几种；未知 `type` 保留原样、不当已知控件渲染。 */
 export type AcpElicitationField = {
     type: "string";
     title?: string;
     description?: string;
+    /** 单选：只有取值。 */
     enum?: string[];
     enumNames?: string[];
+    /** 单选：带标题的取值（`const` / `title`）。 */
+    oneOf?: AcpEnumOption[];
     format?: string;
+    pattern?: string;
     minLength?: number;
     maxLength?: number;
     default?: string;
@@ -257,7 +284,27 @@ export type AcpElicitationField = {
     title?: string;
     description?: string;
     default?: boolean;
+} | {
+    /** 字符串多选：提交值是 `string[]`。 */
+    type: "array";
+    title?: string;
+    description?: string;
+    minItems?: number;
+    maxItems?: number;
+    /** `{ type: "string", enum }`（只有取值）或 `{ anyOf: [{ const, title }] }`（带标题）。 */
+    items: {
+        type?: "string";
+        enum?: string[];
+        anyOf?: AcpEnumOption[];
+    };
+    default?: string[];
 };
+/** 表单字段的提交值：多选是字符串数组。 */
+export type AcpElicitationValue = string | number | boolean | string[];
+/** 多选字段可选的项：带标题的 `anyOf` 或只有取值的 `enum`（标题取值本身）；不是多选字段返回 undefined。 */
+export declare function multiSelectOptions(field: AcpElicitationField): AcpEnumOption[] | undefined;
+/** 单选字符串字段可选的项：`oneOf`（带标题）优先，其次 `enum`（可配 `enumNames`）；没有枚举返回 undefined。 */
+export declare function singleSelectOptions(field: AcpElicitationField): AcpEnumOption[] | undefined;
 export interface AcpElicitationSchema {
     type: "object";
     properties: Record<string, AcpElicitationField>;
@@ -266,6 +313,12 @@ export interface AcpElicitationSchema {
 /** Agent 发来的 `elicitation/create` 参数；未知字段保留。 */
 export interface AcpElicitationParams {
     sessionId?: string;
+    /** 关联的工具调用（会话范围的 elicitation 可带）。 */
+    toolCallId?: string | null;
+    /** 不在会话里时关联的请求 id（请求范围）。 */
+    requestId?: string | number;
+    /** URL 型 elicitation 的 id；之后 Agent 以 `elicitation/complete` 通知它在带外完成。 */
+    elicitationId?: string;
     message: string;
     /** `form`（缺省）或 `url`。 */
     mode?: "form" | "url" | (string & {});
@@ -273,11 +326,16 @@ export interface AcpElicitationParams {
     url?: string;
     [key: string]: unknown;
 }
+/** `elicitation/complete` 通知的参数：URL 型 elicitation 已完成。 */
+export interface AcpCompleteElicitationParams {
+    elicitationId: string;
+    _meta?: Record<string, unknown> | null;
+}
 export type AcpElicitationAction = "accept" | "decline" | "cancel";
 export interface AcpElicitationResult {
     action: AcpElicitationAction;
     /** 只随 `accept`。 */
-    content?: Record<string, string | number | boolean>;
+    content?: Record<string, AcpElicitationValue>;
 }
 export type AcpResumeSessionParams = AcpLoadSessionParams;
 export type AcpResumeSessionResult = AcpLoadSessionResult;
@@ -288,8 +346,12 @@ export interface AcpListSessionsParams {
 export interface AcpSessionInfo {
     sessionId: string;
     cwd: string;
+    /** Agent 报告的额外工作区根（绝对路径）；缺省与空数组等价。 */
+    additionalDirectories?: string[];
     title?: string | null;
+    /** ISO 8601 的最近活动时间。 */
     updatedAt?: string | null;
+    _meta?: Record<string, unknown> | null;
 }
 export interface AcpListSessionsResult {
     sessions: AcpSessionInfo[];
@@ -298,6 +360,10 @@ export interface AcpListSessionsResult {
 export interface AcpCloseSessionParams {
     sessionId: string;
 }
+/** `session/close` 的答复：规范里只有 `_meta`。 */
+export type AcpCloseSessionResult = {
+    _meta?: Record<string, unknown> | null;
+};
 export interface AcpSetModeParams {
     sessionId: string;
     modeId: string;

package/dist/drivers/acp/types.js

@@ -13,8 +13,10 @@ export const ACP_PROTOCOL_VERSION = 1;
 /** 方法名（客户端 → Agent 的请求 / 通知，Agent → 客户端的请求 / 通知）。 */
 export const ACP_METHODS = {
     initialize: "initialize",
-    /** ama 不实现（只给 terminal 型认证方法，规范要求这类方法不经 authenticate）。 */
+    /** 客户端 → Agent：agent 型认证方法经它完成；terminal 型不经它（规范）。 */
     authenticate: "authenticate",
+    /** 客户端 → Agent：登出当前账号（Agent 声明 `agentCapabilities.auth.logout` 才可用）。 */
+    logout: "logout",
     sessionNew: "session/new",
     sessionLoad: "session/load",
     sessionResume: "session/resume",
@@ -27,6 +29,8 @@ export const ACP_METHODS = {
     sessionUpdate: "session/update",
     requestPermission: "session/request_permission",
     elicitationCreate: "elicitation/create",
+    /** Agent → 客户端通知：URL 型 elicitation 已在带外完成。 */
+    elicitationComplete: "elicitation/complete",
     /** 协议级取消（双向通知，`requestId` 指对端发来的、尚未答复的请求）。 */
     cancelRequest: "$/cancel_request",
 };
@@ -42,5 +46,30 @@ export const RPC_ERRORS = {
     /** 请求被 `$/cancel_request` 撤回。 */
     requestCancelled: -32800,
 };
+/** 是 terminal 型认证方法：这类方法不经 `authenticate`。 */
+export function isTerminalAuthMethod(method) {
+    return method.type === "terminal";
+}
+/** 多选字段可选的项：带标题的 `anyOf` 或只有取值的 `enum`（标题取值本身）；不是多选字段返回 undefined。 */
+export function multiSelectOptions(field) {
+    if (field.type !== "array")
+        return undefined;
+    const items = field.items;
+    if (Array.isArray(items?.anyOf))
+        return items.anyOf.map((o) => ({ const: o.const, title: o.title }));
+    if (Array.isArray(items?.enum))
+        return items.enum.map((value) => ({ const: value, title: value }));
+    return undefined;
+}
+/** 单选字符串字段可选的项：`oneOf`（带标题）优先，其次 `enum`（可配 `enumNames`）；没有枚举返回 undefined。 */
+export function singleSelectOptions(field) {
+    if (field.type !== "string")
+        return undefined;
+    if (Array.isArray(field.oneOf))
+        return field.oneOf.map((o) => ({ const: o.const, title: o.title }));
+    if (Array.isArray(field.enum))
+        return field.enum.map((value, i) => ({ const: value, title: field.enumNames?.[i] ?? value }));
+    return undefined;
+}
 /** ama 自己的 `_meta` 命名空间（客户端不得假设其含义）。 */
 export const ACP_META_KEY = "ama";

package/dist/drivers/agents.js

@@ -82,7 +82,7 @@ export class ExternalAgents {
     }
     /** `task(agent=<spec>)` 的 runner；不可用时抛 AmaError（`agent_host_only` / `agent_unknown`）。 */
     resolve(spec) {
-        const hosted = this.hostRunners.get(spec);
+        const hosted = this.hostRunners.resolve(spec);
         if (hosted !== undefined)
             return hosted;
         if (this.options.hosted)

package/dist/drivers/host-runners.d.ts

@@ -4,15 +4,40 @@
  * 一个宿主适配器一份（host/api-impl.ts 建，经 {@link ExternalAgents} 的 `hostRunners` 选项交给每个
  * 主会话）：宿主可以在 `create()` 里或之后任何时候 `provide`，同名替换；返回的函数注销。
  * `onChange` 供 `/agents` / RPC `get_agents` 的缓存刷新。
+ *
+ * [#226] `onDone`（`HostApi.runners.onDone`）：任务入口经 {@link HostRunnerRegistry.resolve} 拿到的是
+ * 观察包装——句柄的每一轮（`start` 之后、每次 `send` / `interrupt` / `message` 之后）在 `wait()` 落定时
+ * 发一次 {@link RunnerDoneEvent}。包装只观察：`wait()` 的结果与异常原样返回，其余成员原样转给宿主句柄；
+ * 同一轮里多次 `wait()` 只发一次，落定后没有新一轮的 `wait()` 不再发。
  */
-import type { HostRunner } from "../host/types.js";
+import type { HostRunner, RunnerDoneEvent } from "../host/types.js";
+export type RunnerDoneHandler = (event: RunnerDoneEvent) => void | Promise<void>;
+export interface HostRunnerRegistryOptions {
+    /** 毫秒时钟（测试注入）。 */
+    now?: () => number;
+    /** `onDone` 处理器异常的去处；缺省丢弃。 */
+    log?: (message: string, error: unknown) => void;
+}
 export declare class HostRunnerRegistry {
     private readonly runners;
     private readonly listeners;
+    private readonly doneHandlers;
+    private readonly observed;
+    private readonly now;
+    private readonly log;
+    constructor(options?: HostRunnerRegistryOptions);
     provide(runner: HostRunner): () => void;
     get(id: string): HostRunner | undefined;
+    /** [#226] 任务入口用：同 {@link get}，但返回发 `onDone` 的观察包装（同一 runner 包装复用）。 */
+    resolve(id: string): HostRunner | undefined;
     list(): HostRunner[];
     /** 注入 / 注销时回调；返回取消订阅。 */
     onChange(listener: () => void): () => void;
+    /** [#226] 每轮结束时回调（`HostApi.runners.onDone`）；返回注销函数。 */
+    onDone(handler: RunnerDoneHandler): () => void;
     private changed;
+    private emitDone;
+    private fail;
+    private observe;
+    private observeHandle;
 }