c0de-agent 1.13.1 → 1.14.0

package/dist/mcp/index.d.ts

@@ -0,0 +1,46 @@
+import type { Config, MCPServerConfig } from '../shared/types/config.js';
+import type { ToolDef, ToolResult } from '../shared/types/tool.js';
+import type { ToolRegistry } from '../tools/types.js';
+import { type MCPTransport } from './transport.js';
+import type { MCPSession } from './types.js';
+/** initialize/tools/list 的默认超时。 */
+declare const CONNECT_TIMEOUT_MS = 30000;
+type ConnectOptions = {
+    /** initialize/tools/list 超时（默认 30s）。 */
+    timeoutMs?: number;
+    /** 测试注入：直接提供 transport，跳过按配置构建。 */
+    transport?: MCPTransport;
+    /** 测试注入：按配置构建 transport 的工厂（默认 buildTransport）。 */
+    createTransport?: (config: MCPServerConfig) => MCPTransport;
+};
+/** 连接一个 MCP 服务器：initialize 握手 → tools/list → 返回会话。失败抛错。 */
+declare function connectMCPServer(config: MCPServerConfig, opts?: ConnectOptions): Promise<MCPSession>;
+/** 会话已发现工具 → 内部 ToolDef[]（spec §6.2 discoverTools）。 */
+declare function discoverTools(session: MCPSession): ToolDef[];
+/** 直接调用一个 MCP 工具（spec §6.2 callMCPTool）。 */
+declare function callMCPTool(session: MCPSession, name: string, args: unknown): Promise<ToolResult>;
+/** 断开连接（spec §6.2 disconnectMCPServer）。幂等。 */
+declare function disconnectMCPServer(session: MCPSession): void;
+type RegisterResult = {
+    /** 已连接会话（宿主持有，用于关闭清理）。 */
+    sessions: MCPSession[];
+    /** 连接失败列表：`<serverName>: <原因>`。 */
+    failures: string[];
+};
+type RegisterOptions = {
+    timeoutMs?: number;
+    createTransport?: (config: MCPServerConfig) => MCPTransport;
+};
+/** 连接多台 MCP 服务器并把工具注册进 registry。逐台隔离，失败不抛。 */
+declare function registerMCPServers(registry: ToolRegistry, servers: MCPServerConfig[], opts?: RegisterOptions): Promise<RegisterResult>;
+/**
+ * 从配置作用域收集「当前应连接」的 MCP 服务器：
+ * 全局作用域（用户本机显式配置）始终连接；项目作用域（随 git clone 传播的
+ * 任意命令执行面）仅在项目已信任时连接——与插件加载、工作流发现同口径。
+ */
+declare function collectScopedMCPServers(scopes: {
+    global?: Partial<Config>;
+    project?: Partial<Config>;
+}, projectTrusted: boolean): MCPServerConfig[];
+export type { ConnectOptions, RegisterOptions, RegisterResult };
+export { CONNECT_TIMEOUT_MS, callMCPTool, collectScopedMCPServers, connectMCPServer, disconnectMCPServer, discoverTools, registerMCPServers, };

package/dist/mcp/index.js

