agentfootprint 12.1.0 → 12.2.0

package/dist/esm/mcp/clientPort.d.ts

@@ -0,0 +1,78 @@
+/**
+ * clientPort — what the MCP client pool asks of a client it opens, and what the
+ * client hands back beside the ordinary `McpClient`.
+ *
+ * Pattern: an internal seam, never on a door.
+ * Role:    The pool's clients are ordinary `mcpClient`s (`mcpClient.ts`): their
+ *          discovery, their per-tool checks (`callChecks.ts`, counted per
+ *          client object by `listingGenerations.ts`), their retry series and
+ *          their request ledger are the library's, unchanged. A pool needs
+ *          four things more, and only a pool does, so they cross here:
+ *
+ *   - a CONNECT signal apart from the client's lifetime signal: one open runs
+ *     under the pool's own signal and open deadline, never a caller's;
+ *   - the request guard of whatever the pool is doing on the client
+ *     (`requestGuard.ts`), so every request is checked and counted;
+ *   - the server's tools-changed notice, heard through the SDK's
+ *     `listChanged.tools` with its automatic refresh OFF — a notice can only
+ *     make the pool list again, through `listing`, which `mcpClient` counts;
+ *   - a port back: a listing under the pool's own signal, a callable tool for a
+ *     definition this client did not list (a shared one), and an ending whose
+ *     settlement is reported apart from its answer.
+ */
+import type { Tool } from '../tools/tools.js';
+import type { RequestGuard } from './requestGuard.js';
+import type { Ending } from './terminate.js';
+import type { McpListedTool } from './types.js';
+import type { ThrottleFetch } from './throttleRetry.js';
+/** @internal What a pool passes when it opens a client. */
+export interface PooledClientSeam {
+    /** Bounds the connect (`initialize`) only: the pool's signal and its open deadline. */
+    readonly connectSignal: AbortSignal;
+    /**
+     * Wrap the transport's outermost `fetch`. `claim` finds the guard of the
+     * pooled tool call a request body belongs to (its ledger), `undefined` for
+     * any other request.
+     */
+    readonly wrapFetch: (inner: ThrottleFetch, claim: (body: unknown) => RequestGuard | undefined) => ThrottleFetch;
+    /** The guard for a message that is not a pooled tool call — asked at the watched `send`. */
+    readonly guardFor: (message: unknown) => RequestGuard | undefined;
+    /** The server said its tool list changed. Called by the SDK; must not throw. */
+    readonly onToolsChanged: () => void;
+}
+/** @internal One listing, through the client's own discovery. */
+export interface ClientListing {
+    /** The tools as `mcpClient` wraps them: each carries the checks of this listing. */
+    readonly tools: readonly Tool[];
+    /** The definitions as the server listed them, in the same order. */
+    readonly listed: readonly McpListedTool[];
+}
+/** @internal What a pooled client hands the pool. */
+export interface ClientPort {
+    /** List every page through the client's own discovery, under `signal`. Replaces its cache. */
+    listing(signal: AbortSignal | undefined): Promise<ClientListing>;
+    /**
+     * A callable tool for `listed` on this connection that carries its OWN
+     * checks — for a definition this client did not list itself, so the SDK on
+     * this connection holds none for it.
+     */
+    bind(listed: McpListedTool): Tool;
+    /** End the remote session and close: the answer by its deadline, the settlement apart. */
+    end(): Ending;
+}
+/**
+ * @internal What a pooled open that FAILED leaves behind: the server may have
+ * opened a session all the same (its `initialize` answer can land after the
+ * open was aborted), so the pool can still end it — once the open's work has
+ * settled, it asks `hasSession` and, if so, ends it under the ending rule.
+ */
+export interface HalfOpen {
+    /** Does the transport hold a session id the server issued — read when asked. */
+    hasSession(): boolean;
+    /** End that session, then close locally. */
+    end(): Ending;
+}
+/** @internal Remember what `error` (a failed pooled open's) left behind. */
+export declare function rememberHalfOpen(error: unknown, halfOpen: HalfOpen): void;
+/** @internal What a failed pooled open left behind, if anything. */
+export declare function halfOpenOf(error: unknown): HalfOpen | undefined;

package/dist/esm/mcp/clientPort.js

