@migor/agentia 0.10.1 → 0.10.3

package/dist/integrations/file-sink.js

@@ -3,8 +3,8 @@ import { dirname } from 'node:path';
 /**
  * Agentia —— JSONL 文件 sink：一行一条**裸 Trace** 追加落盘。
  *
- * 这是 CLI 三件套 `agentia report` / `agentia diff` / `agentia harvest` 的**输入格式**
- * （每行一个 JSON，裸 Trace）—— 消费侧早就吃这个文件，产出侧此前要用户手写
+ * 这是 CLI 四件套 `agentia report` / `agentia diff` / `agentia harvest` / `agentia export`
+ * 的**输入格式**（每行一个 JSON，裸 Trace）—— 消费侧早就吃这个文件，产出侧此前要用户手写
  * `appendFileSync` 的 sink，这里把它收进框架。
  *
  * 语义：

package/dist/integrations/mcp-http.js

@@ -1,4 +1,4 @@
-import { DEFAULT_CLIENT_INFO, DEFAULT_PROTOCOL_VERSION, MCP_DEFAULT_TIMEOUT_MS, brief, isJsonRpcResponse, unwrap, withDeadline, } from './mcp-protocol.js';
+import { DEFAULT_CLIENT_INFO, DEFAULT_PROTOCOL_VERSION, MCP_DEFAULT_TIMEOUT_MS, assertToolResultNotError, canSelfHealSession, mcpHttpError, parseToolList, readMcpResult, readMcpText, toolsCallParams, withDeadline, } from './mcp-protocol.js';
 /**
  * **StreamableHTTP 连接器**：一个 endpoint，POST JSON-RPC（MCP 2025-03-26 起的
  * Streamable HTTP 传输）。
@@ -36,20 +36,6 @@ export function createStreamableHttpMcpConnector(url, opts = {}) {
     let reinit = 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 —— 请重新创建一个');
@@ -73,55 +59,6 @@ export function createStreamableHttpMcpConnector(url, opts = {}) {
             sessionId = sid;
         return res;
     };
-    /** 非 SSE 报文（单条 JSON-RPC）→ 取 result；SSE 里可能有别的通知帧，只取与 `id` 配对的 */
-    const pickResult = (msg, id, method) => {
-        // id 必须**等值**配对（与 SSE 分支同款）：只验「是带 id 的响应」会把别的请求的
-        // 结果当本次的返回（代理串包/通知帧），静默错值比报错难查得多。
-        if (!isJsonRpcResponse(msg) || msg.id !== id) {
-            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);
-    };
     /**
      * 会话过期自愈的互斥：并发请求同时吃到 404 时**共享同一次重握手**。
      * 没有这层时，两个并发调用各自执行 `ready = null`（第二个会把第一个刚建的握手
@@ -154,20 +91,20 @@ export function createStreamableHttpMcpConnector(url, opts = {}) {
     const rpc = async (method, params, withVersion, allowReinit = true, abandoned) => {
         const id = nextId++;
         const res = await post({ jsonrpc: '2.0', id, method, params }, { withVersion, ...(abandoned !== undefined ? { signal: abandoned } : {}) });
-        if (res.status === 404 && sessionId !== null && allowReinit) {
-            await readText(res); // 排空，别把连接晾着
+        if (canSelfHealSession(res.status, sessionId !== null, allowReinit)) {
+            await readMcpText(res); // 排空，别把连接晾着
             opts.onSessionExpired?.();
             await reinitialize();
             // 自愈重试那次同样带上 abandoned —— 裁判放弃时两条在飞 fetch 都要被掐
             return rpc(method, params, withVersion, false, abandoned);
         }
         if (!res.ok)
-            throw httpError(res.status, method, await readText(res));
+            throw mcpHttpError(res.status, method, await readMcpText(res));
         // 计时裁判权在调用方（initialize / notifications / tools/list 都在调用点自带
         // guard —— 它们是装配期路径、没有别的裁判）；`tools/call` 不在此起计时器：
-        // 它的裁判是引擎的 `toolTimeoutMs`（spec §10 2026-09-17 ① 超时单源化）——
+        // 它的裁判是引擎的 `toolTimeoutMs`（spec §10 2026-09-17 ref-mcp-timeout-single-source 超时单源化）——
         // 再包一层 guard 就是双计时器，同一事件两本账（stdio 侧就没有这层）。
-        return readResult(res, id, method);
+        return readMcpResult(res, id, method);
     };
     const ensureReady = () => {
         if (ready)
@@ -181,33 +118,23 @@ export function createStreamableHttpMcpConnector(url, opts = {}) {
             }
             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));
+                throw mcpHttpError(res.status, 'notifications/initialized', await readMcpText(res));
             }
-            await readText(res); // 排空：202 + 空体是合法应答，但别把连接晾着
+            await readMcpText(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;
+        return parseToolList(r);
     };
     const callTool = async (name, args, callOpts) => {
         await ensureReady();
-        const r = await rpc('tools/call', { name, arguments: args }, true, true, callOpts?.abandoned);
-        // 承重同 stdio：协议层 isError 只有连接器看得见
-        if (typeof r === 'object' && r !== null && r.isError) {
-            throw new Error(`MCP 工具 ${name} 返回 isError: ${brief(r.content)}`);
-        }
+        // `toolsCallParams` 把 SEP-414 的 traceparent 放进 params._meta（裸键）；没有则不留 _meta 键
+        const r = await rpc('tools/call', toolsCallParams(name, args, callOpts?.traceparent), true, true, callOpts?.abandoned);
+        // 承重同 stdio：协议层 isError 只有连接器看得见（判定与文案在 mcp-protocol.ts）
+        assertToolResultNotError(r, name);
         return r;
     };
     return {
@@ -228,7 +155,7 @@ export function createStreamableHttpMcpConnector(url, opts = {}) {
                 // **抛错**，兜不住**挂死** —— server 接受连接后不回（半开 / 卡在代理后面），
                 // `close()` 就永久挂住，而调用方（宿主停机路径）会一直等它。**挂住比失败更糟**，
                 // 与「best-effort、不抛错」的承诺相悖。fetch 与排空**一起**进 guard：
-                // 只护住响应头、body 照样能卡（`readText` 读的是 body）。
+                // 只护住响应头、body 照样能卡（`readMcpText` 读的是 body）。
                 await guard((async () => {
                     const res = await fetchImpl(url, {
                         method: 'DELETE',
@@ -238,7 +165,7 @@ export function createStreamableHttpMcpConnector(url, opts = {}) {
                             'mcp-protocol-version': negotiated,
                         },
                     });
-                    await readText(res);
+                    await readMcpText(res);
                 })(), 'close');
             }
             catch {

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

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

package/dist/integrations/mcp-protocol.d.ts

@@ -26,6 +26,26 @@ export interface McpToolInfo {
     /** MCP 协议里已是 JSON Schema → 直接当框架的 `inputSchema` 用 */
     inputSchema?: unknown;
 }
