@migor/agentia 0.6.3 → 0.7.1

package/dist/integrations/mcp.d.ts

@@ -1,19 +1,22 @@
 import type { AgentTool } from '../core/tool.js';
 /**
- * Agentia —— MCP 桥（D1，spec §10 决策记录）。
+ * Agentia —— MCP 桥（D1）+ 两个内置连接器（spec §10 决策记录）。
  *
- * 设计原则同 `RedisLike`：框架只定义**结构面**，不 import `@modelcontextprotocol/sdk`，
- * 也**不含任何传输实现**（stdio spawn / StreamableHTTP 都在独立可选包 `@migor/mcp`，
- * 或用户自己接 SDK 后实现 `McpClientLike`）。本文件只依赖 core，符合分层约定
- * （`integrations` → `core`）。
+ * **桥**：框架只定义**结构面** —— 不 import `@modelcontextprotocol/sdk`，任何实现了
+ * `McpClientLike` 的客户端都能接（同 `RedisLike` 的 duck-typing）。本文件只依赖 core，
+ * 符合分层约定（`integrations` → `core`）。
  *
- * 用法：在 `createApp({ providers })` 里放一个 provider 即可 ——
+ * **连接器**（2026-09-18 起**内置**，见文件末「连接器」一节与 spec §10 同日条）：
+ * `createStdioMcpConnector` / `createStreamableHttpMcpConnector`。二者只用标准库
+ * （`node:child_process` + 全局 `fetch`），**不新增任何第三方依赖**。
+ *
+ * 用法（接入点是 `AppOptions.tools` 这条**裸工具缝**）：
  * ```ts
- * createApp({
- *   system: '…',
- *   providers: [{ provide: 'mcp', useFactory: () => mcpTools(client, { server: 'time' }) }],
- * });
+ * const mcp = createStdioMcpConnector(['uvx', 'mcp-server-time']);
+ * createApp({ system: '…', tools: await mcpTools(mcp, { server: 'time' }) });
  * ```
+ * ⚠️ **不是** `providers: [{ provide: 'mcp', useFactory: … }]` —— 那条路落地时不成立
+ * （菜单只从装饰器注册表收集，`useFactory` 的返回值根本不进菜单；见 spec §10 2026-09-11）。
  * 复用既有装配 / 查重 / 中间件，**零新机制**（MCP 工具与本地 @Tool 同处一个命名空间，
  * 重名由 AgentApp 的装配期查重拦下）。
  *
@@ -37,7 +40,15 @@ export interface McpToolInfo {
  */
 export interface McpClientLike {
     listTools(): Promise<McpToolInfo[]>;
-    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * `opts.abandoned`：裁判（引擎 `toolTimeoutMs` / 桥兜底超时）**放弃等待**的通知信号。
+     * 放弃 ≠ 取消 —— 但连接器应借此清掉这次调用的簿记（stdio 的 pending 条目、
+     * HTTP 的在飞 fetch），否则「server 活着但不回包」时每超时一次就泄漏一条。
+     * 只实现两个参数的旧客户端依然兼容（可选参数，鸭子类型）。
+     */
+    callTool(name: string, args: Record<string, unknown>, opts?: {
+        abandoned?: AbortSignal;
+    }): Promise<unknown>;
 }
 export interface McpToolsOptions {
     /**
@@ -86,3 +97,97 @@ export declare function withDeadline<T>(p: Promise<T>, timeoutMs: number, label:
  *   不做「把 content 拼成字符串」这类有损加工 —— 需要塑形请自行包一层工具。
  */
 export declare function mcpTools(client: McpClientLike, opts?: McpToolsOptions): Promise<AgentTool[]>;
+/**
+ * 连接器公共面：`McpClientLike` + 一个关闭句柄（两个内置连接器都返回它）。
+ *
+ * 缝的形状没有变化 —— 需要自己的传输（官方 SDK / 远程 server / 复用长连接）时，
+ * 实现 `McpClientLike` 两个方法即可，不必碰这里。
+ */
+export interface McpConnector extends McpClientLike {
+    /**
+     * 释放底层资源，**幂等**；stdio 侧**保证返回时子进程已终止**：
+     * 先 SIGTERM，宽限期（{@link MCP_CLOSE_GRACE_MS}）后 SIGKILL，然后**等真正的 `'exit'`**
+     * （2026-09-18 收紧：此前到点即返回、不等 reap，会留下孤儿进程而调用方无从知晓）。
+     * HTTP 侧 = 尽力 `DELETE` 终止会话（server 不认也无所谓，失败不抛）。
+     *
+     * 关闭后再调用 `listTools` / `callTool` 会抛出可读错误（不静默挂死）。
+     */
+    close(): Promise<void>;
+}
+/** `close()` 里 SIGTERM → SIGKILL 的宽限期（毫秒） */
+export declare const MCP_CLOSE_GRACE_MS = 2000;
+export interface StdioMcpConnectorOptions {
+    /** 追加 / 覆盖的环境变量（缺省继承 `process.env`） */
+    env?: Record<string, string>;
+    /** 子进程工作目录 */
+    cwd?: string;
+    /** 子进程 stderr 去向：`'inherit'`（缺省，server 日志直通终端）| `'ignore'` */
+    stderr?: 'inherit' | 'ignore';
+    /** 见 {@link DEFAULT_CLIENT_INFO} */
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** 请求的协议版本，缺省 `'2024-11-05'` */
+    protocolVersion?: string;
+    /**
+     * 装配期超时（毫秒）—— 只作用于**握手 + `tools/list`**，缺省
+     * {@link MCP_DEFAULT_TIMEOUT_MS}；非正数 = 不限。语义见 {@link Guard}。
+     *
+     * 超时同样只是一类账（`code='timeout'`）：**不终止子进程**，与仓库其余「等待的终点」
+     * 一致（超时 = 放弃等待）。
+     */
+    timeoutMs?: number;
+}
+/**
+ * **stdio 连接器**：spawn 一个 MCP server 子进程，走换行分隔的 JSON-RPC 2.0
+ * （`initialize` → `notifications/initialized` → `tools/list` / `tools/call`）。
+ *
+ * 进程与握手都是**惰性**的 —— 构造不产生副作用，第一次 `listTools` / `callTool` 才 spawn；
+ * 握手只做一次（并发调用共享同一次握手）。
+ *
+ * 三处非显然的坑，这里都兜住了（此前 `scripts/e2e-mcp.ts` 内联的那 94 行踩过）：
+ * 1. spawn **失败**（命令不存在 → `ENOENT`）是异步的 `'error'` 事件，不是抛出 ——
+ *    没有监听器就是未捕获异常、直接把宿主进程带崩，所以必须接住并拒绝在途请求；
+ * 2. 分帧：一条报文可能跨多个 chunk，必须自己攒 buffer 按 `\n` 切；
+ * 3. **协议层 `isError: true` 必须转成抛错** —— 否则模型收到一条「成功」的结果，
+ *    trace 也把它记成成功的调用（`McpClientLike` 的约定，见其注释）。
+ */
+export declare function createStdioMcpConnector(cmd: readonly string[], opts?: StdioMcpConnectorOptions): McpConnector;
+export interface StreamableHttpMcpConnectorOptions {
+    /** 附加请求头（鉴权等）。会覆盖缺省的 `content-type` / `accept` 同名字段 */
+    headers?: Record<string, string>;
+    /** 见 {@link DEFAULT_CLIENT_INFO} */
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** 请求的协议版本，缺省 `'2024-11-05'`；协商结果以 server 回的为准 */
+    protocolVersion?: string;
+    /** 装配期超时（毫秒）—— 只作用于**握手 + `tools/list`**，语义同 {@link StdioMcpConnectorOptions.timeoutMs} */
+    timeoutMs?: number;
+    /**
+     * 会话过期时被调一次（见 `rpc` 的 404 自愈）。**给可观测用**：默认自愈是静默的，
+     * 而「静默恢复」和「静默失效」在监控上看不出区别 —— 要计数 / 告警 / 打日志就挂这个钩子。
+     */
+    onSessionExpired?: () => void;
+    /** 注入 `fetch`（测试用；缺省全局 `fetch`，与 `createOpenAIClient` 同款） */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * **StreamableHTTP 连接器**：一个 endpoint，POST JSON-RPC（MCP 2025-03-26 起的
+ * Streamable HTTP 传输）。
+ *
+ * - 两种响应形态**都要接**：`application/json`（整条报文）与 `text/event-stream`
+ *   （报文按 SSE 帧下发，server 应在发完响应后关流）；
+ * - 会话：`initialize` 响应里的 `Mcp-Session-Id` 会被记住并在后续请求上回带
+ *   （后续响应不带该头时**不覆盖**）；`close()` 尽力 `DELETE` 终止会话；
+ *   **会话过期自愈**：带会话 id 收到 `404` ⇒ 视为「会话已终止、该请求未被 server 执行」
+ *   ⇒ 丢会话 → 重新握手 → 把这一次**重试一次**（只一次，不再循环）。自愈是静默的，
+ *   所以给了 `onSessionExpired` 钩子给你计数 / 告警 —— 否则它和「静默失效」没区别。
+ * - 协议版本：请求头 `MCP-Protocol-Version` 带**协商到的**版本（2025-06-18 起要求，
+ *   老 server 忽略未知头）；
+ * - HTTP 层失败**挂数值 `status`** ⇒ `engine/errors.ts::classifyError` 自动分流
+ *   （429 → `rate_limit` 可重试 / ≥500 → `server` 可重试 / 其余 4xx → `api` 不可重试）。
+ */
+export declare function createStreamableHttpMcpConnector(url: string, opts?: StreamableHttpMcpConnectorOptions): McpConnector;