@@ -0,0 +1,106 @@
+// MCP 包入口（spec §6）：连接外部 MCP 服务器（stdio / http / sse），发现其工具，
+// 适配为内部 ToolDef 并注册进 ToolRegistry——对 agent 透明，与内置工具同接口。
+//
+// 连接失败（配置坏/服务器不可用）不抛给宿主：registerMCPServers 逐台隔离，
+// 失败告警并跳过该台（与插件加载「单个坏插件不影响其余」同口径），
+// 保证一个坏 MCP 配置不会拖垮 serve/chat 启动。
+import { registerTool } from '../tools/registry.js';
+import { createMCPClient } from './client.js';
+import { adaptMCPTool, mcpResultToToolResult } from './tool-adapter.js';
+import { buildTransport } from './transport.js';
+/** initialize/tools/list 的默认超时。 */
+const CONNECT_TIMEOUT_MS = 30_000;
+/** 连接一个 MCP 服务器：initialize 握手 → tools/list → 返回会话。失败抛错。 */
+async function connectMCPServer(config, opts = {}) {
+    const transport = opts.transport ?? (opts.createTransport ?? buildTransport)(config);
+    const client = createMCPClient(transport);
+    try {
+        const timeoutMs = opts.timeoutMs ?? CONNECT_TIMEOUT_MS;
+        await client.request('initialize', {
+            protocolVersion: '2025-03-26',
+            capabilities: {},
+            clientInfo: { name: 'c0de-agent', version: '0.0.0' },
+        }, timeoutMs);
+        // 握手后半步：声明客户端已就绪（notifications/initialized）。
+        client.notify('notifications/initialized');
+        const list = (await client.request('tools/list', undefined, timeoutMs));
+        const tools = Array.isArray(list?.tools) ? list.tools : [];
+        return {
+            name: config.name,
+            config,
+            tools,
+            request: (method, params, t) => client.request(method, params, t),
+            close: () => client.close(),
+        };
+    }
+    catch (error) {
+        client.close();
+        throw error;
+    }
+}
+/** 会话已发现工具 → 内部 ToolDef[]（spec §6.2 discoverTools）。 */
+function discoverTools(session) {
+    return session.tools.map((t) => adaptMCPTool(session, t));
+}
+/** 直接调用一个 MCP 工具（spec §6.2 callMCPTool）。 */
+async function callMCPTool(session, name, args) {
+    try {
+        const result = await session.request('tools/call', { name, arguments: args ?? {} });
+        return mcpResultToToolResult(result);
+    }
+    catch (error) {
+        return { _tag: 'error', error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** 断开连接（spec §6.2 disconnectMCPServer）。幂等。 */
+function disconnectMCPServer(session) {
+    session.close();
+}
+/** 连接多台 MCP 服务器并把工具注册进 registry。逐台隔离，失败不抛。 */
+async function registerMCPServers(registry, servers, opts = {}) {
+    const sessions = [];
+    const failures = [];
+    for (const server of servers) {
+        try {
+            const session = await connectMCPServer(server, opts);
+            sessions.push(session);
+            for (const def of discoverTools(session)) {
+                registerTool(registry, def);
+            }
+            if (session.tools.length > 0) {
+                console.info(`[mcp] 已连接 ${server.name}（${server.transport}），注册 ${session.tools.length} 个工具`);
+            }
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            failures.push(`${server.name}: ${reason}`);
+            console.warn(`[mcp] 连接 ${server.name} 失败，跳过该服务器：${reason}`);
+        }
+    }
+    return { sessions, failures };
+}
+/**
+ * 从配置作用域收集「当前应连接」的 MCP 服务器：
+ * 全局作用域（用户本机显式配置）始终连接；项目作用域（随 git clone 传播的
+ * 任意命令执行面）仅在项目已信任时连接——与插件加载、工作流发现同口径。
+ */
+function collectScopedMCPServers(scopes, projectTrusted) {
+    const out = [];
+    const add = (list) => {
+        if (!Array.isArray(list))
+            return;
+        for (const entry of list) {
+            if (entry === null || typeof entry !== 'object')
+                continue;
+            const e = entry;
+            if (typeof e.name !== 'string' || typeof e.transport !== 'string')
+                continue;
+            out.push(e);
+        }
+    };
+    add(scopes.global?.mcpServers);
+    if (projectTrusted)
+        add(scopes.project?.mcpServers);
+    return out;
+}
+export { CONNECT_TIMEOUT_MS, callMCPTool, collectScopedMCPServers, connectMCPServer, disconnectMCPServer, discoverTools, registerMCPServers, };

package/dist/mcp/tool-adapter.d.ts

@@ -0,0 +1,14 @@
+import type { ToolDef, ToolResult } from '../shared/types/tool.js';
+import type { MCPSession, MCPTool } from './types.js';
+/** 工具调用超时：外部服务器执行可慢，给足余量。 */
+declare const TOOL_CALL_TIMEOUT_MS = 120000;
+/** MCP 工具名 → provider 函数名：`mcp__<server>__<tool>`，两侧片段各自规范化并按
+ *  64 字符上限分配预算。超长时优先保留工具名（截尾保尾：工具语义在尾部，同一
+ *  服务器下的不同工具因此仍互不相同），服务器名段相应截断。 */
+declare function toolName(sessionName: string, name: string): string;
+/** MCP tools/call 结果 → ToolResult：text 内容拼接；isError 标记映射为 error。 */
+declare function mcpResultToToolResult(result: unknown): ToolResult;
+/** 把一个 MCP 工具适配为内部 ToolDef（execute 闭包持有 session）。 */
+declare function adaptMCPTool(session: MCPSession, tool: MCPTool): ToolDef;
+export type { MCPSession, MCPTool };
+export { adaptMCPTool, mcpResultToToolResult, TOOL_CALL_TIMEOUT_MS, toolName };

package/dist/mcp/tool-adapter.js

@@ -0,0 +1,65 @@
+// MCP tool → 内部 ToolDef 适配（spec §6.2）：MCP 工具的 inputSchema 直接映射为
+// ToolDef.parameters；工具名命名空间化为 `mcp__<server>__<tool>` 防与内置/跨服务器
+// 冲突；执行时经 session 发 tools/call 并把 MCP content 折回 ToolResult。
+// 权限 ask：MCP 服务器是外部任意代码执行面（与插件同级），默认需确认。
+/** 工具调用超时：外部服务器执行可慢，给足余量。 */
+const TOOL_CALL_TIMEOUT_MS = 120_000;
+/** provider 的函数名文法（OpenAI 与 Anthropic 一致）：`^[a-zA-Z0-9_-]{1,64}$`。
+ *  服务器名来自用户配置、工具名来自远端服务——两者都可能带 `.`/`@`/`/`/空格
+ *  （例如照抄 npm 包名 `@modelcontextprotocol/server-filesystem`）或超长。未规范化
+ *  就拼进该槽位时，请求体 tools[].function.name 非法，provider 400 拒绝**整个请求**：
+ *  不是这台服务器的工具不可用，而是该工作区所有对话都发不出去。 */
+const TOOL_NAME_MAX = 64;
+const TOOL_NAME_SEP = '__';
+const TOOL_NAME_PREFIX = 'mcp';
+/** 规范化单个名字片段：非法字符折成 `_`，去掉首尾 `_`。 */
+function sanitizeSegment(value) {
+    return value.replace(/[^a-zA-Z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
+}
+/** MCP 工具名 → provider 函数名：`mcp__<server>__<tool>`，两侧片段各自规范化并按
+ *  64 字符上限分配预算。超长时优先保留工具名（截尾保尾：工具语义在尾部，同一
+ *  服务器下的不同工具因此仍互不相同），服务器名段相应截断。 */
+function toolName(sessionName, name) {
+    const server = sanitizeSegment(sessionName) || 'server';
+    const tool = sanitizeSegment(name) || 'tool';
+    const budget = TOOL_NAME_MAX - TOOL_NAME_PREFIX.length - TOOL_NAME_SEP.length * 2;
+    const keepTool = tool.length < budget ? tool : tool.slice(-(budget - 1));
+    const keepServer = server.slice(0, Math.max(1, budget - keepTool.length));
+    return `${TOOL_NAME_PREFIX}${TOOL_NAME_SEP}${keepServer}${TOOL_NAME_SEP}${keepTool}`;
+}
+/** MCP tools/call 结果 → ToolResult：text 内容拼接；isError 标记映射为 error。 */
+function mcpResultToToolResult(result) {
+    const r = result;
+    const parts = Array.isArray(r?.content) ? r.content : [];
+    const text = parts
+        .filter((c) => c !== null && typeof c === 'object' && c.type === 'text')
+        .map((c) => (typeof c.text === 'string' ? c.text : JSON.stringify(c.text)))
+        .join('\n');
+    if (r?.isError) {
+        return { _tag: 'error', error: text || 'MCP tool reported an error' };
+    }
+    if (text.length === 0) {
+        const nonText = parts.length > 0 ? `（${parts.length} 个非文本 content 项，不支持渲染）` : '';
+        return { _tag: 'success', output: `(empty result)${nonText}` };
+    }
+    return { _tag: 'success', output: text };
+}
+/** 把一个 MCP 工具适配为内部 ToolDef（execute 闭包持有 session）。 */
+function adaptMCPTool(session, tool) {
+    return {
+        name: toolName(session.name, tool.name),
+        description: tool.description?.trim() || `MCP tool \`${tool.name}\` from server \`${session.name}\`.`,
+        parameters: tool.inputSchema,
+        permission: 'ask',
+        execute: async (input) => {
+            try {
+                const result = await session.request('tools/call', { name: tool.name, arguments: input ?? {} }, TOOL_CALL_TIMEOUT_MS);
+                return mcpResultToToolResult(result);
+            }
+            catch (error) {
+                return { _tag: 'error', error: error instanceof Error ? error.message : String(error) };
+            }
+        },
+    };
+}
+export { adaptMCPTool, mcpResultToToolResult, TOOL_CALL_TIMEOUT_MS, toolName };

package/dist/mcp/transport.d.ts

@@ -0,0 +1,35 @@
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+import type { JSONRPCNotification, JSONRPCRequest, MCPIncoming } from './types.js';
+/** 底层传输抽象：发 JSON-RPC 消息、收服务端消息、关连接。 */
+type MCPTransport = {
+    send: (msg: JSONRPCRequest | JSONRPCNotification) => void;
+    onMessage: (handler: (msg: MCPIncoming) => void) => void;
+    onClose: (handler: () => void) => void;
+    close: () => void;
+};
+/** 可注入的 spawn：返回带 stdin/stdout/stderr 流的子进程（测试注入假进程）。 */
+type SpawnFn = (command: string, args: string[]) => ChildProcessWithoutNullStreams;
+/** 可注入的 fetch（测试注入假 Response）。 */
+type FetchFn = (input: string, init: RequestInit) => Promise<Response>;
+declare function createStdioTransport(command: string, args?: string[], spawnFn?: SpawnFn): MCPTransport;
+/** 从 ReadableStream 增量解析 SSE（`data:` 行 + 空行分事件），收到即回调。 */
+declare function parseSSEStream(body: ReadableStream<Uint8Array>, onEvent: (data: string) => void, shouldStop: () => boolean): Promise<void>;
+/**
+ * Streamable HTTP 传输：每条消息一次 POST，响应按 Content-Type 解析
+ * （application/json 直接读 body；text/event-stream 流式解析）。
+ * `sse` 为 true 时请求头声明 Accept: text/event-stream（spec §6.2 的 'sse' 传输）。
+ * 收到匹配当前请求的 response 后主动取消读取并断连，避免挂住长连接。
+ */
+declare function createHttpTransport(url: string, opts?: {
+    sse?: boolean;
+    fetchFn?: FetchFn;
+}): MCPTransport;
+/** 按配置构建生产传输。校验失败抛错（配置面错误，连接前暴露）。 */
+declare function buildTransport(config: {
+    transport: 'stdio' | 'sse' | 'http';
+    command?: string;
+    args?: string[];
+    url?: string;
+}): MCPTransport;
+export type { FetchFn, MCPTransport, SpawnFn };
+export { buildTransport, createHttpTransport, createStdioTransport, parseSSEStream };

package/dist/mcp/transport.js

@@ -0,0 +1,243 @@
+// MCP 传输层（spec §6.1）：stdio（子进程 + 换行分帧 JSON）与 streamable HTTP
+// （POST JSON / SSE 流式响应）两种传输。零外部依赖；IO 边界（spawn/fetch）可注入，
+// 协议分帧与客户端逻辑纯逻辑可测。
+import { spawn } from 'node:child_process';
+/** 错误响应构造（-32000 = server error，JSON-RPC 惯例）。 */
+function errorResponse(msg, message) {
+    return {
+        jsonrpc: '2.0',
+        id: 'id' in msg ? msg.id : 0,
+        error: { code: -32000, message },
+    };
+}
+/**
+ * stdio 传输：spawn 子进程，stdout 按行解析 JSON（MCP stdio 规范：
+ * 每行一条 JSON-RPC 消息，无 Content-Length 分帧）。跨 chunk / 粘包已处理。
+ */
+/** 单条 stdio 消息行上限（字符）：服务器持续输出不换行或单条消息超大时，
+ *  `buffer += chunk` 会无限增长直至 OOM——超限整行丢弃并告警，防缓冲无界。 */
+const MAX_LINE_CHARS = 32 * 1024 * 1024;
+function createStdioTransport(command, args = [], spawnFn = spawn) {
+    const child = spawnFn(command, args);
+    // 子进程不参与父进程事件循环存活：父退出 → stdin 管道关闭 → 合规 MCP
+    // 服务器读到 EOF 自行退出。否则长驻的 MCP 服务器会让 CLI 进程无法结束。
+    child.unref();
+    const handlers = [];
+    const closeHandlers = [];
+    let buffer = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+        buffer += chunk;
+        // 超长行防护：无换行的持续输出或单条超限消息立即丢弃，防缓冲无界增长。
+        // 丢弃不改变「完整合法行仍可解析」的语义——超限行本身本就无法作为
+        // 合法 JSON-RPC 消息使用。
+        const nl = buffer.indexOf('\n');
+        if (buffer.length > MAX_LINE_CHARS && (nl === -1 || nl > MAX_LINE_CHARS)) {
+            const drop = nl === -1 ? buffer.length : nl + 1;
+            console.warn(`[mcp:stdio] 丢弃超长输出 ${drop} 字符（单行超过 ${MAX_LINE_CHARS} 上限）`);
+            buffer = buffer.slice(drop);
+        }
+        const consume = () => {
+            const idx = buffer.indexOf('\n');
+            if (idx < 0)
+                return;
+            const line = buffer.slice(0, idx).trim();
+            buffer = buffer.slice(idx + 1);
+            if (line.length > 0) {
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    consume(); // 非 JSON 行（日志等）忽略，继续解析后续行
+                    return;
+                }
+                for (const h of handlers)
+                    h(msg);
+            }
+            consume();
+        };
+        consume();
+    });
+    // 不读取 stderr 会让管道写满卡死子进程——消费并透传到父进程 stderr。
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+        process.stderr.write(`[mcp:stdio] ${chunk}`);
+    });
+    // spawn 失败（ENOENT 等）：无监听器时 unhandled 'error' 会击穿父进程。
+    // 仅记录——随后的 'close' 事件走既有关闭路径 reject pending。
+    child.on('error', (err) => {
+        console.warn(`[mcp] stdio 子进程错误：${err.message}`);
+    });
+    // 服务器崩溃/提前 close(0) 时 stdin 管道写入会异步触发 EPIPE 'error'，
+    // 该事件发在 stdin socket 上而非 child 上——无监听器同样击穿宿主进程。
+    child.stdin.on('error', (err) => {
+        console.warn(`[mcp] stdio 写入失败（服务器可能已退出）：${err.message}`);
+    });
+    child.on('close', () => {
+        for (const h of closeHandlers)
+            h();
+    });
+    return {
+        send(msg) {
+            if (child.stdin.destroyed)
+                return;
+            child.stdin.write(`${JSON.stringify(msg)}\n`);
+        },
+        onMessage(handler) {
+            handlers.push(handler);
+        },
+        onClose(handler) {
+            closeHandlers.push(handler);
+        },
+        close() {
+            if (!child.killed)
+                child.kill();
+        },
+    };
+}
+/** 从 ReadableStream 增量解析 SSE（`data:` 行 + 空行分事件），收到即回调。 */
+async function parseSSEStream(body, onEvent, shouldStop) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        const consume = () => {
+            const idx = buffer.indexOf('\n\n');
+            if (idx < 0)
+                return;
+            const eventBlock = buffer.slice(0, idx);
+            buffer = buffer.slice(idx + 2);
+            for (const line of eventBlock.split('\n')) {
+                if (!line.startsWith('data:'))
+                    continue;
+                const data = line.slice(5).trimStart();
+                if (data.length > 0)
+                    onEvent(data);
+            }
+            consume();
+        };
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                // 流正常关闭：flush decoder 内部缓冲 + 残留尾部事件。最后一个 data: 行
+                // 无尾随空行（服务器发完直接关流）时事件此前被静默丢弃——MCP 客户端
+                // 等最后一条响应直到超时。空行分帧 consume 无法覆盖该帧，须显式收尾。
+                buffer += decoder.decode();
+                buffer = buffer.replace(/\r\n/g, '\n');
+                if (buffer.trim().length > 0) {
+                    for (const line of buffer.trim().split('\n')) {
+                        if (!line.startsWith('data:'))
+                            continue;
+                        const data = line.slice(5).trimStart();
+                        if (data.length > 0)
+                            onEvent(data);
+                    }
+                }
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            // SSE 规范允许 CRLF 行结束——归一化为 LF 再按空行分事件，
+            // 否则 \r\n\r\n 分隔的事件滞留缓冲区永不派发。
+            buffer = buffer.replace(/\r\n/g, '\n');
+            consume();
+            if (shouldStop()) {
+                await reader.cancel();
+                break;
+            }
+        }
+    }
+    catch {
+        // 流被取消/连接被关闭：调用方已不需要继续读取
+    }
+}
+/**
+ * Streamable HTTP 传输：每条消息一次 POST，响应按 Content-Type 解析
+ * （application/json 直接读 body；text/event-stream 流式解析）。
+ * `sse` 为 true 时请求头声明 Accept: text/event-stream（spec §6.2 的 'sse' 传输）。
+ * 收到匹配当前请求的 response 后主动取消读取并断连，避免挂住长连接。
+ */
+function createHttpTransport(url, opts = {}) {
+    const fetchFn = opts.fetchFn ?? fetch;
+    const handlers = [];
+    const closeHandlers = [];
+    const controller = new AbortController();
+    let closed = false;
+    const emit = (msg) => {
+        for (const h of handlers)
+            h(msg);
+    };
+    const send = (msg) => {
+        void (async () => {
+            try {
+                const res = await fetchFn(url, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        accept: opts.sse ? 'text/event-stream' : 'application/json, text/event-stream',
+                    },
+                    body: JSON.stringify(msg),
+                    signal: controller.signal,
+                });
+                if (!res.ok) {
+                    emit(errorResponse(msg, `MCP HTTP ${res.status}: ${res.statusText}`));
+                    return;
+                }
+                const contentType = res.headers.get('content-type') ?? '';
+                if (contentType.includes('text/event-stream') && res.body) {
+                    let receivedResponse = false;
+                    await parseSSEStream(res.body, (data) => {
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(data);
+                        }
+                        catch {
+                            return;
+                        }
+                        if ('id' in parsed && 'id' in msg && parsed.id === msg.id)
+                            receivedResponse = true;
+                        emit(parsed);
+                    }, () => receivedResponse);
+                }
+                else {
+                    const parsed = (await res.json());
+                    emit(parsed);
+                }
+            }
+            catch (err) {
+                if (closed)
+                    return; // close() 触发的 abort，静默
+                emit(errorResponse(msg, err instanceof Error ? err.message : String(err)));
+            }
+        })();
+    };
+    return {
+        send,
+        onMessage(handler) {
+            handlers.push(handler);
+        },
+        onClose(handler) {
+            closeHandlers.push(handler);
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            controller.abort();
+            for (const h of closeHandlers)
+                h();
+        },
+    };
+}
+/** 按配置构建生产传输。校验失败抛错（配置面错误，连接前暴露）。 */
+function buildTransport(config) {
+    if (config.transport === 'stdio') {
+        if (!config.command)
+            throw new Error('stdio transport requires "command"');
+        return createStdioTransport(config.command, config.args ?? []);
+    }
+    if (!config.url)
+        throw new Error(`${config.transport} transport requires "url"`);
+    return createHttpTransport(config.url, { sse: config.transport === 'sse' });
+}
+export { buildTransport, createHttpTransport, createStdioTransport, parseSSEStream };

