@armadra/agent 0.6.4 → 0.6.5

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.5 (2026-10-03)
+
+- **`AcpClient` can pass MCP servers when opening a session**: `newSession`, `resumeSession` and `loadSession` take an
+  optional third argument `{ mcpServers }` that is forwarded as-is in `session/new|resume|load` (default still `[]`, the
+  wire is unchanged when it is omitted). `AcpClient.features.mcpServers` lets a host detect support. ama itself still
+  sends none. Docs: docs/acp.md "As a client".
+
 ## 0.6.4 (2026-10-03)
 
 - **Interrupt and send now**: while a run is in progress, Enter still queues the message as a steer (delivered at the next

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,12 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.6.5（2026-10-03）
+
+- **`AcpClient` 开会话可传 MCP 服务器**：`newSession`、`resumeSession`、`loadSession` 新增可选的第三个参数
+  `{ mcpServers }`，原样随 `session/new|resume|load` 发出（缺省仍是 `[]`，不传时线路不变）；宿主用
+  `AcpClient.features.mcpServers` 检测是否支持。ama 自己仍不传。文档：docs/acp.md「作为客户端」。
+
 ## 0.6.4（2026-10-03）
 
 - **打断并立即发送**：运行中按 Enter 仍是排队插话（等下一个投递点送达），新增 `Ctrl+X`（键位动作 `app.message.interrupt`）立即中止

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.4" : readPackageVersion();
+    AMA_VERSION = true ? "0.6.5" : readPackageVersion();
   }
 });
 
@@ -30738,6 +30738,9 @@ var init_jsonrpc = __esm({
 });
 
 // src/drivers/acp/client.ts
