@armadra/agent 0.6.8 → 0.7.1

package/dist/modes/acp/acp-server.d.ts

@@ -1,23 +1,27 @@
 /**
- * `ama --mode acp`：把 ama 的会话暴露为 ACP Agent（docs/wave5-plan.md §5.6，D14）。[W5-E]
+ * `ama --mode acp`：把 ama 的会话暴露为 ACP Agent（docs/wave5-plan.md §5.6，D14；多会话见
+ * docs/acp-plan.md D1、D2、D11、D12、§2.1）。[W5-E，ACP-B]
  *
- * 与 `--mode rpc` 同一引擎（Runtime + 组装根的会话切换），一次只有一个活动会话：
- * - `session/new` 新开（启动时那个空会话第一次直接认领）；`session/load` 切到该会话并回放历史；
- *   `session/resume` 切换不回放；`session/list` 列本 cwd 的会话；`session/close` 中断并释放；
- *   对非活动会话发 `session/prompt` 时（空闲）先切过去。
- * - `session/prompt` → `prompt`（文本 + 图片；资源链接以 `@uri` 文本给出，嵌入资源取文本）；
- *   回合结束按会话状态给 stopReason：中断 → cancelled，输出截断 → max_tokens，出错 → JSON-RPC 错误。
- * - `session/cancel` → `abort`；`session/set_mode` → `setPermissionMode`（模式 id = ama 权限模式）。
- * - 审批：ama 的审批请求经 `session/request_permission` 交给客户端（允许 / 本会话允许 / 拒绝）；
- *   客户端回 cancelled、连接断开或回合被中断 → 交给链上下一个回答者（无人 → 拒绝）。
- * - 不声明 / 不使用客户端的 `fs`、`terminal` 能力（Armadra Q5）；ama 自己读写、自己跑命令。
- * - cwd 固定为启动目录（信任与项目配置都按它判定）；客户端给别的 cwd → invalid params。
+ * 与 `--mode rpc` 同一引擎（Runtime + 组装根）。多会话：
+ * - 每个 ACP sessionId 一个常驻会话（会话池，acp-sessions.ts），各有自己的事件映射器与权限模式；
+ *   启动时那个空会话由第一个 `session/new` 认领，之后的 new / load / resume 建兄弟会话（不 dispose 旧的）。
+ * - 同一时刻只跑一个回合：其它会话的 `session/prompt` 进 FIFO 队列；出队时把该会话切为前台
+ *   （宿主 / Hook / 工具工厂跟随，清「本会话允许」记忆），并把它自己的权限模式重放到共享管线。
+ * - `session/cancel`：在跑 → abort；排队中 → 直接回 cancelled。`session/close`：中断、释放并出池，
+ *   之后对该 id 发 prompt 回 -32002。`$/cancel_request` 撤回 prompt 等价 cancel，答复 -32800。
+ * - `session/set_mode`：记在会话上；是前台就立即生效，否则出队时生效（仍发 `current_mode_update`）。
+ * - `session/list`：按 cwd 过滤（别的目录 → 空列表），每页 50 条，cursor 翻页；标题去掉嵌入资源块。
+ * - 回合结束：stopReason（中断 → cancelled、截断 → max_tokens、拒答 → refusal、出错 → JSON-RPC 错误），
+ *   并发 `session_info_update`。
+ * - 审批经 `session/request_permission` 交给客户端；不声明 / 不使用客户端的 `fs`、`terminal` 能力。
+ * - cwd 固定为启动目录；客户端给的 `mcpServers` / `additionalDirectories` 忽略（stderr 一行）。
  */
 import type { ImageBlock } from "../../ai/types.js";
 import type { AgentSession } from "../../agent/types.js";
 import type { Runtime } from "../../cli/runtime.js";
-import { JsonRpcPeer } from "../../drivers/jsonrpc.js";
+import { type IncomingRequestContext, type JsonRpcPeer } from "../../drivers/jsonrpc.js";
 import type { ApprovalBroker } from "../../permissions/types.js";
