agentfootprint 12.0.1 → 12.2.0

package/dist/types/mcp/callChecks.d.ts

@@ -0,0 +1,161 @@
+/**
+ * callChecks — a listing never makes a callable tool lose its checks.
+ *
+ * Pattern: the SDK's three per-tool call checks, carried by every tool the
+ *          library hands out, plus one typed refusal.
+ * Role:    The MCP SDK's `Client` runs three checks inside `callTool`, and it
+ *          keeps them only for the tools of its most recent `tools/list`
+ *          answer (1.32: `cacheToolMetadata` replaces them on every answer):
+ *
+ *   1. a tool with `execution.taskSupport: 'required'` is refused before a
+ *      plain `tools/call` is sent;
+ *   2. a tool with an `outputSchema` must answer with `structuredContent`,
+ *      unless the answer is an error;
+ *   3. that `structuredContent` must match the schema.
+ *
+ * So a tool that declares any of them carries them itself, as the listing it
+ * came from declared them. The library leaves them to the SDK only for a tool
+ * of a ONE-page list whose answer is still the latest, with no list request
+ * out (`listingGenerations.ts`), both when the call starts and when its answer
+ * comes in: the one-page normal case, which runs exactly as it always did.
+ * Every other call runs the tool's own checks, at the SDK's moments — the first
+ * before sending, the other two once the answer is in, before anything reads it
+ * — and raises the SDK's error: its own `McpError` where this arm loaded the
+ * SDK, otherwise an error with the same name, code and message. Those calls
+ * are to a tool of a paged list, a tool whose list a later answer replaced (a
+ * refresh that failed or succeeded; a reference held across it), and any call
+ * made while a list is being read.
+ *
+ * All of this covers the lists the library reads (`tools()`, `refresh()`); a
+ * listing it does not send — the SDK client's own automatic refresh, a
+ * `listTools` call of the caller's — is not seen (`listingGenerations.ts`).
+ *
+ * The output checks need a JSON Schema validator equal to the client's: the
+ * SDK's default (`AjvJsonSchemaValidator`, loaded with the SDK on the Node
+ * loader arm), or the caller's `jsonSchemaValidator`. Where neither exists — an
+ * `sdk` or `connection` arm given none — an answer under these rules is never
+ * returned unchecked (`McpOutputUncheckedError`):
+ *
+ *   - a call under the tool's own checks from the start, to a tool that
+ *     declares an `outputSchema`, is refused before it is sent (`sent: false`);
+ *   - a call that started under the SDK's checks is refused once its answer is
+ *     in, unread, when the library sent a `tools/list` request while the call
+ *     was out (`sent: true`): the SDK may have checked it against another list.
+ *
+ * A schema is compiled when a tool's own checks first need it, never before:
+ * the one-page normal case compiles nothing twice.
+ */
+import type { McpCallToolResult, McpJsonSchemaValidator, McpListedTool } from './types.js';
+import type { ListingGenerations } from './listingGenerations.js';
+/** The SDK's `McpError` constructor, as `@modelcontextprotocol/sdk/types.js` exports it. */
+export type McpErrorClass = new (code: number, message: string, data?: unknown) => Error;
+/** A compiled output check, as the SDK's validator returns one. */
+type Validate = (input: unknown) => {
+    readonly valid: boolean;
+    readonly errorMessage?: string;
+};
+/**
+ * What one connection checks its tools' calls with: a validator equal to its
+ * client's, the SDK's own error class where the library loaded the SDK, and
+ * which `tools/list` answer the SDK holds its checks for.
+ */
+export interface CallCheckKit {
+    /** The client's name, as its refusals name it. */
+    readonly server: string;
+    /** The validator; created on first use. `undefined` when none is reachable. */
+    validator(): McpJsonSchemaValidator | undefined;
+    /** The SDK's own `McpError`, when this arm loaded the SDK. */
+    readonly McpError?: McpErrorClass;
+    /** This connection's list requests, counted (`listingGenerations.ts` · `listingsOf`). */
+    readonly listings: ListingGenerations;
+}
+/**
+ * The kit for one connection, named `server`, whose list requests `listings`
+ * counts (`listingsOf(connection)`, shared by every client over it). `given` is
+ * the caller's `jsonSchemaValidator`; `loaded` holds what the library loaded
+ * with the SDK on the Node loader arm — the SDK's default validator class and
+ * its `McpError` — each `undefined` where it is not a constructor (another arm,
+ * or an SDK without it).
+ */
+export declare function callCheckKit(server: string, listings: ListingGenerations, given: McpJsonSchemaValidator | undefined, loaded?: {
+    readonly Validator?: unknown;
+    readonly McpError?: unknown;
+}): CallCheckKit;
+/**
+ * `value` as a validator, or `undefined` when it was not given. Refused by name
+ * when it is something else, before anything connects.
+ */
+export declare function validatorOption(value: unknown, at: string): McpJsonSchemaValidator | undefined;
+/** The checks one listed tool carries, as the listing it came from declared them. */
+export interface CallChecks {
+    readonly server: string;
+    readonly tool: string;
+    /** `execution.taskSupport: 'required'`: only ever run as a task. */
+    readonly taskRequired: boolean;
+    /** The tool declares an `outputSchema`. */
+    readonly outputDeclared: boolean;
+    /**
+     * True while the SDK's `Client` holds this tool's checks: the tool came from
+     * a one-page list whose answer is still the latest, and no list request is
+     * out. Then the SDK checks the call, and nothing here runs.
+     */
+    heldBySdk(): boolean;
+    /**
+     * The compiled output check, compiled from the declared schema on first use.
+     * `undefined` when no output is declared or no validator is reachable.
+     */
+    validate(): Validate | undefined;
+    /** Raise an SDK error, as this arm can: the SDK's class, or its exact shape. */
+    fail(code: number, message: string): Error;
+}
+/**
+ * The checks `listed` carries — `undefined` when it declares none. `generation`
+ * is the one answer its list was read in, when it was read in one
+ * (`toolList.ts` · `ToolListing`); a paged list's tools have none, so the SDK
+ * never holds all of them.
+ */
+export declare function checksFor(listed: McpListedTool, kit: CallCheckKit, generation: number | undefined): CallChecks | undefined;
+/**
+ * True when this call's output cannot be checked here: it runs under the
+ * tool's own checks, the tool declares an `outputSchema`, no validator is
+ * reachable, and it is not refused as a required task anyway (that refusal is
+ * the SDK's, and comes first). The call is then refused before it is sent.
+ */
+export declare function outputUnchecked(checks: CallChecks): boolean;
+/** The SDK's task refusal, word for word, before anything is sent. */
+export declare function refuseRequiredTask(checks: CallChecks): void;
+/**
+ * The SDK's two output checks, in its order and with its sentences, once the
+ * answer is in and before anything reads it. An answer no validator here can
+ * check is never returned: it is refused, unread, as sent.
+ */
+export declare function checkOutput(checks: CallChecks, result: McpCallToolResult): void;
+/**
+ * A tool call whose output this connection cannot check, refused. The tool
+ * declares an `outputSchema`, the MCP SDK no longer holds the checks of the
+ * tool list it came from, and this connection has no JSON Schema validator to
+ * check it with — so its answer is never returned:
+ *
+ *   - `sent: false` — refused before it was sent: nothing reached the server.
+ *     The tool came from a paged list, from a list a later answer replaced, or
+ *     the call was made while a list was being read.
+ *   - `sent: true` — the call was sent, and a `tools/list` request went out
+ *     before its answer came in: the SDK may have checked that answer against
+ *     the other list, so it is refused unread. The tool may have run.
+ *
+ * Pass `jsonSchemaValidator` — the validator your client uses — to `mcpClient`.
+ * Names the server and the tool, never an argument or an answer.
+ */
+export declare class McpOutputUncheckedError extends Error {
+    readonly server: string;
+    readonly tool: string;
+    /** Whether the request left the client: `false` when the refusal came before it. */
+    readonly sent: boolean;
+    readonly code: "ERR_MCP_OUTPUT_UNCHECKED";
+    readonly reason: "output-unchecked";
+    constructor(server: string, tool: string, 
+    /** Whether the request left the client: `false` when the refusal came before it. */
+    sent: boolean);
+}
+export {};
+//# sourceMappingURL=callChecks.d.ts.map

