maestro-agent-sdk 0.1.0

package/dist/mcp/client.js

@@ -0,0 +1,176 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { logger } from "../platform/logger.js";
+export class MaestroMcpClient {
+    name;
+    spec;
+    transportOverride;
+    client;
+    transport;
+    started = false;
+    constructor(name, spec, 
+    /**
+     * Test-only override: when supplied, `start()` connects to this transport
+     * instead of building one from `spec`. Production callers pass two args.
+     */
+    transportOverride) {
+        this.name = name;
+        this.spec = spec;
+        this.transportOverride = transportOverride;
+        this.client = new Client({ name: "clawgram-maestro", version: "0.1.0" }, { capabilities: {} });
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.transport = this.transportOverride ?? this.buildTransport();
+        await this.client.connect(this.transport);
+        this.started = true;
+    }
+    /** Fetch `tools/list` and convert to Maestro/Anthropic shape with prefixed names. */
+    async listTools() {
+        const res = await this.client.listTools();
+        const tools = Array.isArray(res.tools) ? res.tools : [];
+        const out = [];
+        for (const t of tools) {
+            const original = String(t.name ?? "");
+            if (!original)
+                continue;
+            const publicName = makePublicName(this.name, original);
+            out.push({
+                publicName,
+                originalName: original,
+                serverName: this.name,
+                schema: {
+                    name: publicName,
+                    description: typeof t.description === "string" ? t.description : "",
+                    input_schema: normalizeInputSchema(t.inputSchema),
+                },
+            });
+        }
+        return out;
+    }
+    /**
+     * Invoke an MCP tool. Returns the FULL rendered payload string for the
+     * Maestro tool_result block — the model needs to see complete tool output on
+     * the next turn, matching how claude/codex SDKs feed full payloads back.
+     * The 200-char cap that claude-provider.ts:373 and codex-provider.ts apply
+     * is a UnifiedEvent display concern only; Maestro enforces it inside the
+     * agent loop (`loop.ts:TOOL_RESULT_PREVIEW_MAX`) at the emit site, not here.
+     *
+     * Optional `abortSignal` propagates the Maestro-level abort down into the
+     * SDK's JSON-RPC request, so an in-flight `tools/call` is cancelled instead
+     * of left blocking on a dead server.
+     */
+    async callTool(originalName, input, abortSignal) {
+        const res = await this.client.callTool({ name: originalName, arguments: input }, undefined, abortSignal ? { signal: abortSignal } : undefined);
+        return renderCallResult(res);
+    }
+    async close() {
+        if (!this.started)
+            return;
+        this.started = false;
+        try {
+            await this.client.close();
+        }
+        catch (err) {
+            logger.warn({ err, server: this.name }, "maestro mcp client: close failed (continuing)");
+        }
+    }
+    buildTransport() {
+        if (this.spec.type === "sse") {
+            if (!this.spec.url) {
+                throw new Error(`Maestro MCP '${this.name}': sse spec missing url`);
+            }
+            // Use the URL exactly as supplied — same posture as claude/codex SDKs.
+            // We used to rewrite `localhost` → `127.0.0.1` here as a workaround for
+            // a playwright-mcp that bound IPv4-only while Node `eventsource`
+            // resolved `::1` first; the playwright spawn args now pin `--host
+            // 127.0.0.1` so every transport reaches the same address family
+            // without per-client hacks, and a future remote-MCP URL won't get
+            // silently rewritten under us.
+            return new SSEClientTransport(new URL(this.spec.url));
+        }
+        if (!this.spec.command) {
+            throw new Error(`Maestro MCP '${this.name}': no command and no sse url`);
+        }
+        return new StdioClientTransport({
+            command: this.spec.command,
+            args: this.spec.args ?? [],
+            env: filteredEnv(this.spec.env),
+            stderr: "inherit",
+        });
+    }
+}
+/**
+ * Public MCP tool name. Mirrors Claude SDK's `mcp__<server>__<tool>` convention
+ * so the model sees consistent names across providers in the same topic.
+ */
+export function makePublicName(server, tool) {
+    return `mcp__${sanitizeName(server)}__${sanitizeName(tool)}`;
+}
+/** Allowed by Anthropic tool name regex: `^[a-zA-Z0-9_-]+$`. */
+function sanitizeName(s) {
+    return s.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function normalizeInputSchema(s) {
+    if (s && typeof s === "object") {
+        const obj = s;
+        const props = obj.properties && typeof obj.properties === "object"
+            ? obj.properties
+            : {};
+        const required = Array.isArray(obj.required) ? obj.required : undefined;
+        return {
+            type: "object",
+            properties: props,
+            ...(required ? { required } : {}),
+        };
+    }
+    return { type: "object", properties: {} };
+}
+/**
+ * Render an MCP `callTool` result into a full payload string for the Maestro
+ * tool_result block. No length cap here — the model must see the complete
+ * output to act on it (e.g. accessibility trees from playwright, OCR text).
+ * The 200-char display cap lives in `loop.ts` where the UnifiedEvent is
+ * surfaced, mirroring claude/codex (their SDK feeds full payloads to the
+ * model and only the UnifiedEvent emit path truncates for downstream
+ * telegram-render layout).
+ */
+function renderCallResult(res) {
+    const r = res;
+    const blocks = Array.isArray(r.content) ? r.content : [];
+    const text = blocks
+        .map((b) => {
+        if (b && typeof b === "object" && "type" in b && b.type === "text") {
+            const t = b.text;
+            return typeof t === "string" ? t : "";
+        }
+        return "";
+    })
+        .filter(Boolean)
+        .join("\n");
+    if (r.isError) {
+        return JSON.stringify({ error: text || "mcp tool error" });
+    }
+    if (text)
+        return text;
+    // Non-text content (image / structured): pass JSON dump so the model still has signal.
+    return JSON.stringify(r.content ?? null);
+}
+/** StdioClientTransport requires `Record<string, string>`; drop undefined values from process.env. */
+function filteredEnv(extra) {
+    const out = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (typeof v === "string")
+            out[k] = v;
+    }
+    if (extra) {
+        for (const [k, v] of Object.entries(extra)) {
+            if (typeof v === "string")
+                out[k] = v;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=client.js.map

package/dist/mcp/client.js.map

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

package/dist/mcp/pool-cache.d.ts

@@ -0,0 +1,103 @@
+import { MaestroMcpClient, type MaestroMcpServerSpec } from "../mcp/client.js";
+/**
+ * MCP client cache — process-wide pool of started `MaestroMcpClient`s keyed on
+ * (userId, session, groupId, agentKind, serverName, specHash).
+ *
+ * Motivation: every `maestroProvider` invocation previously called
+ * `startMcpPool` which spawned every configured MCP server fresh. Most servers
+ * are stdio bun subprocesses (send-file, ocr, wiki, session-comm, etc.) and
+ * each one costs ~80–200ms to spawn + handshake. With 8–10 servers per turn
+ * that's ~1s of pure spawn latency before the model even starts thinking.
+ *
+ * Phase 1 caching reuses the same `MaestroMcpClient` across turns within the
+ * same session — the MCP `Client` connection stays open, only the
+ * `registerMcpTools` wiring is rebuilt per turn (cheap, just a Map fill).
+ *
+ * Lifecycle invariants:
+ *   - One physical `MaestroMcpClient.start()` per cache key.
+ *   - Per-turn callers acquire via `getOrStartClient` (refcount++) and release
+ *     via `releaseClient` (refcount--). Eviction never closes a client whose
+ *     refcount > 0 — an abort that closes the pool only drops the lease.
+ *   - Idle TTL (`MAESTRO_MCP_POOL_IDLE_TTL_MS`) and LRU cap
+ *     (`MAESTRO_MCP_POOL_MAX`) evict clients whose refcount is 0.
+ *   - One process-wide `beforeExit`/`SIGINT`/`SIGTERM` handler closes every
+ *     cached client on graceful shutdown so MCP subprocesses don't outlive us.
+ *
+ * Negative caching is off in Phase 1 — a failed `start()` is not cached, so
+ * the next turn retries fresh. Means a server that's transiently down doesn't
+ * stay marked-bad past one turn, at the cost of paying its spawn-fail latency
+ * again next time.
+ */
+/** Idle TTL — clients with refcount 0 evicted after this many ms. */
+export declare const MAESTRO_MCP_POOL_IDLE_TTL_MS: number;
+/** Hard cap on cached clients. LRU eviction past this. */
+export declare const MAESTRO_MCP_POOL_MAX: number;
+/** Context that scopes a cache key. Two turns with the same context + server
+ *  + spec share the same client; otherwise they get separate slots. */
+export interface CacheKeyContext {
+    /** Telegram user id as string. Different users never share clients. */
+    userId?: string;
+    /** Topic/session name. */
+    session?: string;
+    /** Forum group id (manager-scope servers vary by group). */
+    groupId?: number;
+    /** Agent kind — currently always "maestro" but reserved so a future
+     *  cross-agent MCP cache won't collide. */
+    agentKind?: string;
+}
+/** Client factory — overridable in tests to inject an InMemoryTransport-backed
+ *  `MaestroMcpClient` instead of spawning a real stdio/sse subprocess. */
+type ClientFactory = (name: string, spec: MaestroMcpServerSpec) => MaestroMcpClient;
+/**
+ * Build a stable hash of a server spec. We hash command + args + transport
+ * url + sorted env keys (values excluded — they often contain per-turn
+ * variables like depth, group ids; would defeat caching).
+ *
+ * Two callers with the same hash get the same client back — caller is
+ * responsible for ensuring that's semantically correct (i.e. they pass the
+ * same `CacheKeyContext` if their spec encodes the context).
+ */
+export declare function hashSpec(spec: MaestroMcpServerSpec): string;
+/**
+ * Acquire a started `MaestroMcpClient` for (ctx, serverName, spec). If a fresh
+ * spawn is needed it happens inside this call; the returned client is already
+ * past `start()`.
+ *
+ * Refcount semantics: every successful call increments refcount by 1 and the
+ * caller MUST pair it with `releaseClient` (typically in a finally block, or
+ * inside the pool object's close()).
+ */
+export declare function getOrStartClient(ctx: CacheKeyContext, serverName: string, spec: MaestroMcpServerSpec): Promise<MaestroMcpClient>;
+/**
+ * Decrement refcount on a previously-acquired client. Does not close anything;
+ * the sweeper / cap-evictor closes idle clients later.
+ *
+ * `clientRef` should be the exact instance returned by `getOrStartClient`.
+ * Releasing a client we don't track is a no-op + warn (defensive against
+ * double-release).
+ */
+export declare function releaseClient(clientRef: MaestroMcpClient): void;
+/** Run one idle-TTL sweep. Exported for tests. */
+export declare function sweepIdle(now?: number): Promise<number>;
+/** Stop the sweeper. Used by tests to reset state. */
+export declare function stopSweeper(): void;
+/**
+ * Close every cached client. Awaits up to `timeoutMs` total (3s default).
+ * Safe to call multiple times — entries are removed as they close.
+ */
+export declare function closeAll(timeoutMs?: number): Promise<void>;
+/** Test-only: drop all entries without closing. Used to reset state between
+ *  test runs that share the module singleton. */
+export declare function __resetForTests(): void;
+/** Test-only: swap the client factory. Used to inject a fake client backed by
+ *  `InMemoryTransport` so tests don't spawn real MCP subprocesses. */
+export declare function __setClientFactoryForTests(factory: ClientFactory): void;
+/** Test-only: read cache size. */
+export declare function __cacheSize(): number;
+/** Test-only: read entry by key parts. */
+export declare function __getEntry(ctx: CacheKeyContext, serverName: string, spec: MaestroMcpServerSpec): {
+    refcount: number;
+    lastUsed: number;
+} | null;
+export {};
+//# sourceMappingURL=pool-cache.d.ts.map

package/dist/mcp/pool-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-cache.d.ts","sourceRoot":"","sources":["../../src/mcp/pool-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAI3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,qEAAqE;AACrE,eAAO,MAAM,4BAA4B,QAGxC,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,QAAgE,CAAC;AAElG;uEACuE;AACvE,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;+CAC2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAcD;0EAC0E;AAC1E,KAAK,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,KAAK,gBAAgB,CAAC;AAGpF;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAW3D;AAaD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,eAAe,EACpB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAyC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAc/D;AA2BD,kDAAkD;AAClD,wBAAsB,SAAS,CAAC,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CASzE;AAeD,sDAAsD;AACtD,wBAAgB,WAAW,IAAI,IAAI,CAKlC;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB9D;AAYD;iDACiD;AACjD,wBAAgB,eAAe,IAAI,IAAI,CAKtC;AAED;sEACsE;AACtE,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAEvE;AAED,kCAAkC;AAClC,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,0CAA0C;AAC1C,wBAAgB,UAAU,CACxB,GAAG,EAAE,eAAe,EACpB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,oBAAoB,GACzB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAG/C"}

package/dist/mcp/pool-cache.js

@@ -0,0 +1,249 @@
+import { createHash } from "node:crypto";
+import { MaestroMcpClient } from "../mcp/client.js";
+import { onShutdown } from "../platform/lifecycle.js";
+import { logger } from "../platform/logger.js";
+/**
+ * MCP client cache — process-wide pool of started `MaestroMcpClient`s keyed on
+ * (userId, session, groupId, agentKind, serverName, specHash).
+ *
+ * Motivation: every `maestroProvider` invocation previously called
+ * `startMcpPool` which spawned every configured MCP server fresh. Most servers
+ * are stdio bun subprocesses (send-file, ocr, wiki, session-comm, etc.) and
+ * each one costs ~80–200ms to spawn + handshake. With 8–10 servers per turn
+ * that's ~1s of pure spawn latency before the model even starts thinking.
+ *
+ * Phase 1 caching reuses the same `MaestroMcpClient` across turns within the
+ * same session — the MCP `Client` connection stays open, only the
+ * `registerMcpTools` wiring is rebuilt per turn (cheap, just a Map fill).
+ *
+ * Lifecycle invariants:
+ *   - One physical `MaestroMcpClient.start()` per cache key.
+ *   - Per-turn callers acquire via `getOrStartClient` (refcount++) and release
+ *     via `releaseClient` (refcount--). Eviction never closes a client whose
+ *     refcount > 0 — an abort that closes the pool only drops the lease.
+ *   - Idle TTL (`MAESTRO_MCP_POOL_IDLE_TTL_MS`) and LRU cap
+ *     (`MAESTRO_MCP_POOL_MAX`) evict clients whose refcount is 0.
+ *   - One process-wide `beforeExit`/`SIGINT`/`SIGTERM` handler closes every
+ *     cached client on graceful shutdown so MCP subprocesses don't outlive us.
+ *
+ * Negative caching is off in Phase 1 — a failed `start()` is not cached, so
+ * the next turn retries fresh. Means a server that's transiently down doesn't
+ * stay marked-bad past one turn, at the cost of paying its spawn-fail latency
+ * again next time.
+ */
+/** Idle TTL — clients with refcount 0 evicted after this many ms. */
+export const MAESTRO_MCP_POOL_IDLE_TTL_MS = Number.parseInt(process.env.MAESTRO_MCP_POOL_IDLE_TTL_MS ?? "300000", 10);
+/** Hard cap on cached clients. LRU eviction past this. */
+export const MAESTRO_MCP_POOL_MAX = Number.parseInt(process.env.MAESTRO_MCP_POOL_MAX ?? "16", 10);
+const cache = new Map();
+let sweeperHandle = null;
+let shutdownRegistered = false;
+let clientFactory = (name, spec) => new MaestroMcpClient(name, spec);
+/**
+ * Build a stable hash of a server spec. We hash command + args + transport
+ * url + sorted env keys (values excluded — they often contain per-turn
+ * variables like depth, group ids; would defeat caching).
+ *
+ * Two callers with the same hash get the same client back — caller is
+ * responsible for ensuring that's semantically correct (i.e. they pass the
+ * same `CacheKeyContext` if their spec encodes the context).
+ */
+export function hashSpec(spec) {
+    const normalized = {
+        command: spec.command ?? null,
+        args: spec.args ?? [],
+        type: spec.type ?? null,
+        url: spec.url ?? null,
+        // env values vary per turn (e.g. session-comm --depth). Hash only the keys
+        // so an env-mutating caller still gets a cache hit on the same shape.
+        envKeys: spec.env ? Object.keys(spec.env).sort() : [],
+    };
+    return createHash("sha256").update(JSON.stringify(normalized)).digest("hex").slice(0, 16);
+}
+function makeCacheKey(ctx, serverName, specHash) {
+    return [
+        ctx.userId ?? "_",
+        ctx.session ?? "_",
+        ctx.groupId ?? "_",
+        ctx.agentKind ?? "maestro",
+        serverName,
+        specHash,
+    ].join("::");
+}
+/**
+ * Acquire a started `MaestroMcpClient` for (ctx, serverName, spec). If a fresh
+ * spawn is needed it happens inside this call; the returned client is already
+ * past `start()`.
+ *
+ * Refcount semantics: every successful call increments refcount by 1 and the
+ * caller MUST pair it with `releaseClient` (typically in a finally block, or
+ * inside the pool object's close()).
+ */
+export async function getOrStartClient(ctx, serverName, spec) {
+    ensureSweeper();
+    ensureShutdownHook();
+    const specHash = hashSpec(spec);
+    const key = makeCacheKey(ctx, serverName, specHash);
+    const existing = cache.get(key);
+    if (existing) {
+        existing.refcount++;
+        existing.lastUsed = Date.now();
+        return existing.client;
+    }
+    // Fresh spawn. We intentionally don't pre-register the entry — if start()
+    // throws we don't want a dead entry sitting in cache (negative caching off).
+    const client = clientFactory(serverName, spec);
+    await client.start();
+    // Race check: a concurrent acquire of the same key could have raced ahead
+    // while we were in `await client.start()`. If so, drop ours and use theirs.
+    const racer = cache.get(key);
+    if (racer) {
+        await client.close().catch(() => { });
+        racer.refcount++;
+        racer.lastUsed = Date.now();
+        return racer.client;
+    }
+    const entry = {
+        key,
+        client,
+        refcount: 1,
+        lastUsed: Date.now(),
+        serverName,
+    };
+    cache.set(key, entry);
+    // Enforce hard cap by evicting LRU idle entries.
+    evictOverCap();
+    return client;
+}
+/**
+ * Decrement refcount on a previously-acquired client. Does not close anything;
+ * the sweeper / cap-evictor closes idle clients later.
+ *
+ * `clientRef` should be the exact instance returned by `getOrStartClient`.
+ * Releasing a client we don't track is a no-op + warn (defensive against
+ * double-release).
+ */
+export function releaseClient(clientRef) {
+    // Linear scan — cache is small (≤ MAESTRO_MCP_POOL_MAX). Avoids a second
+    // index keyed by client identity.
+    for (const entry of cache.values()) {
+        if (entry.client === clientRef) {
+            if (entry.refcount > 0)
+                entry.refcount--;
+            entry.lastUsed = Date.now();
+            return;
+        }
+    }
+    logger.warn({ server: clientRef.name }, "maestro mcp pool-cache: release of unknown client (double-release?)");
+}
+/** Force-evict and close a single entry. Used by the sweeper / cap evictor /
+ *  shutdown hook. Does nothing if the client is in use (refcount > 0). */
+async function tryEvict(entry) {
+    if (entry.refcount > 0)
+        return false;
+    cache.delete(entry.key);
+    try {
+        await entry.client.close();
+    }
+    catch (err) {
+        logger.warn({ err, server: entry.serverName }, "maestro mcp pool-cache: close on evict failed");
+    }
+    return true;
+}
+function evictOverCap() {
+    if (cache.size <= MAESTRO_MCP_POOL_MAX)
+        return;
+    const idle = [...cache.values()]
+        .filter((e) => e.refcount === 0)
+        .sort((a, b) => a.lastUsed - b.lastUsed);
+    for (const e of idle) {
+        if (cache.size <= MAESTRO_MCP_POOL_MAX)
+            return;
+        // Fire-and-forget close — the entry is already detached from cache.
+        void tryEvict(e);
+    }
+}
+/** Run one idle-TTL sweep. Exported for tests. */
+export async function sweepIdle(now = Date.now()) {
+    let evicted = 0;
+    const stale = [...cache.values()].filter((e) => e.refcount === 0 && now - e.lastUsed >= MAESTRO_MCP_POOL_IDLE_TTL_MS);
+    for (const e of stale) {
+        if (await tryEvict(e))
+            evicted++;
+    }
+    return evicted;
+}
+function ensureSweeper() {
+    if (sweeperHandle)
+        return;
+    // Half the TTL keeps the worst-case eviction lag at ~1.5× TTL.
+    const interval = Math.max(30_000, Math.floor(MAESTRO_MCP_POOL_IDLE_TTL_MS / 2));
+    sweeperHandle = setInterval(() => {
+        sweepIdle().catch((err) => {
+            logger.warn({ err }, "maestro mcp pool-cache: sweep failed");
+        });
+    }, interval);
+    // unref so the interval doesn't keep the process alive at shutdown.
+    if (typeof sweeperHandle.unref === "function")
+        sweeperHandle.unref();
+}
+/** Stop the sweeper. Used by tests to reset state. */
+export function stopSweeper() {
+    if (sweeperHandle) {
+        clearInterval(sweeperHandle);
+        sweeperHandle = null;
+    }
+}
+/**
+ * Close every cached client. Awaits up to `timeoutMs` total (3s default).
+ * Safe to call multiple times — entries are removed as they close.
+ */
+export async function closeAll(timeoutMs = 3000) {
+    const entries = [...cache.values()];
+    cache.clear();
+    const closes = entries.map(async (e) => {
+        try {
+            await e.client.close();
+        }
+        catch (err) {
+            logger.warn({ err, server: e.serverName }, "maestro mcp pool-cache: close during shutdown failed");
+        }
+    });
+    await Promise.race([
+        Promise.allSettled(closes),
+        new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+    ]);
+}
+function ensureShutdownHook() {
+    if (shutdownRegistered)
+        return;
+    shutdownRegistered = true;
+    // High priority: graceful close of MCP clients should finish BEFORE
+    // other shutdown handlers start killing external processes (PII server,
+    // playwright children, codex trees) — otherwise an in-flight MCP tool
+    // call could lose its subprocess mid-handshake.
+    onShutdown("maestro-mcp-pool", 100, () => closeAll());
+}
+/** Test-only: drop all entries without closing. Used to reset state between
+ *  test runs that share the module singleton. */
+export function __resetForTests() {
+    cache.clear();
+    stopSweeper();
+    shutdownRegistered = false;
+    clientFactory = (name, spec) => new MaestroMcpClient(name, spec);
+}
+/** Test-only: swap the client factory. Used to inject a fake client backed by
+ *  `InMemoryTransport` so tests don't spawn real MCP subprocesses. */
+export function __setClientFactoryForTests(factory) {
+    clientFactory = factory;
+}
+/** Test-only: read cache size. */
+export function __cacheSize() {
+    return cache.size;
+}
+/** Test-only: read entry by key parts. */
+export function __getEntry(ctx, serverName, spec) {
+    const e = cache.get(makeCacheKey(ctx, serverName, hashSpec(spec)));
+    return e ? { refcount: e.refcount, lastUsed: e.lastUsed } : null;
+}
+//# sourceMappingURL=pool-cache.js.map

package/dist/mcp/pool-cache.js.map

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

package/dist/mcp/pool.d.ts

@@ -0,0 +1,65 @@
+import type { MaestroMcpClient, MaestroMcpTool } from "../mcp/client.js";
+import { type CacheKeyContext } from "../mcp/pool-cache.js";
+import type { ToolRegistry } from "../tools/registry.js";
+/**
+ * MCP pool — per-turn lease view over the process-wide cache in `pool-cache.ts`.
+ *
+ * Each `maestroProvider` call builds one pool, which acquires a refcounted lease
+ * on every configured MCP client from the cache (spawning fresh on cache miss).
+ * When the turn ends, `pool.close()` releases the leases — the actual MCP
+ * subprocess stays alive, ready for the next turn within the same session.
+ * Eviction (idle TTL or LRU cap) happens in `pool-cache.ts`.
+ *
+ * What's the same as the pre-cache pool:
+ *   - Failure-isolation via `Promise.allSettled` (one bad server doesn't take
+ *     out the rest).
+ *   - `mcp__<server>__<tool>` naming consistent with Claude SDK.
+ *   - builtin/MCP tool-name collisions: builtin wins + warn (handled in
+ *     `registerMcpTools` here).
+ *   - `tools/call` abortSignal still plumbed through so an aborted turn
+ *     cancels in-flight RPCs without killing the (still-cached) client.
+ *
+ * What's different with caching:
+ *   - `pool.close()` now releases leases, not closes clients.
+ *   - `startMcpPool` takes a `CacheKeyContext` so two users (or two sessions
+ *     within the same user) get separate cached clients even when the spec
+ *     hash matches.
+ */
+export interface MaestroMcpPool {
+    /** Live clients leased for this turn, indexed by server name. */
+    readonly clients: MaestroMcpClient[];
+    /** All tools that successfully listed across every client. */
+    readonly tools: MaestroMcpTool[];
+    /** Release the leases. Safe to call multiple times. */
+    close(): Promise<void>;
+}
+/**
+ * Acquire a lease on every MCP server in `servers` from the cache and collect
+ * their tool schemas. On cache miss the server is spawned fresh; on hit the
+ * pre-warmed client is reused (no spawn cost, no handshake cost).
+ *
+ * Failure isolation: one server failing to start does not abort the others,
+ * we log and continue. Partial MCP availability is preferable to losing the
+ * whole toolset for a turn — same stance as the pre-cache implementation and
+ * the Playwright exit-propagation path.
+ *
+ * `ctx` scopes the cache key. Pass userId/session/groupId from `AgentQueryOptions`.
+ * Same spec across two contexts ⇒ two separate cached clients (correct: e.g.
+ * playwright stdio with `--user-data-dir` differs per user-session anyway, but
+ * scoping by context keeps the invariant even when specs happen to match).
+ */
+export declare function startMcpPool(servers: Record<string, unknown>, ctx?: CacheKeyContext): Promise<MaestroMcpPool>;
+/**
+ * Register every MCP tool in the pool into the given Maestro ToolRegistry.
+ *
+ * Name collisions (e.g. a builtin already owns the same prefixed name) are
+ * logged and skipped rather than thrown — builtins win because they're more
+ * stable than MCP servers that come and go per turn.
+ *
+ * Optional `abortSignal` is forwarded into every MCP `tools/call` so a
+ * Maestro-level abort cancels in-flight JSON-RPC requests instead of leaving
+ * them blocked on a dead/slow server. The cached client itself stays alive —
+ * only the in-flight RPC is cancelled, so the next turn can reuse it.
+ */
+export declare function registerMcpTools(registry: ToolRegistry, pool: MaestroMcpPool, abortSignal?: AbortSignal): void;
+//# sourceMappingURL=pool.d.ts.map

package/dist/mcp/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/mcp/pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAwB,cAAc,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,EAAE,KAAK,eAAe,EAAmC,MAAM,kBAAkB,CAAC;AACzF,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IACrC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC;IACjC,uDAAuD;IACvD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,GAAG,GAAE,eAAoB,GACxB,OAAO,CAAC,cAAc,CAAC,CAuCzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,cAAc,EACpB,WAAW,CAAC,EAAE,WAAW,GACxB,IAAI,CAwBN"}