@epoch-agent/plugin-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,1709 @@
+// src/cache.ts
+import { createHash } from "crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { dirname } from "path";
+function configFingerprint(config) {
+  const payload = JSON.stringify({
+    transport: config.transport,
+    command: config.command ?? null,
+    args: config.args ?? [],
+    url: config.url ?? null,
+    streamable: config.streamable ?? false,
+    // header 的值可能是 token，指纹只取键名 + 值的哈希，不落明文
+    headers: Object.keys(config.headers ?? {}).sort(),
+    headersDigest: hash(JSON.stringify(config.headers ?? {})),
+    env: Object.keys(config.env ?? {}).sort()
+  });
+  return hash(payload).slice(0, 16);
+}
+function hash(input) {
+  return createHash("sha256").update(input, "utf-8").digest("hex");
+}
+var McpSchemaCache = class {
+  /** @param cacheFile 磁盘缓存文件路径；传 null 表示只用内存（测试 / 无家目录场景） */
+  constructor(cacheFile = null) {
+    this.cacheFile = cacheFile;
+  }
+  cacheFile;
+  memory = /* @__PURE__ */ new Map();
+  disk = null;
+  /** 内存命中才算「新鲜」—— 磁盘的走 {@link getPersisted} */
+  getFresh(name, fingerprint) {
+    const entry = this.memory.get(name);
+    return entry && entry.fingerprint === fingerprint ? entry.tools : null;
+  }
+  /** 上次成功落盘的 schema，仅在 live 调用失败时作为降级使用 */
+  getPersisted(name, fingerprint) {
+    const entry = this.loadDisk()[name];
+    return entry && entry.fingerprint === fingerprint ? entry.tools : null;
+  }
+  /** live 拉取成功后写入两层 */
+  set(name, fingerprint, tools) {
+    const entry = { fingerprint, tools };
+    this.memory.set(name, entry);
+    this.writeDisk(name, entry);
+  }
+  /**
+   * 显式失效。不传 name 清全部。
+   *
+   * 调用方：`McpRegistry.reconnect()`，以及将来的 `notifications/tools/list_changed`。
+   */
+  invalidate(name) {
+    if (name === void 0) {
+      this.memory.clear();
+      return;
+    }
+    this.memory.delete(name);
+  }
+  // ---- 磁盘 ----
+  loadDisk() {
+    if (this.disk) return this.disk;
+    if (!this.cacheFile) {
+      this.disk = {};
+      return this.disk;
+    }
+    try {
+      const parsed = JSON.parse(readFileSync(this.cacheFile, "utf-8"));
+      this.disk = isDiskShape(parsed) ? parsed : {};
+    } catch {
+      this.disk = {};
+    }
+    return this.disk;
+  }
+  writeDisk(name, entry) {
+    if (!this.cacheFile) return;
+    const data = this.loadDisk();
+    if (JSON.stringify(data[name]) === JSON.stringify(entry)) return;
+    data[name] = entry;
+    try {
+      mkdirSync(dirname(this.cacheFile), { recursive: true });
+      const tmp = `${this.cacheFile}.tmp`;
+      writeFileSync(tmp, JSON.stringify(data), { encoding: "utf-8", mode: 384 });
+      renameSync(tmp, this.cacheFile);
+    } catch {
+    }
+  }
+};
+function isDiskShape(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every(
+    (entry) => typeof entry === "object" && entry !== null && typeof entry.fingerprint === "string" && Array.isArray(entry.tools)
+  );
+}
+
+// src/client.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { ToolListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+
+// src/content.ts
+var DEFAULT_MEDIA_TYPE = "application/octet-stream";
+function str(v) {
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+function kindOf(mediaType) {
+  if (mediaType.startsWith("image/")) return "image";
+  if (mediaType.startsWith("audio/")) return "audio";
+  return "file";
+}
+function lastSegment(uri) {
+  if (!uri) return void 0;
+  const trimmed = uri.split(/[?#]/, 1)[0].replace(/\/+$/, "");
+  const seg = trimmed.slice(trimmed.lastIndexOf("/") + 1);
+  return seg.length > 0 ? seg : void 0;
+}
+function fromMedia(item, fallbackKind) {
+  const data = str(item.data);
+  if (!data) return null;
+  const mediaType = str(item.mimeType) ?? (fallbackKind === "image" ? "image/png" : "audio/wav");
+  return { kind: kindOf(mediaType), mediaType, base64: data };
+}
+function fromResource(item) {
+  const res = item.resource;
+  if (!res) return {};
+  const text = str(res.text);
+  if (text) return { text };
+  const blob = str(res.blob);
+  if (!blob) return {};
+  const mediaType = str(res.mimeType) ?? DEFAULT_MEDIA_TYPE;
+  const filename = lastSegment(str(res.uri));
+  return {
+    artifact: {
+      kind: kindOf(mediaType),
+      mediaType,
+      base64: blob,
+      ...filename ? { filename } : {}
+    }
+  };
+}
+function convertMcpContent(content) {
+  const items = Array.isArray(content) ? content : [];
+  const texts = [];
+  const artifacts = [];
+  for (const item of items) {
+    const type = typeof item?.type === "string" ? item.type : void 0;
+    switch (type) {
+      case "text": {
+        const t = str(item.text);
+        if (t) texts.push(t);
+        break;
+      }
+      case "image":
+      case "audio": {
+        const a = fromMedia(item, type);
+        if (a) artifacts.push(a);
+        break;
+      }
+      case "resource": {
+        const { text, artifact } = fromResource(item);
+        if (text) texts.push(text);
+        if (artifact) artifacts.push(artifact);
+        break;
+      }
+      case "resource_link": {
+        const uri = str(item.uri);
+        if (uri) texts.push(`${str(item.title) ?? str(item.name) ?? "\u8D44\u6E90"}: ${uri}`);
+        break;
+      }
+      default:
+        texts.push(`[\u672A\u77E5 content \u7C7B\u578B ${type ?? "(\u7F3A\u5931)"}\uFF0C\u5DF2\u5FFD\u7565]`);
+    }
+  }
+  return { text: texts.join("\n"), artifacts };
+}
+
+// src/oauth/attach.ts
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+
+// src/oauth/provider.ts
+import { randomBytes } from "crypto";
+
+// src/oauth/types.ts
+var McpLoginRequiredError = class extends Error {
+  constructor(server, detail) {
+    super(
+      `MCP server "${server}" \u9700\u8981 OAuth \u767B\u5F55\uFF1A\u5148\u8DD1 epoch mcp login ${server}` + (detail ? `\uFF08${detail}\uFF09` : "")
+    );
+    this.server = server;
+    this.name = "McpLoginRequiredError";
+  }
+  server;
+};
+
+// src/oauth/provider.ts
+var CLIENT_NAME = "epoch-agent";
+var CLIENT_URI = "https://gitlab.linkworld.cn/chenboxuan/epoch-agent";
+var PLACEHOLDER_REDIRECT_URI = "http://127.0.0.1:0/callback";
+var McpOAuthProvider = class {
+  opts;
+  /** 本次流程生成的 state，回调时用来验 CSRF */
+  currentState;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /** 本次授权流程用的 state，回调服务器拿它比对 */
+  get expectedState() {
+    return this.currentState;
+  }
+  /** 见 `PLACEHOLDER_REDIRECT_URI`：这里返回 undefined 会让 SDK 跳过 refresh */
+  get redirectUrl() {
+    return this.opts.redirectUri ?? PLACEHOLDER_REDIRECT_URI;
+  }
+  /** 真的能跳转吗（交互式登录才能）。占位地址不算 */
+  get interactive() {
+    return this.opts.onRedirect !== void 0;
+  }
+  get clientMetadata() {
+    return {
+      client_name: CLIENT_NAME,
+      client_uri: CLIENT_URI,
+      redirect_uris: [this.redirectUrl],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+      ...this.opts.scope ? { scope: this.opts.scope } : {}
+    };
+  }
+  /**
+   * OAuth 的 `state` 参数。
+   *
+   * SDK 把它当**生成器**调（每次授权一个新值），不是「读一个固定值」——
+   * opencode `src/mcp/oauth-provider.ts` 里踩过这个：写成只读缓存的话，
+   * 两次登录会拿到同一个 state，回调分不清是哪一次。
+   */
+  state() {
+    this.currentState = randomBytes(32).toString("base64url");
+    return this.currentState;
+  }
+  clientInformation() {
+    return this.entry()?.client;
+  }
+  saveClientInformation(info) {
+    this.opts.store.update(this.opts.server, this.opts.serverUrl, {
+      client: info
+    });
+  }
+  tokens() {
+    return this.entry()?.tokens;
+  }
+  /**
+   * 存 token。
+   *
+   * 顺手把 `expires_in`（相对秒数）换算成绝对时刻落盘 —— 相对值一重启就是错的。
+   * 同时清掉 `codeVerifier`：它只在「跳转了、还没换到 token」那段窗口有用，
+   * 换到了就是一份没有用处的秘密，留着只是多一处泄漏点。
+   */
+  saveTokens(tokens) {
+    const expiresAt = typeof tokens.expires_in === "number" && tokens.expires_in > 0 ? Date.now() + tokens.expires_in * 1e3 : void 0;
+    this.opts.store.update(this.opts.server, this.opts.serverUrl, {
+      tokens,
+      expiresAt,
+      codeVerifier: void 0,
+      updatedAt: Date.now()
+    });
+  }
+  async redirectToAuthorization(url) {
+    if (!this.opts.onRedirect) {
+      throw new McpLoginRequiredError(this.opts.server, "\u5DF2\u6709\u51ED\u636E\u65E0\u6CD5\u7EED\u671F\u6216\u5C1A\u672A\u6388\u6743");
+    }
+    await this.opts.onRedirect(url);
+  }
+  saveCodeVerifier(codeVerifier) {
+    this.opts.store.update(this.opts.server, this.opts.serverUrl, { codeVerifier });
+  }
+  codeVerifier() {
+    const verifier = this.entry()?.codeVerifier;
+    if (!verifier) {
+      throw new McpLoginRequiredError(this.opts.server, "PKCE code_verifier \u5DF2\u5931\u6548\uFF0C\u8BF7\u91CD\u65B0\u767B\u5F55");
+    }
+    return verifier;
+  }
+  /**
+   * 服务端说凭据不好使了，SDK 调这里让我们删掉。
+   *
+   * 不实现的话用户要自己去删 `~/.epoch/mcp-auth.json` —— 而「client 注册
+   * 被服务端撤销」这种情况下，不删就会一直拿同一个失效 client_id 重试。
+   */
+  invalidateCredentials(scope) {
+    if (scope === "all") {
+      this.opts.store.remove(this.opts.server);
+      return;
+    }
+    const patch = {
+      client: { client: void 0 },
+      tokens: { tokens: void 0, expiresAt: void 0 },
+      verifier: { codeVerifier: void 0 },
+      discovery: { discovery: void 0 }
+    }[scope];
+    this.opts.store.update(this.opts.server, this.opts.serverUrl, patch);
+  }
+  saveDiscoveryState(state) {
+    this.opts.store.update(this.opts.server, this.opts.serverUrl, {
+      discovery: state
+    });
+  }
+  discoveryState() {
+    return this.entry()?.discovery;
+  }
+  entry() {
+    return this.opts.store.get(this.opts.server, this.opts.serverUrl);
+  }
+};
+
+// src/oauth/attach.ts
+function createAuthProvider(config, store) {
+  if (config.transport === "stdio" || !config.url) return void 0;
+  if (config.oauth?.enabled === false) return void 0;
+  if (hasAuthorizationHeader(config.headers)) return void 0;
+  return new McpOAuthProvider({
+    server: config.name,
+    serverUrl: config.url,
+    store,
+    scope: config.oauth?.scope
+    // 刻意不给 onRedirect：连接期绝不弹浏览器，需要授权就抛「请先 login」
+  });
+}
+function hasAuthorizationHeader(headers) {
+  if (!headers) return false;
+  return Object.keys(headers).some((k) => k.toLowerCase() === "authorization");
+}
+function describeAuthFailure(err, server) {
+  if (err instanceof McpLoginRequiredError) return err.message;
+  if (err instanceof UnauthorizedError) {
+    return new McpLoginRequiredError(server, err.message || "token \u5DF2\u5931\u6548\u4E14\u65E0\u6CD5\u7EED\u671F").message;
+  }
+  const cause = err?.cause;
+  if (cause !== void 0 && cause !== err) return describeAuthFailure(cause, server);
+  return null;
+}
+
+// src/oauth/store.ts
+import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync as renameSync2, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2 } from "path";
+import {
+  getDataKey,
+  isEnvelope,
+  mcpAuthPath,
+  openEnvelope,
+  sealEnvelope
+} from "@epoch-agent/infra";
+var FILE_VERSION = 1;
+var REFRESH_SKEW_MS = 3e4;
+var McpAuthStore = class {
+  filePath;
+  cache = null;
+  /** 磁盘上是密文、但本次运行拿不到数据密钥。此时**只读不写**，见 load() / save() */
+  locked = false;
+  /** @param filePath 显式路径（测试用）；不传走 infra 的路径真源 */
+  constructor(filePath, homeDir) {
+    this.filePath = filePath ?? mcpAuthPath(homeDir);
+  }
+  get path() {
+    return this.filePath;
+  }
+  /**
+   * 读一个 server 的凭据。
+   *
+   * @param serverUrl 当前配置里的 URL。和落盘时记的对不上就返回 undefined ——
+   *                  换了地址的 token 不能拿去打新地址。
+   */
+  get(server, serverUrl) {
+    const entry = this.load().servers[server];
+    if (!entry) return void 0;
+    if (serverUrl !== void 0 && !sameEndpoint(entry.serverUrl, serverUrl)) return void 0;
+    return entry;
+  }
+  /** 不比对 URL 的读法，只给 `epoch mcp status` 展示用 */
+  getRaw(server) {
+    return this.load().servers[server];
+  }
+  list() {
+    return Object.entries(this.load().servers);
+  }
+  /** 局部更新一个 server 的条目；`serverUrl` 变了会先清空旧凭据 */
+  update(server, serverUrl, patch) {
+    const file = this.load();
+    this.assertWritable();
+    const existing = file.servers[server];
+    const base = existing && sameEndpoint(existing.serverUrl, serverUrl) ? existing : { serverUrl };
+    file.servers[server] = { ...base, ...patch, serverUrl };
+    this.save(file);
+  }
+  /** 删掉一个 server 的全部凭据。@returns 之前是否存在 */
+  remove(server) {
+    const file = this.load();
+    this.assertWritable();
+    if (!(server in file.servers)) return false;
+    delete file.servers[server];
+    this.save(file);
+    return true;
+  }
+  /** 强制下次 `get` 重新读盘。外部改过文件（另一个进程登录过）时用 */
+  invalidate() {
+    this.cache = null;
+  }
+  // ---- 内部 ----
+  load() {
+    if (this.cache) return this.cache;
+    if (!existsSync(this.filePath)) {
+      this.cache = { version: FILE_VERSION, servers: {} };
+      return this.cache;
+    }
+    const raw = readFileSync2(this.filePath, "utf-8");
+    this.locked = isEnvelope(raw) && getDataKey() === null;
+    try {
+      this.cache = normalize(JSON.parse(this.locked ? "{}" : decrypt(raw)));
+    } catch {
+      this.cache = { version: FILE_VERSION, servers: {} };
+    }
+    return this.cache;
+  }
+  /**
+   * 磁盘上是密文而当前解不开时，任何写操作都必须**当场失败**。
+   *
+   * 在改动内存状态之前就拦（而不是等到 save()）：`update()` 是先改缓存再落盘的，
+   * 到 save() 才抛会留下一个「内存里改了、盘上没改」的错位状态，
+   * 下一次读会拿到一份不存在于磁盘的凭据。
+   */
+  assertWritable() {
+    if (!this.locked) return;
+    throw new Error(
+      `${this.filePath} \u662F\u52A0\u5BC6\u7684\uFF0C\u4F46\u5F53\u524D\u62FF\u4E0D\u5230\u6570\u636E\u5BC6\u94A5\uFF0C\u62D2\u7EDD\u5199\u5165\u4EE5\u514D\u8986\u76D6\u5DF2\u6709\u51ED\u636E\u3002\u8DD1 epoch doctor \u770B Secret \u90A3\u4E00\u884C\u662F\u4EC0\u4E48\u539F\u56E0\u3002`
+    );
+  }
+  save(file) {
+    this.assertWritable();
+    mkdirSync2(dirname2(this.filePath), { recursive: true });
+    const tmp = `${this.filePath}.${process.pid}.tmp`;
+    try {
+      writeFileSync2(tmp, encrypt(JSON.stringify(file, null, 2)), {
+        encoding: "utf-8",
+        mode: 384
+      });
+      renameSync2(tmp, this.filePath);
+    } catch (err) {
+      rmSync(tmp, { force: true });
+      throw new Error(
+        `MCP \u51ED\u636E ${this.filePath} \u5199\u5165\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    this.cache = file;
+  }
+};
+function encrypt(json) {
+  const key = getDataKey();
+  return key ? sealEnvelope(key, json) : json;
+}
+function decrypt(raw) {
+  if (!isEnvelope(raw)) return raw;
+  const key = getDataKey();
+  if (!key) throw new Error("mcp-auth.json \u662F\u5BC6\u6587\uFF0C\u4F46\u5F53\u524D\u6CA1\u6709\u53EF\u7528\u7684\u6570\u636E\u5BC6\u94A5");
+  return openEnvelope(key, raw);
+}
+function isExpired(entry, now = Date.now()) {
+  if (!entry?.expiresAt) return false;
+  return now + REFRESH_SKEW_MS >= entry.expiresAt;
+}
+function sameEndpoint(a, b) {
+  return a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
+}
+function normalize(parsed) {
+  if (typeof parsed !== "object" || parsed === null) {
+    return { version: FILE_VERSION, servers: {} };
+  }
+  const servers = parsed.servers;
+  if (typeof servers !== "object" || servers === null) {
+    return { version: FILE_VERSION, servers: {} };
+  }
+  const out = {};
+  for (const [name, value] of Object.entries(servers)) {
+    if (typeof value !== "object" || value === null) continue;
+    const url = value.serverUrl;
+    if (typeof url !== "string" || url.length === 0) continue;
+    out[name] = value;
+  }
+  return { version: FILE_VERSION, servers: out };
+}
+
+// src/transport/index.ts
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import {
+  collectProcessTree,
+  createStreamDecoder,
+  killPids
+} from "@epoch-agent/infra";
+function createStdioTransport(config, onStderr) {
+  const transport = new StdioClientTransport({
+    command: config.command ?? "node",
+    args: config.args,
+    env: config.env,
+    stderr: "pipe"
+  });
+  let decoder = null;
+  transport.stderr?.on("data", (chunk) => {
+    decoder ??= createStreamDecoder();
+    onStderr(decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+  });
+  transport.stderr?.on("end", () => {
+    const rest = decoder?.end() ?? "";
+    if (rest.length > 0) onStderr(rest);
+  });
+  return transport;
+}
+function createHttpTransport(config, authProvider) {
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(config.url ?? "");
+  } catch {
+    throw new Error(`\u65E0\u6548\u7684 MCP URL: ${config.url}`);
+  }
+  const requestInit = config.headers ? { headers: config.headers } : void 0;
+  const opts = { requestInit, authProvider };
+  return config.streamable || config.transport === "http" ? new StreamableHTTPClientTransport(parsedUrl, opts) : new SSEClientTransport(parsedUrl, opts);
+}
+function stdioChildPid(transport) {
+  const proc = transport._process;
+  const pid = proc?.pid;
+  return typeof pid === "number" && Number.isInteger(pid) && pid > 1 ? pid : null;
+}
+async function closeTransportAndReap(transport) {
+  const pid = stdioChildPid(transport);
+  const orphans = pid === null ? [] : await collectProcessTree(pid);
+  try {
+    await transport.close();
+  } catch {
+  }
+  if (orphans.length > 0) await killPids(orphans, { escalate: true });
+}
+
+// src/types.ts
+var DEFAULTS = {
+  timeout: 300,
+  connectTimeout: 60,
+  keepaliveInterval: 180,
+  idleTimeoutSeconds: 0,
+  maxLifetimeSeconds: 0,
+  supportsParallel: false,
+  skipPreflight: false
+};
+
+// src/client.ts
+var MAX_RECONNECT = 3;
+var RECONNECT_BACKOFF = [1e3, 2e3, 4e3];
+var STDERR_TAIL_LINES = 20;
+var McpClient = class {
+  config;
+  client = null;
+  transport = null;
+  keepaliveTimer = null;
+  lifetimeTimer = null;
+  idleTimer = null;
+  reconnectTimer = null;
+  reconnectAttempts = 0;
+  lastError = null;
+  toolCount = 0;
+  stderrTail = [];
+  /** 上一个 chunk 末尾那截还没等到换行的文本，见 {@link collectStderr} */
+  stderrPartial = "";
+  /** 主动 disconnect 时置位，避免自己触发的 onclose 又去排一次重连 */
+  closingIntentionally = false;
+  /** 认证过不去。重连解决不了这个问题，只有 `epoch mcp login` 能 */
+  needsLogin = false;
+  cache;
+  fingerprint;
+  authProvider;
+  /**
+   * 收到 `notifications/tools/list_changed` 时的回调。
+   *
+   * McpRegistry 用它把「工具表已经不是启动时那份了」冒泡给宿主。
+   * 注意**这不是热更新**：AgentLoop 的工具集是构造参数，本进程内换不掉。
+   * 详见 registry 的 `refresh()`。
+   */
+  onToolsChanged;
+  /**
+   * 这台是谁带进来的（方案 44 PR-2）。
+   *
+   * **由 `McpRegistry.connectAll()` 那一侧说了算，不从 `config` 里读** ——
+   * `McpServerConfig` 是用户手写的 `mcp.json` 解析出来的形状，来源要是它的一个
+   * 字段，用户就能在自己的文件里写 `"source": "host"` 给自己那台贴上宿主的标。
+   * 判据同角色那条「命名空间由装配层拼，宿主自己写的不算数」。
+   */
+  source;
+  constructor(config, cache, authStore, source = "user") {
+    this.config = { ...DEFAULTS, ...config };
+    this.cache = cache ?? new McpSchemaCache(null);
+    this.fingerprint = configFingerprint(this.config);
+    this.authProvider = createAuthProvider(this.config, authStore ?? new McpAuthStore());
+    this.source = source;
+  }
+  get status() {
+    return {
+      name: this.config.name,
+      connected: this.client !== null,
+      toolCount: this.toolCount,
+      lastError: this.lastError ?? void 0,
+      reconnectAttempts: this.reconnectAttempts,
+      needsLogin: this.needsLogin,
+      source: this.source
+    };
+  }
+  /** 底层 SDK client，`null` 表示没连上。resources / prompts 那几个原语要用 */
+  get raw() {
+    return this.client;
+  }
+  get serverConfig() {
+    return this.config;
+  }
+  async connect() {
+    await this.connectInner();
+    if (this.client) {
+      this.startKeepalive();
+      this.startLifetime();
+    }
+  }
+  /**
+   * 取本 server 的工具 schema —— 缓存优先。
+   *
+   * 三级：内存缓存 → live `tools/list` → 上次落盘的 schema（降级）。
+   * 详见 [cache.ts](./cache.ts) 里两层分工的说明。
+   */
+  async getToolSchemas() {
+    const name = this.config.name;
+    const cached = this.cache.getFresh(name, this.fingerprint);
+    if (cached) {
+      this.toolCount = cached.length;
+      return cached;
+    }
+    const live = await this.fetchToolSchemas();
+    if (live) {
+      this.cache.set(name, this.fingerprint, live);
+      this.toolCount = live.length;
+      return live;
+    }
+    const persisted = this.cache.getPersisted(name, this.fingerprint);
+    if (persisted) {
+      this.toolCount = persisted.length;
+      this.lastError = `${this.lastError ?? "tools/list \u5931\u8D25"}\uFF08\u5DF2\u964D\u7EA7\u7528\u4E0A\u6B21\u7F13\u5B58\u7684 ${persisted.length} \u4E2A\u5DE5\u5177\uFF09`;
+      return persisted;
+    }
+    return [];
+  }
+  /** live 拉取；失败返回 null（错误记进 lastError，由调用方决定降不降级） */
+  async fetchToolSchemas() {
+    if (!this.client) return null;
+    this.resetIdle();
+    try {
+      const result = await this.withTimeout(
+        this.client.listTools(),
+        (this.config.timeout ?? DEFAULTS.timeout) * 1e3
+      );
+      return (result.tools ?? []).map((t) => {
+        const tool = t;
+        return {
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+          title: tool.title,
+          annotations: tool.annotations
+        };
+      });
+    } catch (err) {
+      this.lastError = err instanceof Error ? err.message : String(err);
+      return null;
+    }
+  }
+  /**
+   * 调用工具。
+   *
+   * **断线不在这里等重连**：以前这里 `await this.reconnect()`，而 reconnect 是
+   * 1s + 2s + 4s 的 backoff 循环 —— 工具执行路径上最多阻塞 7 秒，用户看到的是
+   * agent 卡住。现在改成排一次后台重连、立刻返回一条可重试的错误。
+   */
+  async callTool(name, args) {
+    if (!this.client) {
+      this.scheduleReconnect();
+      return { success: false, output: this.unavailableMessage() };
+    }
+    this.resetIdle();
+    try {
+      const result = await this.withTimeout(
+        this.client.callTool({ name, arguments: args }),
+        (this.config.timeout ?? DEFAULTS.timeout) * 1e3
+      );
+      const { text, artifacts } = convertMcpContent(result.content);
+      return {
+        success: !result.isError,
+        output: text,
+        ...artifacts.length > 0 ? { artifacts } : {}
+      };
+    } catch (err) {
+      const authHint = describeAuthFailure(err, this.config.name);
+      if (authHint) {
+        this.needsLogin = true;
+        this.lastError = authHint;
+        return { success: false, output: authHint };
+      }
+      return { success: false, output: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  async disconnect() {
+    this.closingIntentionally = true;
+    this.clearTimers();
+    if (this.transport) {
+      await closeTransportAndReap(this.transport);
+      this.transport = null;
+    }
+    this.client = null;
+    this.closingIntentionally = false;
+  }
+  // ---- 内部 ----
+  /**
+   * 建连。**握手成功之前不写 this.client**。
+   *
+   * 以前是先 `this.client = new Client(...)` 再 await 握手，于是
+   * `status.connected`（判据就是 `client !== null`）在握手还没跑完时就报 true ——
+   * 调用方据此以为能用了，实际 SDK 会抛 "Not connected"。
+   *
+   * 失败路径也补上了 `transport.close()`：以前 connect 超时只是把字段置 null，
+   * stdio 已经起来的子进程没人收，直接漏成孤儿进程。
+   */
+  async connectInner() {
+    const transport = this.config.transport === "stdio" || !this.config.url ? createStdioTransport(this.config, (text) => this.collectStderr(text)) : createHttpTransport(this.config, this.authProvider);
+    const client = new Client({ name: "epoch-agent", version: "0.0.0" }, { capabilities: {} });
+    client.onclose = () => this.onTransportClosed(client);
+    client.setNotificationHandler(ToolListChangedNotificationSchema, () => {
+      this.onToolsListChanged();
+    });
+    const connectTimeoutMs = (this.config.connectTimeout ?? DEFAULTS.connectTimeout) * 1e3;
+    try {
+      await this.withTimeout(
+        client.connect(transport, { timeout: connectTimeoutMs }),
+        connectTimeoutMs
+      );
+    } catch (err) {
+      await closeTransportAndReap(transport);
+      const authHint = describeAuthFailure(err, this.config.name);
+      if (authHint) {
+        this.needsLogin = true;
+        this.lastError = authHint;
+        throw err;
+      }
+      const base = err instanceof Error ? err.message : String(err);
+      this.lastError = this.stderrTail.length > 0 ? `${base}\uFF1Bstderr: ${this.stderrHint()}` : base;
+      throw err;
+    }
+    this.transport = transport;
+    this.client = client;
+    this.reconnectAttempts = 0;
+    this.lastError = null;
+    this.needsLogin = false;
+  }
+  /**
+   * 攒起 stderr 的尾部若干**行**。
+   *
+   * ⚠️ **`text` 是一个 chunk，不是一行。** 一行长过一个 chunk（管道一次 64 KB）
+   * 时它会被切开，而不留半截的话每一截都变成尾部里独立的一条 —— 既占掉好几个
+   * 名额，`stderrHint()` 拼出来还像是好几件事（`……前半 | 后半`）。
+   * 一个把栈打进 stderr 的 server 很容易做到这一点。
+   *
+   * ⚠️ 别把 `cmd.exe` 那句「不是内部或外部命令」的两行当成这个 bug 的例子 ——
+   * 实测过，**那句话本身就是两行**（「……可运行的程序」后面真有一个 `\r\n`），
+   * 拼出来带 `|` 是忠实的。
+   */
+  collectStderr(text) {
+    const parts = (this.stderrPartial + text).split("\n");
+    this.stderrPartial = parts.pop() ?? "";
+    for (const line of parts) {
+      if (line.trim().length === 0) continue;
+      this.stderrTail.push(line.trim());
+    }
+    if (this.stderrTail.length > STDERR_TAIL_LINES) {
+      this.stderrTail = this.stderrTail.slice(-STDERR_TAIL_LINES);
+    }
+  }
+  /**
+   * 最后三行，给错误消息当尾巴。
+   *
+   * 把还没等到换行的那半行也算进来：server 崩在半句话上时，那半句往往正是
+   * 最要紧的一句（而它永远等不到自己的 `\n`）。
+   */
+  stderrHint() {
+    const partial = this.stderrPartial.trim();
+    const lines = partial.length > 0 ? [...this.stderrTail, partial] : this.stderrTail;
+    return lines.slice(-3).join(" | ");
+  }
+  /**
+   * server 说工具表变了。
+   *
+   * 只做两件事：**失效 schema 缓存**（下次 `getToolSchemas()` 会真去拉一次），
+   * 然后把事件冒泡出去。刻意不在这里自己去 `listTools()` —— 通知可能连着来，
+   * 每条都拉一次是在替 server 打自己。
+   */
+  onToolsListChanged() {
+    this.cache.invalidate(this.config.name);
+    this.onToolsChanged?.();
+  }
+  /**
+   * @param closed 触发 onclose 的那个 Client。重连成功后旧连接的迟到通知
+   *               不能把新连接连坐掉，所以要比对身份。
+   */
+  onTransportClosed(closed) {
+    if (this.closingIntentionally) return;
+    if (this.client !== null && this.client !== closed) return;
+    this.client = null;
+    this.transport = null;
+    this.stopKeepalive();
+    this.lastError = `\u8FDE\u63A5\u5DF2\u65AD\u5F00${this.stderrTail.length > 0 ? `\uFF1Bstderr: ${this.stderrHint()}` : ""}`;
+    this.scheduleReconnect();
+  }
+  /**
+   * 排一次后台重连（幂等）。
+   *
+   * 看门狗语义：重连全程不占用调用方的时间片，失败就按 backoff 再排一次，
+   * 到 MAX_RECONNECT 为止把 server 标成不可用。
+   */
+  scheduleReconnect() {
+    if (this.reconnectTimer || this.client) return;
+    if (this.needsLogin) return;
+    if (this.reconnectAttempts >= MAX_RECONNECT) {
+      this.lastError = `\u91CD\u8FDE ${MAX_RECONNECT} \u6B21\u5931\u8D25\uFF0C${this.config.name} \u6807\u8BB0\u4E3A\u4E0D\u53EF\u7528`;
+      return;
+    }
+    const delay = RECONNECT_BACKOFF[this.reconnectAttempts] ?? 4e3;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      void this.attemptReconnect();
+    }, delay);
+    this.reconnectTimer.unref?.();
+  }
+  async attemptReconnect() {
+    this.reconnectAttempts++;
+    try {
+      await this.connectInner();
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    if (this.client) {
+      this.cache.invalidate(this.config.name);
+      this.onToolsChanged?.();
+      this.startKeepalive();
+      this.startLifetime();
+    }
+  }
+  unavailableMessage() {
+    if (this.needsLogin) {
+      return this.lastError ?? `MCP server ${this.config.name} \u9700\u8981 OAuth \u767B\u5F55`;
+    }
+    if (this.reconnectAttempts >= MAX_RECONNECT) {
+      return `MCP server ${this.config.name} \u4E0D\u53EF\u7528\uFF08\u91CD\u8FDE ${MAX_RECONNECT} \u6B21\u5931\u8D25\uFF09${this.lastError ? `\uFF1A${this.lastError}` : ""}`;
+    }
+    return `MCP server ${this.config.name} \u8FDE\u63A5\u5DF2\u65AD\u5F00\uFF0C\u6B63\u5728\u540E\u53F0\u91CD\u8FDE\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5${this.lastError ? `\uFF08\u4E0A\u6B21\u9519\u8BEF\uFF1A${this.lastError}\uFF09` : ""}`;
+  }
+  startKeepalive() {
+    this.stopKeepalive();
+    const interval = Math.max(this.config.keepaliveInterval ?? DEFAULTS.keepaliveInterval, 5) * 1e3;
+    this.keepaliveTimer = setInterval(() => {
+      void this.pingOnce();
+    }, interval);
+    this.keepaliveTimer.unref?.();
+  }
+  async pingOnce() {
+    if (!this.client) return;
+    try {
+      await this.withTimeout(this.client.listTools(), 1e4);
+    } catch {
+      this.lastError = "keepalive \u5931\u8D25";
+      this.client = null;
+      this.stopKeepalive();
+      this.scheduleReconnect();
+    }
+  }
+  stopKeepalive() {
+    if (this.keepaliveTimer) {
+      clearInterval(this.keepaliveTimer);
+      this.keepaliveTimer = null;
+    }
+  }
+  /**
+   * 起 idle / max-lifetime 两个自动断连定时器。
+   *
+   * 这里刻意**不**调 `clearTimers()`：它连 keepalive 一起清，而调用顺序是
+   * `startKeepalive(); startLifetime();` —— 等于刚起的 keepalive 立刻被自己清掉，
+   * keepalive 从来没真正跑过。只清自己的两个定时器。
+   */
+  startLifetime() {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    if (this.lifetimeTimer) clearTimeout(this.lifetimeTimer);
+    this.idleTimer = null;
+    this.lifetimeTimer = null;
+    if ((this.config.idleTimeoutSeconds ?? 0) > 0) {
+      this.idleTimer = this.armDisconnect(this.config.idleTimeoutSeconds ?? 3600);
+    }
+    if ((this.config.maxLifetimeSeconds ?? 0) > 0) {
+      this.lifetimeTimer = this.armDisconnect(this.config.maxLifetimeSeconds ?? 86400);
+    }
+  }
+  resetIdle() {
+    if ((this.config.idleTimeoutSeconds ?? 0) > 0) {
+      if (this.idleTimer) clearTimeout(this.idleTimer);
+      this.idleTimer = this.armDisconnect(this.config.idleTimeoutSeconds ?? 3600);
+    }
+  }
+  armDisconnect(seconds2) {
+    const timer = setTimeout(() => void this.disconnect(), seconds2 * 1e3);
+    timer.unref?.();
+    return timer;
+  }
+  clearTimers() {
+    this.stopKeepalive();
+    for (const timer of [this.idleTimer, this.lifetimeTimer, this.reconnectTimer]) {
+      if (timer) clearTimeout(timer);
+    }
+    this.idleTimer = null;
+    this.lifetimeTimer = null;
+    this.reconnectTimer = null;
+  }
+  async withTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`\u8D85\u65F6 (${ms}ms)`)), ms);
+      timer.unref?.();
+    });
+    try {
+      return await Promise.race([promise, timeout]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+};
+
+// src/oauth/callback.ts
+import { createServer } from "http";
+var CALLBACK_TIMEOUT_MS = 5 * 60 * 1e3;
+var CALLBACK_PATH = "/callback";
+async function startCallbackServer(port, timeoutMs = CALLBACK_TIMEOUT_MS) {
+  let onResult = null;
+  let pending = null;
+  let expectedState;
+  let armed = false;
+  const emit = (result) => {
+    if (onResult) onResult(result);
+    else pending = result;
+  };
+  const server = createServer((req, res) => {
+    handleRequest(req, res, emit);
+  });
+  const actualPort = await listen(server, port);
+  const redirectUri = `http://127.0.0.1:${actualPort}${CALLBACK_PATH}`;
+  let closed = false;
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    server.close();
+    server.closeAllConnections?.();
+  };
+  return {
+    redirectUri,
+    close,
+    expect(state) {
+      expectedState = state;
+      armed = true;
+    },
+    waitForCode() {
+      return new Promise((resolve, reject) => {
+        const settle = (result) => {
+          setTimeout(close, 100).unref?.();
+          if (result.error) reject(result.error);
+          else if (result.code) resolve(result.code);
+          else reject(new Error("OAuth \u56DE\u8C03\u91CC\u6CA1\u6709\u6388\u6743\u7801"));
+        };
+        if (pending) {
+          settle(pending);
+          return;
+        }
+        const timer = setTimeout(() => {
+          close();
+          reject(new Error(`\u7B49\u5F85 OAuth \u56DE\u8C03\u8D85\u65F6\uFF08${timeoutMs / 1e3}s\uFF09\uFF0C\u767B\u5F55\u672A\u5B8C\u6210`));
+        }, timeoutMs);
+        timer.unref?.();
+        onResult = (result) => {
+          clearTimeout(timer);
+          onResult = null;
+          settle(result);
+        };
+      });
+    }
+  };
+  function handleRequest(req, res, emit2) {
+    const url = new URL(req.url ?? "/", redirectUri);
+    if (url.pathname !== CALLBACK_PATH) {
+      res.writeHead(404).end("Not Found");
+      return;
+    }
+    if (!armed) {
+      respond(res, 400, "\u6388\u6743\u5931\u8D25", "\u672C\u6B21\u767B\u5F55\u5C1A\u672A\u5F00\u59CB\uFF0C\u8FD9\u4E2A\u56DE\u8C03\u4E0D\u5C5E\u4E8E\u4EFB\u4F55\u6D41\u7A0B");
+      return;
+    }
+    const params = url.searchParams;
+    const oauthError = params.get("error");
+    if (oauthError) {
+      const detail = params.get("error_description");
+      respond(res, 400, "\u6388\u6743\u5931\u8D25", detail ?? oauthError);
+      emit2({
+        error: new Error(`\u6388\u6743\u670D\u52A1\u5668\u8FD4\u56DE ${oauthError}${detail ? `\uFF1A${detail}` : ""}`)
+      });
+      return;
+    }
+    const state = params.get("state");
+    if (expectedState !== void 0 && state !== expectedState) {
+      respond(res, 400, "\u6388\u6743\u5931\u8D25", "state \u4E0D\u5339\u914D\uFF0C\u8FD9\u6B21\u56DE\u8C03\u5DF2\u88AB\u62D2\u7EDD");
+      emit2({ error: new Error("OAuth \u56DE\u8C03\u7684 state \u4E0D\u5339\u914D\uFF08\u53EF\u80FD\u662F CSRF\uFF09\uFF0C\u5DF2\u62D2\u7EDD") });
+      return;
+    }
+    const code = params.get("code");
+    if (!code) {
+      respond(res, 400, "\u6388\u6743\u5931\u8D25", "\u56DE\u8C03\u91CC\u6CA1\u6709 code");
+      emit2({ error: new Error("OAuth \u56DE\u8C03\u91CC\u6CA1\u6709\u6388\u6743\u7801") });
+      return;
+    }
+    respond(res, 200, "\u6388\u6743\u6210\u529F", "\u53EF\u4EE5\u5173\u6389\u8FD9\u4E2A\u9875\u9762\u56DE\u5230\u7EC8\u7AEF\u4E86\u3002");
+    emit2({ code });
+  }
+}
+function listen(server, port) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port ?? 0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address) {
+        reject(new Error("\u56DE\u8C03\u670D\u52A1\u5668\u542F\u52A8\u5931\u8D25\uFF1A\u62FF\u4E0D\u5230\u7AEF\u53E3"));
+        return;
+      }
+      server.removeListener("error", reject);
+      resolve(address.port);
+    });
+  });
+}
+function respond(res, status, title, detail) {
+  const body = `<!doctype html><html lang="zh"><head><meta charset="utf-8">
+<title>${title}</title></head>
+<body style="font-family:system-ui;max-width:32rem;margin:6rem auto;text-align:center">
+<h1>${title}</h1><p>${escapeHtml(detail)}</p><p style="color:#888">epoch-agent</p>
+</body></html>`;
+  res.writeHead(status, { "content-type": "text/html; charset=utf-8" }).end(body);
+}
+function escapeHtml(text) {
+  return text.replace(
+    /[&<>"']/g,
+    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] ?? c
+  );
+}
+
+// src/oauth/login.ts
+import { spawn } from "child_process";
+import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
+async function loginToMcpServer(opts) {
+  const store = opts.store ?? new McpAuthStore();
+  const print = opts.print ?? (() => {
+  });
+  const openBrowser = opts.openBrowser ?? openInBrowser;
+  const callback = await startCallbackServer(opts.port);
+  let redirected = false;
+  const provider = new McpOAuthProvider({
+    server: opts.server,
+    serverUrl: opts.serverUrl,
+    store,
+    redirectUri: callback.redirectUri,
+    scope: opts.scope,
+    onRedirect: async (url) => {
+      redirected = true;
+      callback.expect(provider.expectedState);
+      print(`\u5728\u6D4F\u89C8\u5668\u91CC\u5B8C\u6210\u6388\u6743\uFF1A
+  ${url.toString()}`);
+      await openBrowser(url.toString());
+    }
+  });
+  try {
+    provider.invalidateCredentials("verifier");
+    dropUnusableClient(provider, store, opts, callback.redirectUri);
+    const first = await auth(provider, { serverUrl: opts.serverUrl, scope: opts.scope });
+    if (first === "AUTHORIZED" && !redirected) {
+      return { server: opts.server, refreshedOnly: true };
+    }
+    const code = await callback.waitForCode();
+    const second = await auth(provider, {
+      serverUrl: opts.serverUrl,
+      authorizationCode: code,
+      scope: opts.scope
+    });
+    if (second !== "AUTHORIZED") {
+      throw new Error(`\u6388\u6743\u672A\u5B8C\u6210\uFF08SDK \u8FD4\u56DE ${second}\uFF09`);
+    }
+    return { server: opts.server, refreshedOnly: false };
+  } finally {
+    callback.close();
+  }
+}
+function dropUnusableClient(provider, store, opts, redirectUri) {
+  const entry = store.get(opts.server, opts.serverUrl);
+  if (!entry?.client || entry.tokens?.refresh_token) return;
+  const registered = entry.client.redirect_uris;
+  if (Array.isArray(registered) && registered.includes(redirectUri)) return;
+  provider.invalidateCredentials("client");
+}
+function logoutFromMcpServer(server, store) {
+  return (store ?? new McpAuthStore()).remove(server);
+}
+function mcpAuthStatus(config, store) {
+  const s = store ?? new McpAuthStore();
+  if (config.transport === "stdio" || !config.url) {
+    return { server: config.name, state: "not-applicable" };
+  }
+  if (hasAuthorizationHeader2(config.headers)) {
+    return { server: config.name, state: "bearer-header", url: config.url };
+  }
+  const entry = s.get(config.name, config.url);
+  const base = { server: config.name, url: config.url };
+  if (!entry?.tokens?.access_token) {
+    return { ...base, state: "logged-out" };
+  }
+  const state = !isExpired(entry) ? "authorized" : entry.tokens.refresh_token ? "refreshable" : "logged-out";
+  return {
+    ...base,
+    state,
+    expiresAt: entry.expiresAt,
+    updatedAt: entry.updatedAt,
+    scope: entry.tokens.scope
+  };
+}
+function hasAuthorizationHeader2(headers) {
+  if (!headers) return false;
+  return Object.keys(headers).some((k) => k.toLowerCase() === "authorization");
+}
+function isBrowsableUrl(url) {
+  try {
+    const { protocol } = new URL(url);
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function browserLaunchArgv(url, platform = process.platform) {
+  if (!isBrowsableUrl(url)) return null;
+  if (platform === "darwin") return { command: "open", args: [url] };
+  if (platform === "win32") {
+    return { command: "rundll32.exe", args: ["url.dll,FileProtocolHandler", url] };
+  }
+  return { command: "xdg-open", args: [url] };
+}
+async function openInBrowser(url) {
+  const launch = browserLaunchArgv(url);
+  if (!launch) return;
+  try {
+    const child = spawn(launch.command, launch.args, { stdio: "ignore", detached: true });
+    child.unref();
+    child.on("error", () => {
+    });
+  } catch {
+  }
+}
+
+// src/primitives.ts
+var METHOD_NOT_FOUND = -32601;
+var MAX_PAGES = 50;
+async function listResources(client) {
+  if (!client.getServerCapabilities()?.resources) return [];
+  return paginate(async (cursor) => {
+    const res = await client.listResources(cursor ? { cursor } : {});
+    return { items: res.resources ?? [], nextCursor: res.nextCursor };
+  });
+}
+async function listPrompts(client) {
+  if (!client.getServerCapabilities()?.prompts) return [];
+  return paginate(async (cursor) => {
+    const res = await client.listPrompts(cursor ? { cursor } : {});
+    return { items: res.prompts ?? [], nextCursor: res.nextCursor };
+  });
+}
+async function readResourceText(client, uri) {
+  const result = await client.readResource({ uri });
+  const parts = [];
+  for (const content of result.contents ?? []) {
+    if ("text" in content && typeof content.text === "string") {
+      parts.push(content.text);
+    } else if ("blob" in content && typeof content.blob === "string") {
+      const mime = typeof content.mimeType === "string" ? content.mimeType : "\u672A\u77E5\u7C7B\u578B";
+      parts.push(`[\u4E8C\u8FDB\u5236\u5185\u5BB9 ${mime}\uFF0C${content.blob.length} \u5B57\u8282 base64\uFF0C\u672A\u5C55\u5F00]`);
+    }
+  }
+  return parts.join("\n");
+}
+async function getPromptText(client, name, args = {}) {
+  const result = await client.getPrompt({ name, arguments: args });
+  return (result.messages ?? []).map((msg) => {
+    const { text, artifacts } = convertMcpContent([msg.content]);
+    const placeholders = artifacts.map(
+      (a) => `[${a.kind} ${a.mediaType}\uFF0C${a.base64.length} \u5B57\u8282 base64\uFF0C\u672A\u5C55\u5F00]`
+    );
+    return `[${msg.role}] ${[text, ...placeholders].filter(Boolean).join("\n")}`;
+  }).join("\n");
+}
+async function paginate(fetchPage) {
+  const all = [];
+  let cursor;
+  try {
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const { items, nextCursor } = await fetchPage(cursor);
+      all.push(...items);
+      if (!nextCursor) break;
+      cursor = nextCursor;
+    }
+  } catch (err) {
+    if (isMethodNotFound(err)) return [];
+    throw err;
+  }
+  return all;
+}
+function isMethodNotFound(err) {
+  return err?.code === METHOD_NOT_FOUND;
+}
+
+// src/registry.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import { mcpConfigPath, mcpSchemaCachePath } from "@epoch-agent/infra";
+
+// src/tool-adapter.ts
+function prefixedName(serverName, toolName) {
+  return `mcp__${serverName}__${toolName}`;
+}
+function toEpochTools(serverName, schemas, call) {
+  return schemas.map((schema) => toEpochTool(serverName, schema, call));
+}
+function toEpochTool(serverName, schema, call) {
+  const title = schema.annotations?.title ?? schema.title;
+  const description = [
+    title && title !== schema.name ? `${title} \u2014\u2014 ` : "",
+    schema.description ?? `MCP \u5DE5\u5177 ${schema.name}\uFF08\u6765\u81EA ${serverName}\uFF09`
+  ].join("");
+  return {
+    name: prefixedName(serverName, schema.name),
+    description,
+    parameters: schema.inputSchema ?? {
+      type: "object",
+      properties: {}
+    },
+    annotations: schema.annotations ? stripTitle(schema.annotations) : void 0,
+    execute: async (args) => {
+      const startedAt = performance.now();
+      const result = await call(schema.name, args);
+      return {
+        success: result.success,
+        output: result.output,
+        // 原样往上交，不在这里判「模型认不认图」—— 那是 ToolExecutor 的四道闸门
+        ...result.artifacts && result.artifacts.length > 0 ? { artifacts: result.artifacts } : {},
+        duration: Math.round(performance.now() - startedAt)
+      };
+    }
+  };
+}
+function stripTitle(annotations) {
+  if (!annotations) return void 0;
+  const { readOnlyHint, destructiveHint, idempotentHint, openWorldHint } = annotations;
+  const hints = { readOnlyHint, destructiveHint, idempotentHint, openWorldHint };
+  const given = Object.entries(hints).filter(([, v]) => v !== void 0);
+  return given.length > 0 ? Object.fromEntries(given) : void 0;
+}
+
+// src/resource-tools.ts
+var MAX_LISTED = 200;
+function createResourceTools(serverName, getClient) {
+  const client = getClient();
+  if (!client?.getServerCapabilities()?.resources) return [];
+  return [
+    {
+      name: prefixedName(serverName, "list_resources"),
+      description: `\u5217\u51FA MCP server\u300C${serverName}\u300D\u63D0\u4F9B\u7684\u6240\u6709\u8D44\u6E90\uFF08URI + \u8BF4\u660E\uFF09\u3002\u60F3\u8BFB\u67D0\u4E2A\u8D44\u6E90\u7684\u5185\u5BB9\uFF0C\u518D\u8C03 ${prefixedName(serverName, "read_resource")}\u3002`,
+      parameters: { type: "object", properties: {} },
+      // 这两个 hint 是**我们自己**的声明，不是 server 给的：按 MCP 规范
+      // resources/list 与 resources/read 都是只读操作。server 声明的 annotations
+      // 走 tool-adapter.ts，两条路不会混
+      annotations: { readOnlyHint: true, openWorldHint: true },
+      execute: async () => {
+        return run(async () => {
+          const current = requireClient(getClient, serverName);
+          const resources = await listResources(current);
+          if (resources.length === 0) return `${serverName} \u6CA1\u6709\u63D0\u4F9B\u4EFB\u4F55\u8D44\u6E90`;
+          const shown = resources.slice(0, MAX_LISTED);
+          const lines = shown.map(
+            (r) => [
+              r.uri,
+              r.name && r.name !== r.uri ? `\uFF08${r.name}\uFF09` : "",
+              r.description ? ` \u2014 ${r.description}` : ""
+            ].join("")
+          );
+          const omitted = resources.length - shown.length;
+          if (omitted > 0) lines.push(`\u2026\u2026 \u53E6\u6709 ${omitted} \u6761\u672A\u5217\u51FA`);
+          return lines.join("\n");
+        });
+      }
+    },
+    {
+      name: prefixedName(serverName, "read_resource"),
+      description: `\u8BFB\u53D6 MCP server\u300C${serverName}\u300D\u4E0A\u67D0\u4E2A\u8D44\u6E90\u7684\u5185\u5BB9\u3002uri \u4ECE ${prefixedName(serverName, "list_resources")} \u62FF\u3002`,
+      parameters: {
+        type: "object",
+        properties: { uri: { type: "string", description: "\u8D44\u6E90 URI" } },
+        required: ["uri"]
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+      execute: async (args) => {
+        return run(async () => {
+          const uri = args["uri"];
+          if (typeof uri !== "string" || uri.length === 0) throw new Error("\u7F3A\u5C11 uri \u53C2\u6570");
+          const current = requireClient(getClient, serverName);
+          const text = await readResourceText(current, uri);
+          return text.length > 0 ? text : `\u8D44\u6E90 ${uri} \u6CA1\u6709\u53EF\u8BFB\u7684\u6587\u672C\u5185\u5BB9`;
+        });
+      }
+    }
+  ];
+}
+function requireClient(getClient, serverName) {
+  const client = getClient();
+  if (!client) throw new Error(`MCP server ${serverName} \u5F53\u524D\u672A\u8FDE\u63A5`);
+  return client;
+}
+async function run(fn) {
+  const startedAt = performance.now();
+  try {
+    const output = await fn();
+    return { success: true, output, duration: Math.round(performance.now() - startedAt) };
+  } catch (err) {
+    return {
+      success: false,
+      output: err instanceof Error ? err.message : String(err),
+      duration: Math.round(performance.now() - startedAt)
+    };
+  }
+}
+
+// src/schema.ts
+import { z } from "zod";
+import { parseLenient } from "@epoch-agent/infra";
+var seconds = z.number().positive().finite();
+var OAuthSchema = z.object({
+  enabled: z.boolean().optional(),
+  scope: z.string().optional(),
+  callbackPort: z.number().int().min(1024).max(65535).optional()
+});
+var RawServerSchema = z.object({
+  transport: z.enum(["stdio", "sse", "http"]).optional(),
+  /**
+   * `transport` 的别名。**MCP 生态里的通用写法是 `type`**（Claude Desktop /
+   * Cursor 等客户端的 mcp.json 都是它），我们自己的名字是 `transport`。
+   *
+   * 不收它的代价不是「多一条警告」而是**静默选错传输**：`type` 落进未知字段被丢掉，
+   * 下面那行 `raw.url ? 'sse' : 'stdio'` 于是把一个 `{"type":"http","url":…}` 的
+   * Streamable HTTP server 连成 SSE。这正是本文件下面那句注释说已经堵掉的坑
+   * （「写 `transport: 'http'` 的用户会静默走到 SSE 上去」），当时只堵了我们自己
+   * 这个字段名的那一半。2026-08-12 拿真实配置试出来的。
+   */
+  type: z.enum(["stdio", "sse", "http"]).optional(),
+  command: z.string().min(1).optional(),
+  args: z.array(z.string()).optional(),
+  url: z.string().min(1).optional(),
+  streamable: z.boolean().optional(),
+  headers: z.record(z.string(), z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  timeout: seconds.optional(),
+  connect_timeout: seconds.optional(),
+  connectTimeout: seconds.optional(),
+  keepalive_interval: seconds.optional(),
+  keepaliveInterval: seconds.optional(),
+  idle_timeout_seconds: seconds.optional(),
+  idleTimeoutSeconds: seconds.optional(),
+  max_lifetime_seconds: seconds.optional(),
+  maxLifetimeSeconds: seconds.optional(),
+  supports_parallel: z.boolean().optional(),
+  supportsParallel: z.boolean().optional(),
+  skip_preflight: z.boolean().optional(),
+  skipPreflight: z.boolean().optional(),
+  oauth: OAuthSchema.optional()
+});
+var KNOWN_KEYS = new Set(Object.keys(RawServerSchema.shape));
+var RawConfigSchema = z.object({
+  servers: z.record(z.string(), z.unknown()).optional(),
+  mcpServers: z.record(z.string(), z.unknown()).optional()
+});
+function parseMcpConfig(raw, label) {
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return { servers: [], issues: [{ path: label, message: `JSON \u8BED\u6CD5\u9519\u8BEF\uFF1A${detail}` }] };
+  }
+  const issues = [];
+  const top = parseLenient(RawConfigSchema, json, {});
+  issues.push(...prefix(top.issues, label));
+  const entries = top.value.servers;
+  if (!entries) {
+    if (top.value.mcpServers) {
+      issues.push({
+        path: label,
+        message: "\u68C0\u6D4B\u5230 `mcpServers` \u5B57\u6BB5\uFF1Bepoch \u8BFB\u7684\u662F `servers`\uFF0C\u8BF7\u6539\u952E\u540D"
+      });
+    } else if (issues.length === 0) {
+      issues.push({ path: label, message: "\u7F3A\u5C11 `servers` \u5B57\u6BB5\uFF0C\u6CA1\u6709\u53EF\u7528\u7684 MCP server" });
+    }
+    return { servers: [], issues };
+  }
+  const servers = [];
+  for (const [name, value] of Object.entries(entries)) {
+    const at = `${label}.servers.${name}`;
+    const parsed = parseLenient(RawServerSchema.nullable(), value, null);
+    if (!parsed.value) {
+      issues.push(...prefix(parsed.issues, at));
+      issues.push({ path: at, message: "\u914D\u7F6E\u65E0\u6548\uFF0C\u8BE5 server \u5DF2\u8DF3\u8FC7" });
+      continue;
+    }
+    issues.push(...unknownKeyIssues(value, at));
+    const { config, issues: crossIssues } = normalize2(name, parsed.value, at);
+    issues.push(...crossIssues);
+    if (config) servers.push(config);
+  }
+  return { servers, issues };
+}
+function normalize2(name, raw, at) {
+  const issues = [];
+  const transport = raw.transport ?? raw.type ?? (raw.url ? "sse" : "stdio");
+  if (transport === "stdio" && !raw.command) {
+    issues.push({ path: `${at}.command`, message: "stdio \u4F20\u8F93\u7F3A\u5C11 command\uFF0C\u8BE5 server \u5DF2\u8DF3\u8FC7" });
+  }
+  if (transport !== "stdio") {
+    if (!raw.url) {
+      issues.push({ path: `${at}.url`, message: `${transport} \u4F20\u8F93\u7F3A\u5C11 url\uFF0C\u8BE5 server \u5DF2\u8DF3\u8FC7` });
+    } else if (!isValidUrl(raw.url)) {
+      issues.push({ path: `${at}.url`, message: `\u4E0D\u662F\u5408\u6CD5\u7684 URL\uFF1A${raw.url}\uFF0C\u8BE5 server \u5DF2\u8DF3\u8FC7` });
+    }
+  }
+  if (issues.length > 0) return { config: null, issues };
+  const streamable = raw.streamable ?? transport === "http";
+  return {
+    config: {
+      name,
+      transport,
+      command: raw.command,
+      args: raw.args,
+      url: raw.url,
+      streamable,
+      headers: raw.headers,
+      env: raw.env,
+      timeout: raw.timeout,
+      connectTimeout: raw.connectTimeout ?? raw.connect_timeout,
+      keepaliveInterval: raw.keepaliveInterval ?? raw.keepalive_interval,
+      idleTimeoutSeconds: raw.idleTimeoutSeconds ?? raw.idle_timeout_seconds,
+      maxLifetimeSeconds: raw.maxLifetimeSeconds ?? raw.max_lifetime_seconds,
+      supportsParallel: raw.supportsParallel ?? raw.supports_parallel,
+      skipPreflight: raw.skipPreflight ?? raw.skip_preflight,
+      oauth: raw.oauth
+    },
+    issues
+  };
+}
+function unknownKeyIssues(value, at) {
+  if (typeof value !== "object" || value === null) return [];
+  return Object.keys(value).filter((k) => !KNOWN_KEYS.has(k)).map((k) => ({ path: `${at}.${k}`, message: "\u672A\u77E5\u5B57\u6BB5\uFF0C\u5DF2\u5FFD\u7565\uFF08\u62FC\u5199\u9519\u4E86\uFF1F\uFF09" }));
+}
+function isValidUrl(url) {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function prefix(issues, at) {
+  return issues.map((i) => ({
+    path: i.path === "(root)" ? at : `${at}.${i.path}`,
+    message: i.message
+  }));
+}
+
+// src/registry.ts
+var McpRegistry = class {
+  clients = /* @__PURE__ */ new Map();
+  cache;
+  authStore;
+  /**
+   * 某个 server 的工具表变了（收到 `notifications/tools/list_changed`）。
+   *
+   * registry 这层只负责把缓存失效掉并转发这个信号 —— **真正的热更新做不到**：
+   * `AgentLoop` 的工具集是构造参数，一次性传进去的，没有「运行中换一套工具」
+   * 的入口。要做需要先给 loop 引入 `ToolProvider` 接口，那是另一个方案的事，
+   * 本方案明确不碰 loop.ts。当前的效果是：下一次 `getAllTools()` / `refresh()`
+   * 能拿到新工具表，正在跑的那一轮不受影响。
+   */
+  onToolsChanged;
+  constructor(options = {}) {
+    const cacheFile = options.cacheFile !== void 0 ? options.cacheFile : mcpSchemaCachePath(options.homeDir);
+    this.cache = new McpSchemaCache(cacheFile);
+    this.authStore = options.authStore ?? new McpAuthStore(void 0, options.homeDir);
+  }
+  /**
+   * 从配置文件加载所有 MCP servers。
+   *
+   * 返回值带 `issues`：以前是 `catch { return [] }`，mcp.json 写错一个字符
+   * 用户只会发现「MCP 没了」，看不到任何提示。调用方**必须**把 issues
+   * 写进 diagnostics（见 runtime/tools.ts）。
+   */
+  loadFromConfig(configPath) {
+    const path = configPath ?? mcpConfigPath();
+    if (!existsSync2(path)) return { servers: [], issues: [] };
+    let raw;
+    try {
+      raw = readFileSync3(path, "utf-8");
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      return { servers: [], issues: [{ path, message: `\u8BFB\u53D6\u5931\u8D25\uFF1A${detail}` }] };
+    }
+    return parseMcpConfig(raw, path);
+  }
+  /**
+   * 连接所有已配置的 servers。
+   *
+   * @param source 这一批是谁带进来的（方案 44 PR-2）。**由调用方说了算，不从
+   *   `configs` 里读** —— 判据在 `McpClient.source` 上：`McpServerConfig` 是
+   *   用户手写文件解析出来的形状，来源要是它的一个字段，用户就能给自己那台
+   *   贴上宿主的标。缺省 `'user'`，于是老调用点（`epoch mcp` 那几条、用例）
+   *   一个字都不用改
+   *
+   * ⚠️ **可以调多次（两批 server 各一发），但名字必须在批与批之间唯一** ——
+   * `clients` 是一张按名字索引的表，重名的后一发会把前一发整个顶掉，而这里
+   * 拿不到诊断口说不出这件事。去重归调用方，`runtime/src/tools.ts` 的
+   * `registerMcpTools` 就是这么做的（用户那批先到、宿主重名的那台被跳过并报一条）。
+   */
+  async connectAll(configs, source = "user") {
+    const promises = configs.map(async (cfg) => {
+      await this.clients.get(cfg.name)?.disconnect();
+      const client = new McpClient(cfg, this.cache, this.authStore, source);
+      client.onToolsChanged = () => this.onToolsChanged?.(cfg.name);
+      this.clients.set(cfg.name, client);
+      try {
+        await client.connect();
+        return client.status;
+      } catch {
+        return client.status;
+      }
+    });
+    return Promise.all(promises);
+  }
+  /**
+   * 获取所有 MCP 工具（扁平化）。
+   *
+   * schema 走缓存，第二次调用不再打网络；工具本身每次重建
+   * （execute 闭包要绑到当前的 client 实例上，重连后不能还指向旧连接）。
+   */
+  async getAllTools() {
+    const allTools = [];
+    for (const [name, client] of this.clients) {
+      const schemas = await client.getToolSchemas();
+      allTools.push(...toEpochTools(name, schemas, (tool, args) => client.callTool(tool, args)));
+      allTools.push(...createResourceTools(name, () => client.raw));
+    }
+    return allTools;
+  }
+  /**
+   * 丢掉 schema 缓存后重新取一遍工具表。
+   *
+   * 给 `onToolsChanged` 的消费方用：收到通知 → `refresh()` → 拿到新工具表。
+   * 不传 name 就刷所有 server。
+   */
+  async refresh(name) {
+    this.cache.invalidate(name);
+    return this.getAllTools();
+  }
+  /**
+   * 列出某个 server 的 prompts。
+   *
+   * **prompts 不包成工具**，与 resources 的处理刻意不同：MCP 规范把 prompts
+   * 定义成 user-controlled（用户主动挑一个模板来用），tools 才是 model-controlled。
+   * gemini 也是这么分的 —— 它把 prompts 注册成斜杠命令（`PromptRegistry`），
+   * 不给模型。所以这里只提供查询 API，暴露方式交给 CLI/TUI。
+   */
+  async listPrompts(name) {
+    const client = this.requireClient(name);
+    return client.raw ? listPrompts(client.raw) : [];
+  }
+  /** 取一个 prompt 渲染后的文本 */
+  async getPrompt(name, promptName, args = {}) {
+    const client = this.requireClient(name);
+    if (!client.raw) throw new Error(`MCP server "${name}" \u5F53\u524D\u672A\u8FDE\u63A5`);
+    return getPromptText(client.raw, promptName, args);
+  }
+  /** 各 server 的登录态。纯读本地凭据文件，不打网络 */
+  getAuthStatus() {
+    return [...this.clients.values()].map((c) => mcpAuthStatus(c.serverConfig, this.authStore));
+  }
+  /** 凭据存储。`epoch mcp login/logout` 要用同一份，否则缓存不一致 */
+  get auth() {
+    return this.authStore;
+  }
+  /** 重连指定 server。工具表可能已变，顺带失效它的 schema 缓存 */
+  async reconnect(name) {
+    const client = this.requireClient(name);
+    this.cache.invalidate(name);
+    await client.disconnect();
+    await client.connect();
+    return client.status;
+  }
+  /**
+   * 显式失效 schema 缓存，不传 name 清全部。
+   *
+   * 给 `epoch mcp reconnect` 和将来的 `notifications/tools/list_changed` 用。
+   */
+  invalidateSchemaCache(name) {
+    this.cache.invalidate(name);
+  }
+  /**
+   * 断开**一台**并把它从表里删掉。返回 false 表示本来就没有这一台。
+   *
+   * ## 为什么在 `disconnectAll()` 之外单开这一个（2026-08-18）
+   *
+   * 在这之前，「让一台 server 在这个进程里消失」**做不到** —— 只能把所有连接一起
+   * 断掉。而 `mcp.json` 的一次编辑真的会删掉一台（runtime 的 `applyMcpConfig`），
+   * 那时全断再全连是错的：宿主注入的和插件带来的那两批也会被连带断开，而它们
+   * 一个字节都不在这份文件里。
+   *
+   * ⚠️ **它连带失效 schema 缓存**：那台下次要是又被配回来，缓存里躺着的是上一份
+   * 工具表。同 `reconnect()` 里那一下，理由逐字相同。
+   *
+   * ⚠️ **工具表不在这一层清**。这里只管连接；把 `mcp:<名字>` 那一组工具从
+   * `ToolRegistry` 里摘掉是装配层的事（`ToolSync.replace`，判据在 runtime 的
+   * `ToolSync` 上：三条路必须排同一条队）。少了那一下的表现是**工具表里留着一批
+   * 指向已断连接的工具**，模型下一轮照着调，报一个它读不懂的错。
+   */
+  async disconnect(name) {
+    const client = this.clients.get(name);
+    if (!client) return false;
+    this.cache.invalidate(name);
+    await client.disconnect();
+    this.clients.delete(name);
+    return true;
+  }
+  /**
+   * 这台 server 在**这个进程里此刻按的是哪份配置**（2026-08-18）。
+   *
+   * 给「盘上那份和进程里这份差在哪」用（runtime 的 `applyMcpConfig` 拿它做 diff）。
+   * ⚠️ 真源必须是 client 手上那一份，**不能是调用方自己记的一份快照**：那份快照
+   * 会和这里分叉，而分叉的表现是「明明改了配置，应用之后说没动」。
+   */
+  configOf(name) {
+    return this.clients.get(name)?.serverConfig ?? null;
+  }
+  /** 断开所有连接 */
+  async disconnectAll() {
+    for (const client of this.clients.values()) {
+      await client.disconnect();
+    }
+    this.clients.clear();
+  }
+  /** 获取状态 */
+  getStatus(name) {
+    return this.clients.get(name)?.status ?? null;
+  }
+  getAllStatus() {
+    return [...this.clients.values()].map((c) => c.status);
+  }
+  requireClient(name) {
+    const client = this.clients.get(name);
+    if (!client) throw new Error(`MCP server "${name}" not found`);
+    return client;
+  }
+};
+export {
+  CALLBACK_TIMEOUT_MS,
+  McpAuthStore,
+  McpClient,
+  McpLoginRequiredError,
+  McpOAuthProvider,
+  McpRegistry,
+  McpSchemaCache,
+  REFRESH_SKEW_MS,
+  configFingerprint,
+  createResourceTools,
+  getPromptText,
+  isExpired,
+  listPrompts,
+  listResources,
+  loginToMcpServer,
+  logoutFromMcpServer,
+  mcpAuthStatus,
+  parseMcpConfig,
+  prefixedName,
+  readResourceText,
+  startCallbackServer,
+  toEpochTools
+};