package/dist/types/mcp/callChecks.d.ts.map

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

package/dist/types/mcp/callLifetime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callLifetime.d.ts","sourceRoot":"","sources":["../../../src/mcp/callLifetime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,oBAAoB,CAAC;AAEvE,mHAAmH;AACnH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACjD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC;IACtD;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,WAAW,GAAG,SAAS,EACrC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,MAAM,EAAE,MAAM,GACb,QAAQ,CAAC,CAAC,CAAC,CA0Cb"}
+{"version":3,"file":"callLifetime.d.ts","sourceRoot":"","sources":["../../../src/mcp/callLifetime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAQH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,oBAAoB,CAAC;AAEvE,mHAAmH;AACnH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACjD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC;IACtD;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,WAAW,GAAG,SAAS,EACrC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,MAAM,EAAE,MAAM,GACb,QAAQ,CAAC,CAAC,CAAC,CA4Cb"}

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

@@ -0,0 +1,79 @@
+/**
+ * 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;
+//# sourceMappingURL=clientPort.d.ts.map

package/dist/types/mcp/clientPort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientPort.d.ts","sourceRoot":"","sources":["../../../src/mcp/clientPort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAClB,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,YAAY,GAAG,SAAS,KAC/C,aAAa,CAAC;IACnB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,YAAY,GAAG,SAAS,CAAC;IAClE,gFAAgF;IAChF,QAAQ,CAAC,cAAc,EAAE,MAAM,IAAI,CAAC;CACrC;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;CAC3C;AAED,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,8FAA8F;IAC9F,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjE;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAClC,0FAA0F;IAC1F,GAAG,IAAI,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,gFAAgF;IAChF,UAAU,IAAI,OAAO,CAAC;IACtB,4CAA4C;IAC5C,GAAG,IAAI,MAAM,CAAC;CACf;AAID,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAEzE;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAE/D"}

package/dist/types/mcp/gatewayTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gatewayTransport.d.ts","sourceRoot":"","sources":["../../../src/mcp/gatewayTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEnF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,mBAAmB,CAatF;AAED;;;;;;GAMG;AACH,qBAAa,iCAAkC,SAAQ,KAAK;IAC1D,QAAQ,CAAC,IAAI,uCAAiD;IAC9D,sCAAsC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM;CAUtD;AAgBD,0FAA0F;AAC1F,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEjG;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,mBAAmB,EAC9B,SAAS,GAAE,SAA6C,GACvD,SAAS,CAuCX"}
+{"version":3,"file":"gatewayTransport.d.ts","sourceRoot":"","sources":["../../../src/mcp/gatewayTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAGnF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,mBAAmB,CAatF;AAED;;;;;;GAMG;AACH,qBAAa,iCAAkC,SAAQ,KAAK;IAC1D,QAAQ,CAAC,IAAI,uCAAiD;IAC9D,sCAAsC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM;CAUtD;AAgBD,0FAA0F;AAC1F,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEjG;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,mBAAmB,EAC9B,SAAS,GAAE,SAA6C,GACvD,SAAS,CA+CX"}

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

@@ -13,5 +13,15 @@ export { retryingFetch } from './throttleRetry.js';
 export type { RetryOnThrottle, ThrottleFetch, ThrottleRetryInfo, ThrottleRetryOptions, } from './throttleRetry.js';
 export type { McpReplayDeduplication, McpReplayKind, McpReplayOptions, McpReplayPolicy, McpReplayTool, } from './replay.js';
 export { McpReplayUnavailableError, type McpReplayUnavailableReason } from './replayUnavailable.js';
-export type { McpCallToolResult, McpClient, McpClientOptions, McpConnection, McpConnectionOptions, McpSdk, McpGatewayTransport, McpHttpTransport, McpStdioTransport, McpTransport, McpSdkClient, McpServeOptions, McpServeHandle, McpServeTransport, McpHttpServeTransport, McpStdioServeTransport, McpSdkServer, } from './types.js';
+export { McpToolListIncompleteError, type McpToolListIncompleteReason } from './toolList.js';
+export { McpOutputUncheckedError } from './callChecks.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';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","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;AAGzC,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EACL,gBAAgB,EAChB,iCAAiC,EACjC,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACV,sBAAsB,EACtB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,yBAAyB,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpG,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,MAAM,EACN,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","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;AAGzC,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EACL,gBAAgB,EAChB,iCAAiC,EACjC,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACV,sBAAsB,EACtB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,yBAAyB,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAGpG,OAAO,EAAE,0BAA0B,EAAE,KAAK,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAI7F,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAG1D,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC/F,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,SAAS,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC5E,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,MAAM,EACN,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/types/mcp/listingGenerations.d.ts

@@ -0,0 +1,55 @@
+/**
+ * listingGenerations — which `tools/list` answer the MCP SDK's `Client` holds
+ * its per-tool call checks for, as far as one connection can tell.
+ *
+ * Pattern: a count of the list requests one connection sent and settled.
+ * Role:    The SDK's `Client` keeps its per-tool call checks (`callChecks.ts`)
+ *          for the tools of the last `tools/list` answer it received: every
+ *          answer replaces them. A request that FAILED can replace them too: the
+ *          SDK caches an answer before it returns it, and caching can throw after
+ *          the old checks are cleared (1.32: an `outputSchema` its validator
+ *          cannot compile). The library cannot see inside the SDK, but it sends
+ *          every list request it makes. So it counts them:
+ *
+ *   - a request is OUT from the moment it is sent until it settles, because the
+ *     SDK replaces its checks before the library sees the answer;
+ *   - each request that settles, answered or failed, starts a new GENERATION.
+ *
+ * The SDK holds the checks of a listing's one answer only while the generation
+ * that answer settled at is the latest and no request is out. The SDK keeps one
+ * set of checks per client, so there is one count per connection object: every
+ * `mcpClient` over the same client shares it (`listingsOf`). A `tools/list`
+ * request the library did not send — your own code calling `listTools` on a
+ * client passed as `connection`, or that client's own automatic refresh
+ * (`listChanged.tools` with `autoRefresh`) — is not counted: the library cannot
+ * see it, and a tool it handed out goes on leaving its checks to an SDK that no
+ * longer holds them. That limit is documented, and pinned by
+ * `test/mcp/listingKeepsChecks.limits.test.ts`.
+ */
+/** One settled `tools/list` request's answer, and the generation it settled at. */
+export interface SettledListing<T> {
+    readonly answer: T;
+    readonly generation: number;
+}
+/** The `tools/list` requests one connection has out, and the generations they settled at. */
+export declare class ListingGenerations {
+    private settled;
+    private out;
+    /**
+     * Send one `tools/list` request with `send`, counted as out from the moment it
+     * is sent until it settles. Settling starts a new generation, answered or not.
+     *
+     * @throws whatever `send` rejects with, as it rejected
+     */
+    ask<T>(send: () => Promise<T>): Promise<SettledListing<T>>;
+    /** True while `generation` is the latest settled one and no request is out. */
+    isLatest(generation: number): boolean;
+    private settle;
+}
+/**
+ * The count for `connection`: the same one for every `mcpClient` that adapts
+ * the same client, because the SDK keeps one set of checks per client and a
+ * listing by any of them replaces it.
+ */
+export declare function listingsOf(connection: object): ListingGenerations;
+//# sourceMappingURL=listingGenerations.d.ts.map

package/dist/types/mcp/listingGenerations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listingGenerations.d.ts","sourceRoot":"","sources":["../../../src/mcp/listingGenerations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,mFAAmF;AACnF,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,6FAA6F;AAC7F,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,GAAG,CAAK;IAEhB;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAWhE,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAIrC,OAAO,CAAC,MAAM;CAKf;AAKD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAOjE"}

package/dist/types/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,4 +68,19 @@ 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'>;
 //# sourceMappingURL=mcpClient.d.ts.map

package/dist/types/mcp/mcpClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../src/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAKH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAEhB,oBAAoB,EAKrB,MAAM,YAAY,CAAC;AAiCpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CA8DjG"}
+{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../src/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAEV,SAAS,EACT,gBAAgB,EAEhB,oBAAoB,EAEpB,aAAa,EAId,MAAM,YAAY,CAAC;AAqCpB,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAkBzB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CAEjG;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAEpE;AAsnBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAuB1F"}

package/dist/types/mcp/mockMcpClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mockMcpClient.d.ts","sourceRoot":"","sources":["../../../src/mcp/mockMcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGjF,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,KAC5D,OAAO,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC;mFAC+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;CACtD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAqCtE"}
+{"version":3,"file":"mockMcpClient.d.ts","sourceRoot":"","sources":["../../../src/mcp/mockMcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAIpB,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,KAC5D,OAAO,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC;mFAC+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;CACtD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAgDtE"}

package/dist/types/mcp/pool/boundTool.d.ts

@@ -0,0 +1,59 @@
+/**
+ * boundTool — a tool bound to its conversation, the list it came from and that
+ * list's generation, re-checked after every wait and at the send gate.
+ *
+ * Pattern: the shape every MCP tool takes (`mcpClient.ts` · `mcpToolShape`) +
+ *          one `execute` that runs the five steps of § 6.3.
+ * Role:    A bound tool carries its BINDING: the key it was listed for; the
+ *          context it was listed in (per client, the configuration; shared, the
+ *          entry's context); the list it came from (per client, the client
+ *          incarnation; shared, the entry); and that list's generation. Its
+ *          `execute`:
+ *
+ *   1. checks that the calling run's caller identity encodes to its key —
+ *      otherwise `identity-mismatch`, nothing sent;
+ *   2. checks its binding is current — otherwise `stale-tools`, nothing sent;
+ *   3. is admitted against `maxOperations` and takes a lease on its key's
+ *      client, opening one from a plan resolved now when the key has none. A
+ *      client whose plan's context differs from the binding's refuses with
+ *      `binding-changed` (the client stays for the next list). A client that is
+ *      not the incarnation the tool was listed from is checked against its OWN
+ *      fresh list — the call goes on only if that list holds the same
+ *      definition, compared as canonical JSON; otherwise `stale-tools`. Under
+ *      the app's sharing contract, a replacement whose context matches uses the
+ *      shared entry as it stands;
+ *   4. after every wait, checks step 2 again — and asks the app's `share`
+ *      again, so a changed authorization name refuses it (`binding-changed`);
+ *   5. sends through the send gate (`mcp/requestGuard.ts`), asked at every
+ *      boundary the request crosses — before every attempt, after a credential
+ *      arrives, after signing — classifies the outcome (a server's 404 for the
+ *      session is `SessionExpiredError`; a handle this process lost is
+ *      `LocalSessionHandleLostError`; neither is repeated), files its use, and
+ *      releases its lease once the request's own work has settled.
+ *
+ * Never another conversation's connection: the binding is to the KEY, and a
+ * client of any other key never serves it.
+ */
+import type { Tool } from '../../tools/tools.js';
+import type { Definition } from './definitions.js';
+import { type PoolKey } from './identityKey.js';
+import type { Pool } from './pool.js';
+import { UseFacts } from './record.js';
+/** What a bound tool was listed under. */
+export interface Binding {
+    readonly key: PoolKey;
+    /** The definitions context: `pc:<configHash>` per client, `sh:<context>` shared. */
+    readonly context: string;
+    readonly shared: boolean;
+    /** The list it came from: an incarnation's own, or a shared entry's. */
+    readonly listId: string;
+    readonly generation: number;
+    /** Per client: the incarnation it was listed from. */
+    readonly clientId?: string;
+    readonly definition: Definition;
+}
+/** A callable tool for `binding`, shaped as every MCP tool is. */
+export declare function boundTool(pool: Pool, binding: Binding): Tool;
+/** A refusal's word on the record. */
+export declare function noteRefusal(facts: UseFacts, error: unknown): void;
+//# sourceMappingURL=boundTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"boundTool.d.ts","sourceRoot":"","sources":["../../../../src/mcp/pool/boundTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAwB,MAAM,sBAAsB,CAAC;AAMvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,0CAA0C;AAC1C,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAK5D;AAuKD,sCAAsC;AACtC,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAUjE"}

package/dist/types/mcp/pool/clientSet.d.ts

@@ -0,0 +1,74 @@
+/**
+ * clientSet — which clients the pool holds, and in which of its two sets.
+ *
+ * Pattern: two sets and their indexes, mutated only together.
+ * Role:    § 5.3 of the design. The OPEN set holds every client that counts
+ *          toward `maxClients` — opening, busy, idle, deferred, or an abandoned
+ *          open that has not settled. The ENDING set holds every client from the
+ *          decision to end it until that ending's work has settled, and counts
+ *          toward `maxEnding`. A client leaves the open set only into the ending
+ *          set — a lost handle too: its ending is its local close — or, when its
+ *          open failed and left nothing to end, by being dropped. So the pool
+ *          holds at most `maxClients + maxEnding` client objects.
+ *
+ * Each key has at most one CURRENT client — the one new leases go to. A client
+ * named by `terminate`, or whose session expired, stops being current at once
+ * while it stays in the open set, counted, until it can end.
+ *
+ * What the pool remembers of a key after its client left — the incarnation
+ * count and why the last one left — is bounded (`KEY_MEMORY`), least recently
+ * used forgotten first: after that a key's count starts again at 1. The record
+ * reads it; no binding depends on it.
+ */
+import type { EndReason, PooledClient } from './pooledClient.js';
+/** How many keys' incarnation counts the pool remembers. */
+export declare const KEY_MEMORY = 4096;
+/** Why a key's previous client left, as the record names it. */
+export type PreviousEnd = 'idle' | 'evicted' | 'expired' | 'handle-lost' | 'terminated';
+export declare class ClientSet {
+    private readonly open;
+    private readonly ending;
+    private readonly current;
+    private readonly perPrincipal;
+    private readonly memory;
+    /** Clients in the open set. */
+    get openCount(): number;
+    /** Clients in the ending set. */
+    get endingCount(): number;
+    /** Every client in the open set. */
+    openClients(): readonly PooledClient[];
+    /** Clients of the open set that count for `principal`. */
+    principalCount(principal: string): number;
+    /** The key's current client — opening or open, taking new leases — if it has one. */
+    currentFor(key: string): PooledClient | undefined;
+    /** The next incarnation number for `key`, and why its previous client left. */
+    nextIncarnation(key: string): {
+        readonly generation: number;
+        readonly previous?: PreviousEnd;
+    };
+    /** A new client joins the open set as its key's current client. */
+    admit(client: PooledClient): void;
+    /**
+     * The client stops taking new leases: its key has no current client until the
+     * next open, and that open's record says `why`. A client that is no longer
+     * its key's current one has already left it, so nothing is recorded again —
+     * a later client of the key keeps its own reason.
+     */
+    retire(client: PooledClient, why: PreviousEnd): void;
+    /** The client moves from the open set into the ending set. */
+    moveToEnding(client: PooledClient, why: PreviousEnd | undefined): void;
+    /** The client's ending settled: it leaves the ending set. */
+    ended(client: PooledClient): void;
+    /** The client leaves the open set without ending — a failed open, a lost handle. */
+    drop(client: PooledClient, why?: PreviousEnd): void;
+    /**
+     * The least recently used idle client of the open set — among those `pick`
+     * accepts — or `undefined` when every one is busy.
+     */
+    leastRecentlyUsedIdle(pick: (client: PooledClient) => boolean): PooledClient | undefined;
+    private leaveOpen;
+    private remember;
+}
+/** The record's `previous` for an end reason, when it names one. */
+export declare function previousOf(reason: EndReason): PreviousEnd | undefined;
+//# sourceMappingURL=clientSet.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clientSet.d.ts","sourceRoot":"","sources":["../../../../src/mcp/pool/clientSet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjE,4DAA4D;AAC5D,eAAO,MAAM,UAAU,OAAO,CAAC;AAE/B,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,YAAY,CAAC;AAQxF,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2B;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IAEvD,+BAA+B;IAC/B,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,iCAAiC;IACjC,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,oCAAoC;IACpC,WAAW,IAAI,SAAS,YAAY,EAAE;IAItC,0DAA0D;IAC1D,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIzC,qFAAqF;IACrF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIjD,+EAA+E;IAC/E,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAA;KAAE;IAQ9F,mEAAmE;IACnE,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAMjC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI;IAMpD,8DAA8D;IAC9D,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI;IAOtE,6DAA6D;IAC7D,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAIjC,oFAAoF;IACpF,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,IAAI;IAMnD;;;OAGG;IACH,qBAAqB,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,GAAG,YAAY,GAAG,SAAS;IASxF,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,QAAQ;CAYjB;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAarE"}