@@ -0,0 +1,33 @@
+/**
+ * clientPort — what the MCP client pool asks of a client it opens, and what the
+ * client hands back beside the ordinary `McpClient`.
+ *
+ * Pattern: an internal seam, never on a door.
+ * Role:    The pool's clients are ordinary `mcpClient`s (`mcpClient.ts`): their
+ *          discovery, their per-tool checks (`callChecks.ts`, counted per
+ *          client object by `listingGenerations.ts`), their retry series and
+ *          their request ledger are the library's, unchanged. A pool needs
+ *          four things more, and only a pool does, so they cross here:
+ *
+ *   - a CONNECT signal apart from the client's lifetime signal: one open runs
+ *     under the pool's own signal and open deadline, never a caller's;
+ *   - the request guard of whatever the pool is doing on the client
+ *     (`requestGuard.ts`), so every request is checked and counted;
+ *   - the server's tools-changed notice, heard through the SDK's
+ *     `listChanged.tools` with its automatic refresh OFF — a notice can only
+ *     make the pool list again, through `listing`, which `mcpClient` counts;
+ *   - a port back: a listing under the pool's own signal, a callable tool for a
+ *     definition this client did not list (a shared one), and an ending whose
+ *     settlement is reported apart from its answer.
+ */
+const HALF_OPENS = new WeakMap();
+/** @internal Remember what `error` (a failed pooled open's) left behind. */
+export function rememberHalfOpen(error, halfOpen) {
+    if (error !== null && typeof error === 'object')
+        HALF_OPENS.set(error, halfOpen);
+}
+/** @internal What a failed pooled open left behind, if anything. */
+export function halfOpenOf(error) {
+    return error !== null && typeof error === 'object' ? HALF_OPENS.get(error) : undefined;
+}
+//# sourceMappingURL=clientPort.js.map

package/dist/esm/mcp/clientPort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientPort.js","sourceRoot":"","sources":["../../../src/mcp/clientPort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA8DH,MAAM,UAAU,GAAG,IAAI,OAAO,EAAoB,CAAC;AAEnD,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,KAAc,EAAE,QAAkB;IACjE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACnF,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACzF,CAAC"}

package/dist/esm/mcp/gatewayTransport.js

@@ -35,6 +35,7 @@
  */
 import { isCredentialIssued } from '../identity/types.js';
 import { throwIfAborted, untilAborted } from '../lib/abort.js';
