agent.libx.js 0.93.17 → 0.93.19

package/dist/{mcp-DGWuuWJm.d.ts → mcp-C5GuDinb.d.ts}

@@ -55,18 +55,47 @@ interface MountedMcpLike {
         callTool(name: string, args: unknown): Promise<unknown>;
     };
 }
+/** A flattened catalog entry's origin: which server owns it + the un-prefixed raw tool name. */
+interface McpRoute {
+    server: string;
+    rawName: string;
+}
+/** Flatten servers' specs into one `mcp__<server>__<tool>` namespace + a display→origin map.
+ *  Sanitizing/truncating to provider name rules can MERGE distinct names (`a/b` & `a:b` → `a_b`),
+ *  so dedupe with a numeric suffix — a silent overwrite would orphan a tool. */
+declare function buildMcpCatalog(servers: {
+    name: string;
+    specs: McpToolSpec[];
+}[]): {
+    specs: McpToolSpec[];
+    routes: Map<string, McpRoute>;
+};
+/** Resolve a routed MCP call to its result. Throw to surface an error to the model. */
+type McpRouteResolver = (server: string, rawName: string, args: any) => Promise<unknown>;
 /**
  * Ergonomic deferred-mount over already-mounted MCP servers: flattens their specs into one
- * `mcp__<server>__<tool>` namespace (sanitized to provider name rules) and wires a single
- * `ToolSearch`/`McpCall` pair that routes each call to the owning server's RAW `callTool`
- * (so result normalization happens exactly once — double-normalizing corrupts image blocks).
- * Display names are `mcp__<server>__` prefixed, then deduped (sanitization can merge distinct
- * names) so every tool stays uniquely addressable and routed to its own client.
+ * `mcp__<server>__<tool>` namespace and wires a single `ToolSearch`/`McpCall` pair that routes
+ * each call to the owning server's RAW `callTool` (so result normalization happens exactly once —
+ * double-normalizing corrupts image blocks).
  */
 declare function makeMcpToolSearchFromMounted(mounted: MountedMcpLike[], options?: McpToolSearchOptions): {
     tools: AgentTool[];
     serverNames: string[];
     toolCount: number;
 };
+/**
+ * Lazy variant: same `ToolSearch`/`McpCall` surface, but the server isn't required to be connected.
+ * Each `McpCall` resolves the owning server from the catalog and `resolve(server, rawName, args)`
+ * connects-on-demand — so a turn that calls no MCP tool opens ZERO connections. Edge-safe: the
+ * caller (`mountMcpCatalog` in `mcp.client.ts`) supplies the node-side connect/pool logic.
+ */
+declare function makeLazyMcpToolSearch(servers: {
+    name: string;
+    specs: McpToolSpec[];
+}[], resolve: McpRouteResolver, options?: McpToolSearchOptions): {
+    tools: AgentTool[];
+    serverNames: string[];
+    toolCount: number;
+};
 
-export { type McpCall as M, type McpImage as a, type McpToolResult as b, type McpToolSearchOptions as c, type McpToolSpec as d, type MountedMcpLike as e, makeMcpToolSearchFromMounted as f, mcpToolToAgentTool as g, mcpToolsToAgentTools as h, makeMcpToolSearch as m };
+export { type McpCall as M, type McpImage as a, type McpRoute as b, type McpRouteResolver as c, type McpToolResult as d, type McpToolSearchOptions as e, type McpToolSpec as f, type MountedMcpLike as g, buildMcpCatalog as h, makeMcpToolSearch as i, makeMcpToolSearchFromMounted as j, mcpToolToAgentTool as k, mcpToolsToAgentTools as l, makeLazyMcpToolSearch as m };

package/dist/mcp.client.d.ts

@@ -1,4 +1,4 @@
-import { d as McpToolSpec, c as McpToolSearchOptions } from './mcp-DGWuuWJm.js';
+import { e as McpToolSearchOptions, f as McpToolSpec } from './mcp-C5GuDinb.js';
 import { A as AgentTool } from './tools-GPWp7oXq.js';
 import '@livx.cc/wcli/core';
 