package/dist/mcp/types.d.ts

@@ -0,0 +1,55 @@
+import type { JSONSchema } from '../shared/types/base.js';
+import type { MCPServerConfig } from '../shared/types/config.js';
+/** JSON-RPC 2.0 request（client → server，带 id，期待 response）。 */
+type JSONRPCRequest = {
+    jsonrpc: '2.0';
+    id: number;
+    method: string;
+    params?: unknown;
+};
+/** JSON-RPC 2.0 notification（client → server，无 id，不期待响应）。 */
+type JSONRPCNotification = {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+};
+/** JSON-RPC 2.0 response（server → client）。 */
+type JSONRPCResponse = {
+    jsonrpc: '2.0';
+    id: number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+};
+/** 服务端发来的消息：响应或通知。 */
+type MCPIncoming = JSONRPCResponse | JSONRPCNotification;
+/** MCP tools/list 返回的单个工具描述（inputSchema 是 JSON Schema）。 */
+type MCPTool = {
+    name: string;
+    description?: string;
+    inputSchema: JSONSchema;
+};
+/** MCP tools/call 返回结果：content 数组（text 为主），isError 标记工具语义失败。 */
+type MCPCallResult = {
+    content: Array<{
+        type: string;
+        [key: string]: unknown;
+    }>;
+    isError?: boolean;
+};
+/** 已连接的 MCP 会话：持有连接与已发现工具，供 tool-adapter 消费。 */
+type MCPSession = {
+    /** 配置中的服务器名（工具命名空间来源）。 */
+    name: string;
+    config: MCPServerConfig;
+    /** tools/list 快照（连接时发现，会话内不变）。 */
+    tools: MCPTool[];
+    /** 发送 JSON-RPC request（带默认超时，可覆盖）。 */
+    request: (method: string, params?: unknown, timeoutMs?: number) => Promise<unknown>;
+    /** 关闭底层连接。幂等。 */
+    close: () => void;
+};
+export type { JSONRPCNotification, JSONRPCRequest, JSONRPCResponse, MCPCallResult, MCPIncoming, MCPSession, MCPTool, };