+import { guardOf, trackedBy } from './requestGuard.js';
 const DEFAULT_SERVICE = 'gateway';
 /**
  * Describe an MCP connection whose auth headers are vended per request.
@@ -128,16 +129,25 @@ export function createVendingFetch(transport, baseFetch = globalThis.fetch.bind(
         throwIfAborted(signal);
         // The provider gets the signal, to stop its own work. The wait is raced
         // against it, so a provider that ignores it cannot hold the request open.
-        const result = await untilAborted(transport.credentials.getCredential({
+        const vend = Promise.resolve(transport.credentials.getCredential({
             service: transport.service,
             ...(transport.scopes !== undefined && { scopes: transport.scopes }),
             ...(transport.mode !== undefined && { mode: transport.mode }),
             ...(signal !== undefined && { signal }),
-        }), signal);
+        }));
+        // A pooled request counts the vend itself, not the raced wait: a provider
+        // that ignores the abort is still work under the operation until it
+        // settles (`requestGuard.ts`).
+        const guard = guardOf(init);
+        guard?.track(vend);
+        const result = await untilAborted(vend, signal);
         // Checked again once the credential is here, before the request is handed
         // on: a credential that lands after the abort is never used, so an aborted
         // or timed-out request is never sent, however late the provider answers.
+        // A pooled request's send gate is asked here too: a binding that went
+        // stale while the credential was vended sends nothing.
         throwIfAborted(signal);
+        guard?.check();
         if (!isCredentialIssued(result)) {
             throw new GatewayAuthorizationRequiredError(transport.service, result.authorizationUrl);
         }
@@ -151,7 +161,7 @@ export function createVendingFetch(transport, baseFetch = globalThis.fetch.bind(
         }
         // The vended value exists only inside this call, on this Headers object,
         // for the duration of this request. Nothing above closes over it.
-        return baseFetch(input, { ...init, headers });
+        return trackedBy(init, baseFetch(input, { ...init, headers }));
     };
 }
 //# sourceMappingURL=gatewayTransport.js.map

package/dist/esm/mcp/gatewayTransport.js.map

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

package/dist/esm/mcp/index.d.ts

@@ -15,4 +15,12 @@ export type { McpReplayDeduplication, McpReplayKind, McpReplayOptions, McpReplay
 export { McpReplayUnavailableError, type McpReplayUnavailableReason } from './replayUnavailable.js';
 export { McpToolListIncompleteError, type McpToolListIncompleteReason } from './toolList.js';
 export { McpOutputUncheckedError } from './callChecks.js';
-export type { McpCallToolResult, McpClient, McpClientOptions, McpConnection, McpConnectionOptions, McpJsonSchemaValidator, McpSdk, McpGatewayTransport, McpHttpTransport, McpStdioTransport, McpTransport, McpSdkClient, McpServeOptions, McpServeHandle, McpServeTransport, McpHttpServeTransport, McpStdioServeTransport, McpSdkServer, } from './types.js';
+export { canTerminate, type TerminableMcpClient } from './terminate.js';
+export { mcpClientPool, type McpClientPool, type McpPoolScope } from './pool/mcpClientPool.js';
+export { MCP_POOL_DEFAULTS, MAX_DEFINITION_ENTRIES, MAX_SHARED_TOOLS, type McpClientPoolOptions, type McpPoolDefinitionSharing, type McpPoolIdentity, type McpPoolShareContext, } from './pool/options.js';
+export { McpPoolRefusedError, PoolFullError, type McpPoolLimit, type McpPoolRefusal, } from './pool/errors.js';
+export type { McpPoolLease } from './pool/lease.js';
+export type { McpPoolReport } from './pool/record.js';
+export type { McpPoolStats } from './pool/pool.js';
+export type { EndReason as McpPoolEndReason } from './pool/pooledClient.js';
+export type { McpCallToolResult, McpClient, McpClientOptions, McpConnection, McpConnectionOptions, McpJsonSchemaValidator, McpSdk, McpGatewayTransport, McpHttpTransport, McpStdioTransport, McpTerminateOutcome, McpTransport, McpTransportSettings, McpSdkClient, McpServeOptions, McpServeHandle, McpServeTransport, McpHttpServeTransport, McpStdioServeTransport, McpSdkServer, } from './types.js';

package/dist/esm/mcp/index.js

@@ -25,4 +25,12 @@ export { McpToolListIncompleteError } from './toolList.js';
 // cannot check — no JSON Schema validator reachable — is refused, never answered
 // unchecked.
 export { McpOutputUncheckedError } from './callChecks.js';
+// Ending a client's remote session: a feature-detected capability, never a
+// required member of `McpClient` (`close()` stays local).
+export { canTerminate } from './terminate.js';
+// A client per conversation, for one server: bounded, ended remotely, and its
+// tool definitions per client incarnation unless the app declares sharing.
+export { mcpClientPool } from './pool/mcpClientPool.js';
+export { MCP_POOL_DEFAULTS, MAX_DEFINITION_ENTRIES, MAX_SHARED_TOOLS, } from './pool/options.js';
+export { McpPoolRefusedError, PoolFullError, } from './pool/errors.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,8EAA8E;AAC9E,0EAA0E;AAC1E,OAAO,EAAE,mBAAmB,EAAsB,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAA+C,MAAM,oBAAoB,CAAC;AAChG,OAAO,EACL,gBAAgB,EAChB,iCAAiC,GAElC,MAAM,uBAAuB,CAAC;AAC/B,6EAA6E;AAC7E,4EAA4E;AAC5E,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAgBnD,2EAA2E;AAC3E,0CAA0C;AAC1C,OAAO,EAAE,yBAAyB,EAAmC,MAAM,wBAAwB,CAAC;AACpG,gFAAgF;AAChF,8EAA8E;AAC9E,OAAO,EAAE,0BAA0B,EAAoC,MAAM,eAAe,CAAC;AAC7F,8EAA8E;AAC9E,iFAAiF;AACjF,aAAa;AACb,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,8EAA8E;AAC9E,0EAA0E;AAC1E,OAAO,EAAE,mBAAmB,EAAsB,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAA+C,MAAM,oBAAoB,CAAC;AAChG,OAAO,EACL,gBAAgB,EAChB,iCAAiC,GAElC,MAAM,uBAAuB,CAAC;AAC/B,6EAA6E;AAC7E,4EAA4E;AAC5E,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAgBnD,2EAA2E;AAC3E,0CAA0C;AAC1C,OAAO,EAAE,yBAAyB,EAAmC,MAAM,wBAAwB,CAAC;AACpG,gFAAgF;AAChF,8EAA8E;AAC9E,OAAO,EAAE,0BAA0B,EAAoC,MAAM,eAAe,CAAC;AAC7F,8EAA8E;AAC9E,iFAAiF;AACjF,aAAa;AACb,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,2EAA2E;AAC3E,0DAA0D;AAC1D,OAAO,EAAE,YAAY,EAA4B,MAAM,gBAAgB,CAAC;AACxE,8EAA8E;AAC9E,2EAA2E;AAC3E,OAAO,EAAE,aAAa,EAAyC,MAAM,yBAAyB,CAAC;AAC/F,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,GAKjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,aAAa,GAGd,MAAM,kBAAkB,CAAC"}

package/dist/esm/mcp/mcpClient.d.ts

@@ -42,7 +42,9 @@
  * loads only when a consumer actually constructs a client. Tests
  * inject `_client` and skip the import path entirely.
  */