@@ -116,21 +116,84 @@ interface MountedMcp {
 /** Connect one server, discover its tools, and adapt them to prefixed AgentTools (`mcp__<name>__`). */
 declare function mountMcpServer(name: string, cfg: McpServerConfig): Promise<MountedMcp>;
 /**
- * Mount every configured server. A server that fails (bad command, no handshake, timeout) is
- * logged and skipped — one broken server can never block the agent from starting.
+ * Mount every configured server in PARALLEL (one slow/dead server no longer serializes the rest);
+ * each may carry a `mountTimeoutMs` deadline. A server that fails is logged and skipped.
  */
-declare function mountMcpServers(servers?: Record<string, McpServerConfig>): Promise<MountedMcp[]>;
+declare function mountMcpServers(servers?: Record<string, McpServerConfig>, opts?: {
+    mountTimeoutMs?: number;
+}): Promise<MountedMcp[]>;
 /**
  * One-shot deferred MCP mount: connect every entry (failures dropped, never block startup) and
  * fold the survivors into a single `ToolSearch`/`McpCall` pair via `makeMcpToolSearchFromMounted`.
  * The node-only counterpart to that edge-safe helper — returns `mounted` too so callers can close
- * the clients on shutdown.
+ * the clients on shutdown. Eager: it connects all servers up front. For lazy connect + a cached
+ * catalog (zero connections on a turn that uses no MCP tool), use `mountMcpCatalog`.
  */
-declare function mountMcpDeferred(servers?: Record<string, McpServerConfig>, options?: McpToolSearchOptions): Promise<{
+declare function mountMcpDeferred(servers?: Record<string, McpServerConfig>, options?: McpToolSearchOptions & {
+    mountTimeoutMs?: number;
+}): Promise<{
     tools: AgentTool[];
     serverNames: string[];
     toolCount: number;
     mounted: MountedMcp[];
 }>;
+/** A persistent tool catalog: lets `mountMcpCatalog` build `ToolSearch` WITHOUT connecting when a
+ *  fresh entry exists. The lib defines the interface; the consumer supplies the store (RAM/disk).
+ *  Key = a hash of the server's resolved config (see `mcpConfigKey`). TTL/versioning is the store's. */
+interface McpCatalogStore {
+    get(key: string): McpToolSpec[] | null;
+    set(key: string, specs: McpToolSpec[]): void;
+}
+/** Stable cache key for a server config — command/args/cwd + env NAMES (not secret values), or
+ *  url + header names. Changing any of these invalidates the cached catalog; rotating a secret does not. */
+declare function mcpConfigKey(cfg: McpServerConfig): string;
+/** Default in-memory catalog: process-lifetime, hash-keyed, TTL-expiring (so a server that gains
+ *  tools is picked up after the TTL without a restart). Shared module singleton → cross-turn reuse. */
+declare class MemMcpCatalog implements McpCatalogStore {
+    private ttlMs;
+    private m;
+    constructor(ttlMs?: number);
+    get(key: string): McpToolSpec[] | null;
+    set(key: string, specs: McpToolSpec[]): void;
+}
+/** Opt-in warm pool: keeps stdio MCP clients connected across turns, reaping each after `ttlMs`
+ *  idle. Most stdio MCPs are per-turn by design, so this is off by default; HTTP servers are
+ *  stateless and never pooled. */
+declare class McpPool {
+    private ttlMs;
+    private warm;
+    constructor(ttlMs?: number);
+    get(key: string): McpClient | null;
+    put(key: string, client: McpClient): void;
+    private arm;
+    private evict;
+    closeAll(): Promise<void>;
+}
+interface McpCatalogOptions extends McpToolSearchOptions {
+    /** Where to read/write discovered specs. Default: a shared process-lifetime `MemMcpCatalog`. */
+    catalog?: McpCatalogStore;
+    /** Per-server deadline for the connect+list on a cache MISS. A hung server is skipped, not blocking. */
+    mountTimeoutMs?: number;
+    /** Opt-in: keep stdio clients warm across turns (see `McpPool`). HTTP servers are never pooled. */
+    keepWarm?: boolean;
+    /** Warm-client pool. Default: a shared process-lifetime `McpPool` (only used when `keepWarm`). */
+    pool?: McpPool;
+}
+/**
+ * Lazy + cached MCP mount. Builds the `ToolSearch`/`McpCall` pair from the CACHED catalog when one
+ * exists — connecting NOTHING. On a cache miss it connects once (parallel, deadline-bounded), lists,
+ * caches, then disconnects (or keeps warm if `keepWarm`). A server is connected only when one of its
+ * tools is actually invoked via `McpCall` (memoized per turn; reused from the warm pool if enabled).
+ *
+ * Per-turn cost: a turn using NO MCP tool → 0 connections; a turn using one → exactly one. Latency
+ * scales with tools-used, not servers-configured. Returns `connect`/`close` for explicit control.
+ */
+declare function mountMcpCatalog(servers?: Record<string, McpServerConfig>, opts?: McpCatalogOptions): Promise<{
+    tools: AgentTool[];
+    serverNames: string[];
+    toolCount: number;
+    connect(name: string): Promise<McpClient>;
+    close(): Promise<void>;
+}>;
 
-export { type HttpServerSpec, HttpTransport, McpAuthError, McpClient, type McpServerConfig, type McpTransport, type MountedMcp, type StdioServerSpec, StdioTransport, mountMcpDeferred, mountMcpServer, mountMcpServers };
+export { type HttpServerSpec, HttpTransport, McpAuthError, type McpCatalogOptions, type McpCatalogStore, McpClient, McpPool, type McpServerConfig, type McpTransport, MemMcpCatalog, type MountedMcp, type StdioServerSpec, StdioTransport, mcpConfigKey, mountMcpCatalog, mountMcpDeferred, mountMcpServer, mountMcpServers };

package/dist/mcp.client.js

@@ -1,5 +1,6 @@
 // src/mcp.client.ts
 import { spawn } from "child_process";
+import { createHash } from "crypto";
 
 // src/logging.ts
 import { log } from "libx.js/src/modules/log";
@@ -147,24 +148,36 @@ function makeMcpToolSearch(specs, callTool, options = {}) {
   };
   return [searchTool, callMcpTool];
 }
-function makeMcpToolSearchFromMounted(mounted, options) {
+function buildMcpCatalog(servers) {
   const specs = [];
-  const callMap = /* @__PURE__ */ new Map();
-  for (const m of mounted) {
+  const routes = /* @__PURE__ */ new Map();
+  for (const m of servers) {
     for (const s of m.specs) {
       const base = `mcp__${m.name}__${s.name}`.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128);
       let display = base;
-      for (let i = 2; callMap.has(display); i++) display = `${base.slice(0, 128 - String(i).length - 1)}_${i}`;
+      for (let i = 2; routes.has(display); i++) display = `${base.slice(0, 128 - String(i).length - 1)}_${i}`;
       specs.push({ name: display, description: s.description, inputSchema: s.inputSchema });
-      callMap.set(display, (_n, args) => m.client.callTool(s.name, args));
+      routes.set(display, { server: m.name, rawName: s.name });
     }
   }
+  return { specs, routes };
+}
+function searchOverCatalog(servers, specs, routes, resolve, options) {
   const tools = specs.length ? makeMcpToolSearch(specs, (name, args) => {
-    const call = callMap.get(name);
-    if (!call) throw new Error(`unknown MCP tool '${name}' \u2014 use ToolSearch to find valid names`);
-    return call(name, args ?? {});
+    const r = routes.get(name);
+    if (!r) throw new Error(`unknown MCP tool '${name}' \u2014 use ToolSearch to find valid names`);
+    return resolve(r.server, r.rawName, args ?? {});
   }, options) : [];
-  return { tools, serverNames: mounted.map((m) => m.name), toolCount: specs.length };
+  return { tools, serverNames: servers, toolCount: specs.length };
+}
+function makeMcpToolSearchFromMounted(mounted, options) {
+  const { specs, routes } = buildMcpCatalog(mounted);
+  const byName = new Map(mounted.map((m) => [m.name, m]));
+  return searchOverCatalog(mounted.map((m) => m.name), specs, routes, (server, rawName, args) => byName.get(server).client.callTool(rawName, args), options);
+}
+function makeLazyMcpToolSearch(servers, resolve, options) {
+  const { specs, routes } = buildMcpCatalog(servers);
+  return searchOverCatalog(servers.map((s) => s.name), specs, routes, resolve, options);
 }
 
 // src/mcp.client.ts
@@ -360,42 +373,210 @@ var McpClient = class {
     await this.transport.close();
   }
 };
-async function mountMcpServer(name, cfg) {
-  const transport = cfg.url ? new HttpTransport({ url: cfg.url, headers: cfg.headers, bearerToken: cfg.bearerToken, timeoutMs: cfg.timeoutMs }) : new StdioTransport({ command: cfg.command, args: cfg.args, env: cfg.env, cwd: cfg.cwd, timeoutMs: cfg.timeoutMs });
-  const client = new McpClient(transport);
-  const init = await client.connect();
-  const specs = await client.listTools();
-  const tools = mcpToolsToAgentTools(specs, (tool, a) => client.callTool(tool, a), `mcp__${name}__`);
-  return { name, client, tools, specs, serverInfo: init?.serverInfo };
+function buildTransport(cfg) {
+  return cfg.url ? new HttpTransport({ url: cfg.url, headers: cfg.headers, bearerToken: cfg.bearerToken, timeoutMs: cfg.timeoutMs }) : new StdioTransport({ command: cfg.command, args: cfg.args, env: cfg.env, cwd: cfg.cwd, timeoutMs: cfg.timeoutMs });
 }
-async function mountMcpServers(servers = {}) {
-  const out = [];
-  for (const [name, cfg] of Object.entries(servers)) {
-    if (!cfg || cfg.disabled) continue;
+function withTimeout(p, ms, label) {
+  if (!ms || ms <= 0) return p;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`MCP "${label}" mount exceeded ${ms}ms`)), ms);
+    timer.unref?.();
+    p.then((v) => {
+      clearTimeout(timer);
+      resolve(v);
+    }, (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+  });
+}
+async function mountWithDeadline(name, cfg, mountTimeoutMs) {
+  const client = new McpClient(buildTransport(cfg));
+  try {
+    return await withTimeout((async () => {
+      const init = await client.connect();
+      const specs = await client.listTools();
+      const tools = mcpToolsToAgentTools(specs, (tool, a) => client.callTool(tool, a), `mcp__${name}__`);
+      return { name, client, tools, specs, serverInfo: init?.serverInfo };
+    })(), mountTimeoutMs, name);
+  } catch (e) {
+    await client.close().catch((err) => log2.debug(`close after failed mount of "${name}": ${err}`));
+    throw e;
+  }
+}
+function mountMcpServer(name, cfg) {
+  return mountWithDeadline(name, cfg);
+}
+function validEntries(servers) {
+  return Object.entries(servers).filter(([name, cfg]) => {
+    if (!cfg || cfg.disabled) return false;
     if (!cfg.command && !cfg.url) {
       log2.warn(`MCP server "${name}" needs a command (stdio) or url (http) \u2014 skipping`);
-      continue;
+      return false;
     }
-    try {
-      const m = await mountMcpServer(name, cfg);
-      out.push(m);
-      log2.info(`MCP "${name}" mounted \u2014 ${m.tools.length} tool(s)${m.serverInfo?.name ? ` from ${m.serverInfo.name}` : ""}`);
-    } catch (e) {
-      if (e instanceof McpAuthError) log2.warn(`MCP "${name}" needs-auth: HTTP ${e.status} \u2014 set bearerToken or headers in its config; skipping`);
-      else log2.error(`MCP server "${name}" failed to mount: ${e?.message ?? e}`);
-    }
-  }
+    return true;
+  });
+}
+function logMountFailure(name, e) {
+  if (e instanceof McpAuthError) log2.warn(`MCP "${name}" needs-auth: HTTP ${e.status} \u2014 set bearerToken or headers in its config; skipping`);
+  else log2.error(`MCP server "${name}" failed to mount: ${e?.message ?? e}`);
+}
+async function mountMcpServers(servers = {}, opts = {}) {
+  const entries = validEntries(servers);
+  const settled = await Promise.allSettled(entries.map(([name, cfg]) => mountWithDeadline(name, cfg, opts.mountTimeoutMs)));
+  const out = [];
+  settled.forEach((r, i) => {
+    const name = entries[i][0];
+    if (r.status === "fulfilled") {
+      out.push(r.value);
+      log2.info(`MCP "${name}" mounted \u2014 ${r.value.tools.length} tool(s)${r.value.serverInfo?.name ? ` from ${r.value.serverInfo.name}` : ""}`);
+    } else logMountFailure(name, r.reason);
+  });
   return out;
 }
 async function mountMcpDeferred(servers = {}, options) {
-  const mounted = await mountMcpServers(servers);
+  const mounted = await mountMcpServers(servers, { mountTimeoutMs: options?.mountTimeoutMs });
   return { ...makeMcpToolSearchFromMounted(mounted, options), mounted };
 }