+function mcpServersOf(options) {
+  return [...options?.mcpServers ?? []];
+}
 function unattendedOutcome(params) {
   const reject2 = params.options.find((o) => o.kind === "reject_once");
   return {
@@ -30769,6 +30772,11 @@ var init_client = __esm({
         });
       }
       options;
+      /**
+       * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
+       * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+       */
+      static features = { mcpServers: true };
       peer;
       /** sessionId → 挂起权限请求的取消器。 */
       pendingPermissions = /* @__PURE__ */ new Map();
@@ -30818,16 +30826,28 @@ var init_client = __esm({
       supportsImages() {
         return this.agentCapabilities.promptCapabilities?.image === true;
       }
-      newSession(cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionNew, { cwd, mcpServers: [] }, signal);
+      newSession(cwd, signal, options) {
+        return this.peer.request(
+          ACP_METHODS.sessionNew,
+          { cwd, mcpServers: mcpServersOf(options) },
+          signal
+        );
       }
       /** 不回放历史（优先，R13：v2 计划取消 load）。 */
-      resumeSession(sessionId, cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionResume, { sessionId, cwd, mcpServers: [] }, signal);
+      resumeSession(sessionId, cwd, signal, options) {
+        return this.peer.request(
+          ACP_METHODS.sessionResume,
+          { sessionId, cwd, mcpServers: mcpServersOf(options) },
+          signal
+        );
       }
       /** 回放历史（以 session/update 通知）。 */
-      loadSession(sessionId, cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionLoad, { sessionId, cwd, mcpServers: [] }, signal);
+      loadSession(sessionId, cwd, signal, options) {
+        return this.peer.request(
+          ACP_METHODS.sessionLoad,
+          { sessionId, cwd, mcpServers: mcpServersOf(options) },
+          signal
+        );
       }
       listSessions(cwd, cursor) {
         return this.peer.request(ACP_METHODS.sessionList, {

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

@@ -8,8 +8,10 @@
  *   没有处理器时按无人值守回首个 `reject_once`（没有则 cancelled）。
  * - `cancel(sessionId)` 发 `session/cancel` 通知，并让该会话所有挂起的权限请求回 `cancelled`
  *   （规范要求：客户端取消回合后必须以 cancelled 回答挂起的请求）。
+ * - 开会话（new / resume / load）的 `mcpServers` 缺省为空数组；宿主可经 {@link AcpSessionOptions}
+ *   传入，原样转发。
  */
-import { type AcpAgentCapabilities, type AcpContentBlock, type AcpImplementationInfo, type AcpInitializeResult, type AcpListSessionsResult, type AcpLoadSessionResult, type AcpNewSessionResult, type AcpPromptResult, type AcpRequestPermissionParams, type AcpRequestPermissionResult, type AcpSessionNotification } from "./types.js";
+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";
 export interface AcpClientHandlers {
     onUpdate?(notification: AcpSessionNotification): void;
     /** `signal`：该会话被 cancel、连接关闭时 abort（此时应尽快回 cancelled）。 */
@@ -26,6 +28,13 @@ export interface AcpClientOptions extends AcpClientHandlers {
 export declare function unattendedOutcome(params: AcpRequestPermissionParams): AcpRequestPermissionResult;
 export declare class AcpClient {
     private readonly options;
+    /**
+     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
+     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+     */
+    static readonly features: {
+        readonly mcpServers: true;
+    };
     private readonly peer;
     /** sessionId → 挂起权限请求的取消器。 */
     private readonly pendingPermissions;
@@ -41,11 +50,11 @@ export declare class AcpClient {
     supportsList(): boolean;
     supportsClose(): boolean;
     supportsImages(): boolean;
-    newSession(cwd: string, signal?: AbortSignal): Promise<AcpNewSessionResult>;
+    newSession(cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpNewSessionResult>;
     /** 不回放历史（优先，R13：v2 计划取消 load）。 */
-    resumeSession(sessionId: string, cwd: string, signal?: AbortSignal): Promise<AcpLoadSessionResult>;
+    resumeSession(sessionId: string, cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpLoadSessionResult>;
     /** 回放历史（以 session/update 通知）。 */
-    loadSession(sessionId: string, cwd: string, signal?: AbortSignal): Promise<AcpLoadSessionResult>;
+    loadSession(sessionId: string, cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpLoadSessionResult>;
     listSessions(cwd?: string, cursor?: string): Promise<AcpListSessionsResult>;
     closeSession(sessionId: string): Promise<unknown>;
     prompt(sessionId: string, prompt: AcpContentBlock[], signal?: AbortSignal): Promise<AcpPromptResult>;

package/dist/drivers/acp/client.js

@@ -8,9 +8,15 @@
  *   没有处理器时按无人值守回首个 `reject_once`（没有则 cancelled）。
  * - `cancel(sessionId)` 发 `session/cancel` 通知，并让该会话所有挂起的权限请求回 `cancelled`
  *   （规范要求：客户端取消回合后必须以 cancelled 回答挂起的请求）。
+ * - 开会话（new / resume / load）的 `mcpServers` 缺省为空数组；宿主可经 {@link AcpSessionOptions}
+ *   传入，原样转发。
  */
 import { JsonRpcPeer, RpcError } from "../jsonrpc.js";
 import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./types.js";
+/** 开会话参数里的 `mcpServers`：拷一份，缺省空数组。 */
+function mcpServersOf(options) {
+    return [...(options?.mcpServers ?? [])];
+}
 /** 无人值守的回答：首个 reject_once，没有就 cancelled。 */
 export function unattendedOutcome(params) {
     const reject = params.options.find((o) => o.kind === "reject_once");
@@ -22,6 +28,11 @@ export function unattendedOutcome(params) {
 }
 export class AcpClient {
     options;
+    /**
+     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
+     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+     */
+    static features = { mcpServers: true };
     peer;
     /** sessionId → 挂起权限请求的取消器。 */
     pendingPermissions = new Map();
@@ -85,16 +96,16 @@ export class AcpClient {
     supportsImages() {
         return this.agentCapabilities.promptCapabilities?.image === true;
     }
-    newSession(cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionNew, { cwd, mcpServers: [] }, signal);
+    newSession(cwd, signal, options) {
+        return this.peer.request(ACP_METHODS.sessionNew, { cwd, mcpServers: mcpServersOf(options) }, signal);
     }
     /** 不回放历史（优先，R13：v2 计划取消 load）。 */
-    resumeSession(sessionId, cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionResume, { sessionId, cwd, mcpServers: [] }, signal);
+    resumeSession(sessionId, cwd, signal, options) {
+        return this.peer.request(ACP_METHODS.sessionResume, { sessionId, cwd, mcpServers: mcpServersOf(options) }, signal);
     }
     /** 回放历史（以 session/update 通知）。 */
-    loadSession(sessionId, cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionLoad, { sessionId, cwd, mcpServers: [] }, signal);
+    loadSession(sessionId, cwd, signal, options) {
+        return this.peer.request(ACP_METHODS.sessionLoad, { sessionId, cwd, mcpServers: mcpServersOf(options) }, signal);
     }
     listSessions(cwd, cursor) {
         return this.peer.request(ACP_METHODS.sessionList, {

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

@@ -111,8 +111,28 @@ export interface AcpInitializeResult {
     authMethods?: AcpAuthMethod[];
     agentInfo?: AcpImplementationInfo;
 }
-/** ama 不向外部 Agent 传 MCP 服务器（Skills 不做 MCP），总是空数组。 */
-export type AcpMcpServer = Record<string, unknown>;
+/** `session/new.mcpServers[].env` 的一项。 */
+export type AcpEnvVariable = {
+    name: string;
+    value: string;
+};
+/** stdio 传输的 MCP 服务器：ACP v1 要求每个 Agent 都支持这一种。 */
+export type AcpStdioMcpServer = {
+    name: string;
+    command: string;
+    args: string[];
+    env: AcpEnvVariable[];
+};
+/**
+ * 交给外部 Agent 的 MCP 服务器。ama 自己不加（Skills 不做 MCP），缺省是空数组；宿主（如 Armadra）
+ * 经 {@link AcpSessionOptions} 传入的原样转发，http / sse 变体不在这里解释。
+ */
+export type AcpMcpServer = AcpStdioMcpServer | Record<string, unknown>;
+/** `AcpClient.newSession` / `resumeSession` / `loadSession` 的可选项。 */
+export interface AcpSessionOptions {
+    /** 随 `session/new|resume|load` 发给 Agent；缺省空数组。 */
+    mcpServers?: readonly AcpMcpServer[];
+}
 export interface AcpSessionMode {
     id: string;
     name: string;

package/docs/acp.md

@@ -64,6 +64,9 @@ stdin 关闭后等已开始的运行结束再退出（0）；SIGINT / SIGTERM
 - `session/request_permission` 交给 `onPermission`；没有处理器时回首个 `reject_once`（无人值守）。
 - `cancel(sessionId)` 发 `session/cancel`，并让该会话挂起的权限请求回 `cancelled`（规范要求）。
 - 只接受 Agent 自己给出的 `optionId`。
+- 开会话（`newSession` / `resumeSession` / `loadSession`）的 `mcpServers` 缺省为空数组；宿主可传第三个参数
+  `{ mcpServers }`（如 stdio 的 `{ name, command, args, env: [{ name, value }] }`），原样转发给 Agent。
+  `AcpClient.features.mcpServers === true` 表示支持（旧版没有 `features`）。ama 自己作客户端时仍不传。
 
 `AcpDriver` 在客户端之上实现驱动契约（`AgentDriver`）：续接优先 `session/resume`，其次 `session/load`（回放的历史丢弃），都不支持就新开并提示；按 ama 模式 `session/set_mode`，只读模式找不到对应模式 id 时拒绝启动。
 

package/package.json

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