-import type { McpClient, McpClientOptions, McpConnectionOptions } from './types.js';
+import type { Tool } from '../tools/tools.js';
+import type { McpClient, McpClientOptions, McpConnectionOptions, McpListedTool } from './types.js';
+import { type ClientPort, type PooledClientSeam } from './clientPort.js';
 /**
  * Connect to an MCP server. Returns an `McpClient` that exposes the
  * server's tools as agentfootprint `Tool[]` and a `close()` to tear
@@ -66,3 +68,18 @@ import type { McpClient, McpClientOptions, McpConnectionOptions } from './types.
  *   transport fails to connect.
  */
 export declare function mcpClient(opts: McpClientOptions | McpConnectionOptions): Promise<McpClient>;
+/**
+ * @internal The MCP client pool's way to open a client (`mcp/pool/`): an
+ * ordinary `mcpClient` — the same discovery, checks, ledger and retry series —
+ * plus what only a pool asks for (`clientPort.ts`), and the port back.
+ */
+export declare function openPooledClient(opts: McpClientOptions, seam: PooledClientSeam): Promise<{
+    readonly client: McpClient;
+    readonly port: ClientPort;
+}>;
+/**
+ * @internal What a listed MCP tool looks like as a `Tool`, less its `execute`:
+ * its schema, its provenance and the declarations its `_meta` carries. The ONE
+ * shape both an `mcpClient` tool and an MCP client pool's bound tool take.
+ */
+export declare function mcpToolShape(serverName: string, mcp: McpListedTool): Omit<Tool, 'execute'>;

package/dist/esm/mcp/mcpClient.js

@@ -58,6 +58,8 @@ import { refuseConflictingOptions } from './connectionRefusals.js';
 import { sdkLoadFailure } from './sdkLoadFailure.js';
 import { transportUrl } from './transportUrl.js';
 import { lazyRequire } from '../lib/lazyRequire.js';
+import { rememberHalfOpen, } from './clientPort.js';
+import { DeleteWatch, endLocally, endSession, } from './terminate.js';
 // Version-less identity. The MCP `clientInfo` field is informational
 // (server logs it); a hardcoded number drifts every release. Consumers
 // who care about wire-level identity pass `clientInfo` explicitly.