+function mcpConfigKey(cfg) {
+  const parts = cfg.url ? ["http", cfg.url, ...Object.keys(cfg.headers ?? {}).sort()] : ["stdio", cfg.command ?? "", ...cfg.args ?? [], cfg.cwd ?? "", ...Object.keys(cfg.env ?? {}).sort()];
+  return createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, 16);
+}
+var MemMcpCatalog = class {
+  constructor(ttlMs = 5 * 6e4) {
+    this.ttlMs = ttlMs;
+  }
+  ttlMs;
+  m = /* @__PURE__ */ new Map();
+  get(key) {
+    const e = this.m.get(key);
+    if (!e) return null;
+    if (Date.now() > e.exp) {
+      this.m.delete(key);
+      return null;
+    }
+    return e.specs;
+  }
+  set(key, specs) {
+    this.m.set(key, { specs, exp: Date.now() + this.ttlMs });
+  }
+};
+var McpPool = class {
+  constructor(ttlMs = 5 * 6e4) {
+    this.ttlMs = ttlMs;
+  }
+  ttlMs;
+  warm = /* @__PURE__ */ new Map();
+  get(key) {
+    const e = this.warm.get(key);
+    if (!e) return null;
+    this.arm(key, e);
+    return e.client;
+  }
+  put(key, client) {
+    const prev = this.warm.get(key);
+    if (prev) {
+      clearTimeout(prev.timer);
+      if (prev.client !== client) void prev.client.close().catch((err) => log2.debug(`warm-pool replace close failed: ${err}`));
+    }
+    const e = { client, timer: void 0 };
+    this.warm.set(key, e);
+    this.arm(key, e);
+  }
+  arm(key, e) {
+    clearTimeout(e.timer);
+    e.timer = setTimeout(() => {
+      void this.evict(key);
+    }, this.ttlMs);
+    e.timer.unref?.();
+  }
+  async evict(key) {
+    const e = this.warm.get(key);
+    if (!e) return;
+    this.warm.delete(key);
+    await e.client.close().catch((err) => log2.debug(`warm-pool evict close failed: ${err}`));
+  }
+  async closeAll() {
+    for (const e of this.warm.values()) {
+      clearTimeout(e.timer);
+      await e.client.close().catch(() => {
+      });
+    }
+    this.warm.clear();
+  }
+};
+var defaultCatalog = new MemMcpCatalog();
+var defaultPool = new McpPool();
+async function mountMcpCatalog(servers = {}, opts = {}) {
+  const catalog = opts.catalog ?? defaultCatalog;
+  const pool = opts.pool ?? defaultPool;
+  const discovered = (await Promise.all(validEntries(servers).map(async ([name, cfg]) => {
+    const key = mcpConfigKey(cfg);
+    const cached = catalog.get(key);
+    if (cached) return { name, cfg, key, specs: cached };
+    const client = new McpClient(buildTransport(cfg));
+    try {
+      const specs = await withTimeout((async () => {
+        await client.connect();
+        return client.listTools();
+      })(), opts.mountTimeoutMs, name);
+      catalog.set(key, specs);
+      if (opts.keepWarm && !cfg.url) pool.put(key, client);
+      else await client.close().catch(() => {
+      });
+      return { name, cfg, key, specs };
+    } catch (e) {
+      await client.close().catch(() => {
+      });
+      logMountFailure(name, e);
+      return null;
+    }
+  }))).filter(Boolean);
+  const byName = new Map(discovered.map((d) => [d.name, d]));
+  const inflight = /* @__PURE__ */ new Map();
+  const live = [];
+  const connect = (name) => {
+    let p = inflight.get(name);
+    if (p) return p;
+    p = (async () => {
+      const d = byName.get(name);
+      if (!d) throw new Error(`MCP server '${name}' is not in the catalog`);
+      const warmable = opts.keepWarm && !d.cfg.url;
+      if (warmable) {
+        const w = pool.get(d.key);
+        if (w) return w;
+      }
+      const client = new McpClient(buildTransport(d.cfg));
+      await client.connect();
+      if (warmable) pool.put(d.key, client);
+      else live.push(client);
+      return client;
+    })();
+    inflight.set(name, p);
+    return p;
+  };
+  const search = makeLazyMcpToolSearch(
+    discovered.map((d) => ({ name: d.name, specs: d.specs })),
+    async (server, rawName, args) => (await connect(server)).callTool(rawName, args),
+    opts
+  );
+  const close = async () => {
+    for (const c of live) await c.close().catch(() => {
+    });
+    live.length = 0;
+    inflight.clear();
+  };
+  return { ...search, connect, close };
+}
 export {
   HttpTransport,
   McpAuthError,
   McpClient,
+  McpPool,
+  MemMcpCatalog,
   StdioTransport,
+  mcpConfigKey,
+  mountMcpCatalog,
   mountMcpDeferred,
   mountMcpServer,
   mountMcpServers