@armadra/agent 0.6.7 → 0.6.8

package/CHANGELOG.md

@@ -5,6 +5,15 @@ English · [简体中文](CHANGELOG.zh-CN.md)
 > This file is in English starting with 0.6.0. Release notes for 0.1 through 0.5.1 are in Chinese in
 > [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md). New entries go into both files.
 
+## 0.6.8 (2026-10-04)
+
+- **ACP client: elicitation and session config options**: `AcpClient` takes an optional `onElicitation(params, signal)`;
+  when given, `initialize` declares `clientCapabilities.elicitation` and `elicitation/create` goes to it (answers normalized
+  to `accept` / `decline` / `cancel`; pending ones resolve `cancel` on `cancel(sessionId)` or connection close). New
+  `setConfigOption(sessionId, configId, value)` and `configOptions` on session-open results. `AcpClient.features` gains
+  `elicitation` and `configOptions`. Without a handler the wire is unchanged. The fake ACP agent adds `[elicit]`, `[model]`
+  and `[env NAME]` markers and `--config-options`. Docs: docs/acp.md.
+
 ## 0.6.7 (2026-10-03)
 
 - **A host runner with id `ama` is used**: when the host registers a runner for `ama` via `HostApi.runners.provide`

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,14 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.6.8（2026-10-04）
+
+- **ACP 客户端：elicitation 与会话配置项**：`AcpClient` 可选构造参数 `onElicitation(params, signal)`，给了才在 `initialize`
+  声明 `clientCapabilities.elicitation` 并把 `elicitation/create` 交给它（答复收成 `accept` / `decline` / `cancel`；
+  `cancel(sessionId)` 或连接关闭时挂起的回 `cancel`）。新增 `setConfigOption(sessionId, configId, value)`，开会话答复带
+  `configOptions`。`AcpClient.features` 多 `elicitation` 与 `configOptions`。不给处理器时线路不变。假 ACP Agent 加
+  `[elicit]`、`[model]`、`[env NAME]` 标记与 `--config-options`。文档：docs/acp.md。
+
 ## 0.6.7（2026-10-03）
 
 - **宿主注入的 `ama` runner 生效**：宿主经 `HostApi.runners.provide` 注入 id 为 `ama` 的 runner（如 Armadra 画布上另一个

package/dist/bundle/ama.cjs

@@ -41,7 +41,7 @@ var AMA_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    AMA_VERSION = true ? "0.6.7" : readPackageVersion();
+    AMA_VERSION = true ? "0.6.8" : readPackageVersion();
   }
 });
 