+import { type AcpConnection } from "./acp-connection.js";
 export declare const ACP_AGENT_CAPABILITIES: {
     loadSession: boolean;
     promptCapabilities: {
@@ -35,6 +39,7 @@ export declare const ACP_AGENT_CAPABILITIES: {
         close: {};
     };
 };
+export type Params = Record<string, unknown>;
 /** ACP 提示 → ama 的文本与图片。 */
 export declare function promptOf(blocks: unknown): {
     text: string;
@@ -42,38 +47,60 @@ export declare function promptOf(blocks: unknown): {
 };
 export declare class AcpServer {
     private readonly runtime;
+    readonly connection: AcpConnection;
     private readonly log;
     readonly peer: JsonRpcPeer;
-    private activeId;
-    /** 启动时的空会话还没被 session/new 认领。 */
-    private freshUnclaimed;
-    private mapper;
-    private unsubscribe;
-    private cancelRequested;
     private readonly cwd;
-    constructor(runtime: Runtime, streams: {
-        input: NodeJS.ReadableStream;
-        output: NodeJS.WritableStream;
-    }, log?: (message: string) => void);
+    /** ACP sessionId → 常驻会话。 */
+    private readonly pool;
+    /** 还没交给客户端的会话（启动时那个；关掉最后一个前台会话后补的）：`session/new` 认领。 */
+    private standby;
+    /** 新会话的初始权限模式（启动参数 / 配置给的）。 */
+    private readonly initialMode;
+    private readonly queue;
+    /**
+     * 连接由调用方建（`createAcpConnection`），其 handlers 转到 {@link handle} 与
+     * {@link handleNotification}；认证门在 bootstrap 成功后以同一条连接构造服务端。
+     */
+    constructor(runtime: Runtime, connection: AcpConnection, log?: (message: string) => void);
+    /** 前台会话（宿主 / Hook / 工具工厂当前操作的那个）。 */
     session(): AgentSession;
+    /** 会话池里的全部会话（含未认领的待命会话）；stdin 关闭时逐个收尾。 */
+    sessions(): AgentSession[];
     /** 审批交给客户端：ama 的 UI broker。 */
     readonly broker: ApprovalBroker;
-    private makeMapper;
-    private emit;
-    private subscribe;
-    dispose(): void;
-    private handle;
+    private extras;
+    private configOptions;
+    /** 把会话放进池：自己的映射器（`session/update` 带它自己的 id）与订阅。 */
+    private adopt;
+    /**
+     * 释放全部会话（stdin 关闭后由模式调用）：排队的回 cancelled，等在跑的结束，兄弟会话依次
+     * dispose（跑 SessionEnd Hook）；前台会话留给 `Runtime.dispose`。
+     */
+    dispose(abort?: boolean): Promise<void>;
+    /** 客户端通知（`session/cancel`）。 */
+    handleNotification(method: string, params: unknown): void;
+    /** 客户端请求；认证门交接时也由它处理当次请求。 */
+    handle(method: string, params: Params, ctx?: IncomingRequestContext): Promise<unknown>;
     private initialize;
-    private checkCwd;
-    private modes;
-    private switchTo;
+    /** 开会话请求的公共检查：cwd 固定；`mcpServers` / `additionalDirectories` 忽略并在 stderr 说一行。 */
+    private checkOpen;
+    /** new / load / resume 的答复：模式与配置项；答复发出后再公布命令表与配置项。 */
+    private opened;
     private newSession;
     private openSession;
     private list;
+    private entryOf;
     private close;
-    private ensureIdle;
     private prompt;
+    /** 出队：切前台、重放权限模式、跑回合、算 stopReason，再发 `session_info_update`。 */
+    private runPrompt;
+    /** 中断一个提示：在跑 → abort；排队中 → 出队后立即回 cancelled（`runPrompt` 见标记直接返回）。 */
+    private cancelJob;
     private cancel;
     private setMode;
+    /** `session/set_mode` 与 `mode` 配置项共用：按会话记，前台立即生效，否则出队时生效。 */
+    private applyMode;
+    private setConfigOption;
     private askClient;
 }