@armadra/agent 0.6.7 → 0.7.0

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

@@ -13,16 +13,54 @@
  * | `[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>`（测环境变量到没到，不回显值）                  |
+ * | `[cancel-request]` | 同 `[permission]` 发权限请求，挂起 `cancelRequestMs`（缺省 2 s）后自己发            |
+ * |                  | `$/cancel_request` 撤回；`tool_call_update` failed，回 `permission withdrawn`、`end_turn` |
+ *
+ * `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` 列本进程建过的会话。
  */
+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 = [
+    { 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",
+    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 +75,43 @@ function waitAbort(signal) {
 export function runFakeAcpAgent(input, output, options = {}) {
     const sessions = new Map();
     let counter = 0;
+    /** 客户端在 initialize 里声明了 elicitation。 */
+    let canElicit = false;
+    const configOf = (s) => [
+        ...(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) => 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;
@@ -45,7 +120,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,10 +150,77 @@ 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");
         }
+        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, {
@@ -138,10 +280,14 @@ 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) {
-                case ACP_METHODS.initialize:
+                case ACP_METHODS.initialize: {
+                    const capabilities = params["clientCapabilities"];
+                    canElicit = capabilities?.["elicitation"] != null;
                     return {
                         protocolVersion: ACP_PROTOCOL_VERSION,
                         agentCapabilities: options.minimal
@@ -151,18 +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 };
-                    return { sessionId: s.id, modes: { currentModeId: s.mode, availableModes: MODES } };
+                        return { sessionId: s.id, ...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}`);
@@ -177,7 +326,7 @@ export function runFakeAcpAgent(input, output, options = {}) {
                             content: { type: "text", text: "echo: earlier" },
                         });
                     }
-                    return { modes: { currentModeId: s.mode, availableModes: MODES } };
+                    return { ...modes(s), ...config(s) };
                 }
                 case ACP_METHODS.sessionList:
                     return {
@@ -193,6 +342,26 @@ export function runFakeAcpAgent(input, output, options = {}) {
                     await update(s.id, { sessionUpdate: "current_mode_update", currentModeId: s.mode });
                     return {};
                 }
+                case ACP_METHODS.sessionSetConfigOption: {
+                    if (!hasConfig)
+                        throw new RpcError(RPC_ERRORS.methodNotFound, `method not found: ${method}`);
+                    const s = session(params["sessionId"]);
+                    const value = String(params["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:
                     return prompt(raw);
                 default:

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`、
- * `session/update`（含 `usage_update`）、`session/request_permission`。字段名与规范一致（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";
@@ -22,8 +24,12 @@ 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";
+    /** 协议级取消（双向通知，`requestId` 指对端发来的、尚未答复的请求）。 */
+    readonly cancelRequest: "$/cancel_request";
 };
 /** JSON-RPC 错误码（规范沿用 JSON-RPC 2.0；`-32000` 为 ACP 的 auth_required）。 */
 export declare const RPC_ERRORS: {
@@ -34,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";
@@ -76,6 +84,18 @@ export interface AcpClientCapabilities {
         writeTextFile?: boolean;
     };
     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;
@@ -99,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;
@@ -149,6 +188,7 @@ export interface AcpNewSessionParams {
 export interface AcpNewSessionResult {
     sessionId: string;
     modes?: AcpSessionModeState | null;
+    configOptions?: AcpSessionConfigOption[] | null;
 }
 export interface AcpLoadSessionParams {
     sessionId: string;
@@ -157,6 +197,87 @@ 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[];
+}
+/** 配置项的语义分类：只是给客户端排版的提示，不参与正确性。 */
+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?: AcpConfigCategory | 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;
@@ -186,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;
@@ -202,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 {
@@ -229,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> & {
@@ -270,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`、
- * `session/update`（含 `usage_update`）、`session/request_permission`。字段名与规范一致（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",
@@ -21,8 +23,12 @@ 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",
+    /** 协议级取消（双向通知，`requestId` 指对端发来的、尚未答复的请求）。 */
+    cancelRequest: "$/cancel_request",
 };
 /** JSON-RPC 错误码（规范沿用 JSON-RPC 2.0；`-32000` 为 ACP 的 auth_required）。 */
 export const RPC_ERRORS = {
@@ -33,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>;