@armadra/agent 0.6.8 → 0.7.1

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

@@ -17,9 +17,15 @@
  * |                  | 没声明 `elicitation` 能力时回 `elicit: unsupported`；`cancel` 时本回合 `cancelled` |
  * | `[model]`        | 回 `model <当前模型>`（`configOptions` 关着时是 `model none`）                     |
  * | `[env NAME]`     | 回 `env NAME <值的 sha256 | absent>`（测环境变量到没到，不回显值）                  |
+ * | `[cancel-request]` | 同 `[permission]` 发权限请求，挂起 `cancelRequestMs`（缺省 2 s）后自己发            |
+ * |                  | `$/cancel_request` 撤回；`tool_call_update` failed，回 `permission withdrawn`、`end_turn` |
  *
- * `configOptions: true`（可执行入口 `--config-options`）：开会话答一个 `model` 配置项（`small`，分组
- * `big` 里有 `large`），`session/set_config_option` 可改；缺省不答，线路与之前相同。
+ * `configOptions: true`（可执行入口 `--config-options`）：开会话答一个 `model` 配置项（分组 `fast` 里有
+ * `small`、`big` 里有 `large`，当前 `small`），`session/set_config_option` 可改；缺省不答，线路与之前相同。
+ * `configOnly: true`（`--config-only`）：开会话不答 `modes`，改在 `configOptions` 里给 category `mode` 的
+ * 选择项（id `mode`），经 `session/set_config_option` 切换；可与 `configOptions` 同开（两项都给）。
+ * `authRequired: true`（`--auth-required`）：`initialize` 给一条 terminal 型认证方法，开会话
+ * （new / load / resume）一律回 -32000。
  *
  * 会话：`session/new` 发 `fake-<n>`；`session/resume` / `session/load` 接受任何 `fake-` 开头的 id
  * （load 先回放一条用户消息与一条回复）；`session/list` 列本进程建过的会话。
@@ -27,15 +33,25 @@
 import { createHash } from "node:crypto";
 import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS } from "../types.js";
 import { JsonRpcPeer, RpcError } from "../../jsonrpc.js";
+/** `authRequired` 时 `initialize` 给的认证方法。 */
+export const FAKE_AUTH_METHOD = {
+    type: "terminal",
+    id: "login",
+    name: "Log in",
+    description: "Run the fake agent's login command",
+    args: ["--login"],
+};
 const MODES = [
     { id: "default", name: "Default" },
     { id: "plan", name: "Plan" },
 ];
+/** 规范要求选项全部平铺或全部分组（不能混排），所以 `small` 也放进一组。 */
 const MODELS = [
-    { value: "small", name: "Small" },
+    { group: "fast", name: "Fast", options: [{ value: "small", name: "Small" }] },
     { group: "big", name: "Big", options: [{ value: "large", name: "Large", description: "slow" }] },
 ];
 const MODEL_VALUES = ["small", "large"];