@@ -30592,8 +30592,10 @@ var init_types9 = __esm({
       sessionPrompt: "session/prompt",
       sessionCancel: "session/cancel",
       sessionSetMode: "session/set_mode",
+      sessionSetConfigOption: "session/set_config_option",
       sessionUpdate: "session/update",
-      requestPermission: "session/request_permission"
+      requestPermission: "session/request_permission",
+      elicitationCreate: "elicitation/create"
     };
     RPC_ERRORS = {
       parseError: -32700,
@@ -30790,18 +30792,25 @@ var init_jsonrpc = __esm({
 function mcpServersOf(options) {
   return [...options?.mcpServers ?? []];
 }
+function elicitationAnswer(answer) {
+  const action = answer?.action;
+  if (action === void 0 || !ELICITATION_ACTIONS.has(action)) return { action: "cancel" };
+  if (action !== "accept" || answer?.content === void 0) return { action };
+  return { action, content: answer.content };
+}
 function unattendedOutcome(params) {
   const reject2 = params.options.find((o) => o.kind === "reject_once");
   return {
     outcome: reject2 !== void 0 ? { outcome: "selected", optionId: reject2.optionId } : { outcome: "cancelled" }
   };
 }
-var AcpClient;
+var ELICITATION_ACTIONS, AcpClient;
 var init_client = __esm({
   "src/drivers/acp/client.ts"() {
     "use strict";
     init_jsonrpc();
     init_types9();
+    ELICITATION_ACTIONS = /* @__PURE__ */ new Set(["accept", "decline", "cancel"]);
     AcpClient = class {
       constructor(options) {
         this.options = options;
@@ -30815,6 +30824,7 @@ var init_client = __esm({
           },
           onClose: () => {
             for (const set of this.pendingPermissions.values()) for (const c of set) c.abort();
+            for (const set of this.pendingElicitations.values()) for (const c of set) c.abort();
             options.onClose?.();
           },
           ...options.onProtocolError !== void 0 ? { onProtocolError: options.onProtocolError } : {}
@@ -30822,13 +30832,17 @@ var init_client = __esm({
       }
       options;
       /**
-       * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
-       * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+       * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段，旧一点的只有 `mcpServers`）：
+       * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
+       * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
+       * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`。
        */
-      static features = { mcpServers: true };
+      static features = { mcpServers: true, elicitation: true, configOptions: true };
       peer;
       /** sessionId → 挂起权限请求的取消器。 */
       pendingPermissions = /* @__PURE__ */ new Map();
+      /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
+      pendingElicitations = /* @__PURE__ */ new Map();
       initResult;
       get closed() {
         return this.peer.closed;
@@ -30847,7 +30861,11 @@ var init_client = __esm({
           ACP_METHODS.initialize,
           {
             protocolVersion: ACP_PROTOCOL_VERSION,
-            clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+            clientCapabilities: {
+              fs: { readTextFile: false, writeTextFile: false },
+              terminal: false,
+              ...this.options.onElicitation !== void 0 ? { elicitation: {} } : {}
+            },
             ...this.options.clientInfo !== void 0 ? { clientInfo: this.options.clientInfo } : {}
           },
           signal
@@ -30913,15 +30931,22 @@ var init_client = __esm({
       setMode(sessionId, modeId) {
         return this.peer.request(ACP_METHODS.sessionSetMode, { sessionId, modeId });
       }
-      /** 协议级取消：发通知，并让挂起的权限请求回 cancelled。 */
+      /** 改一个会话配置项（如模型）；答复是全部配置项的新状态。 */
+      setConfigOption(sessionId, configId, value) {
+        return this.peer.request(ACP_METHODS.sessionSetConfigOption, { sessionId, configId, value });
+      }
+      /** 协议级取消：发通知，并让挂起的权限请求回 cancelled、挂起的 elicitation 回 cancel。 */
       async cancel(sessionId) {
         for (const controller of this.pendingPermissions.get(sessionId) ?? []) controller.abort();
+        for (const controller of this.pendingElicitations.get(sessionId) ?? []) controller.abort();
         await this.peer.notify(ACP_METHODS.sessionCancel, { sessionId });
       }
       close() {
         this.peer.close();
       }
       async onRequest(method, params, connection) {
+        if (method === ACP_METHODS.elicitationCreate && this.options.onElicitation !== void 0)
+          return this.onElicitation(params, connection);
         if (method !== ACP_METHODS.requestPermission)
           throw new RpcError(RPC_ERRORS.methodNotFound, `client does not support ${method}`);
         const request = params;
@@ -30953,6 +30978,32 @@ var init_client = __esm({
           set.delete(controller);
         }
       }
+      async onElicitation(params, connection) {
+        const request = params;
+        if (request === null || typeof request !== "object" || typeof request.message !== "string")
+          throw new RpcError(RPC_ERRORS.invalidParams, "invalid elicitation/create params");
+        const handler = this.options.onElicitation;
+        const key = typeof request.sessionId === "string" ? request.sessionId : "";
+        const controller = new AbortController();
+        const set = this.pendingElicitations.get(key) ?? /* @__PURE__ */ new Set();
+        set.add(controller);
+        this.pendingElicitations.set(key, set);
+        const signal = AbortSignal.any([controller.signal, connection]);
+        try {
+          const answer = await Promise.race([
+            handler(request, signal),
+            new Promise((resolve39) => {
+              const cancelled = () => resolve39({ action: "cancel" });
+              if (signal.aborted) cancelled();
+              else signal.addEventListener("abort", cancelled, { once: true });
+            })
+          ]);
+          if (signal.aborted) return { action: "cancel" };
+          return elicitationAnswer(answer);
+        } finally {
+          set.delete(controller);
+        }
+      }
     };
   }
 });

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

@@ -10,12 +10,22 @@
  *   （规范要求：客户端取消回合后必须以 cancelled 回答挂起的请求）。
  * - 开会话（new / resume / load）的 `mcpServers` 缺省为空数组；宿主可经 {@link AcpSessionOptions}
  *   传入，原样转发。
+ * - `elicitation/create` 交给 `onElicitation`；给了它 `initialize` 才声明 `clientCapabilities.elicitation`，
+ *   没给时线路与旧版相同（不声明，Agent 发来的请求回 method not found）。`cancel(sessionId)`、连接关闭时
+ *   挂起的 elicitation 一律回 `{ action: "cancel" }`；ama 从不替人填表。
+ * - `setConfigOption(sessionId, configId, value)` 发 `session/set_config_option`；开会话答的 `configOptions`
+ *   原样交回。
  */
-import { type AcpAgentCapabilities, type AcpContentBlock, type AcpImplementationInfo, type AcpInitializeResult, type AcpListSessionsResult, type AcpLoadSessionResult, type AcpNewSessionResult, type AcpPromptResult, type AcpRequestPermissionParams, type AcpRequestPermissionResult, type AcpSessionNotification, type AcpSessionOptions } from "./types.js";
+import { type AcpAgentCapabilities, 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";
 export interface AcpClientHandlers {
     onUpdate?(notification: AcpSessionNotification): void;
     /** `signal`：该会话被 cancel、连接关闭时 abort（此时应尽快回 cancelled）。 */
     onPermission?(params: AcpRequestPermissionParams, signal: AbortSignal): Promise<AcpRequestPermissionResult>;
+    /**
+     * `elicitation/create`：Agent 向人要结构化输入。给了它才声明 `clientCapabilities.elicitation`。
+     * `signal`：该会话被 cancel、连接关闭时 abort（此时回 `{ action: "cancel" }`，不必再答）。
+     */
+    onElicitation?(params: AcpElicitationParams, signal: AbortSignal): Promise<AcpElicitationResult>;
     onProtocolError?(line: string, reason: string): void;
     onClose?(): void;
 }
@@ -29,15 +39,21 @@ export declare function unattendedOutcome(params: AcpRequestPermissionParams): A
 export declare class AcpClient {
     private readonly options;
     /**
-     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
-     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段，旧一点的只有 `mcpServers`）：
+     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
+     * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
+     * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`。
      */
     static readonly features: {
         readonly mcpServers: true;
+        readonly elicitation: true;
+        readonly configOptions: true;
     };
     private readonly peer;
     /** sessionId → 挂起权限请求的取消器。 */
     private readonly pendingPermissions;
+    /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
+    private readonly pendingElicitations;
     private initResult;
     constructor(options: AcpClientOptions);
     get closed(): Promise<void>;
@@ -59,8 +75,11 @@ export declare class AcpClient {
     closeSession(sessionId: string): Promise<unknown>;
     prompt(sessionId: string, prompt: AcpContentBlock[], signal?: AbortSignal): Promise<AcpPromptResult>;
     setMode(sessionId: string, modeId: string): Promise<unknown>;
-    /** 协议级取消：发通知，并让挂起的权限请求回 cancelled。 */
+    /** 改一个会话配置项（如模型）；答复是全部配置项的新状态。 */
+    setConfigOption(sessionId: string, configId: string, value: string): Promise<AcpSetConfigOptionResult>;
+    /** 协议级取消：发通知，并让挂起的权限请求回 cancelled、挂起的 elicitation 回 cancel。 */
     cancel(sessionId: string): Promise<void>;
     close(): void;
     private onRequest;
+    private onElicitation;
 }

package/dist/drivers/acp/client.js

@@ -10,6 +10,11 @@
  *   （规范要求：客户端取消回合后必须以 cancelled 回答挂起的请求）。
  * - 开会话（new / resume / load）的 `mcpServers` 缺省为空数组；宿主可经 {@link AcpSessionOptions}
  *   传入，原样转发。
+ * - `elicitation/create` 交给 `onElicitation`；给了它 `initialize` 才声明 `clientCapabilities.elicitation`，
+ *   没给时线路与旧版相同（不声明，Agent 发来的请求回 method not found）。`cancel(sessionId)`、连接关闭时
+ *   挂起的 elicitation 一律回 `{ action: "cancel" }`；ama 从不替人填表。
+ * - `setConfigOption(sessionId, configId, value)` 发 `session/set_config_option`；开会话答的 `configOptions`
+ *   原样交回。
  */
 import { JsonRpcPeer, RpcError } from "../jsonrpc.js";
 import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./types.js";
@@ -17,6 +22,16 @@ import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./types.js";
 function mcpServersOf(options) {
     return [...(options?.mcpServers ?? [])];
 }
+const ELICITATION_ACTIONS = new Set(["accept", "decline", "cancel"]);
+/** 处理器的答复收成规范形状：动作不认识当 cancel，`content` 只随 accept。 */
+function elicitationAnswer(answer) {
+    const action = answer?.action;
+    if (action === undefined || !ELICITATION_ACTIONS.has(action))
+        return { action: "cancel" };
+    if (action !== "accept" || answer?.content === undefined)
+        return { action };
+    return { action, content: answer.content };
+}
 /** 无人值守的回答：首个 reject_once，没有就 cancelled。 */
 export function unattendedOutcome(params) {
     const reject = params.options.find((o) => o.kind === "reject_once");
@@ -29,13 +44,17 @@ export function unattendedOutcome(params) {
 export class AcpClient {
     options;
     /**
-     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
-     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段，旧一点的只有 `mcpServers`）：
+     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
+     * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
+     * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`。
      */
-    static features = { mcpServers: true };
+    static features = { mcpServers: true, elicitation: true, configOptions: true };
     peer;
     /** sessionId → 挂起权限请求的取消器。 */
     pendingPermissions = new Map();
+    /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
+    pendingElicitations = new Map();
     initResult;
     constructor(options) {
         this.options = options;
@@ -51,6 +70,9 @@ export class AcpClient {
                 for (const set of this.pendingPermissions.values())
                     for (const c of set)
                         c.abort();
+                for (const set of this.pendingElicitations.values())
+                    for (const c of set)
+                        c.abort();
                 options.onClose?.();
             },
             ...(options.onProtocolError !== undefined
@@ -73,7 +95,11 @@ export class AcpClient {
     async initialize(signal) {
         const result = await this.peer.request(ACP_METHODS.initialize, {
             protocolVersion: ACP_PROTOCOL_VERSION,
-            clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+            clientCapabilities: {
+                fs: { readTextFile: false, writeTextFile: false },
+                terminal: false,
+                ...(this.options.onElicitation !== undefined ? { elicitation: {} } : {}),
+            },
             ...(this.options.clientInfo !== undefined ? { clientInfo: this.options.clientInfo } : {}),
         }, signal);
         if (result.protocolVersion !== ACP_PROTOCOL_VERSION)
@@ -122,16 +148,24 @@ export class AcpClient {
     setMode(sessionId, modeId) {
         return this.peer.request(ACP_METHODS.sessionSetMode, { sessionId, modeId });
     }
-    /** 协议级取消：发通知，并让挂起的权限请求回 cancelled。 */
+    /** 改一个会话配置项（如模型）；答复是全部配置项的新状态。 */
+    setConfigOption(sessionId, configId, value) {
+        return this.peer.request(ACP_METHODS.sessionSetConfigOption, { sessionId, configId, value });
+    }
+    /** 协议级取消：发通知，并让挂起的权限请求回 cancelled、挂起的 elicitation 回 cancel。 */
     async cancel(sessionId) {
         for (const controller of this.pendingPermissions.get(sessionId) ?? [])
             controller.abort();
+        for (const controller of this.pendingElicitations.get(sessionId) ?? [])
+            controller.abort();
         await this.peer.notify(ACP_METHODS.sessionCancel, { sessionId });
     }
     close() {
         this.peer.close();
     }
     async onRequest(method, params, connection) {
+        if (method === ACP_METHODS.elicitationCreate && this.options.onElicitation !== undefined)
+            return this.onElicitation(params, connection);
         if (method !== ACP_METHODS.requestPermission)
             throw new RpcError(RPC_ERRORS.methodNotFound, `client does not support ${method}`);
         const request = params;
@@ -168,4 +202,34 @@ export class AcpClient {
             set.delete(controller);
         }
     }
+    async onElicitation(params, connection) {
+        const request = params;
+        if (request === null || typeof request !== "object" || typeof request.message !== "string")
+            throw new RpcError(RPC_ERRORS.invalidParams, "invalid elicitation/create params");
+        const handler = this.options.onElicitation;
+        const key = typeof request.sessionId === "string" ? request.sessionId : "";
+        const controller = new AbortController();
+        const set = this.pendingElicitations.get(key) ?? new Set();
+        set.add(controller);
+        this.pendingElicitations.set(key, set);
+        const signal = AbortSignal.any([controller.signal, connection]);
+        try {
+            const answer = await Promise.race([
+                handler(request, signal),
+                new Promise((resolve) => {
+                    const cancelled = () => resolve({ action: "cancel" });
+                    if (signal.aborted)
+                        cancelled();
+                    else
+                        signal.addEventListener("abort", cancelled, { once: true });
+                }),
+            ]);
+            if (signal.aborted)
+                return { action: "cancel" };
+            return elicitationAnswer(answer);
+        }
+        finally {
+            set.delete(controller);
+        }
+    }
 }

package/dist/drivers/acp/testing/fake-agent-main.d.ts

@@ -1,5 +1,5 @@
 /**
- * 假 ACP Agent 的进程入口：`node dist/drivers/acp/testing/fake-agent-main.js [--minimal]`。[W5-E]
+ * 假 ACP Agent 的进程入口：`node dist/drivers/acp/testing/fake-agent-main.js [--minimal] [--config-options]`。[W5-E]
  * 行为见 fake-agent.ts；stdin 结束即退出。
  */
 export {};

package/dist/drivers/acp/testing/fake-agent-main.js

@@ -1,7 +1,8 @@
 /**
- * 假 ACP Agent 的进程入口：`node dist/drivers/acp/testing/fake-agent-main.js [--minimal]`。[W5-E]
+ * 假 ACP Agent 的进程入口：`node dist/drivers/acp/testing/fake-agent-main.js [--minimal] [--config-options]`。[W5-E]
  * 行为见 fake-agent.ts；stdin 结束即退出。
  */
 import { runFakeAcpAgent } from "./fake-agent.js";
 const minimal = process.argv.includes("--minimal");
-void runFakeAcpAgent(process.stdin, process.stdout, { minimal }).then(() => process.exit(0));
+const configOptions = process.argv.includes("--config-options");
+void runFakeAcpAgent(process.stdin, process.stdout, { minimal, configOptions }).then(() => process.exit(0));

package/dist/drivers/acp/testing/fake-agent.d.ts

@@ -13,6 +13,13 @@
  * | `[plan]`         | 先发 `plan`（两条）再回文本                                                      |
  * | `[think]`        | 先发 `agent_thought_chunk`                                                        |
  * | `[refuse]`       | `refusal`                                                                         |
+ * | `[elicit]`       | `elicitation/create`（选颜色的表单）→ 回 `elicit: <action> <content JSON>`；客户端    |
+ * |                  | 没声明 `elicitation` 能力时回 `elicit: unsupported`；`cancel` 时本回合 `cancelled` |
+ * | `[model]`        | 回 `model <当前模型>`（`configOptions` 关着时是 `model none`）                     |
+ * | `[env NAME]`     | 回 `env NAME <值的 sha256 | absent>`（测环境变量到没到，不回显值）                  |
+ *
+ * `configOptions: true`（可执行入口 `--config-options`）：开会话答一个 `model` 配置项（`small`，分组
+ * `big` 里有 `large`），`session/set_config_option` 可改；缺省不答，线路与之前相同。
  *
  * 会话：`session/new` 发 `fake-<n>`；`session/resume` / `session/load` 接受任何 `fake-` 开头的 id
  * （load 先回放一条用户消息与一条回复）；`session/list` 列本进程建过的会话。
@@ -22,6 +29,8 @@ export interface FakeAcpAgentOptions {
     name?: string;
     /** 不声明 resume / list / close / loadSession（测降级路径）。 */
     minimal?: boolean;
+    /** 开会话答 `configOptions`（一个 `model` 选择项）并接 `session/set_config_option`。 */
+    configOptions?: boolean;
 }
 /** 在给定流上跑假 Agent；输入流结束时 resolve。 */
 export declare function runFakeAcpAgent(input: NodeJS.ReadableStream, output: NodeJS.WritableStream, options?: FakeAcpAgentOptions): Promise<void>;

package/dist/drivers/acp/testing/fake-agent.js

@@ -13,16 +13,38 @@
  * | `[plan]`         | 先发 `plan`（两条）再回文本                                                      |
  * | `[think]`        | 先发 `agent_thought_chunk`                                                        |
  * | `[refuse]`       | `refusal`                                                                         |
+ * | `[elicit]`       | `elicitation/create`（选颜色的表单）→ 回 `elicit: <action> <content JSON>`；客户端    |
+ * |                  | 没声明 `elicitation` 能力时回 `elicit: unsupported`；`cancel` 时本回合 `cancelled` |
+ * | `[model]`        | 回 `model <当前模型>`（`configOptions` 关着时是 `model none`）                     |
+ * | `[env NAME]`     | 回 `env NAME <值的 sha256 | absent>`（测环境变量到没到，不回显值）                  |
+ *
+ * `configOptions: true`（可执行入口 `--config-options`）：开会话答一个 `model` 配置项（`small`，分组
+ * `big` 里有 `large`），`session/set_config_option` 可改；缺省不答，线路与之前相同。
  *
  * 会话：`session/new` 发 `fake-<n>`；`session/resume` / `session/load` 接受任何 `fake-` 开头的 id
  * （load 先回放一条用户消息与一条回复）；`session/list` 列本进程建过的会话。
  */
+import { createHash } from "node:crypto";
 import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS } from "../types.js";
 import { JsonRpcPeer, RpcError } from "../../jsonrpc.js";
 const MODES = [
     { id: "default", name: "Default" },
     { id: "plan", name: "Plan" },
 ];
+const MODELS = [
+    { value: "small", name: "Small" },
+    { group: "big", name: "Big", options: [{ value: "large", name: "Large", description: "slow" }] },
+];
+const MODEL_VALUES = ["small", "large"];
+/** 一个表单：必填的颜色（枚举）与可选的数量。 */
+const ELICIT_SCHEMA = {
+    type: "object",
+    properties: {
+        color: { type: "string", enum: ["red", "blue"] },
+        count: { type: "integer", minimum: 1 },
+    },
+    required: ["color"],
+};
 function textOf(blocks) {
     return blocks.map((b) => (b.type === "text" ? b.text : `[${b.type}]`)).join("");
 }
@@ -37,6 +59,20 @@ function waitAbort(signal) {
 export function runFakeAcpAgent(input, output, options = {}) {
     const sessions = new Map();
     let counter = 0;
+    /** 客户端在 initialize 里声明了 elicitation。 */
+    let canElicit = false;
+    const configOf = (s) => [
+        {
+            id: "model",
+            name: "Model",
+            category: "model",
+            type: "select",
+            currentValue: s.model,
+            options: MODELS,
+        },
+    ];
+    /** 开会话答复里的 `configOptions`（关着时不加这个键）。 */
+    const config = (s) => options.configOptions === true ? { configOptions: configOf(s) } : {};
     const update = (sessionId, value) => peer.notify(ACP_METHODS.sessionUpdate, { sessionId, update: value });
     const session = (id) => {
         const found = typeof id === "string" ? sessions.get(id) : undefined;
@@ -45,7 +81,7 @@ export function runFakeAcpAgent(input, output, options = {}) {
         return found;
     };
     const open = (id, cwd) => {
-        const created = { id, cwd, mode: "default", turns: 0 };
+        const created = { id, cwd, mode: "default", model: "small", turns: 0 };
         sessions.set(id, created);
         return created;
     };
@@ -75,6 +111,37 @@ export function runFakeAcpAgent(input, output, options = {}) {
             });
         if (text.includes("[refuse]"))
             return done("refusal");
+        const say = (line) => update(s.id, { sessionUpdate: "agent_message_chunk", content: { type: "text", text: line } });
+        if (text.includes("[elicit]")) {
+            if (!canElicit) {
+                await say("elicit: unsupported");
+                return done("end_turn");
+            }
+            let answer;
+            try {
+                answer = await peer.request(ACP_METHODS.elicitationCreate, {
+                    sessionId: s.id,
+                    message: "Pick a color",
+                    requestedSchema: ELICIT_SCHEMA,
+                });
+            }
+            catch {
+                return done("cancelled");
+            }
+            await say(`elicit: ${answer.action} ${JSON.stringify(answer.content ?? null)}`);
+            return done(answer.action === "cancel" ? "cancelled" : "end_turn");
+        }
+        if (text.includes("[model]")) {
+            await say(`model ${options.configOptions === true ? s.model : "none"}`);
+            return done("end_turn");
+        }
+        const env = /\[env ([A-Z0-9_]+)\]/.exec(text);
+        if (env !== null) {
+            const value = process.env[env[1]];
+            const digest = value === undefined ? "absent" : createHash("sha256").update(value).digest("hex");
+            await say(`env ${env[1]} ${digest}`);
+            return done("end_turn");
+        }
         if (text.includes("[slow]")) {
             await waitAbort(turn.signal);
             return done("cancelled");
@@ -141,7 +208,9 @@ export function runFakeAcpAgent(input, output, options = {}) {
         async onRequest(method, raw) {
             const params = (raw ?? {});
             switch (method) {
-                case ACP_METHODS.initialize:
+                case ACP_METHODS.initialize: {
+                    const capabilities = params["clientCapabilities"];
+                    canElicit = capabilities?.["elicitation"] != null;
                     return {
                         protocolVersion: ACP_PROTOCOL_VERSION,
                         agentCapabilities: options.minimal
@@ -154,12 +223,17 @@ export function runFakeAcpAgent(input, output, options = {}) {
                         authMethods: [],
                         agentInfo: { name: options.name ?? "fake-acp-agent", version: "1.0.0" },
                     };
+                }
                 case ACP_METHODS.sessionNew: {
                     counter += 1;
                     const s = open(`fake-${counter}`, String(params["cwd"] ?? ""));
                     if (options.minimal)
-                        return { sessionId: s.id };
-                    return { sessionId: s.id, modes: { currentModeId: s.mode, availableModes: MODES } };
+                        return { sessionId: s.id, ...config(s) };
+                    return {
+                        sessionId: s.id,
+                        modes: { currentModeId: s.mode, availableModes: MODES },
+                        ...config(s),
+                    };
                 }
                 case ACP_METHODS.sessionResume:
                 case ACP_METHODS.sessionLoad: {
@@ -177,7 +251,7 @@ export function runFakeAcpAgent(input, output, options = {}) {
                             content: { type: "text", text: "echo: earlier" },
                         });
                     }
-                    return { modes: { currentModeId: s.mode, availableModes: MODES } };
+                    return { modes: { currentModeId: s.mode, availableModes: MODES }, ...config(s) };
                 }
                 case ACP_METHODS.sessionList:
                     return {
@@ -193,6 +267,18 @@ export function runFakeAcpAgent(input, output, options = {}) {
                     await update(s.id, { sessionUpdate: "current_mode_update", currentModeId: s.mode });
                     return {};
                 }
+                case ACP_METHODS.sessionSetConfigOption: {
+                    if (options.configOptions !== true)
+                        throw new RpcError(RPC_ERRORS.methodNotFound, `method not found: ${method}`);
+                    const s = session(params["sessionId"]);
+                    if (params["configId"] !== "model")
+                        throw new RpcError(RPC_ERRORS.invalidParams, `unknown config: ${String(params["configId"])}`);
+                    const value = String(params["value"]);
+                    if (!MODEL_VALUES.includes(value))
+                        throw new RpcError(RPC_ERRORS.invalidParams, `unknown model: ${value}`);
+                    s.model = value;
+                    return { configOptions: configOf(s) };
+                }
                 case ACP_METHODS.sessionPrompt:
                     return prompt(raw);
                 default:

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

@@ -2,8 +2,8 @@
  * ACP（Agent Client Protocol）v1 的子集类型（docs/wave5-plan.md §5.1，D14）。[W5-E]
  *
  * 手写、零依赖；只收 ama 作为客户端（驱动外部 Agent）与服务端（`ama --mode acp`）两侧用到的部分：
- * `initialize`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode`、
- * `session/update`（含 `usage_update`）、`session/request_permission`。字段名与规范一致（camelCase），
+ * `initialize`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode|set_config_option`、
+ * `session/update`（含 `usage_update`）、`session/request_permission`、`elicitation/create`。字段名与规范一致（camelCase），
  * 未知字段一律保留不报错；`_meta` 不解释。
  *
  * 不声明 `fs` / `terminal` 客户端能力（与 Armadra Q5 一致）：外部 Agent 自己读写、自己跑命令，
@@ -22,8 +22,10 @@ export declare const ACP_METHODS: {
     readonly sessionPrompt: "session/prompt";
     readonly sessionCancel: "session/cancel";
     readonly sessionSetMode: "session/set_mode";
+    readonly sessionSetConfigOption: "session/set_config_option";
     readonly sessionUpdate: "session/update";
     readonly requestPermission: "session/request_permission";
+    readonly elicitationCreate: "elicitation/create";
 };
 /** JSON-RPC 错误码（规范沿用 JSON-RPC 2.0；`-32000` 为 ACP 的 auth_required）。 */
 export declare const RPC_ERRORS: {
@@ -76,6 +78,8 @@ export interface AcpClientCapabilities {
         writeTextFile?: boolean;
     };
     terminal?: boolean;
+    /** 能接 `elicitation/create`（存在即支持）。 */
+    elicitation?: Record<string, unknown>;
 }
 export interface AcpInitializeParams {
     protocolVersion: number;
@@ -149,6 +153,7 @@ export interface AcpNewSessionParams {
 export interface AcpNewSessionResult {
     sessionId: string;
     modes?: AcpSessionModeState | null;
+    configOptions?: AcpSessionConfigOption[] | null;
 }
 export interface AcpLoadSessionParams {
     sessionId: string;
@@ -157,6 +162,84 @@ export interface AcpLoadSessionParams {
 }
 export interface AcpLoadSessionResult {
     modes?: AcpSessionModeState | null;
+    configOptions?: AcpSessionConfigOption[] | null;
+}
+/** 配置项里一个可选值。 */
+export interface AcpConfigSelectOption {
+    value: string;
+    name: string;
+    description?: string | null;
+}
+/** 规范允许把可选值分组。 */
+export interface AcpConfigSelectGroup {
+    group: string;
+    name: string;
+    options: AcpConfigSelectOption[];
+}
+/** `session/new|load|resume` 答的 `configOptions[]` 的一项（目前规范只有 `select`）。 */
+export interface AcpSessionConfigOption {
+    id: string;
+    name: string;
+    description?: string | null;
+    /** `mode` / `model` / `thought_level`，或 Agent 自己的。 */
+    category?: string | null;
+    type: "select" | (string & {});
+    currentValue: string;
+    options: (AcpConfigSelectOption | AcpConfigSelectGroup)[];
+}
+export interface AcpSetConfigOptionParams {
+    sessionId: string;
+    configId: string;
+    value: string;
+}
+/** 答复带全部配置项的新状态（改一项可能连带别的）。 */
+export interface AcpSetConfigOptionResult {
+    configOptions?: AcpSessionConfigOption[] | null;
+}
+/** 表单里的一个字段：扁平的原始类型，规范只允许这几种。 */
+export type AcpElicitationField = {
+    type: "string";
+    title?: string;
+    description?: string;
+    enum?: string[];
+    enumNames?: string[];
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+    default?: string;
+} | {
+    type: "number" | "integer";
+    title?: string;
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    default?: number;
+} | {
+    type: "boolean";
+    title?: string;
+    description?: string;
+    default?: boolean;
+};
+export interface AcpElicitationSchema {
+    type: "object";
+    properties: Record<string, AcpElicitationField>;
+    required?: string[];
+}
+/** Agent 发来的 `elicitation/create` 参数；未知字段保留。 */
+export interface AcpElicitationParams {
+    sessionId?: string;
+    message: string;
+    /** `form`（缺省）或 `url`。 */
+    mode?: "form" | "url" | (string & {});
+    requestedSchema?: AcpElicitationSchema;
+    url?: string;
+    [key: string]: unknown;
+}
+export type AcpElicitationAction = "accept" | "decline" | "cancel";
+export interface AcpElicitationResult {
+    action: AcpElicitationAction;
+    /** 只随 `accept`。 */
+    content?: Record<string, string | number | boolean>;
 }
 export type AcpResumeSessionParams = AcpLoadSessionParams;
 export type AcpResumeSessionResult = AcpLoadSessionResult;

package/dist/drivers/acp/types.js

@@ -2,8 +2,8 @@
  * ACP（Agent Client Protocol）v1 的子集类型（docs/wave5-plan.md §5.1，D14）。[W5-E]
  *
  * 手写、零依赖；只收 ama 作为客户端（驱动外部 Agent）与服务端（`ama --mode acp`）两侧用到的部分：
- * `initialize`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode`、
- * `session/update`（含 `usage_update`）、`session/request_permission`。字段名与规范一致（camelCase），
+ * `initialize`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode|set_config_option`、
+ * `session/update`（含 `usage_update`）、`session/request_permission`、`elicitation/create`。字段名与规范一致（camelCase），
  * 未知字段一律保留不报错；`_meta` 不解释。
  *
  * 不声明 `fs` / `terminal` 客户端能力（与 Armadra Q5 一致）：外部 Agent 自己读写、自己跑命令，
@@ -21,8 +21,10 @@ export const ACP_METHODS = {
     sessionPrompt: "session/prompt",
     sessionCancel: "session/cancel",
     sessionSetMode: "session/set_mode",
+    sessionSetConfigOption: "session/set_config_option",
     sessionUpdate: "session/update",
     requestPermission: "session/request_permission",
+    elicitationCreate: "elicitation/create",
 };
 /** JSON-RPC 错误码（规范沿用 JSON-RPC 2.0；`-32000` 为 ACP 的 auth_required）。 */
 export const RPC_ERRORS = {

package/docs/acp.md

@@ -67,12 +67,19 @@ stdin 关闭后等已开始的运行结束再退出（0）；SIGINT / SIGTERM
 - 开会话（`newSession` / `resumeSession` / `loadSession`）的 `mcpServers` 缺省为空数组；宿主可传第三个参数
   `{ mcpServers }`（如 stdio 的 `{ name, command, args, env: [{ name, value }] }`），原样转发给 Agent。
   `AcpClient.features.mcpServers === true` 表示支持（旧版没有 `features`）。ama 自己作客户端时仍不传。
+- `elicitation/create`（Agent 向人要结构化输入）：构造参数给了 `onElicitation(params, signal)` 才在 `initialize` 声明
+  `clientCapabilities.elicitation` 并接这个请求；没给时不声明、请求回 method not found（与旧版相同）。答复收成
+  `{ action: "accept" | "decline" | "cancel", content? }`（`content` 只随 accept，不认识的动作当 cancel）；`cancel(sessionId)`
+  与连接关闭时挂起的一律回 `{ action: "cancel" }`。ama 自己作客户端时不给处理器，从不替人填表。
+- 会话配置项：开会话（new / load / resume）答的 `configOptions` 原样交回；`setConfigOption(sessionId, configId, value)` 发
+  `session/set_config_option`，答复是全部配置项的新状态。
+- `AcpClient.features`：`{ mcpServers, elicitation, configOptions }`，宿主据此做特性检测。
 
 `AcpDriver` 在客户端之上实现驱动契约（`AgentDriver`）：续接优先 `session/resume`，其次 `session/load`（回放的历史丢弃），都不支持就新开并提示；按 ama 模式 `session/set_mode`，只读模式找不到对应模式 id 时拒绝启动。
 
 ## 测试替身
 
-`runFakeAcpAgent(input, output)` 是进程内的假 ACP Agent，`fakeAcpAgentPath()` 是它的可执行入口（`node <path> [--minimal]`）。行为由提示里的标记决定：`[permission]`（请求权限，四个选项）、`[slow]`（等到 cancel）、`[plan]`、`[think]`、`[refuse]`，其余回 `echo: <文本>`。`--minimal` 不声明 resume / load / list / close，也不给模式，用来测降级路径。
+`runFakeAcpAgent(input, output)` 是进程内的假 ACP Agent，`fakeAcpAgentPath()` 是它的可执行入口（`node <path> [--minimal]`）。行为由提示里的标记决定：`[permission]`（请求权限，四个选项）、`[slow]`（等到 cancel）、`[plan]`、`[think]`、`[refuse]`，其余回 `echo: <文本>`。`--minimal` 不声明 resume / load / list / close，也不给模式，用来测降级路径。另有 `[elicit]`（发 `elicitation/create`，客户端没声明能力时回 `elicit: unsupported`）、`[model]`、`[env NAME]`（只回值的 sha256）三个标记；`--config-options`（进程内 `{ configOptions: true }`）让开会话答一个 `model` 配置项并接 `session/set_config_option`。
 
 黄金记录在 `test/fixtures/acp/`：`driver-{allow,reject,cancel}.jsonl`（ama 驱动假 Agent 的三条路径）与 `mode-prompt.jsonl`（`ama --mode acp` 一轮往返）。`UPDATE_GOLDEN=1` 重写。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armadra/agent",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "A coding and coordination agent that runs standalone or embedded in Armadra",
   "type": "module",
   "keywords": [