@migor/agentia 0.7.1 → 0.7.2

package/dist/integrations/mcp-stdio.js

@@ -0,0 +1,230 @@
+import { spawn } from 'node:child_process';
+import { DEFAULT_CLIENT_INFO, DEFAULT_PROTOCOL_VERSION, MCP_DEFAULT_TIMEOUT_MS, brief, isJsonRpcResponse, unwrap, withDeadline, } from './mcp.js';
+/**
+ * MCP **stdio 连接器**（内置默认件之一）：spawn 子进程、换行分隔 JSON-RPC。
+ * 桥与共享 helper 在 `mcp.ts`；本文件只含 stdio 传输。module 级 export，
+ * 公共面仍由 `mcp.ts` re-export（`src/index.ts` 不变）。
+ */
+/** `close()` 里 SIGTERM → SIGKILL 的宽限期（毫秒） */
+export const MCP_CLOSE_GRACE_MS = 2_000;
+/**
+ * **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 function createStdioMcpConnector(cmd, opts = {}) {
+    const bin = cmd[0];
+    if (typeof bin !== 'string' || bin === '') {
+        throw new Error('createStdioMcpConnector：cmd 不能为空（需要可执行文件 + 参数）');
+    }
+    const rest = cmd.slice(1);
+    const timeoutMs = opts.timeoutMs ?? MCP_DEFAULT_TIMEOUT_MS;
+    const clientInfo = opts.clientInfo ?? DEFAULT_CLIENT_INFO;
+    const protocolVersion = opts.protocolVersion ?? DEFAULT_PROTOCOL_VERSION;
+    let proc = null;
+    let fatal = null;
+    let closed = false;
+    let exited = false;
+    let buf = '';
+    let nextId = 1;
+    let ready = null;
+    let resolveExit = null;
+    const exitPromise = new Promise((r) => {
+        resolveExit = r;
+    });
+    const pending = new Map();
+    const markExited = () => {
+        exited = true;
+        resolveExit?.();
+    };
+    /** 进程已死 / 已 close 时一次性拒绝全部在途请求 —— 不留永久挂起的 promise */
+    const fail = (err) => {
+        fatal = err;
+        for (const p of pending.values())
+            p.reject(err);
+        pending.clear();
+    };
+    const guard = (p, label) => withDeadline(p, timeoutMs, label);
+    const ensureProc = () => {
+        if (closed)
+            throw new Error('MCP 连接器已 close —— 请重新创建一个');
+        if (fatal)
+            throw fatal;
+        if (proc)
+            return proc;
+        const spawnOpts = {
+            stdio: ['pipe', 'pipe', opts.stderr ?? 'inherit'],
+            // exactOptionalPropertyTypes：可选字段不能赋 undefined，只能条件展开
+            ...(opts.env ? { env: { ...process.env, ...opts.env } } : {}),
+            ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        };
+        const p = spawn(bin, rest, spawnOpts);
+        proc = p;
+        p.on('error', (err) => {
+            // 见函数头第 1 条：这个监听器不是可选的
+            fail(err instanceof Error ? err : new Error(String(err)));
+            markExited();
+        });
+        p.on('exit', (code, signal) => {
+            if (!closed) {
+                fail(new Error(`MCP server 进程已退出（code=${code ?? 'null'} signal=${signal ?? 'null'}）`));
+            }
+            markExited();
+        });
+        // 'exit' 在 spawn 失败时可能不触发，'close' 一定会 —— close() 靠它才不会白等
+        p.on('close', markExited);
+        // 进程已死时写 stdin 会异步报 EPIPE；真实原因由上面的 'error' / 'exit' 给出
+        p.stdin?.on('error', () => {
+            /* 吞掉：EPIPE 是「进程没了」的次生现象，不是根因 */
+        });
+        p.stdout?.setEncoding('utf8');
+        p.stdout?.on('data', (chunk) => {
+            buf += chunk;
+            for (;;) {
+                const nl = buf.indexOf('\n');
+                if (nl < 0)
+                    break;
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (line.trim() === '')
+                    continue;
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    continue; // MCP 规定 stdout 只走协议，但 server 混日志进来是常事
+                }
+                if (!isJsonRpcResponse(msg))
+                    continue; // 通知（无 id）不配对
+                const waiter = pending.get(msg.id);
+                if (!waiter)
+                    continue;
+                pending.delete(msg.id);
+                try {
+                    waiter.resolve(unwrap(msg, 'response'));
+                }
+                catch (e) {
+                    waiter.reject(e instanceof Error ? e : new Error(String(e)));
+                }
+            }
+        });
+        return p;
+    };
+    const write = (payload) => {
+        const p = ensureProc();
+        p.stdin?.write(`${JSON.stringify(payload)}\n`);
+    };
+    const send = (method, params, abandoned) => {
+        if (closed)
+            return Promise.reject(new Error('MCP 连接器已 close —— 请重新创建一个'));
+        if (fatal)
+            return Promise.reject(fatal);
+        const id = nextId++;
+        return new Promise((resolve, reject) => {
+            try {
+                ensureProc();
+            }
+            catch (e) {
+                reject(e instanceof Error ? e : new Error(String(e)));
+                return;
+            }
+            pending.set(id, { resolve, reject });
+            // 裁判放弃等待 ≠ 条目自动回收：超时的调用（引擎 toolTimeoutMs 或桥兜底）只是
+            // 不再 await，pending 里的 {resolve,reject} 会留到「server 终于回包 / 进程死 /
+            // close」—— 对「活着但不回包」的 server 就是无界泄漏。裁判表过态就删条目：
+            // 之后回包到了也没人等（:441 的 pending.get 落空即忽略，语义安全）。
+            if (abandoned !== undefined) {
+                const drop = () => {
+                    pending.delete(id);
+                };
+                if (abandoned.aborted)
+                    drop();
+                else
+                    abandoned.addEventListener('abort', drop, { once: true });
+            }
+            write({ jsonrpc: '2.0', id, method, params });
+        });
+    };
+    /** 握手只做一次；失败是**粘性**的（连接器已不可用 → 重建，而不是半初始化态） */
+    const ensureReady = () => {
+        if (ready)
+            return ready;
+        ready = (async () => {
+            const init = await guard(send('initialize', { protocolVersion, capabilities: {}, clientInfo }), 'initialize');
+            // 协商结果以 server 回的那个为准（协议允许 server 降级或选自己的版本）
+            void init;
+            write({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} });
+        })();
+        return ready;
+    };
+    const request = async (method, params, abandoned) => {
+        await ensureReady();
+        return send(method, params, abandoned);
+    };
+    const listTools = async () => {
+        const r = await guard(request('tools/list', {}), 'tools/list');
+        if (typeof r !== 'object' || r === null) {
+            throw new Error(`MCP tools/list 返回了非对象：${brief(r)}`);
+        }
+        const listed = r.tools;
+        if (listed === undefined)
+            return [];
+        if (!Array.isArray(listed)) {
+            // 响亮失败：把协议不符吞成空菜单，用户看到的是「一个工具都没有」而不是「server 坏了」
+            throw new Error(`MCP tools/list 的 tools 不是数组：${brief(listed)}`);
+        }
+        return listed;
+    };
+    const callTool = async (name, args, callOpts) => {
+        const r = await request('tools/call', { name, arguments: args }, callOpts?.abandoned);
+        // 承重：协议层 isError 只有连接器看得见（见函数头第 3 条）
+        if (typeof r === 'object' && r !== null && r.isError) {
+            throw new Error(`MCP 工具 ${name} 返回 isError: ${brief(r.content)}`);
+        }
+        return r;
+    };
+    return {
+        listTools,
+        callTool,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            fail(new Error('MCP 连接器已 close —— 请重新创建一个'));
+            const p = proc;
+            proc = null;
+            if (!p)
+                return;
+            p.kill('SIGTERM');
+            if (exited)
+                return;
+            const killTimer = setTimeout(() => {
+                try {
+                    p.kill('SIGKILL');
+                }
+                catch {
+                    /* 已经死了 */
+                }
+                // ⚠️ 这里**不** resolve：SIGKILL 不可被捕获，'exit'/'close' 必达 —— 继续等真的退出。
+                // 到点即返回是 2026-09-18 之前的行为：调用方以为进程没了，实际还留着一个孤儿。
+            }, MCP_CLOSE_GRACE_MS);
+            try {
+                await exitPromise;
+            }
+            finally {
+                clearTimeout(killTimer);
+            }
+        },
+    };
+}
+//# sourceMappingURL=mcp-stdio.js.map