+const MODE_VALUES = MODES.map((m) => m.id);
 /** 一个表单：必填的颜色（枚举）与可选的数量。 */
 const ELICIT_SCHEMA = {
     type: "object",
@@ -62,17 +78,40 @@ export function runFakeAcpAgent(input, output, options = {}) {
     /** 客户端在 initialize 里声明了 elicitation。 */
     let canElicit = false;
     const configOf = (s) => [
-        {
-            id: "model",
-            name: "Model",
-            category: "model",
-            type: "select",
-            currentValue: s.model,
-            options: MODELS,
-        },
+        ...(options.configOnly === true
+            ? [
+                {
+                    id: "mode",
+                    name: "Mode",
+                    category: "mode",
+                    type: "select",
+                    currentValue: s.mode,
+                    options: MODES.map((m) => ({ value: m.id, name: m.name })),
+                },
+            ]
+            : []),
+        ...(options.configOptions === true
+            ? [
+                {
+                    id: "model",
+                    name: "Model",
+                    category: "model",
+                    type: "select",
+                    currentValue: s.model,
+                    options: MODELS,
+                },
+            ]
+            : []),
     ];
+    const hasConfig = options.configOptions === true || options.configOnly === true;
     /** 开会话答复里的 `configOptions`（关着时不加这个键）。 */
-    const config = (s) => options.configOptions === true ? { configOptions: configOf(s) } : {};
+    const config = (s) => hasConfig ? { configOptions: configOf(s) } : {};
+    /** 开会话答复里的 `modes`（`configOnly` 时不给）。 */
+    const modes = (s) => options.configOnly === true ? {} : { modes: { currentModeId: s.mode, availableModes: MODES } };
+    const requireAuth = () => {
+        if (options.authRequired === true)
+            throw new RpcError(RPC_ERRORS.authRequired, "authentication required");
+    };
     const update = (sessionId, value) => peer.notify(ACP_METHODS.sessionUpdate, { sessionId, update: value });
     const session = (id) => {
         const found = typeof id === "string" ? sessions.get(id) : undefined;
@@ -146,6 +185,42 @@ export function runFakeAcpAgent(input, output, options = {}) {
             await waitAbort(turn.signal);
             return done("cancelled");
         }
+        if (text.includes("[cancel-request]")) {
+            const toolCallId = `call-${s.turns}`;
+            await update(s.id, {
+                sessionUpdate: "tool_call",
+                toolCallId,
+                title: "Write note.txt",
+                kind: "edit",
+                status: "pending",
+            });
+            const withdraw = new AbortController();
+            const timer = setTimeout(() => withdraw.abort(), options.cancelRequestMs ?? 2000);
+            const asked = peer
+                .request(ACP_METHODS.requestPermission, {
+                sessionId: s.id,
+                toolCall: { toolCallId, title: "Write note.txt", kind: "edit", status: "pending" },
+                options: [
+                    { optionId: "allow", name: "Allow", kind: "allow_once" },
+                    { optionId: "reject", name: "Reject", kind: "reject_once" },
+                ],
+            }, withdraw.signal)
+                .then((answer) => answer, () => undefined);
+            const answer = await Promise.race([asked, waitAbort(turn.signal).then(() => undefined)]);
+            clearTimeout(timer);
+            if (turn.signal.aborted) {
+                withdraw.abort();
+                return done("cancelled");
+            }
+            if (answer === undefined) {
+                await update(s.id, { sessionUpdate: "tool_call_update", toolCallId, status: "failed" });
+                await say("permission withdrawn");
+                return done("end_turn");
+            }
+            await update(s.id, { sessionUpdate: "tool_call_update", toolCallId, status: "completed" });
+            await say(`answered ${answer.outcome.outcome}`);
+            return done("end_turn");
+        }
         if (text.includes("[permission]")) {
             const toolCallId = `call-${s.turns}`;
             await update(s.id, {
@@ -205,6 +280,8 @@ export function runFakeAcpAgent(input, output, options = {}) {
     const peer = new JsonRpcPeer({
         input,
         output,
+        // 只有 [cancel-request] 会 abort 出站请求；入站撤回目前不影响假 Agent 的处理器
+        cancelRequests: true,
         async onRequest(method, raw) {
             const params = (raw ?? {});
             switch (method) {
@@ -220,23 +297,21 @@ export function runFakeAcpAgent(input, output, options = {}) {
                                 promptCapabilities: { image: false, embeddedContext: false },
                                 sessionCapabilities: { list: {}, resume: {}, close: {} },
                             },
-                        authMethods: [],
+                        authMethods: options.authRequired === true ? [FAKE_AUTH_METHOD] : [],
                         agentInfo: { name: options.name ?? "fake-acp-agent", version: "1.0.0" },
                     };
                 }
                 case ACP_METHODS.sessionNew: {
+                    requireAuth();
                     counter += 1;
                     const s = open(`fake-${counter}`, String(params["cwd"] ?? ""));
                     if (options.minimal)
                         return { sessionId: s.id, ...config(s) };
-                    return {
-                        sessionId: s.id,
-                        modes: { currentModeId: s.mode, availableModes: MODES },
-                        ...config(s),
-                    };
+                    return { sessionId: s.id, ...modes(s), ...config(s) };
                 }
                 case ACP_METHODS.sessionResume:
                 case ACP_METHODS.sessionLoad: {
+                    requireAuth();
                     const id = String(params["sessionId"] ?? "");
                     if (options.minimal || !id.startsWith("fake-"))
                         throw new RpcError(RPC_ERRORS.resourceNotFound, `unknown session: ${id}`);
@@ -251,7 +326,7 @@ export function runFakeAcpAgent(input, output, options = {}) {
                             content: { type: "text", text: "echo: earlier" },
                         });
                     }
-                    return { modes: { currentModeId: s.mode, availableModes: MODES }, ...config(s) };
+                    return { ...modes(s), ...config(s) };
                 }
                 case ACP_METHODS.sessionList:
                     return {
@@ -268,15 +343,23 @@ export function runFakeAcpAgent(input, output, options = {}) {
                     return {};
                 }
                 case ACP_METHODS.sessionSetConfigOption: {
-                    if (options.configOptions !== true)
+                    if (!hasConfig)
                         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;
+                    if (params["configId"] === "model" && options.configOptions === true) {
+                        if (!MODEL_VALUES.includes(value))
+                            throw new RpcError(RPC_ERRORS.invalidParams, `unknown model: ${value}`);
+                        s.model = value;
+                    }
+                    else if (params["configId"] === "mode" && options.configOnly === true) {
+                        if (!MODE_VALUES.includes(value))
+                            throw new RpcError(RPC_ERRORS.invalidParams, `unknown mode: ${value}`);
+                        s.mode = value;
+                    }
+                    else {
+                        throw new RpcError(RPC_ERRORS.invalidParams, `unknown config: ${String(params["configId"])}`);
+                    }
                     return { configOptions: configOf(s) };
                 }
                 case ACP_METHODS.sessionPrompt:

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

@@ -2,9 +2,9 @@
  * 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|set_config_option`、
- * `session/update`（含 `usage_update`）、`session/request_permission`、`elicitation/create`。字段名与规范一致（camelCase），
- * 未知字段一律保留不报错；`_meta` 不解释。
+ * `initialize`、`authenticate`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode|set_config_option`、
+ * `session/update`（含 `usage_update`）、`session/request_permission`、`elicitation/create`、`$/cancel_request`。
+ * 字段名与规范一致（camelCase），未知字段一律保留不报错；`_meta` 不解释（ama 自己发的只用 {@link ACP_META_KEY}）。
  *
  * 不声明 `fs` / `terminal` 客户端能力（与 Armadra Q5 一致）：外部 Agent 自己读写、自己跑命令，
  * 用它自己的权限策略；它要问人的才经 `session/request_permission` 回到 ama。
@@ -14,6 +14,8 @@ export declare const ACP_PROTOCOL_VERSION: 1;
 /** 方法名（客户端 → Agent 的请求 / 通知，Agent → 客户端的请求 / 通知）。 */
 export declare const ACP_METHODS: {
     readonly initialize: "initialize";
+    /** ama 不实现（只给 terminal 型认证方法，规范要求这类方法不经 authenticate）。 */
+    readonly authenticate: "authenticate";
     readonly sessionNew: "session/new";
     readonly sessionLoad: "session/load";
     readonly sessionResume: "session/resume";
@@ -26,6 +28,8 @@ export declare const ACP_METHODS: {
     readonly sessionUpdate: "session/update";
     readonly requestPermission: "session/request_permission";
     readonly elicitationCreate: "elicitation/create";
+    /** 协议级取消（双向通知，`requestId` 指对端发来的、尚未答复的请求）。 */
+    readonly cancelRequest: "$/cancel_request";
 };
 /** JSON-RPC 错误码（规范沿用 JSON-RPC 2.0；`-32000` 为 ACP 的 auth_required）。 */
 export declare const RPC_ERRORS: {
@@ -36,6 +40,8 @@ export declare const RPC_ERRORS: {
     readonly internalError: -32603;
     readonly authRequired: -32000;
     readonly resourceNotFound: -32002;
+    /** 请求被 `$/cancel_request` 撤回。 */
+    readonly requestCancelled: -32800;
 };
 export interface AcpTextContent {
     type: "text";
@@ -80,6 +86,16 @@ export interface AcpClientCapabilities {
     terminal?: boolean;
     /** 能接 `elicitation/create`（存在即支持）。 */
     elicitation?: Record<string, unknown>;
+    /** 会话相关的客户端能力；`configOptions.boolean` 存在即能显示 boolean 型配置项。 */
+    session?: {
+        configOptions?: {
+            boolean?: Record<string, unknown> | null;
+        } | null;
+    } | null;
+    /** `terminal: true`：客户端能替 Agent 起终端跑 terminal 型认证方法。 */
+    auth?: {
+        terminal?: boolean;
+    };
 }
 export interface AcpInitializeParams {
     protocolVersion: number;
@@ -103,11 +119,30 @@ export interface AcpAgentCapabilities {
         resume?: Record<string, unknown> | null;
         close?: Record<string, unknown> | null;
     };
+    /** Agent 侧认证能力（`logout` 存在即支持 `logout`）。 */
+    auth?: {
+        logout?: Record<string, unknown> | null;
+    };
 }
-export interface AcpAuthMethod {
+/**
+ * 认证方法：缺省 / `agent` 型经 `authenticate` 完成；`terminal` 型由客户端起终端跑
+ * `<agent 命令> <args…>`（带 `env`），规范要求这类方法不经 `authenticate`。
+ */
+export type AcpAuthMethod = {
+    type?: "agent";
+    id: string;
+    name: string;
+    description?: string | null;
+} | {
+    type: "terminal";
     id: string;
     name: string;
     description?: string | null;
+    args?: string[];
+    env?: Record<string, string>;
+};
+export interface AcpAuthenticateParams {
+    methodId: string;
 }
 export interface AcpInitializeResult {
     protocolVersion: number;
@@ -176,16 +211,19 @@ export interface AcpConfigSelectGroup {
     name: string;
     options: AcpConfigSelectOption[];
 }
-/** `session/new|load|resume` 答的 `configOptions[]` 的一项（目前规范只有 `select`）。 */
+/** 配置项的语义分类：只是给客户端排版的提示，不参与正确性。 */
+export type AcpConfigCategory = "mode" | "model" | "model_config" | "thought_level" | (string & {});
+/** `session/new|load|resume` 答的 `configOptions[]` 的一项（ama 只发 `select`）。 */
 export interface AcpSessionConfigOption {
     id: string;
     name: string;
     description?: string | null;
     /** `mode` / `model` / `thought_level`，或 Agent 自己的。 */
-    category?: string | null;
+    category?: AcpConfigCategory | null;
     type: "select" | (string & {});
     currentValue: string;
-    options: (AcpConfigSelectOption | AcpConfigSelectGroup)[];
+    /** 全部平铺或全部分组，规范不允许混排。 */
+    options: AcpConfigSelectOption[] | AcpConfigSelectGroup[];
 }
 export interface AcpSetConfigOptionParams {
     sessionId: string;
@@ -269,7 +307,10 @@ export interface AcpPromptParams {
     sessionId: string;
     prompt: AcpContentBlock[];
 }
-/** 本回合用量（可选字段，按 2026-06 稳定的 usage 提案）。 */
+/**
+ * 本回合用量。UNSTABLE：1.24.1 仍只在 schema.unstable.json 里（稳定 schema 的 PromptResponse
+ * 不列它，但允许附加字段，故照发）；客户端不应依赖。
+ */
 export interface AcpPromptUsage {
     totalTokens?: number;
     inputTokens?: number;
@@ -285,6 +326,17 @@ export interface AcpPromptResult {
 export interface AcpCancelParams {
     sessionId: string;
 }
+/** `$/cancel_request` 的参数：被撤回的请求 id。 */
+export interface AcpCancelRequestParams {
+    requestId: string | number | null;
+}
+/** ama 自己的 `_meta` 命名空间（客户端不得假设其含义）。 */
+export declare const ACP_META_KEY: "ama";
+/** `_meta.ama` 的内容。 */
+export interface AcpAmaMeta {
+    /** codemode 内层调用所属的外层工具调用。 */
+    parentToolCallId?: string;
+}
 export type { AcpToolKind };
 export type AcpToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
 export interface AcpToolCallLocation {
@@ -312,6 +364,10 @@ export interface AcpToolCall {
     locations?: AcpToolCallLocation[];
     rawInput?: unknown;
     rawOutput?: unknown;
+    /** 工具名（规范新增，供客户端按工具分组 / 记忆授权）。 */
+    name?: string | null;
+    /** 扩展位；ama 只用 `{ [ACP_META_KEY]: AcpAmaMeta }`。 */
+    _meta?: Record<string, unknown> | null;
 }
 /** `tool_call_update` 与权限请求里的 toolCall：除 id 外都可缺。 */
 export type AcpToolCallUpdate = Partial<AcpToolCall> & {
@@ -353,15 +409,23 @@ export type AcpSessionUpdate = {
     } | null;
 } | {
     sessionUpdate: "available_commands_update";
-    availableCommands: {
-        name: string;
-        description: string;
-    }[];
+    availableCommands: AcpAvailableCommand[];
+} | {
+    sessionUpdate: "config_option_update";
+    configOptions: AcpSessionConfigOption[];
 } | {
     sessionUpdate: "session_info_update";
     title?: string | null;
     updatedAt?: string | null;
 };
+/** 客户端可列给人选的斜杠命令（`/<name>`）；`input.hint` 是参数提示。 */
+export interface AcpAvailableCommand {
+    name: string;
+    description: string;
+    input?: {
+        hint: string;
+    } | null;
+}
 export interface AcpSessionNotification {
     sessionId: string;
     update: AcpSessionUpdate;

package/dist/drivers/acp/types.js

@@ -2,9 +2,9 @@
  * 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|set_config_option`、
- * `session/update`（含 `usage_update`）、`session/request_permission`、`elicitation/create`。字段名与规范一致（camelCase），
- * 未知字段一律保留不报错；`_meta` 不解释。
+ * `initialize`、`authenticate`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode|set_config_option`、
+ * `session/update`（含 `usage_update`）、`session/request_permission`、`elicitation/create`、`$/cancel_request`。
+ * 字段名与规范一致（camelCase），未知字段一律保留不报错；`_meta` 不解释（ama 自己发的只用 {@link ACP_META_KEY}）。
  *
  * 不声明 `fs` / `terminal` 客户端能力（与 Armadra Q5 一致）：外部 Agent 自己读写、自己跑命令，
  * 用它自己的权限策略；它要问人的才经 `session/request_permission` 回到 ama。
@@ -13,6 +13,8 @@ export const ACP_PROTOCOL_VERSION = 1;
 /** 方法名（客户端 → Agent 的请求 / 通知，Agent → 客户端的请求 / 通知）。 */
 export const ACP_METHODS = {
     initialize: "initialize",
+    /** ama 不实现（只给 terminal 型认证方法，规范要求这类方法不经 authenticate）。 */
+    authenticate: "authenticate",
     sessionNew: "session/new",
     sessionLoad: "session/load",
     sessionResume: "session/resume",
@@ -25,6 +27,8 @@ export const ACP_METHODS = {
     sessionUpdate: "session/update",
     requestPermission: "session/request_permission",
     elicitationCreate: "elicitation/create",
+    /** 协议级取消（双向通知，`requestId` 指对端发来的、尚未答复的请求）。 */
+    cancelRequest: "$/cancel_request",
 };
 /** JSON-RPC 错误码（规范沿用 JSON-RPC 2.0；`-32000` 为 ACP 的 auth_required）。 */
 export const RPC_ERRORS = {
@@ -35,4 +39,8 @@ export const RPC_ERRORS = {
     internalError: -32603,
     authRequired: -32000,
     resourceNotFound: -32002,
+    /** 请求被 `$/cancel_request` 撤回。 */
+    requestCancelled: -32800,
 };
+/** ama 自己的 `_meta` 命名空间（客户端不得假设其含义）。 */
+export const ACP_META_KEY = "ama";

package/dist/drivers/jsonrpc.d.ts

@@ -5,7 +5,10 @@
  * - 分帧复用 `modes/rpc/jsonl.ts`（只按 `\n` 切行、64 KiB 分片写、背压等 drain），写入串行；
  * - 双向：本端可发请求 / 通知，也处理对端的请求（`onRequest` 抛 {@link RpcError} 即回错误）与通知；
  * - `jsonrpcField: false` 时不写 `"jsonrpc":"2.0"`（Codex app-server 的线上形状），读取两种都认；
- * - 连接关闭（输入流结束）时所有挂起的请求以 `connection_closed` 失败。
+ * - 连接关闭（输入流结束）时所有挂起的请求以 `connection_closed` 失败；
+ * - `cancelRequests: true`（ACP 两侧）时支持协议级取消 `$/cancel_request`：本端请求的 `signal` abort
+ *   会通知对端；对端撤回本端正在处理的请求时 abort 该请求的 `ctx.signal`，处理器此后抛错一律回 -32800。
+ *   缺省关闭（Codex app-server 不认），线上形状与之前逐字节相同。
  */
 export type RpcId = string | number;
 export declare class RpcError extends Error {
@@ -15,7 +18,7 @@ export declare class RpcError extends Error {
 }
 export interface IncomingRequestContext {
     readonly id: RpcId;
-    /** 连接关闭时 abort。 */
+    /** 连接关闭时 abort；`cancelRequests` 开着时对端发 `$/cancel_request` 撤回本请求也 abort。 */
     readonly signal: AbortSignal;
 }
 export interface JsonRpcPeerOptions {
@@ -29,10 +32,14 @@ export interface JsonRpcPeerOptions {
     onClose?(): void;
     /** 无法解析的行（不影响连接）。 */
     onProtocolError?(line: string, reason: string): void;
+    /** 协议级取消（ACP `$/cancel_request`）：缺省 false（Codex app-server 不认）。 */
+    cancelRequests?: boolean;
 }
 export declare class JsonRpcPeer {
     private readonly options;
     private readonly pending;
+    /** 正在处理的对端请求（只在 `cancelRequests` 时记录），供 `$/cancel_request` 撤回。 */
+    private readonly inflight;
     private readonly reader;
     private readonly lifetime;
     private nextId;
@@ -43,7 +50,10 @@ export declare class JsonRpcPeer {
     readonly closed: Promise<void>;
     constructor(options: JsonRpcPeerOptions);
     get isOpen(): boolean;
-    /** 发请求；`signal` abort 时本端不再等（不通知对端，协议级取消由调用方另发）。 */
+    /**
+     * 发请求；`signal` abort 时本端不再等。`cancelRequests` 开着时同时给对端发
+     * `$/cancel_request { requestId }`（已发出的请求才发），否则不通知对端。
+     */
     request<T = unknown>(method: string, params?: unknown, signal?: AbortSignal): Promise<T>;
     /** 输入流结束后仍可写（对端可能只关了自己的写端，还在读）；写失败静默。 */
     notify(method: string, params?: unknown): Promise<void>;

package/dist/drivers/jsonrpc.js

@@ -5,7 +5,10 @@
  * - 分帧复用 `modes/rpc/jsonl.ts`（只按 `\n` 切行、64 KiB 分片写、背压等 drain），写入串行；
  * - 双向：本端可发请求 / 通知，也处理对端的请求（`onRequest` 抛 {@link RpcError} 即回错误）与通知；
  * - `jsonrpcField: false` 时不写 `"jsonrpc":"2.0"`（Codex app-server 的线上形状），读取两种都认；
- * - 连接关闭（输入流结束）时所有挂起的请求以 `connection_closed` 失败。
+ * - 连接关闭（输入流结束）时所有挂起的请求以 `connection_closed` 失败；
+ * - `cancelRequests: true`（ACP 两侧）时支持协议级取消 `$/cancel_request`：本端请求的 `signal` abort
+ *   会通知对端；对端撤回本端正在处理的请求时 abort 该请求的 `ctx.signal`，处理器此后抛错一律回 -32800。
+ *   缺省关闭（Codex app-server 不认），线上形状与之前逐字节相同。
  */
 import { createLineReader, writeChunked } from "../modes/rpc/jsonl.js";
 import { RPC_ERRORS } from "./acp/types.js";
@@ -19,9 +22,13 @@ export class RpcError extends Error {
         this.name = "RpcError";
     }
 }
+/** `$/cancel_request` 的方法名（与 ACP_METHODS.cancelRequest 相同；这里不依赖 ACP 词汇表）。 */
+const CANCEL_REQUEST = "$/cancel_request";
 export class JsonRpcPeer {
     options;
     pending = new Map();
+    /** 正在处理的对端请求（只在 `cancelRequests` 时记录），供 `$/cancel_request` 撤回。 */
+    inflight = new Map();
     reader;
     lifetime = new AbortController();
     nextId = 1;
@@ -39,14 +46,19 @@ export class JsonRpcPeer {
     get isOpen() {
         return !this.isClosed;
     }
-    /** 发请求；`signal` abort 时本端不再等（不通知对端，协议级取消由调用方另发）。 */
+    /**
+     * 发请求；`signal` abort 时本端不再等。`cancelRequests` 开着时同时给对端发
+     * `$/cancel_request { requestId }`（已发出的请求才发），否则不通知对端。
+     */
     request(method, params, signal) {
         if (this.isClosed)
             return Promise.reject(closedError(method));
         const id = this.nextId++;
         return new Promise((resolve, reject) => {
             const onAbort = () => {
-                this.pending.delete(id);
+                const sent = this.pending.delete(id);
+                if (sent && this.options.cancelRequests === true && !this.isClosed)
+                    void this.notify(CANCEL_REQUEST, { requestId: id });
                 reject(new RpcError(RPC_ERRORS.internalError, `${method}: aborted`));
             };
             if (signal?.aborted === true)
@@ -116,6 +128,14 @@ export class JsonRpcPeer {
             return;
         }
         if (typeof message.method === "string") {
+            if (message.method === CANCEL_REQUEST &&
+                this.options.cancelRequests === true &&
+                (message.id === undefined || message.id === null)) {
+                const requestId = message.params?.requestId;
+                if (typeof requestId === "string" || typeof requestId === "number")
+                    this.inflight.get(requestId)?.abort();
+                return;
+            }
             if (message.id !== undefined && message.id !== null) {
                 void this.handleRequest(message.id, message.method, message.params);
             }
@@ -154,14 +174,23 @@ export class JsonRpcPeer {
             });
             return;
         }
+        let cancel;
+        let signal = this.lifetime.signal;
+        if (this.options.cancelRequests === true) {
+            cancel = new AbortController();
+            this.inflight.set(id, cancel);
+            signal = AbortSignal.any([this.lifetime.signal, cancel.signal]);
+        }
         try {
-            const result = await handler(method, params, { id, signal: this.lifetime.signal });
+            const result = await handler(method, params, { id, signal });
             await this.send({ id, result: result ?? null });
         }
         catch (error) {
-            const rpc = error instanceof RpcError
-                ? error
-                : new RpcError(RPC_ERRORS.internalError, error instanceof Error ? error.message : String(error));
+            const rpc = cancel?.signal.aborted === true
+                ? new RpcError(RPC_ERRORS.requestCancelled, `${method}: request cancelled`)
+                : error instanceof RpcError
+                    ? error
+                    : new RpcError(RPC_ERRORS.internalError, error instanceof Error ? error.message : String(error));
             await this.send({
                 id,
                 error: {
@@ -171,6 +200,10 @@ export class JsonRpcPeer {
                 },
             });
         }
+        finally {
+            if (cancel !== undefined && this.inflight.get(id) === cancel)
+                this.inflight.delete(id);
+        }
     }
 }
 function closedError(method) {

package/dist/drivers/turn.d.ts

@@ -2,7 +2,8 @@
  * 一个回合的结果汇总（各驱动共用）。[W5-E]
  *
  * 驱动把归一化后的 {@link DriverEvent} 交给收集器：它转发给 `onEvent`，同时累计最终文本、
- * 工具摘要（≤ 20 行，§5.2）、触及的文件（edit / delete / move 类工具的 locations）与用量。
+ * 工具摘要（≤ 20 行，§5.2）、触及的文件（edit / delete / move 类工具的 locations，以及带 diff 内容的
+ * 工具改动的路径——不论种类，见 {@link TurnCollector.noteDiff}）与用量。
  * 原始事件只在内存里流过，不落盘（§5.4 敏感数据）。
  */
 import type { AcpToolKind, DriverEvent, DriverTurnResult } from "./types.js";
@@ -12,6 +13,10 @@ interface ToolState {
     kind: AcpToolKind;
     status: "pending" | "in_progress" | "completed" | "failed";
     locations: string[];
+    /** 工具内容里 diff 的路径（ACP `content[].type === "diff"`）。 */
+    diffPaths?: string[];
+    /** 已转发过的状态（去重用）。 */
+    reported: Set<ToolState["status"]>;
 }
 export declare class TurnCollector {
     private readonly onEvent;
@@ -20,8 +25,16 @@ export declare class TurnCollector {
     private readonly order;
     private usage;
     constructor(onEvent: (event: DriverEvent) => void);
-    /** 归一化事件：累计后转发给 onEvent。 */
+    /**
+     * 归一化事件：累计后转发给 onEvent。同一工具调用回到已报过的状态（如审批前后
+     * `in_progress → pending → in_progress`）且标题、种类、位置都没变时不再转发，免得下游重复报进度。
+     */
     push(event: DriverEvent): void;
+    /**
+     * 记下工具改动的文件（diff 内容的路径）：工具完成后计入 filesTouched，不论它报的种类。
+     * 在 `push` 该工具的 `tool_call` 之后调（未知的 id 忽略）。[ACP-D]
+     */
+    noteDiff(id: string, paths: readonly string[]): void;
     /** 工具调用的最近状态（驱动做 tool_call_update 时补全标题与种类）。 */
     tool(id: string): Readonly<ToolState> | undefined;
     /** 回合结束时的累计用量合并（`result.usage` 等）。 */