+/**
+ * `callTool` 的第三参（桥与两个连接器**共用**这一份 —— 2026-10-12 SEP-414 起多了
+ * `traceparent`，形状只许有一处定义）。
+ */
+export interface McpCallOptions {
+    /**
+     * 裁判（引擎 `toolTimeoutMs` / 桥兜底超时）**放弃等待**的通知信号。
+     * 放弃 ≠ 取消 —— 但连接器应借此清掉这次调用的簿记（stdio 的 pending 条目、
+     * HTTP 的在飞 fetch），否则「server 活着但不回包」时每超时一次就泄漏一条。
+     */
+    abandoned?: AbortSignal;
+    /**
+     * 出站传播（SEP-414，Final）：本次调用的 W3C `traceparent`，连接器把它放进
+     * `params._meta.traceparent`（**裸键，不加前缀**；与 `name` / `arguments` 平级，
+     * **绝不进 `arguments`** —— 那是模型可见的工具签名，trace 上下文进去就污染 schema）。
+     * 缺席时 params **不落 `_meta` 键**：「没有上下文可传」与「传一个空上下文」不是一回事。
+     * 不认识该字段的旧客户端忽略即可（可选参数，鸭子类型）。
+     */
+    traceparent?: string;
+}
 /**
  * MCP client 的最小结构面：任何实现了 `tools/list` + `tools/call` 的客户端都能接，
  * 无需继承、无需 import 任何 SDK（duck-typed，与 `RedisLike` 同款）。
@@ -36,15 +56,8 @@ export interface McpToolInfo {
  */
 export interface McpClientLike {
     listTools(): Promise<McpToolInfo[]>;
-    /**
-     * `opts.abandoned`：裁判（引擎 `toolTimeoutMs` / 桥兜底超时）**放弃等待**的通知信号。
-     * 放弃 ≠ 取消 —— 但连接器应借此清掉这次调用的簿记（stdio 的 pending 条目、
-     * HTTP 的在飞 fetch），否则「server 活着但不回包」时每超时一次就泄漏一条。
-     * 只实现两个参数的旧客户端依然兼容（可选参数，鸭子类型）。
-     */
-    callTool(name: string, args: Record<string, unknown>, opts?: {
-        abandoned?: AbortSignal;
-    }): Promise<unknown>;
+    /** 选项见 {@link McpCallOptions}；只实现两个参数的旧客户端依然兼容（可选参数，鸭子类型）。 */
+    callTool(name: string, args: Record<string, unknown>, opts?: McpCallOptions): Promise<unknown>;
 }
 /**
  * 连接器公共面：`McpClientLike` + 一个关闭句柄（两个内置连接器都返回它）。
@@ -90,7 +103,7 @@ export declare const DEFAULT_PROTOCOL_VERSION = "2024-11-05";
  * 给一次 MCP 调用套超时。⚠️ 与引擎的工具超时同样是**放弃等待**而非取消 ——
  * MCP 的 `notifications/cancelled` 属于连接器职责，桥这一层拿不到取消句柄。
  *
- * 实现是 `core/timeout.ts` 共享原语的**薄封装**（2026-09-17 单源化，见 spec §10 2026-09-17 ①）：
+ * 实现是 `core/timeout.ts` 共享原语的**薄封装**（2026-09-17 单源化，见 spec §10 2026-09-17 ref-mcp-timeout-single-source）：
  * 「一次调用只有一个预算判定」在引擎与桥之间只允许有一份实现。此前桥自带一份**纯竞速**
  * 版本，于是 2026-09-14 的「超时是硬的」收紧只落进引擎，桥继续把**超预算**的调用记成成功。
  *
@@ -113,3 +126,66 @@ export declare function unwrap(msg: {
     result?: unknown;
     error?: unknown;
 }, method: string): unknown;
+/**
+ * 读响应体文本；读失败**返回空串而非抛**。
+ *
+ * 为什么吞：调用方用它的地方（排空、错误文案、SSE 解析）都不该因为「body 读不出来」二次失败
+ * —— 真正的原因由 `res.status` / 网络层给出，这里再抛只会把第一条错误盖掉。
+ */
+export declare function readMcpText(res: Response): Promise<string>;
+/** HTTP 层失败：带上数值 `status`，让 `classifyError` 能按状态分流 */
+export declare function mcpHttpError(status: number, method: string, body: string): Error;
+/**
+ * 非 SSE 报文（单条 JSON-RPC）→ 取 result。
+ *
+ * ⚠️ id 必须**等值**配对（与 SSE 分支同款）：只验「是带 id 的响应」会把别的请求的结果
+ * 当本次的返回（代理串包 / 通知帧），**静默错值比报错难查得多**。
+ */
+export declare function pickJsonRpcResult(msg: unknown, id: number, method: string): unknown;
+/**
+ * 从 HTTP 响应取结果 —— 两种响应形态**都要接**（StreamableHTTP 的规范面）。
+ *
+ * SSE 分支一次性读完整个 body 再解析：StreamableHTTP 约定 server 发完响应即关流，
+ * 读全比手写增量解析器稳（`text/event-stream` 里 `data:` 行按规范可跨多行拼接）。
+ * SSE 里可能有别的通知帧或别的请求的应答，**只取与 `id` 配对的**那一条。
+ */
+export declare function readMcpResult(res: Response, id: number, method: string): Promise<unknown>;
+/**
+ * `tools/list` 的应答 → 工具表。**两条连接器共用一份**（此前逐字写了两遍）。
+ *
+ * 形状不对一律**响亮失败**：把协议不符吞成空菜单，用户看到的是「这个 server 一个工具都没有」
+ * 而不是「server 坏了」—— 前者会被当成正常结果排错到别处去。只有 `tools` **缺席**才当空表
+ * （那是合法的「没有工具」）。
+ */
+export declare function parseToolList(r: unknown): McpToolInfo[];
+/**
+ * `tools/call` 的结果里协议层 `isError: true` ⇒ **必须转成抛错**。
+ *
+ * 承重：这个位只有连接器看得见，吞了它模型会收到一条「成功」的结果、trace 也记成成功调用
+ * （见 `McpClientLike` 的约定）。两条连接器共用一份。
+ */
+export declare function assertToolResultNotError(r: unknown, name: string): void;
+/**
+ * **会话过期自愈**的判定（MCP Streamable HTTP 的规范语义）。
+ *
+ * 带会话 id 收到 `404` 的含义是「这个会话我不认识」⇒ **该请求没有被执行** ⇒ 丢会话、
+ * 重新握手、把这一次**重试一次**是安全的（不会重复执行副作用）；规范也要求客户端此时
+ * **必须**新建会话。`allowReinit` 那一位保证**只重试一次**：第二次再 404 说明对面不是
+ * 「会话过期」而是别的问题，直接抛（不循环）。
+ *
+ * 抽成纯函数是为了让这三条判据**可以被单独钉住** —— 它此前内联在 `rpc` 的 `if` 里，
+ * 三个条件任意一个写反都没有用例看得见（症状是「重试带着旧会话再 404」或「无限重握」）。
+ */
+export declare function canSelfHealSession(status: number, hasSessionId: boolean, allowReinit: boolean): boolean;
+/**
+ * 拼 `tools/call` 的 params（**两条连接器共用一份** —— 承载 SEP-414 的 `_meta` 形状
+ * 只许存在一处，否则改一处漏一处没有任何用例看得见）。
+ *
+ * `traceparent`（W3C 串）落在 params 的**兄弟键 `_meta`**：SEP-414 明说这是 `_meta`
+ * DNS 前缀惯例的**例外**（裸键 `traceparent`，不许加成 `io.modelcontextprotocol.traceparent`
+ * —— 加了前缀跨实现的链就断了）。⚠️ **绝不进 `arguments`**：那是模型可见、server 按
+ * inputSchema 校验的工具签名，trace 上下文进去会污染契约（纪律②）。
+ * `traceparent` 缺席时**不落 `_meta` 键**（纪律③：不造空上下文 —— 空 `_meta` 对宽容的
+ * server 无害，但它让「这次到底有没有链路」变得不可判）。
+ */
+export declare function toolsCallParams(name: string, args: Record<string, unknown>, traceparent: string | undefined): Record<string, unknown>;