@@ -88,6 +90,18 @@ const DEFAULT_CLIENT_INFO = {
  *   transport fails to connect.
  */
 export async function mcpClient(opts) {
+    return (await connectClient(opts)).client;
+}
+/**
+ * @internal The MCP client pool's way to open a client (`mcp/pool/`): an
+ * ordinary `mcpClient` — the same discovery, checks, ledger and retry series —
+ * plus what only a pool asks for (`clientPort.ts`), and the port back.
+ */
+export async function openPooledClient(opts, seam) {
+    return connectClient(opts, seam);
+}
+/** The one construction path behind `mcpClient` and the pool's opener. */
+async function connectClient(opts, seam) {
     const name = opts.name ?? 'mcp';
     const resultMode = resultModeOf(opts.resultMode, name);
     // Before anything connects: an option that names a behaviour which cannot
@@ -100,24 +114,27 @@ export async function mcpClient(opts) {
     // The validator a tool's own output checks use (`callChecks.ts`), refused by
     // name now when it is not one.
     const validator = validatorOption(opts.jsonSchemaValidator, `mcpClient[${name}]`);
-    const { connection, ledger, kit } = await openConnection(opts, replay, name, validator);
+    const { connection, ledger, kit, ending } = await openConnection(opts, replay, name, validator, seam);
     const unlisted = new Set();
     // Tool cache so consumers calling `.tools()` more than once don't
     // hammer the server. `.refresh()` invalidates it.
     let cache = null;
     let closed = false;
+    // The one ending this client gets (`terminate.ts`): `terminate()` asks for it
+    // once, and every later call answers the same outcome.
+    let ended;
     const ensureOpen = (op) => {
         if (closed) {
             throw new Error(`mcpClient[${name}].${op}() called after close(). Construct a new client to reconnect.`);
         }
     };
-    const buildTools = async () => {
+    const listWith = async (signal) => {
         // Every page of the server's list (`toolList.ts`). `signal` rides each
         // page in the SDK's trailing options argument, never in the params — see
         // `wrapMcpTool`.
         // Each page request is counted in this connection's listings, whatever it
         // settles to (`listingGenerations.ts`).
-        const listing = await listEveryPage(connection, opts.signal, kit.listings);
+        const listing = await listEveryPage(connection, signal, kit.listings);
         // A list that did not end cannot say which entries name nothing.
         if (listing.incomplete === undefined)
             noteUnlisted(replay, listing.tools, name, unlisted);
@@ -129,9 +146,28 @@ export async function mcpClient(opts) {
         if (listing.incomplete !== undefined) {
             throw new McpToolListIncompleteError(listing.incomplete, name, listing.pages, tools);
         }
-        return tools;
+        return { tools, listed: listing.tools };
     };
-    return {
+    const buildTools = async () => (await listWith(opts.signal)).tools;
+    const closeLocally = async () => {
+        try {
+            await connection.close();
+        }
+        finally {
+            // Nothing this connection sent is awaited any more, however it closed.
+            ledger?.close();
+        }
+    };
+    // The remote session ended, then the local side — at most once.
+    const end = () => {
+        if (ended !== undefined)
+            return ended;
+        closed = true;
+        cache = null;
+        ended = ending(closeLocally);
+        return ended;
+    };
+    const client = {
         name,
         async tools() {
             ensureOpen('tools');
@@ -149,15 +185,37 @@ export async function mcpClient(opts) {
                 return;
             closed = true;
             cache = null;
-            try {
-                await connection.close();
-            }
-            finally {
-                // Nothing this connection sent is awaited any more, however it closed.
-                ledger?.close();
-            }
+            await closeLocally();
+        },
+        async terminate() {
+            if (ended !== undefined)
+                return ended.outcome;
+            ensureOpen('terminate');
+            return end().outcome;
+        },
+    };
+    const port = {
+        async listing(signal) {
+            ensureOpen('tools');
+            const listing = await listWith(signal);
+            cache = listing.tools;
+            return listing;
         },
+        bind: (listed) => 
+        // No listing generation: this connection's SDK holds no checks for a
+        // definition it did not list, so the tool always runs its own.
+        wrapMcpTool(name, connection, listed, opts.signal, resultMode, ledger, strict, checksFor(listed, kit, undefined)),
+        end,
     };
+    return { client, port };
+}
+/**
+ * An ending that sends nothing: the local close, and the outcome that says why
+ * — answered by the teardown deadline even when the close hangs, the close
+ * itself reported apart (`terminate.ts` · `endLocally`).
+ */
+function endingWithout(remote) {
+    return (close) => endLocally(remote, close);
 }
 /**
  * The one funnel every arm passes through, in precedence order: a connection
@@ -168,38 +226,48 @@ export async function mcpClient(opts) {
  * A call with neither `connection` nor `sdk` reaches `resolveClient` with two
  * `undefined` arguments and takes the identical path it always took.
  */
-async function openConnection(opts, replay, name, validator) {
+async function openConnection(opts, replay, name, validator, seam) {
     // A client built elsewhere: the library loads nothing, so only the caller's
     // validator can check a tool's output itself, and errors take the SDK's shape.
     // Its list requests are counted per client: every mcpClient over it shares one
     // count, as they share the SDK's one set of checks (`listingGenerations.ts`).
+    // The library did not build its transport, so it cannot end the session.
     if (opts.connection !== undefined) {
         const kit = callCheckKit(name, listingsOf(opts.connection), validator);
-        return { connection: opts.connection, kit };
+        return { connection: opts.connection, kit, ending: endingWithout('unavailable') };
     }
     if (opts._client !== undefined) {
         return {
             connection: opts._client,
             kit: callCheckKit(name, listingsOf(opts._client), validator),
+            ending: endingWithout('unavailable'),
         };
     }
     // `refuseConflictingOptions` has already refused the case where this is
     // absent, so the assertion documents that guarantee rather than assuming it.
     const transport = opts.transport;
-    return resolveClient(transport, opts.clientInfo, opts.signal, opts.retryOnThrottle, opts.sdk, replay, name, validator);
+    return resolveClient(transport, opts.clientInfo, opts.signal, opts.retryOnThrottle, opts.sdk, replay, name, validator, seam);
 }
 // ─── SDK construction (lazy require, unless the caller supplied it) ─
-async function resolveClient(transport, clientInfo, signal, retryOnThrottle, sdk, replay, name = 'mcp', validator) {
+async function resolveClient(transport, clientInfo, signal, retryOnThrottle, sdk, replay, name = 'mcp', validator, seam) {
     if (sdk !== undefined)
         assertSdk(sdk, transport.transport);
     const mod = sdk ?? loadClientModule();
     // A caller's validator is the client's too, so one validator checks every
-    // page; without one, the options are exactly what they always were.
+    // page; without one, the options are exactly what they always were. A pooled
+    // client hears the server's tools-changed notice with the SDK's automatic
+    // refresh OFF: the notice only makes the pool list again, through this
+    // client's own discovery, which counts every listing (`listingGenerations.ts`).
     const options = validator === undefined
         ? { capabilities: {} }
         : { capabilities: {}, jsonSchemaValidator: validator };
+    if (seam !== undefined) {
+        options.listChanged = {
+            tools: { autoRefresh: false, debounceMs: 0, onChanged: () => seam.onToolsChanged() },
+        };
+    }
     const client = new mod.Client(clientInfo ?? DEFAULT_CLIENT_INFO, options);
-    const built = await buildTransport(transport, retryOnThrottle, sdk, replay, name);
+    const built = await buildTransport(transport, retryOnThrottle, sdk, replay, name, seam);
     // With the SDK loaded here, so is what a tool's own checks run with: its
     // default validator and its own error class. With `sdk`, the loader is never
     // touched (`callChecks.ts`).
@@ -207,14 +275,39 @@ async function resolveClient(transport, clientInfo, signal, retryOnThrottle, sdk
         ? callCheckKit(name, listingsOf(client), validator, loadCheckModules(validator))
         : callCheckKit(name, listingsOf(client), validator);
     // Same rule as callTool: options ride beside the transport, never inside it.
-    if (signal)
-        await client.connect(built.transport, { signal });
-    else
-        await client.connect(built.transport);
+    // A pooled client connects under the pool's own signal and open deadline;
+    // its lifetime signal (`signal`) rides every later request.
+    const connectSignal = seam?.connectSignal ?? signal;
+    try {
+        if (connectSignal)
+            await client.connect(built.transport, { signal: connectSignal });
+        else
+            await client.connect(built.transport);
+    }
+    catch (error) {
+        // A pooled open that failed may still have opened a session on the server:
+        // the pool can end it once the open's work has settled (`clientPort.ts`).
+        if (seam !== undefined) {
+            const transport = built.transport;
+            rememberHalfOpen(error, {
+                hasSession: () => transport?.sessionId !== undefined,
+                end: () => built.ending(async () => {
+                    try {
+                        await client.close();
+                    }
+                    finally {
+                        built.ledger?.close();
+                    }
+                }),
+            });
+        }
+        throw error;
+    }
     return {
         connection: client,
         kit,
         ...(built.ledger !== undefined && { ledger: built.ledger }),
+        ending: built.ending,
     };
 }
 /**
@@ -284,7 +377,7 @@ function loadClientModule() {
         }));
     }
 }
-async function buildTransport(t, retryOnThrottle, sdk, replay, name = 'mcp') {
+async function buildTransport(t, retryOnThrottle, sdk, replay, name = 'mcp', seam) {
     if (t.transport === 'stdio') {
         // Deliberately NOT served by `sdk`: stdio spawns a subprocess, so it can
         // never run in a browser, and `client/stdio.js` is the SDK's one client
@@ -305,14 +398,23 @@ async function buildTransport(t, retryOnThrottle, sdk, replay, name = 'mcp') {
             }));
         }
         // No fetch, so no retry series: a stdio call has no attempts to file.
-        return {
-            transport: new stdioMod.StdioClientTransport({
-                command: t.command,
-                args: t.args ? [...t.args] : [],
-                ...(t.env && { env: { ...t.env } }),
-                ...(t.cwd !== undefined && { cwd: t.cwd }),
-            }),
-        };
+        // stdio has no session id to end: its ending is the local close.
+        const stdio = new stdioMod.StdioClientTransport({
+            command: t.command,
+            args: t.args ? [...t.args] : [],
+            ...(t.env && { env: { ...t.env } }),
+            ...(t.cwd !== undefined && { cwd: t.cwd }),
+        });
+        if (seam === undefined)
+            return { transport: stdio, ending: endingWithout('no-session') };
+        // A pooled client's sends are watched, so the pool's gate is asked at
+        // `send()` — on stdio, which writes without waiting, the last boundary.
+        const ledger = new RequestLedger({
+            server: name,
+            strict: replay?.policy === 'app-authorized',
+            guardFor: seam.guardFor,
+        });
+        return watchedForPool(stdio, ledger, endingWithout('no-session'), name);
     }
     // http + gateway transports both ride Streamable HTTP. They differ only in
     // WHEN the auth headers are decided: `http` fixes them at construction,
@@ -345,7 +447,16 @@ async function buildTransport(t, retryOnThrottle, sdk, replay, name = 'mcp') {
     const ledger = new RequestLedger({
         server: name,
         strict: replay?.policy === 'app-authorized',
+        ...(seam !== undefined && { guardFor: seam.guardFor }),
     });
+    // The pass-through fetch every transport the library builds carries: it
+    // changes no request, and reads a `DELETE`'s answer for `terminate()`
+    // (`terminate.ts`), because the SDK treats a 405 as success. A pooled client's
+    // requests also cross the pool's gate here, before anything else of ours.
+    const watch = new DeleteWatch();
+    const outermost = (inner) => watch.fetch(seam === undefined
+        ? inner
+        : seam.wrapFetch(inner ?? platformFetch, (body) => guardOfCall(ledger, body)));
     if (t.transport === 'gateway') {
         // The consumer's own `fetch` (9.32.0) goes UNDERNEATH the vending, not
         // beside it: `createVendingFetch` resolves the credential, applies it to
@@ -356,9 +467,11 @@ async function buildTransport(t, retryOnThrottle, sdk, replay, name = 'mcp') {
         // the seam existed.
         const gatewayFetch = retried(createVendingFetch(t, t.fetch));
         const ledgered = gatewayFetch && ledgeredFetch(gatewayFetch, ledger, replay);
-        return watched(new httpMod.StreamableHTTPClientTransport(transportUrl(t.url, 'mcpClient'), {
-            fetch: ledgered ?? gatewayFetch,
-        }), ledgered && ledger);
+        const sdkTransport = new httpMod.StreamableHTTPClientTransport(transportUrl(t.url, 'mcpClient'), { fetch: outermost(ledgered ?? gatewayFetch) });
+        if (seam !== undefined) {
+            return watchedForPool(sdkTransport, ledger, sessionEnding(sdkTransport, watch), name);
+        }
+        return watched(sdkTransport, ledgered !== undefined ? ledger : undefined, sessionEnding(sdkTransport, watch));
     }
     // Both options ride the SAME SDK transport, and both are forwarded when both
     // are given. The SDK folds `requestInit.headers` into the `init.headers` it
@@ -366,23 +479,60 @@ async function buildTransport(t, retryOnThrottle, sdk, replay, name = 'mcp') {
     // final word over the bytes — see `McpHttpTransport.fetch`.
     const httpFetch = retried(t.fetch);
     const ledgered = httpFetch && ledgeredFetch(httpFetch, ledger, replay);
-    const fetch = ledgered ?? httpFetch;
-    return watched(new httpMod.StreamableHTTPClientTransport(transportUrl(t.url, 'mcpClient'), {
+    const sdkTransport = new httpMod.StreamableHTTPClientTransport(transportUrl(t.url, 'mcpClient'), {
         ...(t.headers && { requestInit: { headers: { ...t.headers } } }),
-        ...(fetch && { fetch }),
-    }), ledgered && ledger);
+        fetch: outermost(ledgered ?? httpFetch),
+    });
+    if (seam !== undefined) {
+        return watchedForPool(sdkTransport, ledger, sessionEnding(sdkTransport, watch), name);
+    }
+    return watched(sdkTransport, ledgered !== undefined ? ledger : undefined, sessionEnding(sdkTransport, watch));
+}
+/** The guard of the pooled tool call `body` belongs to, by its ledger claim. */
+function guardOfCall(ledger, body) {
+    return ledger.claim(body)?.guard;
+}
+/** How an SDK Streamable HTTP transport's session ends: its own `terminateSession()`. */
+function sessionEnding(transport, watch) {
+    const terminable = transport;
+    if (typeof terminable?.terminateSession !== 'function')
+        return endingWithout('unavailable');
+    return (close) => endSession(terminable, watch, close);
 }
 /**
  * `transport` with its sends watched by `ledger` — the SAME object, its own
  * `send` installed in place. As it is, with no ledger, when there is none or it
  * cannot be watched: then no call expects its attempts filed.
  */
-function watched(transport, ledger) {
+function watched(transport, ledger, ending) {
     if (ledger === undefined || transport === null || typeof transport !== 'object') {
-        return { transport };
+        return { transport, ending };
+    }
+    return ledger.watch(transport) === undefined
+        ? { transport, ending }
+        : { transport, ledger, ending };
+}
+/**
+ * A pooled client's transport, its sends watched — REQUIRED. The pool checks
+ * every request against its binding at the watched `send` (on stdio the last
+ * boundary there is) and ties each tool call to its guard there, so a
+ * transport whose `send` cannot be watched is refused before anything is
+ * built on it or sent: the pool's guarantee needs the watch, whatever the
+ * replay policy. A standalone client never comes here (`watched`).
+ *
+ * @throws when the transport has no `send` to watch or refuses the property
+ */
+function watchedForPool(transport, ledger, ending, name) {
+    const built = watched(transport, ledger, ending);
+    if (built.ledger === undefined) {
+        throw new Error(`mcpClient[${name}]: the MCP client pool checks every request at its transport's \`send\` ` +
+            "before it is sent, and this transport's `send` cannot be watched (it is missing, or a " +
+            'property that cannot be redefined), so the pooled client is not opened. Nothing was sent.');
     }
-    return ledger.watch(transport) === undefined ? { transport } : { transport, ledger };
+    return built;
 }
+/** The platform's fetch, looked up at call time so a later polyfill still wins. */
+const platformFetch = (input, init) => globalThis.fetch(input, init);
 /** The Node loader path for Streamable HTTP — reached only with no `sdk`. */
 function loadHttpModule(transport) {
     try {
@@ -419,8 +569,13 @@ function noteUnlisted(replay, listed, server, noted) {
     }
 }
 // ─── Tool wrapping ─────────────────────────────────────────────────
-function wrapMcpTool(serverName, connection, mcp, signal, resultMode, ledger, strict = false, checks) {
-    const tool = {
+/**
+ * @internal What a listed MCP tool looks like as a `Tool`, less its `execute`:
+ * its schema, its provenance and the declarations its `_meta` carries. The ONE
+ * shape both an `mcpClient` tool and an MCP client pool's bound tool take.
+ */
+export function mcpToolShape(serverName, mcp) {
+    return {
         schema: {
             name: mcp.name,
             description: mcp.description ?? `MCP tool: ${mcp.name}`,
@@ -441,6 +596,11 @@ function wrapMcpTool(serverName, connection, mcp, signal, resultMode, ledger, st
             tool: mcp.name,
             inputSchema: mcp.inputSchema,
         }),
+    };
+}
+function wrapMcpTool(serverName, connection, mcp, signal, resultMode, ledger, strict = false, checks) {
+    const tool = {
+        ...mcpToolShape(serverName, mcp),
         execute: async (args, ctx) => {
             // The agent passes args as `unknown` per Tool contract. MCP
             // expects a JSON object — non-object inputs become `{}` rather