package/dist/mcp/types.js

@@ -0,0 +1,3 @@
+// MCP（Model Context Protocol）客户端协议类型（spec §6）。
+// 零外部依赖的最小 JSON-RPC 2.0 子集 + 工具描述/调用结果。
+export {};

package/dist/plugins/init.d.ts

@@ -16,6 +16,8 @@ type InitPluginsOptions = {
 type InitPluginsResult = {
     pluginRegistry: PluginRegistry;
     hookRunner: HookRunner;
+    /** config:resolve hook 链之后的最终配置（无 handler 时为传入的 config 原引用）。 */
+    config: Config;
 };
 /**
  * 初始化插件系统：注册表 + hook runner + 内置插件 + 外部插件发现。

package/dist/plugins/init.js

@@ -46,6 +46,15 @@ async function initPlugins(opts) {
         registerPlugin(pluginRegistry, plugin);
         await activatePlugin(pluginRegistry, plugin, services);
     }
-    return { pluginRegistry, hookRunner };
+    // config:resolve hook（HookMap 承诺的挂载点）：插件激活后对最终合并配置做链式
+    // 改写（增补默认值/注入运行时密钥等）。handler 返回 false 视为「保持原配置」。
+    // 结果随 InitPluginsResult.config 返回，宿主用于后续运行时消费（权限/预算/auth/
+    // 调度器等）。注册表（llm/tool）在 resolve 之前构建、不重建——provider 运行时
+    // 变更本就需要重启，与 Web PATCH「providers 改动提示重启」的既有语义一致。
+    let resolvedConfig = opts.config;
+    const hookResult = await hookRunner.runHooks('config:resolve', { config: opts.config });
+    if (hookResult !== false)
+        resolvedConfig = hookResult.config;
+    return { pluginRegistry, hookRunner, config: resolvedConfig };
 }
 export { initPlugins };