package/dist/integrations/mcp-protocol.js

@@ -18,7 +18,7 @@ export const DEFAULT_PROTOCOL_VERSION = '2024-11-05';
  * 给一次 MCP 调用套超时。⚠️ 与引擎的工具超时同样是**放弃等待**而非取消 ——
  * MCP 的 `notifications/cancelled` 属于连接器职责，桥这一层拿不到取消句柄。
  *
- * 实现是 `core/timeout.ts` 共享原语的**薄封装**（2026-09-17 单源化，见 spec §10 2026-09-17 ①）：
+ * 实现是 `core/timeout.ts` 共享原语的**薄封装**（2026-09-17 单源化，见 spec §10 2026-09-17 ref-mcp-timeout-single-source）：
  * 「一次调用只有一个预算判定」在引擎与桥之间只允许有一份实现。此前桥自带一份**纯竞速**
  * 版本，于是 2026-09-14 的「超时是硬的」收紧只落进引擎，桥继续把**超预算**的调用记成成功。
  *
@@ -66,4 +66,150 @@ export function unwrap(msg, method) {
         throw new Error(`MCP ${method}：响应里既没有 result 也没有 error`);
     return msg.result;
 }
+// ───────────────────────── 下面这一组：两个内置连接器**共用**的纯件（2026-10-11 抽） ─────────────────────────
+//
+// 为什么抽在这里：它们此前**逐字重复**在两个连接器里（`tools/list` 与 `tools/call` 的结果校验
+// 一字不差地写了两遍），或者只属于协议面的知识（SSE 帧 / JSON-RPC 信封 / id 配对）——
+// 正是本文件头注那句「新增『桥与连接器都要用』的东西请加在这里」。
+//
+// ⚠️ 抽出去的另一半效果是**读数**：`integrations/mcp-http.ts` 与 `mcp-stdio.ts` 的
+// 「最大可调用体」因此从 265 / 252 降下来（见 `tests/architecture/method-size.test.ts`）。
+// 那不是目的、是副作用 —— 目的是这两条连接器从此只有「各自传输那一份」的代码。
+/**
+ * 读响应体文本；读失败**返回空串而非抛**。
+ *
+ * 为什么吞：调用方用它的地方（排空、错误文案、SSE 解析）都不该因为「body 读不出来」二次失败
+ * —— 真正的原因由 `res.status` / 网络层给出，这里再抛只会把第一条错误盖掉。
+ */
+export async function readMcpText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return '';
+    }
+}
+/** HTTP 层失败：带上数值 `status`，让 `classifyError` 能按状态分流 */
+export function mcpHttpError(status, method, body) {
+    const e = new Error(`MCP ${method} HTTP ${status}${body ? `：${body}` : ''}`);
+    e.status = status;
+    return e;
+}
+/**
+ * 非 SSE 报文（单条 JSON-RPC）→ 取 result。
+ *
+ * ⚠️ id 必须**等值**配对（与 SSE 分支同款）：只验「是带 id 的响应」会把别的请求的结果
+ * 当本次的返回（代理串包 / 通知帧），**静默错值比报错难查得多**。
+ */
+export function pickJsonRpcResult(msg, id, method) {
+    if (!isJsonRpcResponse(msg) || msg.id !== id) {
+        throw new Error(`MCP ${method}：响应里没有 id 为 ${id} 的 JSON-RPC 报文`);
+    }
+    return unwrap(msg, method);
+}
+/**
+ * 从 HTTP 响应取结果 —— 两种响应形态**都要接**（StreamableHTTP 的规范面）。
+ *
+ * SSE 分支一次性读完整个 body 再解析：StreamableHTTP 约定 server 发完响应即关流，
+ * 读全比手写增量解析器稳（`text/event-stream` 里 `data:` 行按规范可跨多行拼接）。
+ * SSE 里可能有别的通知帧或别的请求的应答，**只取与 `id` 配对的**那一条。
+ */
+export async function readMcpResult(res, id, method) {
+    const ct = (res.headers.get('content-type') ?? '').toLowerCase();
+    const text = await readMcpText(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 pickJsonRpcResult(msg, id, method);
+}
+/**
+ * `tools/list` 的应答 → 工具表。**两条连接器共用一份**（此前逐字写了两遍）。
+ *
+ * 形状不对一律**响亮失败**：把协议不符吞成空菜单，用户看到的是「这个 server 一个工具都没有」
+ * 而不是「server 坏了」—— 前者会被当成正常结果排错到别处去。只有 `tools` **缺席**才当空表
+ * （那是合法的「没有工具」）。
+ */
+export function parseToolList(r) {
+    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;
+}
+/**
+ * `tools/call` 的结果里协议层 `isError: true` ⇒ **必须转成抛错**。
+ *
+ * 承重：这个位只有连接器看得见，吞了它模型会收到一条「成功」的结果、trace 也记成成功调用
+ * （见 `McpClientLike` 的约定）。两条连接器共用一份。
+ */
+export function assertToolResultNotError(r, name) {
+    if (typeof r === 'object' && r !== null && r.isError) {
+        throw new Error(`MCP 工具 ${name} 返回 isError: ${brief(r.content)}`);
+    }
+}
+/**
+ * **会话过期自愈**的判定（MCP Streamable HTTP 的规范语义）。
+ *
+ * 带会话 id 收到 `404` 的含义是「这个会话我不认识」⇒ **该请求没有被执行** ⇒ 丢会话、
+ * 重新握手、把这一次**重试一次**是安全的（不会重复执行副作用）；规范也要求客户端此时
+ * **必须**新建会话。`allowReinit` 那一位保证**只重试一次**：第二次再 404 说明对面不是
+ * 「会话过期」而是别的问题，直接抛（不循环）。
+ *
+ * 抽成纯函数是为了让这三条判据**可以被单独钉住** —— 它此前内联在 `rpc` 的 `if` 里，
+ * 三个条件任意一个写反都没有用例看得见（症状是「重试带着旧会话再 404」或「无限重握」）。
+ */
+export function canSelfHealSession(status, hasSessionId, allowReinit) {
+    return status === 404 && hasSessionId && allowReinit;
+}
+/**
+ * 拼 `tools/call` 的 params（**两条连接器共用一份** —— 承载 SEP-414 的 `_meta` 形状
+ * 只许存在一处，否则改一处漏一处没有任何用例看得见）。
+ *
+ * `traceparent`（W3C 串）落在 params 的**兄弟键 `_meta`**：SEP-414 明说这是 `_meta`
+ * DNS 前缀惯例的**例外**（裸键 `traceparent`，不许加成 `io.modelcontextprotocol.traceparent`
+ * —— 加了前缀跨实现的链就断了）。⚠️ **绝不进 `arguments`**：那是模型可见、server 按
+ * inputSchema 校验的工具签名，trace 上下文进去会污染契约（纪律②）。
+ * `traceparent` 缺席时**不落 `_meta` 键**（纪律③：不造空上下文 —— 空 `_meta` 对宽容的
+ * server 无害，但它让「这次到底有没有链路」变得不可判）。
+ */
+export function toolsCallParams(name, args, traceparent) {
+    return {
+        name,
+        arguments: args,
+        ...(traceparent !== undefined ? { _meta: { traceparent } } : {}),
+    };
+}
 //# sourceMappingURL=mcp-protocol.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"mcp-protocol.js","sourceRoot":"","sources":["../../src/integrations/mcp-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAkF1E,qDAAqD;AACrD,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsC;IACpE,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,OAAO;CACjB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAAC;AAErD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,CAAa,EAAE,SAAiB,EAAE,KAAa;IACnF,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,+DAA+D;QAC/D,MAAM,IAAI,YAAY,CAAC,WAAW,KAAK,aAAa,SAAS,KAAK,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,KAAK,CAAC,KAAc,EAAE,GAAG,GAAG,GAAG;IAC7C,IAAI,CAAS,CAAC;IACd,IAAI,CAAC;QACH,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,GAA4C,CAAC;QACvE,OAAO,IAAI,KAAK,CAAC,aAAa,MAAM,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,cAAc,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAK5C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,OAAQ,GAAwB,CAAC,EAAE,KAAK,QAAQ,CAC5F,CAAC;AACJ,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,MAAM,CAAC,GAA0C,EAAE,MAAc;IAC/E,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;QAAE,MAAM,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC3D,IAAI,CAAC,CAAC,QAAQ,IAAI,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,OAAO,MAAM,0BAA0B,CAAC,CAAC;IACjF,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC"}
+{"version":3,"file":"mcp-protocol.js","sourceRoot":"","sources":["../../src/integrations/mcp-protocol.ts"],"names":[],"mappings":"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"}