@armadra/agent 0.8.1 → 0.9.1

package/dist/checkpoints/backend.js

@@ -21,6 +21,8 @@ export function createCheckpointBackendFactory(settings) {
             return undefined;
         let tracker;
         let registered = false;
+        // 登记会话根目录的写入（mkdir → tmp → rename）；snapshot 等它结束，收尾时不会还有文件在落盘
+        let registering = Promise.resolve();
         const warn = (message) => ctx.log("warn", message);
         const get = () => {
             tracker ??= new CheckpointTracker({
@@ -34,7 +36,7 @@ export function createCheckpointBackendFactory(settings) {
             });
             if (!registered && settings.sessionsRoot !== undefined) {
                 registered = true;
-                registerSessionRoot(settings.dataDir, settings.sessionsRoot).catch((error) => ctx.log("debug", msg().session.checkpoints.registerFailed(String(error))));
+                registering = registerSessionRoot(settings.dataDir, settings.sessionsRoot).catch((error) => ctx.log("debug", msg().session.checkpoints.registerFailed(String(error))));
             }
             return tracker;
         };
@@ -79,6 +81,9 @@ export function createCheckpointBackendFactory(settings) {
             hooks,
             snapshot: async (userEntryId) => {
                 try {
+                    // 先让登记写完再记检查点：检查点条目落盘之后请求马上发出，不能再被它拖住
+                    get();
+                    await registering;
                     const shadowCommit = await shadowSnapshot(userEntryId);
                     await get().snapshot(userEntryId, shadowCommit !== undefined ? { shadowCommit } : {});
                 }

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

@@ -3,7 +3,8 @@
  *
  * JSON-RPC over NDJSON（{@link JsonRpcPeer}），手写零依赖；`@armadra/agent/acp` 导出供 Armadra 复用。
  *
- * - 不声明 `fs` / `terminal` 能力：Agent 发来的 `fs/*`、`terminal/*` 请求一律 method not found。
+ * - 不声明 `fs` 能力：Agent 发来的 `fs/*` 请求一律 method not found。`terminal` 同理，除非构造参数给了
+ *   `onTerminal`：此时声明 `terminal: true`，`terminal/*` 请求交给它（ama 自己作客户端不给）。
  * - `session/request_permission` 交给 `onPermission`（驱动再交给 ama 的审批通道，只交给人）；
  *   没有处理器时按无人值守回首个 `reject_once`（没有则 cancelled）。
  * - `cancel(sessionId)` 发 `session/cancel` 通知，并让该会话所有挂起的权限请求回 `cancelled`
@@ -29,6 +30,12 @@ export interface AcpClientHandlers {
      * `signal`：该会话被 cancel、连接关闭时 abort（此时回 `{ action: "cancel" }`，不必再答）。
      */
     onElicitation?(params: AcpElicitationParams, signal: AbortSignal): Promise<AcpElicitationResult>;
+    /**
+     * `terminal/*`（create / output / wait_for_exit / kill / release）：宿主替 Agent 起终端。给了它才声明
+     * `clientCapabilities.terminal: true` 并把这些请求交给它；`method` 是完整方法名，`params` 原样交回，返回值即
+     * 答复，抛 `RpcError` 回对应错误。`signal`：连接关闭时 abort。权限、cwd 限制与输出上限由宿主负责。
+     */
+    onTerminal?(method: string, params: unknown, signal: AbortSignal): Promise<unknown>;
     onProtocolError?(line: string, reason: string): void;
     onClose?(): void;
 }
@@ -45,12 +52,14 @@ export declare class AcpClient {
      * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段，旧一点的只有 `mcpServers`）：
      * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
      * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
-     * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`。
+     * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`；
+     * - `terminal`：构造参数 `onTerminal` 接 `terminal/*`。
      */
     static readonly features: {
         readonly mcpServers: true;
         readonly elicitation: true;
         readonly configOptions: true;
+        readonly terminal: true;
     };
     private readonly peer;
     /** sessionId → 挂起权限请求的取消器。 */

package/dist/drivers/acp/client.js

@@ -3,7 +3,8 @@
  *
  * JSON-RPC over NDJSON（{@link JsonRpcPeer}），手写零依赖；`@armadra/agent/acp` 导出供 Armadra 复用。
  *
- * - 不声明 `fs` / `terminal` 能力：Agent 发来的 `fs/*`、`terminal/*` 请求一律 method not found。
+ * - 不声明 `fs` 能力：Agent 发来的 `fs/*` 请求一律 method not found。`terminal` 同理，除非构造参数给了
+ *   `onTerminal`：此时声明 `terminal: true`，`terminal/*` 请求交给它（ama 自己作客户端不给）。
  * - `session/request_permission` 交给 `onPermission`（驱动再交给 ama 的审批通道，只交给人）；
  *   没有处理器时按无人值守回首个 `reject_once`（没有则 cancelled）。
  * - `cancel(sessionId)` 发 `session/cancel` 通知，并让该会话所有挂起的权限请求回 `cancelled`
@@ -50,9 +51,10 @@ export class AcpClient {
      * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段，旧一点的只有 `mcpServers`）：
      * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
      * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
-     * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`。
+     * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`；
+     * - `terminal`：构造参数 `onTerminal` 接 `terminal/*`。
      */
-    static features = { mcpServers: true, elicitation: true, configOptions: true };
+    static features = { mcpServers: true, elicitation: true, configOptions: true, terminal: true };
     peer;
     /** sessionId → 挂起权限请求的取消器。 */
     pendingPermissions = new Map();
@@ -105,7 +107,7 @@ export class AcpClient {
             protocolVersion: ACP_PROTOCOL_VERSION,
             clientCapabilities: {
                 fs: { readTextFile: false, writeTextFile: false },
-                terminal: false,
+                terminal: this.options.onTerminal !== undefined,
                 session: { configOptions: {} },
                 ...(this.options.onElicitation !== undefined ? { elicitation: {} } : {}),
             },
@@ -175,6 +177,8 @@ export class AcpClient {
     async onRequest(method, params, connection) {
         if (method === ACP_METHODS.elicitationCreate && this.options.onElicitation !== undefined)
             return this.onElicitation(params, connection);
+        if (method.startsWith("terminal/") && this.options.onTerminal !== undefined)
+            return this.options.onTerminal(method, params, connection);
         if (method !== ACP_METHODS.requestPermission)
             throw new RpcError(RPC_ERRORS.methodNotFound, `client does not support ${method}`);
         const request = params;

package/docs/en/reference/acp.md

@@ -149,7 +149,7 @@ The model uses ACP agents through `task(agent="acp:<program>")` (ama itself is `
 
 `AcpClient` (`@armadra/agent/acp`): `initialize`, `newSession`, `resumeSession` (preferred, no replay), `loadSession`, `listSessions`, `closeSession`, `prompt`, `setMode`, `cancel`.
 
-- Declared client capabilities: `session.configOptions: {}` (select options; boolean is not declared); `fs` / `terminal` are not declared (`fs/*` and `terminal/*` requests from the agent answer method not found), and neither is `auth.terminal` (ama has no interactive terminal to lend to the agent).
+- Declared client capabilities: `session.configOptions: {}` (select options; boolean is not declared); `fs` is not declared (`fs/*` requests from the agent answer method not found) and `terminal` only when `onTerminal` is given (see below), and neither is `auth.terminal` (ama has no interactive terminal to lend to the agent).
 - `$/cancel_request` is on in both directions: aborting the `signal` of a request after it was sent tells the agent to withdraw it; when the agent withdraws a pending `session/request_permission` / `elicitation/create`, the handler's `signal` aborts and the answer is `cancelled` / `cancel` (a choice the handler makes afterwards does not count).
 - `session/request_permission` goes to `onPermission`; without a handler the first `reject_once` is answered (unattended).
 - `cancel(sessionId)` sends `session/cancel` and answers `cancelled` to that session's pending permission requests (required by the spec).
@@ -157,7 +157,8 @@ The model uses ACP agents through `task(agent="acp:<program>")` (ama itself is `
 - `mcpServers` of session-open calls (`newSession` / `resumeSession` / `loadSession`) defaults to an empty array; a host can pass a third argument `{ mcpServers }` (for stdio, `{ name, command, args, env: [{ name, value }] }`), which is forwarded to the agent as is. `AcpClient.features.mcpServers === true` signals support (older versions have no `features`). ama itself, as a client, still passes none.
 - `elicitation/create` (the agent asking a human for structured input): only when the constructor is given `onElicitation(params, signal)` does `initialize` declare `clientCapabilities.elicitation` and accept this request; otherwise it is not declared and the request answers method not found (as in older versions). Answers are normalized to `{ action: "accept" | "decline" | "cancel", content? }` (`content` only with accept; unknown actions count as cancel); pending ones answer `{ action: "cancel" }` on `cancel(sessionId)` and when the connection closes. ama itself, as a client, gives no handler and never fills in forms for a human.
 - Session config options: the `configOptions` of session-open answers (new / load / resume) are passed through; `setConfigOption(sessionId, configId, value)` sends `session/set_config_option`, and the answer is the new state of all options.
-- `AcpClient.features`: `{ mcpServers, elicitation, configOptions }`, for feature detection by hosts.
+- `terminal/*` (the agent asking the host for a terminal): only when the constructor is given `onTerminal(method, params, signal)` does `initialize` declare `clientCapabilities.terminal: true`; `terminal/create|output|wait_for_exit|kill|release` are then handed to it with the params untouched, its return value is the answer and throwing `RpcError` answers with that error. Without it `terminal: false` is declared and the requests answer method not found (as in older versions). Permissions, cwd restriction and output limits are the host's job; ama itself, as a client, gives no handler.
+- `AcpClient.features`: `{ mcpServers, elicitation, configOptions, terminal }`, for feature detection by hosts.
 
 `AcpDriver` implements the driver contract (`AgentDriver`) on top of the client:
 

package/docs/reference/acp.md

@@ -155,8 +155,8 @@ stdin 关闭后等已开始的运行结束再退出（0）；`ama` 进程的 std
 
 `AcpClient`（`@armadra/agent/acp`）：`initialize`、`newSession`、`resumeSession`（优先，不回放）、`loadSession`、`listSessions`、`closeSession`、`prompt`、`setMode`、`cancel`。
 
-- 声明的客户端能力：`session.configOptions: {}`（接 select 型配置项，不声明 boolean）；不声明 `fs` / `terminal`（Agent 发来的
-  `fs/*`、`terminal/*` 请求回 method not found），也不声明 `auth.terminal`（ama 没有可借给 Agent 的交互终端）。
+- 声明的客户端能力：`session.configOptions: {}`（接 select 型配置项，不声明 boolean）；不声明 `fs`（Agent 发来的 `fs/*` 请求回 method not found）；`terminal` 只在构造参数给了
+  `onTerminal` 时声明（见下），也不声明 `auth.terminal`（ama 没有可借给 Agent 的交互终端）。
 - 线路两侧开 `$/cancel_request`：本端请求的 `signal` 在发出后 abort 会通知 Agent 撤回；Agent 撤回挂起的
   `session/request_permission` / `elicitation/create` 时处理器的 `signal` abort，答 `cancelled` / `cancel`（处理器之后给的选择不作数）。
 - `session/request_permission` 交给 `onPermission`；没有处理器时回首个 `reject_once`（无人值守）。
@@ -171,7 +171,11 @@ stdin 关闭后等已开始的运行结束再退出（0）；`ama` 进程的 std
   与连接关闭时挂起的一律回 `{ action: "cancel" }`。ama 自己作客户端时不给处理器，从不替人填表。
 - 会话配置项：开会话（new / load / resume）答的 `configOptions` 原样交回；`setConfigOption(sessionId, configId, value)` 发
   `session/set_config_option`，答复是全部配置项的新状态。
-- `AcpClient.features`：`{ mcpServers, elicitation, configOptions }`，宿主据此做特性检测。
+- `terminal/*`（Agent 向宿主要终端）：构造参数给了 `onTerminal(method, params, signal)` 才在 `initialize` 声明
+  `clientCapabilities.terminal: true`，并把 `terminal/create|output|wait_for_exit|kill|release` 连同原样参数交给它，返回值即答复，
+  抛 `RpcError` 回对应错误；没给时声明 `terminal: false`、请求回 method not found（与旧版相同）。权限、cwd 限制与输出上限由宿主负责；
+  ama 自己作客户端时不给处理器。
+- `AcpClient.features`：`{ mcpServers, elicitation, configOptions, terminal }`，宿主据此做特性检测。
 
 `AcpDriver` 在客户端之上实现驱动契约（`AgentDriver`）：
 

package/package.json

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