@epoch-agent/plugin-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,980 @@
+import { ParseIssue } from '@epoch-agent/infra';
+import { ToolAnnotations, ToolArtifactInput, EpochTool } from '@epoch-agent/protocol';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { OAuthClientInformationFull, OAuthTokens, OAuthClientMetadata, OAuthClientInformationMixed } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { OAuthClientProvider, OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js';
+
+/**
+ * MCP 插件 — 类型与配置。
+ *
+ * 参考 Hermes tools/mcp_tool.py。
+ */
+
+type McpTransport = 'stdio' | 'sse' | 'http';
+interface McpServerConfig {
+    name: string;
+    transport: McpTransport;
+    command?: string;
+    args?: string[];
+    url?: string;
+    /** SSE 还是 Streamable HTTP（默认 SSE） */
+    streamable?: boolean;
+    /** SSE/HTTP transport 的额外 headers（如 auth） */
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+    timeout?: number;
+    connectTimeout?: number;
+    keepaliveInterval?: number;
+    idleTimeoutSeconds?: number;
+    maxLifetimeSeconds?: number;
+    supportsParallel?: boolean;
+    skipPreflight?: boolean;
+    /** OAuth 设置。远程 server 默认启用（有凭据就用、没有就等 401），见 `McpOAuthConfig` */
+    oauth?: McpOAuthConfig;
+}
+/**
+ * 单个 server 的 OAuth 设置。
+ *
+ * 默认全空就够用了 —— 远程 server 一律挂上 OAuth provider，服务端不要求授权时
+ * 它一次也不会被调用。**要显式配的只有两种情况**：
+ * 用 `enabled: false` 关掉（比如服务端要的是别的认证方式，不想看到 401 时的
+ * 「请先 login」提示），或者授权服务器要求 redirect_uri 事先登记 ——
+ * 那时必须固定 `callbackPort`，临时端口对不上登记值。
+ */
+interface McpOAuthConfig {
+    enabled?: boolean;
+    /** 申请的 scope（空格分隔）。不给就用授权服务器的默认值 */
+    scope?: string;
+    /** 固定回调端口，给要求预先登记 redirect_uri 的授权服务器用 */
+    callbackPort?: number;
+}
+/**
+ * 一台 server 是从哪儿来的（方案 44 §2.1 b 第三行）。
+ *
+ * - `user` —— `~/.epoch/mcp.json` 里配的。今天绝大多数是这一档；
+ * - `host` —— 嵌入宿主在 `buildRuntime({hostCapabilities})` 里递进来的，
+ *   一个字节都不落盘，用户在自己的 `~/.epoch/` 里找不到它；
+ * - `plugin` —— 已装插件根下那份 `mcp.json` 带来的（方案 44 PR-3）。用户能在
+ *   `epoch plugin list` 里查到它是谁带来的，也能 `epoch plugin disable` 掉。
+ *
+ * ⚠️ **这个联合是封闭集，加一格要连着改能力页那张 `MCP_GROUPS` 数组**
+ * （`web/src/capability/connectors.tsx`）—— 那是 `satisfies readonly {…}[]`，
+ * 多一格不会编译红，而页面是「按组过滤后渲染」，漏改的表现是**那一档一行都不
+ * 显示、也没有任何报错**。PR-2 拿 `MCP_GROUPS` 实测复现过这个症状，PR-3 加
+ * `'plugin'` 时照着改了一行。**下一格还得这么办。**
+ */
+type McpServerSource = 'user' | 'host' | 'plugin';
+interface McpServerStatus {
+    name: string;
+    connected: boolean;
+    toolCount: number;
+    lastError?: string;
+    reconnectAttempts: number;
+    /** 认证过不去，需要 `epoch mcp login <name>`。重连不解决这个 */
+    needsLogin?: boolean;
+    /**
+     * 这台 server 是谁带进来的（方案 44 PR-2）。
+     *
+     * ## 宿主注入的 server 名怎么加命名空间：`<namespace>__<server>`
+     *
+     * 装配层（`runtime/src/host-capabilities.ts`）按宿主给的 `namespace` 拼，
+     * 用**两个下划线**，于是 `namespace: 'acme'` + `name: 'github'` 那台的状态名
+     * 是 `acme__github`、它的工具叫 `mcp__acme__github__search_issues`。
+     * 同 PR-1 那条：**前缀由装配层拼，宿主自己在 `name` 上写的不算数**。
+     *
+     * ## ⚠️ 为什么这个前缀和 PR-1 给专家 / 技能拼的那个长得不一样
+     *
+     * PR-1 拼的是 `<namespace>:`（`acme:triage`），这里是 `<namespace>__`。
+     * **不是两套风格，是两条路的终点不同**：
+     *
+     * - **角色名 / 技能名不上网线进 provider。** 它们只在我们自己进程里当键用
+     *   （`delegate_task` 的 `role` 入参、技能索引的那一行），所以拼一个
+     *   `AGENT_ROLE_NAME_PATTERN` 本身不允许的 `:` 是安全的 —— 那条正则管的是
+     *   宿主**写进来**的名字，前缀在校验**之后**拼（顺序是 `loadPluginRoles` 立的）；
+     * - **server 名**会变成工具名的一部分（`tool-adapter.ts` 的 `prefixedName()`
+     *   直接字符串拼 `mcp__<server>__<tool>`），而工具名是**真的发给 provider** 的。
+     *   方案 44 §2.2 第 5 处 2026-08-17 实测过：带 `:` 的工具名被硬拒 ——
+     *   `tools.0.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,128}$'`，
+     *   同一发换成 `mcp__gh__search_issues` 就 200 正常回。所以这里没有第二个选项。
+     *
+     * 拿 PR-1 那条去类推工具名，得到的是一条今天就红的路 —— 这段话存在的理由
+     * 就是拦住那次类推。
+     *
+     * ## 连带一条：宿主给的 server 名收得比 `mcp.json` 严
+     *
+     * 装配层拿 `[a-z0-9][a-z0-9-]*`（逐字同 `AGENT_ROLE_NAME_PATTERN`）卡宿主
+     * 那一批，而用户自己写在 `mcp.json` 里的名字**一个字都没多管**。两条判据：
+     * 那张正则是 provider 那个 `[a-zA-Z0-9_-]{1,128}` 的真子集，所以拼出来的
+     * 工具名一定合法；而它**不含 `_`**，于是 `__` 当分隔符不会有第二种读法。
+     * 只收紧宿主那一批，是因为那批名字是宿主自己起的（改得动），而用户的
+     * `mcp.json` 是既有文件 —— 收紧它等于让一份昨天还能用的配置今天开始报错。
+     *
+     * ## 插件带来的 server 名：`<插件名>__<server>`（方案 44 PR-3）
+     *
+     * 分隔符和宿主那批**一样是 `__`**，理由也一样（它进工具名）。**前缀的来路
+     * 不一样，而这才是要一眼看得出来的那处差别**：
+     *
+     * | 谁带来的 | 前缀是什么             | 谁定的                              | 什么时候卡的形状             |
+     * | -------- | ---------------------- | ----------------------------------- | ---------------------------- |
+     * | 宿主     | `buildRuntime` 的参数  | 宿主自己（编译期写死在应用里）     | **装配时**，每次启动现场校验 |
+     * | 插件     | **插件名**（安装记录） | 用户敲 `epoch plugin install` 那一刻 | **安装时**，`readPluginManifest` |
+     *
+     * 插件那一侧因此不用在装配时再校验一遍前缀：`PLUGIN_NAME_PATTERN` 和
+     * `AGENT_ROLE_NAME_PATTERN` **逐字相同**（core 的 `plugin/manifest.ts` 明写着
+     * 「不是巧合」—— 插件名必须能安全地拼进角色名），所以上面那两条判据
+     * （provider 正则的真子集、不含 `_`）在插件那侧是**安装那一刻**就成立的。
+     * 一个名字不合法的插件压根装不进来。
+     *
+     * ⚠️ **但后半截要卡。** 插件 `mcp.json` 里的 server 名是**插件作者**写的，
+     * 和用户自己那份一样宽 —— 一台叫 `My Server` 的会拼出带空格的工具名。所以
+     * 装配层（`runtime/src/plugin-mcp-servers.ts`）拿同一张正则卡它，坏的那台只跳过它自己。
+     * **这和「用户那批一个字不多管」不矛盾**，判据是两条：
+     *
+     * - 插件带 mcp 是**新开的一条路**，全仓今天零个这样的文件 —— 收紧它谁也不影响，
+     *   而用户的 `~/.epoch/mcp.json` 是既有文件；
+     * - 放着不管的代价**不是只坏它自己**：一个非法工具名会让 provider 拒掉**整份
+     *   工具表**（同下面那条限长 128 的账），于是一台名字写歪的插件 server 能把
+     *   用户所有的工具一起带走。
+     *
+     * ## 为什么这一格是**必填**
+     *
+     * 加一个可选字段是**宽化** —— `server/src/capability.ts` 的结构镜像 `McpView`
+     * 只会把它忽略掉，一声不吭地不下发，而这一整条链上没有任何东西会变红
+     * （方案 44 §3.4 点名的就是这一样）。写成必填之后链条反过来由编译器扛着：
+     * `WireMcpConnector.source` 必填 → `wireFields` 逼着字段清单列它 →
+     * `toWireMcp` 不产出它就编译不过 → `McpView` 不声明它 `toWireMcp` 就读不到 →
+     * `McpView` 声明了而 runtime 不给，`EpochRuntime` 当场不满足 `WebRuntimeView`。
+     */
+    source: McpServerSource;
+}
+/**
+ * MCP server 返回的 annotations。
+ *
+ * 比 protocol 的 `ToolAnnotations` 多一个 `title` —— 它是展示用的名字，
+ * 不是风险声明，所以不进 protocol 的契约（那里只放权限系统要消费的字段）。
+ */
+interface McpToolAnnotations extends ToolAnnotations {
+    /** 人类可读的展示名，比 `mcp__foo__bar` 友好 */
+    title?: string;
+}
+/**
+ * `tools/list` 里单个工具的形状（只取我们用得上的字段）。
+ *
+ * 这一层是**可缓存**的纯数据：schema 缓存存的就是它，
+ * 从缓存里也能原样重建出 EpochTool，不必再打网络。
+ */
+interface McpToolSchema {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    /** MCP 规范 2025-06-18 起 Tool 顶层也有 title，优先级低于 annotations.title */
+    title?: string;
+    annotations?: McpToolAnnotations;
+}
+/**
+ * `loadFromConfig` 的结果。
+ *
+ * 以前这个函数返回裸数组、`catch { return [] }`：mcp.json 少一个逗号
+ * 等于「静默地没有 MCP」。现在把校验问题一并带出来，由调用方写进 diagnostics。
+ */
+interface McpConfigLoadResult {
+    servers: McpServerConfig[];
+    issues: ParseIssue[];
+}
+
+/**
+ * MCP 工具 schema 缓存 —— 内存 + 磁盘两层。
+ *
+ * 参考 Hermes tools/mcp_schema_cache.py（按 server 名 + 连接配置指纹存盘）。
+ *
+ * 为什么要缓存：`getAllTools()` 以前每次都对每个 client 打一次 `tools/list`，
+ * 一次网络往返换一份没变过的 schema。
+ *
+ * 两层的分工是刻意的：
+ *   - **内存**是权威的。同一个进程里连上之后拉过一次就够了。
+ *   - **磁盘**只做降级兜底：live 调用失败（server 挂了 / 网络抖）时，
+ *     拿上次成功的 schema 顶上，让工具至少还在工具表里。
+ *     不拿磁盘做首选是因为它会过期 —— 注册一个 server 已经删掉的工具，
+ *     等于把失败从启动期推迟到调用期。
+ */
+
+/**
+ * 连接配置指纹 —— 只取「决定连到哪、连什么」的字段。
+ *
+ * timeout / keepalive 这类不影响工具表的字段刻意排除在外，
+ * 否则调一下超时就白白丢一次缓存。
+ */
+declare function configFingerprint(config: McpServerConfig): string;
+declare class McpSchemaCache {
+    private readonly cacheFile;
+    private memory;
+    private disk;
+    /** @param cacheFile 磁盘缓存文件路径；传 null 表示只用内存（测试 / 无家目录场景） */
+    constructor(cacheFile?: string | null);
+    /** 内存命中才算「新鲜」—— 磁盘的走 {@link getPersisted} */
+    getFresh(name: string, fingerprint: string): McpToolSchema[] | null;
+    /** 上次成功落盘的 schema，仅在 live 调用失败时作为降级使用 */
+    getPersisted(name: string, fingerprint: string): McpToolSchema[] | null;
+    /** live 拉取成功后写入两层 */
+    set(name: string, fingerprint: string, tools: McpToolSchema[]): void;
+    /**
+     * 显式失效。不传 name 清全部。
+     *
+     * 调用方：`McpRegistry.reconnect()`，以及将来的 `notifications/tools/list_changed`。
+     */
+    invalidate(name?: string): void;
+    private loadDisk;
+    private writeDisk;
+}
+
+/**
+ * MCP OAuth —— 类型。
+ *
+ * [对标 codex rmcp-client/src/oauth.rs 的 `StoredOAuthTokens`
+ *  与 auth_status.rs 的 `McpAuthState`]
+ *
+ * 两个刻意的设计点，三家竞品是一致的：
+ *
+ * 1. **凭据和 URL 绑死**。存的时候记下 `serverUrl`，读的时候对不上就当没有。
+ *    配置里把 url 从 A 改成 B，A 的 access token 绝不能拿去打 B。
+ *    codex 把 url 的哈希编进存储 key，opencode 是 `getForUrl(url)`，
+ *    hermes 是 `entry.server_url != server_url → 丢弃缓存`。
+ * 2. **落盘的是绝对时刻 `expiresAt` 而不是 OAuth 响应里的 `expires_in`**。
+ *    `expires_in` 是「从拿到那一刻起还有多少秒」，进程重启后这个数就是错的
+ *    （hermes mcp_oauth.py:497 的注释说的就是这件事）。
+ */
+
+/** 落盘的单个 server 的 OAuth 状态 */
+interface McpAuthEntry {
+    /** 拿到这份凭据时用的 server URL。和当前配置对不上就整条作废 */
+    serverUrl: string;
+    /** 动态注册（RFC 7591）拿到的 client_id / client_secret */
+    client?: OAuthClientInformationFull;
+    tokens?: OAuthTokens;
+    /** access token 的绝对过期时刻（epoch 毫秒）。没有就是「不知道」 */
+    expiresAt?: number;
+    /**
+     * PKCE 的 code_verifier。
+     *
+     * 只在「已跳转授权页、还没换到 token」这段窗口里有值，换到就清掉 ——
+     * 它和 code 一起才有意义，留着只是多一份可被读取的秘密。
+     */
+    codeVerifier?: string;
+    /** SDK 的发现结果缓存，省掉每次连接的 RFC 9728 往返 */
+    discovery?: Record<string, unknown>;
+    /** 上次成功保存 token 的时刻，只用于 `epoch mcp status` 展示 */
+    updatedAt?: number;
+}
+interface McpAuthFile {
+    version: 1;
+    servers: Record<string, McpAuthEntry>;
+}
+/**
+ * 一个 server 当前的认证状态。
+ *
+ * [对标 codex auth_status.rs 的 `McpAuthState`]，去掉了它的 `Unsupported`
+ * —— 那个值要靠一次 RFC 9728 探测才能得出，而我们不想让 `epoch mcp status`
+ * 变成一条会打网络的命令。「没凭据」和「服务端根本不要 OAuth」在我们这里
+ * 都落在 `logged-out`，由实际连接结果来区分。
+ */
+type McpAuthState = 
+/** 不是远程 server（stdio），OAuth 无从谈起 */
+'not-applicable'
+/** 配置里自带 Authorization header，走静态 bearer，不需要 OAuth */
+ | 'bearer-header'
+/** 有可用的 access token */
+ | 'authorized'
+/** access token 过期了，但有 refresh token，下次连接会自动换 */
+ | 'refreshable'
+/** 没凭据或 refresh 也没了，需要 `epoch mcp login` */
+ | 'logged-out';
+interface McpAuthStatus {
+    server: string;
+    state: McpAuthState;
+    /** 当前配置里的 URL；stdio server 为 undefined */
+    url?: string;
+    expiresAt?: number;
+    updatedAt?: number;
+    scope?: string;
+}
+/**
+ * 需要用户跑一次 `epoch mcp login` 才能继续。
+ *
+ * 单独一个错误类型是为了让工具执行路径能把它和普通网络错误区分开：
+ * 前者要告诉用户去登录，后者只是「重试一下」。
+ * **绝不在工具执行中途弹浏览器** —— agent 跑到一半开个窗口是恶劣体验，
+ * 而且 headless / CI 下根本没有浏览器可弹。
+ */
+declare class McpLoginRequiredError extends Error {
+    readonly server: string;
+    constructor(server: string, detail?: string);
+}
+
+/**
+ * MCP OAuth token 存储 —— `~/.epoch/mcp-auth.json`，权限 0600。
+ *
+ * [对标 codex rmcp-client/src/oauth.rs 的 file fallback（`.credentials.json`）
+ *  与 hermes tools/mcp_oauth.py 的 `_write_secure_json`]
+ *
+ * 三件事是从竞品那儿学来的、不能省的：
+ *
+ * 1. **权限在创建时就是 0600，不是写完再 chmod**。hermes mcp_oauth.py:388
+ *    专门为这个改过一版：先 `write_text` 再 `chmod` 中间有个 TOCTOU 窗口，
+ *    这段时间里同机器的其他用户能把 token 读走。`writeFileSync` 的 `mode`
+ *    参数是建文件时生效的，用它。
+ * 2. **原子写**：临时文件 + rename。写到一半崩溃留下半个 JSON 的话，
+ *    所有 server 的登录状态一起消失。
+ * 3. **凭据和 URL 绑死**：读的时候比对 `serverUrl`，对不上当没有。
+ *
+ * ## 加密（方案 11 落地后新增）
+ *
+ * 这里原来写的是「不做 keyring……等凭据加密方案落地时两边一起搬」——
+ * 现在搬了，但**不是**把整个文件塞进钥匙串，而是**信封加密**：
+ *
+ * - 钥匙串里只放一把 32 字节随机数据密钥（装配层预取一次，见
+ *   [infra/secret/envelope.ts](../../../../infra/src/secret/envelope.ts)）
+ * - 这个文件的内容用它做 AES-256-GCM，加解密由 `node:crypto` **同步**完成
+ *
+ * 为什么不直接 `await secretStore.set(...)`：本类的调用方是 MCP SDK 的
+ * `OAuthClientProvider`，整套接口是**同步 void**（`saveTokens(t): void`），
+ * 没有地方可以 await。fire-and-forget 也不行 —— `epoch mcp login` 写完 token
+ * 立刻退进程，异步的 shell out 可能还没落地，用户的登录就丢了。信封把
+ * 「异步只发生一次（取密钥）」和「写盘永远同步」分开，上面那三条
+ * （0600 建文件、原子写、URL 绑死）一个字都没变。
+ *
+ * **拿不到数据密钥就照旧写明文**（没有钥匙串的机器）。这不是静默降级：
+ * 启动诊断里那行 `Secret: WARN ...` 已经把整体明文这件事说清楚了。
+ */
+
+/** access token 提前多久算「该刷新了」[对标 codex REFRESH_SKEW_MILLIS = 30_000] */
+declare const REFRESH_SKEW_MS = 30000;
+declare class McpAuthStore {
+    private readonly filePath;
+    private cache;
+    /** 磁盘上是密文、但本次运行拿不到数据密钥。此时**只读不写**，见 load() / save() */
+    private locked;
+    /** @param filePath 显式路径（测试用）；不传走 infra 的路径真源 */
+    constructor(filePath?: string, homeDir?: string);
+    get path(): string;
+    /**
+     * 读一个 server 的凭据。
+     *
+     * @param serverUrl 当前配置里的 URL。和落盘时记的对不上就返回 undefined ——
+     *                  换了地址的 token 不能拿去打新地址。
+     */
+    get(server: string, serverUrl?: string): McpAuthEntry | undefined;
+    /** 不比对 URL 的读法，只给 `epoch mcp status` 展示用 */
+    getRaw(server: string): McpAuthEntry | undefined;
+    list(): Array<[string, McpAuthEntry]>;
+    /** 局部更新一个 server 的条目；`serverUrl` 变了会先清空旧凭据 */
+    update(server: string, serverUrl: string, patch: Partial<McpAuthEntry>): void;
+    /** 删掉一个 server 的全部凭据。@returns 之前是否存在 */
+    remove(server: string): boolean;
+    /** 强制下次 `get` 重新读盘。外部改过文件（另一个进程登录过）时用 */
+    invalidate(): void;
+    private load;
+    /**
+     * 磁盘上是密文而当前解不开时，任何写操作都必须**当场失败**。
+     *
+     * 在改动内存状态之前就拦（而不是等到 save()）：`update()` 是先改缓存再落盘的，
+     * 到 save() 才抛会留下一个「内存里改了、盘上没改」的错位状态，
+     * 下一次读会拿到一份不存在于磁盘的凭据。
+     */
+    private assertWritable;
+    private save;
+}
+/**
+ * access token 是否已经（快）过期。
+ *
+ * 提前 30 秒算过期：token 刚好在请求飞在路上时到期是最难查的一类故障。
+ */
+declare function isExpired(entry: McpAuthEntry | undefined, now?: number): boolean;
+
+/**
+ * MCP 客户端 —— 连接状态机：握手、重连、保活 / 生存期 / 空闲计时器、工具调用。
+ *
+ * transport **怎么造出来、怎么关干净**在 [transport/](./transport/index.ts)，
+ * 那部分不持有状态，跟这里的状态机是两件事。
+ *
+ * 参考 Hermes tools/mcp_tool.py + @modelcontextprotocol/sdk。
+ */
+
+/** 一次工具调用的结果。`artifacts` 是**未过闸门**的原始形态，闸门在 core 侧 */
+interface McpToolCallResult {
+    success: boolean;
+    output: string;
+    artifacts?: ToolArtifactInput[];
+}
+declare class McpClient {
+    private config;
+    private client;
+    private transport;
+    private keepaliveTimer;
+    private lifetimeTimer;
+    private idleTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private lastError;
+    private toolCount;
+    private stderrTail;
+    /** 上一个 chunk 末尾那截还没等到换行的文本，见 {@link collectStderr} */
+    private stderrPartial;
+    /** 主动 disconnect 时置位，避免自己触发的 onclose 又去排一次重连 */
+    private closingIntentionally;
+    /** 认证过不去。重连解决不了这个问题，只有 `epoch mcp login` 能 */
+    private needsLogin;
+    private readonly cache;
+    private readonly fingerprint;
+    private readonly authProvider;
+    /**
+     * 收到 `notifications/tools/list_changed` 时的回调。
+     *
+     * McpRegistry 用它把「工具表已经不是启动时那份了」冒泡给宿主。
+     * 注意**这不是热更新**：AgentLoop 的工具集是构造参数，本进程内换不掉。
+     * 详见 registry 的 `refresh()`。
+     */
+    onToolsChanged: (() => void) | undefined;
+    /**
+     * 这台是谁带进来的（方案 44 PR-2）。
+     *
+     * **由 `McpRegistry.connectAll()` 那一侧说了算，不从 `config` 里读** ——
+     * `McpServerConfig` 是用户手写的 `mcp.json` 解析出来的形状，来源要是它的一个
+     * 字段，用户就能在自己的文件里写 `"source": "host"` 给自己那台贴上宿主的标。
+     * 判据同角色那条「命名空间由装配层拼，宿主自己写的不算数」。
+     */
+    private readonly source;
+    constructor(config: McpServerConfig, cache?: McpSchemaCache, authStore?: McpAuthStore, source?: McpServerSource);
+    get status(): McpServerStatus;
+    /** 底层 SDK client，`null` 表示没连上。resources / prompts 那几个原语要用 */
+    get raw(): Client | null;
+    get serverConfig(): McpServerConfig;
+    connect(): Promise<void>;
+    /**
+     * 取本 server 的工具 schema —— 缓存优先。
+     *
+     * 三级：内存缓存 → live `tools/list` → 上次落盘的 schema（降级）。
+     * 详见 [cache.ts](./cache.ts) 里两层分工的说明。
+     */
+    getToolSchemas(): Promise<McpToolSchema[]>;
+    /** live 拉取；失败返回 null（错误记进 lastError，由调用方决定降不降级） */
+    private fetchToolSchemas;
+    /**
+     * 调用工具。
+     *
+     * **断线不在这里等重连**：以前这里 `await this.reconnect()`，而 reconnect 是
+     * 1s + 2s + 4s 的 backoff 循环 —— 工具执行路径上最多阻塞 7 秒，用户看到的是
+     * agent 卡住。现在改成排一次后台重连、立刻返回一条可重试的错误。
+     */
+    callTool(name: string, args: Record<string, unknown>): Promise<McpToolCallResult>;
+    disconnect(): Promise<void>;
+    /**
+     * 建连。**握手成功之前不写 this.client**。
+     *
+     * 以前是先 `this.client = new Client(...)` 再 await 握手，于是
+     * `status.connected`（判据就是 `client !== null`）在握手还没跑完时就报 true ——
+     * 调用方据此以为能用了，实际 SDK 会抛 "Not connected"。
+     *
+     * 失败路径也补上了 `transport.close()`：以前 connect 超时只是把字段置 null，
+     * stdio 已经起来的子进程没人收，直接漏成孤儿进程。
+     */
+    private connectInner;
+    /**
+     * 攒起 stderr 的尾部若干**行**。
+     *
+     * ⚠️ **`text` 是一个 chunk，不是一行。** 一行长过一个 chunk（管道一次 64 KB）
+     * 时它会被切开，而不留半截的话每一截都变成尾部里独立的一条 —— 既占掉好几个
+     * 名额，`stderrHint()` 拼出来还像是好几件事（`……前半 | 后半`）。
+     * 一个把栈打进 stderr 的 server 很容易做到这一点。
+     *
+     * ⚠️ 别把 `cmd.exe` 那句「不是内部或外部命令」的两行当成这个 bug 的例子 ——
+     * 实测过，**那句话本身就是两行**（「……可运行的程序」后面真有一个 `\r\n`），
+     * 拼出来带 `|` 是忠实的。
+     */
+    private collectStderr;
+    /**
+     * 最后三行，给错误消息当尾巴。
+     *
+     * 把还没等到换行的那半行也算进来：server 崩在半句话上时，那半句往往正是
+     * 最要紧的一句（而它永远等不到自己的 `\n`）。
+     */
+    private stderrHint;
+    /**
+     * server 说工具表变了。
+     *
+     * 只做两件事：**失效 schema 缓存**（下次 `getToolSchemas()` 会真去拉一次），
+     * 然后把事件冒泡出去。刻意不在这里自己去 `listTools()` —— 通知可能连着来，
+     * 每条都拉一次是在替 server 打自己。
+     */
+    private onToolsListChanged;
+    /**
+     * @param closed 触发 onclose 的那个 Client。重连成功后旧连接的迟到通知
+     *               不能把新连接连坐掉，所以要比对身份。
+     */
+    private onTransportClosed;
+    /**
+     * 排一次后台重连（幂等）。
+     *
+     * 看门狗语义：重连全程不占用调用方的时间片，失败就按 backoff 再排一次，
+     * 到 MAX_RECONNECT 为止把 server 标成不可用。
+     */
+    private scheduleReconnect;
+    private attemptReconnect;
+    private unavailableMessage;
+    private startKeepalive;
+    private pingOnce;
+    private stopKeepalive;
+    /**
+     * 起 idle / max-lifetime 两个自动断连定时器。
+     *
+     * 这里刻意**不**调 `clearTimers()`：它连 keepalive 一起清，而调用顺序是
+     * `startKeepalive(); startLifetime();` —— 等于刚起的 keepalive 立刻被自己清掉，
+     * keepalive 从来没真正跑过。只清自己的两个定时器。
+     */
+    private startLifetime;
+    private resetIdle;
+    private armDisconnect;
+    private clearTimers;
+    private withTimeout;
+}
+
+/**
+ * MCP OAuth —— 收授权回调的一次性本地 HTTP server。
+ *
+ * [对标 opencode packages/opencode/src/mcp/oauth-callback.ts
+ *  与 codex rmcp-client/src/perform_oauth_login.rs 的 `CallbackServerGuard`]
+ *
+ * 三条都是安全项，不是打磨：
+ *
+ * 1. **只监听 127.0.0.1**。绑 `0.0.0.0` 的话，同一个局域网里的任何人都能
+ *    往这个端口投一个 code，把自己的账号挂到用户的 epoch 上。
+ * 2. **校验 `state`**。不校验就是标准的 OAuth CSRF：攻击者诱导用户点开一个
+ *    带他自己 code 的回调链接，用户的 MCP 连接就连到攻击者的账号上去了。
+ *    opencode / codex 两家都在回调处第一件事就是比对 state。
+ * 3. **超时自己收摊**（默认 5 分钟，两家的默认值也是 300 秒）。用户在授权页
+ *    上关掉浏览器走人是常态，端口不能一直开着。
+ */
+/** [对标 codex DEFAULT_OAUTH_TIMEOUT_SECS = 300 / opencode 的 5 分钟] */
+declare const CALLBACK_TIMEOUT_MS: number;
+interface CallbackServer {
+    /** 注册给授权服务器的 redirect_uri */
+    redirectUri: string;
+    /**
+     * 登记本次流程的 `state`，**必须在把用户送去授权页之前**调用。
+     *
+     * 不能等到 `waitForCode()` 再登记：授权服务器上已经有会话的用户根本不会看到
+     * 同意页，浏览器一个 302 就回来了 —— 回调完全可能比 `waitForCode()` 先到。
+     * 那时既没有 state 可比对，也没人接住这个 code。（这条是被 e2e 实跑撞出来的：
+     * 假浏览器自动跟随跳转，code 秒回，登录卡在这里干等 300 秒超时。）
+     */
+    expect(state: string | undefined): void;
+    /** 等回调；拿到授权码就 resolve，出错 / 超时就 reject。无论如何都会关掉服务器 */
+    waitForCode(): Promise<string>;
+    /** 提前收摊（登录流程在拿到 code 之前失败了） */
+    close(): void;
+}
+/**
+ * 起回调服务器。
+ *
+ * @param port 固定端口。不传用临时端口 —— 但很多授权服务器要求 redirect_uri
+ *             事先登记，那种情况必须指定一个固定端口才对得上。
+ * @param timeoutMs 等回调的上限。只有测试会改它 —— 用例不可能真等 5 分钟
+ */
+declare function startCallbackServer(port?: number, timeoutMs?: number): Promise<CallbackServer>;
+
+/**
+ * MCP OAuth —— 登录 / 登出 / 状态查询。
+ *
+ * [对标 codex rmcp-client/src/perform_oauth_login.rs 的状态机]
+ *
+ * 流程就三步，其中两步是 SDK 做的：
+ *
+ * 1. 起本地回调服务器，拿到 `redirect_uri`
+ * 2. `auth(provider, { serverUrl })` —— SDK 去发现元数据、必要时动态注册客户端、
+ *    生成 PKCE，然后回调 `redirectToAuthorization`。它返回 `'AUTHORIZED'`
+ *    说明**光靠 refresh token 就续上了**，压根不用开浏览器；返回 `'REDIRECT'`
+ *    才需要用户真去授权页点一下
+ * 3. 收到 code 后再调一次 `auth(provider, { serverUrl, authorizationCode })`
+ *    换 token
+ *
+ * 第 2 步返回 `'AUTHORIZED'` 就提前收工这件事很容易漏 —— 漏了的话每次
+ * `epoch mcp login` 都会强开一次浏览器，哪怕 refresh token 明明还好用。
+ */
+
+interface McpLoginOptions {
+    /** server 名（凭据存储 key） */
+    server: string;
+    /** server URL */
+    serverUrl: string;
+    store?: McpAuthStore;
+    /** 固定回调端口。授权服务器要求预先登记 redirect_uri 时必须指定 */
+    port?: number;
+    scope?: string;
+    /** 打开浏览器；测试里换成假的 */
+    openBrowser?: (url: string) => void | Promise<void>;
+    /** 打印进度 */
+    print?: (message: string) => void;
+}
+interface McpLoginResult {
+    server: string;
+    /** true 表示只靠 refresh token 就续上了，没开浏览器 */
+    refreshedOnly: boolean;
+}
+declare function loginToMcpServer(opts: McpLoginOptions): Promise<McpLoginResult>;
+/** 删掉一个 server 的全部 OAuth 凭据。@returns 之前是否存在 */
+declare function logoutFromMcpServer(server: string, store?: McpAuthStore): boolean;
+/**
+ * 查一个 server 现在的认证状态。
+ *
+ * **不打网络**：只看配置和落盘的凭据。
+ * [对标 codex auth_status.rs 的 `auth_status_before_discovery`] —— 它把
+ * 「不打网络就能确定的」和「必须探测才知道的」明确分开，前者能覆盖绝大多数
+ * 情况。我们只做前者，理由见 types.ts 里 `McpAuthState` 的注释。
+ */
+declare function mcpAuthStatus(config: McpServerConfig, store?: McpAuthStore): McpAuthStatus;
+
+/**
+ * MCP OAuth —— `OAuthClientProvider` 实现。
+ *
+ * SDK（`@modelcontextprotocol/sdk/client/auth.js` 的 `auth()`）已经把
+ * RFC 9728 发现、动态客户端注册（RFC 7591）、PKCE、授权码换 token、
+ * refresh token 续期全实现了。**我们要做的只是持久化 + 「跳转」怎么跳**。
+ * 先确认 SDK 提供了什么再决定自己写多少 —— 方案里点名要求的这一步，
+ * 结论就是这个类只有 ~150 行。
+ *
+ * 最要紧的一个决定：**这个 provider 有交互和非交互两副面孔**。
+ *
+ * - 连接 MCP server 时用的是非交互版：有 token 就用，过期就让 SDK 拿
+ *   refresh token 去换，**换不动就抛 `McpLoginRequiredError`**，绝不弹浏览器。
+ *   agent 跑到一半开个授权窗口是恶劣体验，headless / CI 下更是根本没窗口可开。
+ * - `epoch mcp login` 用交互版：允许跳转，配一个本地回调服务器收 code。
+ *
+ * codex 是同一个道理，只是它把两条路分成了 `perform_oauth_login`（交互）
+ * 和 `AuthorizationManager`（连接期）两套入口。
+ */
+
+interface McpOAuthProviderOptions {
+    /** MCP server 在配置里的名字，也是凭据的存储 key */
+    server: string;
+    /** 当前配置里的 URL。凭据和它绑死 */
+    serverUrl: string;
+    store: McpAuthStore;
+    /** 本地回调地址；只有交互式登录才有 */
+    redirectUri?: string;
+    /** 跳转授权页的动作。不给就是非交互 —— 需要跳转时直接抛「请先 login」 */
+    onRedirect?: (url: URL) => void | Promise<void>;
+    /** 申请的 scope；不给就由服务端的默认值决定 */
+    scope?: string;
+}
+declare class McpOAuthProvider implements OAuthClientProvider {
+    private readonly opts;
+    /** 本次流程生成的 state，回调时用来验 CSRF */
+    private currentState;
+    constructor(opts: McpOAuthProviderOptions);
+    /** 本次授权流程用的 state，回调服务器拿它比对 */
+    get expectedState(): string | undefined;
+    /** 见 `PLACEHOLDER_REDIRECT_URI`：这里返回 undefined 会让 SDK 跳过 refresh */
+    get redirectUrl(): string;
+    /** 真的能跳转吗（交互式登录才能）。占位地址不算 */
+    get interactive(): boolean;
+    get clientMetadata(): OAuthClientMetadata;
+    /**
+     * OAuth 的 `state` 参数。
+     *
+     * SDK 把它当**生成器**调（每次授权一个新值），不是「读一个固定值」——
+     * opencode `src/mcp/oauth-provider.ts` 里踩过这个：写成只读缓存的话，
+     * 两次登录会拿到同一个 state，回调分不清是哪一次。
+     */
+    state(): string;
+    clientInformation(): OAuthClientInformationMixed | undefined;
+    saveClientInformation(info: OAuthClientInformationMixed): void;
+    tokens(): OAuthTokens | undefined;
+    /**
+     * 存 token。
+     *
+     * 顺手把 `expires_in`（相对秒数）换算成绝对时刻落盘 —— 相对值一重启就是错的。
+     * 同时清掉 `codeVerifier`：它只在「跳转了、还没换到 token」那段窗口有用，
+     * 换到了就是一份没有用处的秘密，留着只是多一处泄漏点。
+     */
+    saveTokens(tokens: OAuthTokens): void;
+    redirectToAuthorization(url: URL): Promise<void>;
+    saveCodeVerifier(codeVerifier: string): void;
+    codeVerifier(): string;
+    /**
+     * 服务端说凭据不好使了，SDK 调这里让我们删掉。
+     *
+     * 不实现的话用户要自己去删 `~/.epoch/mcp-auth.json` —— 而「client 注册
+     * 被服务端撤销」这种情况下，不删就会一直拿同一个失效 client_id 重试。
+     */
+    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): void;
+    saveDiscoveryState(state: OAuthDiscoveryState): void;
+    discoveryState(): OAuthDiscoveryState | undefined;
+    private entry;
+}
+
+/**
+ * MCP 的另两个原语 —— resources 与 prompts。
+ *
+ * 之前只做了 tools 一个。这里只放**读取**逻辑，怎么暴露给模型 / 用户分别在
+ * `resource-tools.ts` 和 registry 的 `listPrompts()`。
+ *
+ * 三个共同点，都是从 gemini `packages/core/src/tools/mcp-client.ts` 的
+ * `listResources` 抄来的做法：
+ *
+ * 1. **先看 capability**。server 没声明 `resources` 就别问了 —— 问了多半得到
+ *    一个 `-32601 Method not found`，白跑一次往返还污染错误日志。
+ * 2. **翻页**。`resources/list` 和 `prompts/list` 都有 `nextCursor`，
+ *    不翻页就是「只有前 N 个」，而 N 由 server 决定，用户无从察觉。
+ * 3. **method-not-found 当空**。有些 server 声明了 capability 却没实现，
+ *    这种情况下「没有 resources」比「MCP 初始化失败」更贴近事实。
+ *
+ * ## 两个原语的**去处不一样**，这是刻意的
+ *
+ * - **resources → 包成工具**（`resource-tools.ts`：每个 server 一对
+ *   `mcp__<server>__list_resources` / `read_resource`）。不走「上下文注入」是因为
+ *   那条路只有两种走法，都不成立：全量塞（几个 server 就能把上下文吃光），
+ *   或者先猜模型需要哪些资源 —— 而「按需取」正是工具存在的意义。
+ * - **prompts → 不进工具表**，只有 registry 的 `listPrompts()` / `getPrompt()`，
+ *   **模型看不见**。判据在 MCP 规范里：**prompts 是 user-controlled、tools 是
+ *   model-controlled**。混进工具表等于让模型自己决定往自己的上下文里塞什么 ——
+ *   那不是「多一个工具」，是把一个由用户把关的入口改成由模型把关。
+ *   gemini 也把它放在用户侧（slash command）；我们的 TUI 入口还没做。
+ */
+
+interface McpResourceInfo {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+}
+interface McpPromptInfo {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+}
+declare function listResources(client: Client): Promise<McpResourceInfo[]>;
+declare function listPrompts(client: Client): Promise<McpPromptInfo[]>;
+/**
+ * 读一个 resource，压成纯文本。
+ *
+ * 二进制内容（`blob`）只留一行占位说明，不做 base64 透传 —— 那会把几 MB 的
+ * 图片塞进上下文，直接把方案 02 的成本闸门顶爆，而模型也读不懂那串字符。
+ * gemini 的 `read-mcp-resource.ts:145` 是同样的处理。
+ */
+declare function readResourceText(client: Client, uri: string): Promise<string>;
+/**
+ * 取一个 prompt 的消息内容，压成纯文本（给 CLI 展示 / 注入用）。
+ *
+ * 非文本那几支走 `convertMcpContent` 的同一套判别 —— 改造前这里是
+ * `JSON.stringify(content)`，和 tool result 那条路犯的是同一个错：
+ * prompt 里夹一张图，整张 base64 就进了展示文本和注入内容。
+ * 这里**不产生 artifact**：prompt 是给人看 / 拼进 system 的文本通道，
+ * 二进制在这条路上没有去处，只留一行占位。
+ */
+declare function getPromptText(client: Client, name: string, args?: Record<string, string>): Promise<string>;
+
+/**
+ * MCP 注册中心 — 多 server 管理 [Hermes mcp_tool.py]。
+ */
+
+interface McpRegistryOptions {
+    /** 家目录（决定 schema 缓存落在哪）。不传走 infra 的真源解析 */
+    homeDir?: string;
+    /** 显式指定缓存文件；传 null 表示只用内存缓存（测试用） */
+    cacheFile?: string | null;
+    /** 显式指定凭据存储（测试用）。不传就按 homeDir 解析出真源路径 */
+    authStore?: McpAuthStore;
+}
+declare class McpRegistry {
+    private clients;
+    private cache;
+    private authStore;
+    /**
+     * 某个 server 的工具表变了（收到 `notifications/tools/list_changed`）。
+     *
+     * registry 这层只负责把缓存失效掉并转发这个信号 —— **真正的热更新做不到**：
+     * `AgentLoop` 的工具集是构造参数，一次性传进去的，没有「运行中换一套工具」
+     * 的入口。要做需要先给 loop 引入 `ToolProvider` 接口，那是另一个方案的事，
+     * 本方案明确不碰 loop.ts。当前的效果是：下一次 `getAllTools()` / `refresh()`
+     * 能拿到新工具表，正在跑的那一轮不受影响。
+     */
+    onToolsChanged: ((server: string) => void) | undefined;
+    constructor(options?: McpRegistryOptions);
+    /**
+     * 从配置文件加载所有 MCP servers。
+     *
+     * 返回值带 `issues`：以前是 `catch { return [] }`，mcp.json 写错一个字符
+     * 用户只会发现「MCP 没了」，看不到任何提示。调用方**必须**把 issues
+     * 写进 diagnostics（见 runtime/tools.ts）。
+     */
+    loadFromConfig(configPath?: string): McpConfigLoadResult;
+    /**
+     * 连接所有已配置的 servers。
+     *
+     * @param source 这一批是谁带进来的（方案 44 PR-2）。**由调用方说了算，不从
+     *   `configs` 里读** —— 判据在 `McpClient.source` 上：`McpServerConfig` 是
+     *   用户手写文件解析出来的形状，来源要是它的一个字段，用户就能给自己那台
+     *   贴上宿主的标。缺省 `'user'`，于是老调用点（`epoch mcp` 那几条、用例）
+     *   一个字都不用改
+     *
+     * ⚠️ **可以调多次（两批 server 各一发），但名字必须在批与批之间唯一** ——
+     * `clients` 是一张按名字索引的表，重名的后一发会把前一发整个顶掉，而这里
+     * 拿不到诊断口说不出这件事。去重归调用方，`runtime/src/tools.ts` 的
+     * `registerMcpTools` 就是这么做的（用户那批先到、宿主重名的那台被跳过并报一条）。
+     */
+    connectAll(configs: McpServerConfig[], source?: McpServerSource): Promise<McpServerStatus[]>;
+    /**
+     * 获取所有 MCP 工具（扁平化）。
+     *
+     * schema 走缓存，第二次调用不再打网络；工具本身每次重建
+     * （execute 闭包要绑到当前的 client 实例上，重连后不能还指向旧连接）。
+     */
+    getAllTools(): Promise<EpochTool[]>;
+    /**
+     * 丢掉 schema 缓存后重新取一遍工具表。
+     *
+     * 给 `onToolsChanged` 的消费方用：收到通知 → `refresh()` → 拿到新工具表。
+     * 不传 name 就刷所有 server。
+     */
+    refresh(name?: string): Promise<EpochTool[]>;
+    /**
+     * 列出某个 server 的 prompts。
+     *
+     * **prompts 不包成工具**，与 resources 的处理刻意不同：MCP 规范把 prompts
+     * 定义成 user-controlled（用户主动挑一个模板来用），tools 才是 model-controlled。
+     * gemini 也是这么分的 —— 它把 prompts 注册成斜杠命令（`PromptRegistry`），
+     * 不给模型。所以这里只提供查询 API，暴露方式交给 CLI/TUI。
+     */
+    listPrompts(name: string): Promise<McpPromptInfo[]>;
+    /** 取一个 prompt 渲染后的文本 */
+    getPrompt(name: string, promptName: string, args?: Record<string, string>): Promise<string>;
+    /** 各 server 的登录态。纯读本地凭据文件，不打网络 */
+    getAuthStatus(): McpAuthStatus[];
+    /** 凭据存储。`epoch mcp login/logout` 要用同一份，否则缓存不一致 */
+    get auth(): McpAuthStore;
+    /** 重连指定 server。工具表可能已变，顺带失效它的 schema 缓存 */
+    reconnect(name: string): Promise<McpServerStatus>;
+    /**
+     * 显式失效 schema 缓存，不传 name 清全部。
+     *
+     * 给 `epoch mcp reconnect` 和将来的 `notifications/tools/list_changed` 用。
+     */
+    invalidateSchemaCache(name?: string): void;
+    /**
+     * 断开**一台**并把它从表里删掉。返回 false 表示本来就没有这一台。
+     *
+     * ## 为什么在 `disconnectAll()` 之外单开这一个（2026-08-18）
+     *
+     * 在这之前，「让一台 server 在这个进程里消失」**做不到** —— 只能把所有连接一起
+     * 断掉。而 `mcp.json` 的一次编辑真的会删掉一台（runtime 的 `applyMcpConfig`），
+     * 那时全断再全连是错的：宿主注入的和插件带来的那两批也会被连带断开，而它们
+     * 一个字节都不在这份文件里。
+     *
+     * ⚠️ **它连带失效 schema 缓存**：那台下次要是又被配回来，缓存里躺着的是上一份
+     * 工具表。同 `reconnect()` 里那一下，理由逐字相同。
+     *
+     * ⚠️ **工具表不在这一层清**。这里只管连接；把 `mcp:<名字>` 那一组工具从
+     * `ToolRegistry` 里摘掉是装配层的事（`ToolSync.replace`，判据在 runtime 的
+     * `ToolSync` 上：三条路必须排同一条队）。少了那一下的表现是**工具表里留着一批
+     * 指向已断连接的工具**，模型下一轮照着调，报一个它读不懂的错。
+     */
+    disconnect(name: string): Promise<boolean>;
+    /**
+     * 这台 server 在**这个进程里此刻按的是哪份配置**（2026-08-18）。
+     *
+     * 给「盘上那份和进程里这份差在哪」用（runtime 的 `applyMcpConfig` 拿它做 diff）。
+     * ⚠️ 真源必须是 client 手上那一份，**不能是调用方自己记的一份快照**：那份快照
+     * 会和这里分叉，而分叉的表现是「明明改了配置，应用之后说没动」。
+     */
+    configOf(name: string): McpServerConfig | null;
+    /** 断开所有连接 */
+    disconnectAll(): Promise<void>;
+    /** 获取状态 */
+    getStatus(name: string): McpServerStatus | null;
+    getAllStatus(): McpServerStatus[];
+    private requireClient;
+}
+
+/**
+ * 把 MCP resources 包成两个工具暴露给模型。
+ *
+ * **为什么是工具，不是上下文注入**（方案里点名要求写清这个选择）：
+ *
+ * 读了 gemini 的做法 —— 它有一个内置工具
+ * `read_mcp_resource(uri)`（`packages/core/src/tools/read-mcp-resource.ts`），
+ * 外加一个在连接时把 `resources/list` 结果收进去的 registry。也就是说
+ * **gemini 也是包成工具**，不是把内容塞进 system prompt。两条理由我们同样成立：
+ *
+ * 1. resource 的内容量不可控。一个 server 挂几十份文档是常态，全量注入等于
+ *    每一轮对话都为「模型多半用不到的东西」付 token —— 方案 02 的成本闸门
+ *    会第一个报警。
+ * 2. 我们的 `AgentLoop` 工具集是构造参数，注入式上下文没有随会话更新的入口；
+ *    而工具是按需调用的，天然是懒加载。
+ *
+ * 与 gemini 的一个差异：它是**一个全局** `read_mcp_resource`，靠 registry 反查
+ * uri 属于哪个 server；我们是**每个 server 一对**带 `mcp__<server>__` 前缀的工具。
+ * 理由是我们的工具名前缀本来就是撞名处理的依据（见 tool-adapter.ts），
+ * 多一个不走这套规则的全局工具会让「哪个 server 提供了什么」变得不可解释。
+ */
+
+/**
+ * 为一个 server 生成 resources 相关的工具。
+ *
+ * server 没声明 resources capability 时返回空数组 —— 给模型一个调了必然
+ * 报错的工具，只会诱导它反复尝试。
+ *
+ * @param getClient 取当前连接。**不能捕获 Client 实例**：重连后 client 会换一个，
+ *                  闭包里握着旧的就会一直往断掉的连接上打。
+ */
+declare function createResourceTools(serverName: string, getClient: () => Client | null): EpochTool[];
+
+/**
+ * mcp.json 的校验与归一化。
+ *
+ * 存在的理由：以前 `loadFromConfig` 是 `catch { return [] }` —— 配置里少一个逗号、
+ * 把 `timeout` 拼成 `timout`，行为都是「静默地没有 MCP」，用户查不出所以然。
+ * 这里把每一处问题都变成一条带字段路径的 `ParseIssue`，交给调用方写进 diagnostics。
+ *
+ * 归一化只在这一个文件里做：registry 不再手工 `sc.connect_timeout as number`，
+ * 两套映射迟早会分叉（`streamable` / `headers` 就是这么漏掉的）。
+ */
+
+interface ParsedConfig {
+    servers: McpServerConfig[];
+    issues: ParseIssue[];
+}
+/**
+ * 解析 mcp.json 的文本内容。
+ *
+ * 一个 server 配错不影响其他 server —— 逐个校验，坏的跳过并记 issue。
+ */
+declare function parseMcpConfig(raw: string, label: string): ParsedConfig;
+
+/**
+ * `McpToolSchema` → `EpochTool` 的适配。
+ *
+ * 单独一个文件是为了让「从缓存里重建工具」和「从 live 响应里重建工具」
+ * 走同一条代码路径 —— 两条路径分叉的话，缓存命中和不命中会得到不同的工具。
+ */
+
+/** MCP 工具名前缀。撞名交给 ToolRegistry 处理（先注册的胜出） */
+declare function prefixedName(serverName: string, toolName: string): string;
+type McpCall = (toolName: string, args: Record<string, unknown>) => Promise<{
+    success: boolean;
+    output: string;
+    artifacts?: ToolArtifactInput[];
+}>;
+/**
+ * 把一批 MCP 工具 schema 转成 EpochTool。
+ *
+ * annotations 直接透传，**不伪造默认值** —— server 没声明就是 undefined。
+ * 按 MCP 规范 annotations 全是「提示」，编造一个 `readOnlyHint: false`
+ * 会让权限系统（方案 04）把「未声明」和「明确声明有副作用」混为一谈。
+ * 参考 gemini-cli packages/core/src/tools/mcp-client.ts:1365。
+ */
+declare function toEpochTools(serverName: string, schemas: McpToolSchema[], call: McpCall): EpochTool[];
+
+export { CALLBACK_TIMEOUT_MS, type CallbackServer, type McpAuthEntry, type McpAuthFile, type McpAuthState, type McpAuthStatus, McpAuthStore, McpClient, type McpConfigLoadResult, type McpLoginOptions, McpLoginRequiredError, type McpLoginResult, type McpOAuthConfig, McpOAuthProvider, type McpOAuthProviderOptions, type McpPromptInfo, McpRegistry, type McpRegistryOptions, type McpResourceInfo, McpSchemaCache, type McpServerConfig, type McpServerSource, type McpServerStatus, type McpToolAnnotations, type McpToolSchema, type McpTransport, REFRESH_SKEW_MS, configFingerprint, createResourceTools, getPromptText, isExpired, listPrompts, listResources, loginToMcpServer, logoutFromMcpServer, mcpAuthStatus, parseMcpConfig, prefixedName, readResourceText, startCallbackServer, toEpochTools };