@migor/agentia 0.7.0 → 0.7.2

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
@@ -40,7 +42,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 {
     /**
@@ -106,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`）。
+ * 缺省 `clientInfo`（`initialize` 握手要发，协议要求该字段存在）。
  *
- * 进程与握手都是**惰性**的 —— 构造不产生副作用，第一次 `listTools` / `callTool` 才 spawn；
- * 握手只做一次（并发调用共享同一次握手）。
- *
- * 三处非显然的坑，这里都兜住了（此前 `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';

package/dist/integrations/mcp.js

@@ -1,5 +1,5 @@
-import { spawn } from 'node:child_process';
 import { TIMED_OUT, TimeoutError, withTimeout } from '../core/timeout.js';
+import { combineSignals, releaseCombinedSignal } from '../core/abort.js';
 /** 缺省超时：MCP server 可能去连外部系统，60s 是「明显卡死」与「慢但正常」的分界 */
 export const MCP_DEFAULT_TIMEOUT_MS = 60_000;
 /**
@@ -113,16 +113,26 @@ export async function mcpTools(client, opts = {}) {
                 // 与「一次调用只有一个裁判」相反：说了不限就该不限。
                 const engineBudget = ctx?.toolTimeoutMs;
                 if (engineBudget != null) {
-                    return client.callTool(original, args);
+                    // 引擎是裁判：它的 toolTimeoutMs 到点会 fire ctx.abandoned —— 连接器据此
+                    // 清掉这次调用的簿记（stdio 的 pending 条目），不留下等不到回收的残骸。
+                    return client.callTool(original, args, ctx?.abandoned !== undefined ? { abandoned: ctx.abandoned } : undefined);
+                }
+                // 桥兜底裁判（脱离引擎单用 / 引擎没设超时）：到点除了放弃等待，还要通知连接器
+                // 清理簿记 —— 与引擎路径共用同一个 `abandoned` 缝（`core/abort.ts` 合成）。
+                const ac = new AbortController();
+                const abandoned = ctx?.abandoned !== undefined ? combineSignals(ctx.abandoned, ac.signal) : ac.signal;
+                try {
+                    return await withDeadline(client.callTool(original, args, { abandoned }), timeoutMs, original);
+                }
+                finally {
+                    ac.abort(); // 无论成败都摘掉：成功时条目已被响应清掉，超时/出错时靠这次 abort 清
+                    releaseCombinedSignal(abandoned); // 摘除挂在 ctx.abandoned 上的监听器
                 }
-                return withDeadline(client.callTool(original, args), timeoutMs, original);
             },
         });
     }
     return tools;
 }
-/** `close()` 里 SIGTERM → SIGKILL 的宽限期（毫秒） */
-export const MCP_CLOSE_GRACE_MS = 2_000;
 /**
  * 缺省 `clientInfo`（`initialize` 握手要发，协议要求该字段存在）。
  *
@@ -130,14 +140,14 @@ export const MCP_CLOSE_GRACE_MS = 2_000;
  * `src/index.ts`），且 `scripts/release-surface.mjs` 的发版面按**精确版本串**计数 ——
  * 这里多一处版本字面量会让它的 count 断言失配。需要真实版本请自行传 `clientInfo`。
  */
-const DEFAULT_CLIENT_INFO = {
+export const DEFAULT_CLIENT_INFO = {
     name: 'agentia',
     version: '0.0.0',
 };
 /** `initialize` 缺省请求的协议版本（e2e 已验证的版本；要对齐新版 server 请显式传） */
-const DEFAULT_PROTOCOL_VERSION = '2024-11-05';
+export const DEFAULT_PROTOCOL_VERSION = '2024-11-05';
 /** 把可能很大的值截成可读片段（错误消息要能进日志，不能是一兆的 JSON） */
-function brief(value, max = 200) {
+export function brief(value, max = 200) {
     let s;
     try {
         s = typeof value === 'string' ? value : JSON.stringify(value);
@@ -150,7 +160,7 @@ function brief(value, max = 200) {
     return s.length > max ? `${s.slice(0, max)}…` : s;
 }
 /** JSON-RPC 错误对象 → `Error`（`code` 进文案：`classifyError` 只认数值 `status`，这里不冒充它） */
-function jsonRpcError(err) {
+export function jsonRpcError(err) {
     if (typeof err === 'object' && err !== null) {
         const { code, message } = err;
         return new Error(`MCP error ${String(code)}: ${String(message)}`);
@@ -158,425 +168,18 @@ function jsonRpcError(err) {
     return new Error(`MCP error: ${brief(err)}`);
 }
 /** server 混进 stdout / SSE 的非 JSON 行 */
-function isJsonRpcResponse(msg) {
+export function isJsonRpcResponse(msg) {
     return (typeof msg === 'object' && msg !== null && typeof msg.id === 'number');
 }
 /** 从一条已解析的报文里取结果；带 `error` 则抛 */
-function unwrap(msg, method) {
+export function unwrap(msg, method) {
     if (msg.error !== undefined)
         throw jsonRpcError(msg.error);
     if (!('result' in msg))
         throw new Error(`MCP ${method}：响应里既没有 result 也没有 error`);
     return msg.result;
 }
-/**
- * **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) => {
-        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 });
-            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) => {
-        await ensureReady();
-        return send(method, params);
-    };
-    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) => {
-        const r = await request('tools/call', { name, arguments: args });
-        // 承重：协议层 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);
-            }
-        },
-    };
-}
-/**
- * **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 function createStreamableHttpMcpConnector(url, opts = {}) {
-    if (typeof url !== 'string' || url === '') {
-        throw new Error('createStreamableHttpMcpConnector：url 不能为空');
-    }
-    const fetchImpl = opts.fetchImpl ?? fetch;
-    const timeoutMs = opts.timeoutMs ?? MCP_DEFAULT_TIMEOUT_MS;
-    const clientInfo = opts.clientInfo ?? DEFAULT_CLIENT_INFO;
-    const requestedVersion = opts.protocolVersion ?? DEFAULT_PROTOCOL_VERSION;
-    const baseHeaders = {
-        'content-type': 'application/json',
-        // MCP 规定客户端必须同时接受两种响应形态（否则 server 无法按规范回 SSE）
-        accept: 'application/json, text/event-stream',
-        ...opts.headers,
-    };
-    let sessionId = null;
-    let negotiated = requestedVersion;
-    let closed = false;
-    let ready = null;
-    let nextId = 1;
-    const guard = (p, label) => withDeadline(p, timeoutMs, label);
-    /** HTTP 层失败：带上数值 `status`，让 `classifyError` 能按状态分流 */
-    const httpError = (status, method, body) => {
-        const e = new Error(`MCP ${method} HTTP ${status}${body ? `：${body}` : ''}`);
-        e.status = status;
-        return e;
-    };
-    const readText = async (res) => {
-        try {
-            return await res.text();
-        }
-        catch {
-            return '';
-        }
-    };
-    const post = async (payload, o = {}) => {
-        if (closed)
-            throw new Error('MCP 连接器已 close —— 请重新创建一个');
-        const headers = { ...baseHeaders };
-        if (sessionId !== null)
-            headers['mcp-session-id'] = sessionId;
-        if (o.withVersion)
-            headers['mcp-protocol-version'] = negotiated;
-        const res = await fetchImpl(url, { method: 'POST', headers, body: JSON.stringify(payload) });
-        // 会话 id 只在 initialize 响应里出现；后续响应不带时**不能**把它清成 null
-        const sid = res.headers.get('mcp-session-id');
-        if (sid !== null && sid !== '')
-            sessionId = sid;
-        return res;
-    };
-    /** 非 SSE 报文（单条 JSON-RPC）→ 取 result；SSE 里可能有别的通知帧，只取与 `id` 配对的 */
-    const pickResult = (msg, id, method) => {
-        if (!isJsonRpcResponse(msg)) {
-            throw new Error(`MCP ${method}：响应里没有 id 为 ${id} 的 JSON-RPC 报文`);
-        }
-        return unwrap(msg, method);
-    };
-    /**
-     * 从响应取结果。SSE 分支一次性读完整个 body 再解析 —— StreamableHTTP 约定 server 发完
-     * 响应即关流，读全比手写增量解析器稳（`text/event-stream` 里 `data:` 行按规范可跨多行拼接）。
-     */
-    const readResult = async (res, id, method) => {
-        const ct = (res.headers.get('content-type') ?? '').toLowerCase();
-        const text = await readText(res);
-        if (ct.includes('text/event-stream')) {
-            for (const frame of text.split(/\r?\n\r?\n/)) {
-                const data = frame
-                    .split(/\r?\n/)
-                    .filter((l) => l.startsWith('data:'))
-                    .map((l) => l.slice(5).trim())
-                    .join('');
-                if (data === '')
-                    continue;
-                let msg;
-                try {
-                    msg = JSON.parse(data);
-                }
-                catch {
-                    continue;
-                }
-                if (isJsonRpcResponse(msg) && msg.id === id)
-                    return unwrap(msg, method);
-            }
-            throw new Error(`MCP ${method}：SSE 响应里没有 id 为 ${id} 的报文`);
-        }
-        if (text.trim() === '') {
-            throw new Error(`MCP ${method}：响应体为空（期望 id 为 ${id} 的 JSON-RPC 报文）`);
-        }
-        let msg;
-        try {
-            msg = JSON.parse(text);
-        }
-        catch {
-            throw new Error(`MCP ${method}：响应不是合法 JSON：${brief(text)}`);
-        }
-        return pickResult(msg, id, method);
-    };
-    /**
-     * 一次 JSON-RPC 往返，带**会话过期自愈**（2026-09-18；MCP Streamable HTTP 的规范语义）。
-     *
-     * 带会话 id 收到 `404` 的含义是「这个会话我不认识」⇒ **该请求没有被执行** ——
-     * 所以丢掉会话、重新握手、把这一次**重试一次**是安全的（不会重复执行副作用）。
-     * 规范也是这么要求的：客户端**必须**新建会话（不带会话 id 重新 `initialize`）。
-     *
-     * **只重试一次**：第二次再 404 说明对面不是「会话过期」而是别的问题，直接抛（不循环）。
-     * 自愈本身是静默的，但可通过 `onSessionExpired` 观测 —— 否则它和「静默失效」没区别。
-     */
-    const rpc = async (method, params, withVersion, allowReinit = true) => {
-        const id = nextId++;
-        const res = await post({ jsonrpc: '2.0', id, method, params }, { withVersion });
-        if (res.status === 404 && sessionId !== null && allowReinit) {
-            await readText(res); // 排空，别把连接晾着
-            opts.onSessionExpired?.();
-            sessionId = null;
-            ready = null; // 下一次 ensureReady 会新建会话
-            await ensureReady();
-            return rpc(method, params, withVersion, false);
-        }
-        if (!res.ok)
-            throw httpError(res.status, method, await readText(res));
-        return guard(readResult(res, id, method), method);
-    };
-    const ensureReady = () => {
-        if (ready)
-            return ready;
-        ready = (async () => {
-            const init = await guard(rpc('initialize', { protocolVersion: requestedVersion, capabilities: {}, clientInfo }, false), 'initialize');
-            if (typeof init === 'object' && init !== null) {
-                const v = init.protocolVersion;
-                if (typeof v === 'string' && v !== '')
-                    negotiated = v;
-            }
-            const res = await guard(post({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} }, { withVersion: true }), 'notifications/initialized');
-            if (!res.ok) {
-                throw httpError(res.status, 'notifications/initialized', await readText(res));
-            }
-            await readText(res); // 排空：202 + 空体是合法应答，但别把连接晾着
-        })();
-        return ready;
-    };
-    const listTools = async () => {
-        await ensureReady();
-        const r = await guard(rpc('tools/list', {}, true), '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)) {
-            throw new Error(`MCP tools/list 的 tools 不是数组：${brief(listed)}`);
-        }
-        return listed;
-    };
-    const callTool = async (name, args) => {
-        await ensureReady();
-        const r = await rpc('tools/call', { name, arguments: args }, true);
-        // 承重同 stdio：协议层 isError 只有连接器看得见
-        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;
-            const sid = sessionId;
-            sessionId = null;
-            if (sid === null)
-                return;
-            try {
-                // 尽力终止会话（MCP 约定的显式关闭）；server 不认这个方法也不该让 close() 抛
-                const res = await fetchImpl(url, {
-                    method: 'DELETE',
-                    headers: { ...baseHeaders, 'mcp-session-id': sid, 'mcp-protocol-version': negotiated },
-                });
-                await readText(res);
-            }
-            catch {
-                /* 关闭是尽力而为 */
-            }
-        },
-    };
-}
+// 两个内置连接器（2026-09-20 起各居其文件；公共面不变，index.ts 仍从这里取）
+export { createStdioMcpConnector, MCP_CLOSE_GRACE_MS } from './mcp-stdio.js';
+export { createStreamableHttpMcpConnector } from './mcp-http.js';
 //# sourceMappingURL=mcp.js.map