package/dist/integrations/mcp-stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-stdio.js","sourceRoot":"","sources":["../../src/integrations/mcp-stdio.ts"],"names":[],"mappings":"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"}

package/dist/integrations/mcp.d.ts

@@ -6,9 +6,11 @@ import type { AgentTool } from '../core/tool.js';
  * `McpClientLike` 的客户端都能接（同 `RedisLike` 的 duck-typing）。本文件只依赖 core，
  * 符合分层约定（`integrations` → `core`）。
  *
- * **连接器**（2026-09-18 起**内置**，见文件末「连接器」一节与 spec §10 同日条）：
+ * **连接器**（2026-09-18 起**内置**，见文末「连接器」一节与 spec §10 同日条）：
  * `createStdioMcpConnector` / `createStreamableHttpMcpConnector`。二者只用标准库
  * （`node:child_process` + 全局 `fetch`），**不新增任何第三方依赖**。
+ * 2026-09-20 起两个连接器各居其文件（`mcp-stdio.ts` / `mcp-http.ts`，纯结构拆分、
+ * 零行为变化），本文件保留桥 + 共享 helper 并 re-export —— 公共面不变。
  *
  * 用法（接入点是 `AppOptions.tools` 这条**裸工具缝**）：
  * ```ts
@@ -114,80 +116,43 @@ export interface McpConnector extends McpClientLike {
      */
     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；
- * 握手只做一次（并发调用共享同一次握手）。
+ * 缺省 `clientInfo`（`initialize` 握手要发，协议要求该字段存在）。
  *
- * 三处非显然的坑，这里都兜住了（此前 `scripts/e2e-mcp.ts` 内联的那 94 行踩过）：
- * 1. spawn **失败**（命令不存在 → `ENOENT`）是异步的 `'error'` 事件，不是抛出 ——
- *    没有监听器就是未捕获异常、直接把宿主进程带崩，所以必须接住并拒绝在途请求；
- * 2. 分帧：一条报文可能跨多个 chunk，必须自己攒 buffer 按 `\n` 切；
- * 3. **协议层 `isError: true` 必须转成抛错** —— 否则模型收到一条「成功」的结果，
- *    trace 也把它记成成功的调用（`McpClientLike` 的约定，见其注释）。
+ * **刻意不写框架自身版本**：`integrations` 层不 import 公共面（`AGENTIA_VERSION` 在
+ * `src/index.ts`），且 `scripts/release-surface.mjs` 的发版面按**精确版本串**计数 ——
+ * 这里多一处版本字面量会让它的 count 断言失配。需要真实版本请自行传 `clientInfo`。
  */
-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;
-}
+export declare const DEFAULT_CLIENT_INFO: {
+    name: string;
+    version: string;
+};
+/** `initialize` 缺省请求的协议版本（e2e 已验证的版本；要对齐新版 server 请显式传） */
+export declare const DEFAULT_PROTOCOL_VERSION = "2024-11-05";
 /**
- * **StreamableHTTP 连接器**：一个 endpoint，POST JSON-RPC（MCP 2025-03-26 起的
- * Streamable HTTP 传输）。
+ * 装配期超时的落点：**握手 + `tools/list`**。
  *
- * - 两种响应形态**都要接**：`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` 不可重试）。
+ * 为什么不给 `callTool` 也套一个：一次调用只有一个裁判（见 `McpToolsOptions.timeoutMs`）。
+ * 走 `mcpTools` 时 `callTool` 由引擎 / 桥判定；而握手与 `tools/list` 发生在**装配期**，
+ * 没有任何别的裁判 —— server 卡住会让 `createApp` 永久挂起，必须在这里兜住。
  */
-export declare function createStreamableHttpMcpConnector(url: string, opts?: StreamableHttpMcpConnectorOptions): McpConnector;
+export type Guard = <T>(p: Promise<T>, label: string) => Promise<T>;
+/** 把可能很大的值截成可读片段（错误消息要能进日志，不能是一兆的 JSON） */
+export declare function brief(value: unknown, max?: number): string;
+/** JSON-RPC 错误对象 → `Error`（`code` 进文案：`classifyError` 只认数值 `status`，这里不冒充它） */
+export declare function jsonRpcError(err: unknown): Error;
+/** server 混进 stdout / SSE 的非 JSON 行 */
+export declare function isJsonRpcResponse(msg: unknown): msg is {
+    id: number;
+    result?: unknown;
+    error?: unknown;
+};
+/** 从一条已解析的报文里取结果；带 `error` 则抛 */
+export declare function unwrap(msg: {
+    result?: unknown;
+    error?: unknown;
+}, method: string): unknown;
+export { createStdioMcpConnector, MCP_CLOSE_GRACE_MS } from './mcp-stdio.js';
+export type { StdioMcpConnectorOptions } from './mcp-stdio.js';
+export { createStreamableHttpMcpConnector } from './mcp-http.js';
+export type { StreamableHttpMcpConnectorOptions } from './mcp-http.js';