agentfootprint 12.1.0 → 12.2.0

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

@@ -15,5 +15,13 @@ 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';
 //# 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;AAGpG,OAAO,EAAE,0BAA0B,EAAE,KAAK,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAI7F,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,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/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,EAEV,SAAS,EACT,gBAAgB,EAEhB,oBAAoB,EAMrB,MAAM,YAAY,CAAC;AA8CpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CAoFjG"}
+{"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"}

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

@@ -0,0 +1,104 @@
+/**
+ * definitions — the tool lists a pool serves, and when each stops being served.
+ *
+ * Pattern: one list type, two owners — a client incarnation, or a shared entry.
+ * Role:    § 6 of the design. A definition is what one `tools/list` entry says:
+ *          name, description, input schema, and the declarations its `_meta`
+ *          carries. The executable half (the connection) is never shared.
+ *
+ *   - PER CLIENT (the default): a conversation's list is its own client's, and
+ *     it belongs to that client INCARNATION alone — a replacement client, even
+ *     one opened from the same plan, is a new session whose list may differ,
+ *     so it lists again.
+ *   - SHARED, only under the app's declared contract: one entry per context
+ *     (`plan.ts`), listed on the client of whichever conversation needs it,
+ *     bounded at `MAX_DEFINITION_ENTRIES` entries; a list longer than
+ *     `MAX_SHARED_TOOLS` is used by its own client and not shared.
+ *
+ * A list stops being served in four ways, plus a time limit: the configuration
+ * (a new context is a new list), the server's tools-changed notice, the app's
+ * `permissionsChanged`, and `toolsChanged`. Invalidation moves the list's
+ * GENERATION at once — every tool bound to an older one is refused — and marks
+ * it to be listed again. A lapsed time limit lists again at the next list, and
+ * moves the generation only if the new list differs. A generation counts within
+ * one list: a replacement client and a new entry start counts of their own, and
+ * a binding names the list it came from, so no number of an old list can match
+ * a new one. A listing still in flight when its list's generation moved is
+ * discarded, never written.
+ *
+ * Every list is a frozen plain-data copy (`mcp/plainData.ts` · `copyJsonObject`),
+ * written once per generation, by one listing at a time.
+ */
+import type { Tool } from '../../tools/tools.js';
+import type { McpListedTool } from '../types.js';
+/** One definition, frozen, and its canonical JSON — what "the same definition" compares. */
+export interface Definition {
+    readonly listed: McpListedTool;
+    readonly canonical: string;
+}
+/** A frozen copy of `listed`, or `undefined` when it is not plain JSON data. */
+export declare function definitionOf(listed: McpListedTool): Definition | undefined;
+/**
+ * One list: an incarnation's own or a shared entry. Its `id` is stable for its
+ * life; its `generation` moves on invalidation, and on a time-limit relisting
+ * that changed it.
+ */
+export declare class DefinitionList {
+    readonly id: string;
+    private current;
+    private tools;
+    /** Has any listing been written? */
+    private written;
+    /** 0 until the first listing is written. */
+    generation: number;
+    /** Invalidated: listed again before it is served. */
+    stale: boolean;
+    /** When it was last written, on the pool's clock. */
+    listedAt: number;
+    /** The listing in flight, joined by anyone who needs the same list. */
+    listing: Promise<void> | undefined;
+    /** Can it be served at `now`, as it stands? */
+    servable(now: number, ttlMs: number): boolean;
+    /**
+     * Invalidate: every older binding is refused, the next list lists again, and
+     * a listing in flight is discarded — even a first one, before anything was
+     * written. Generations only ever increase.
+     */
+    invalidate(): void;
+    /** The definition named `name`, at the current generation. */
+    definition(name: string): Definition | undefined;
+    /** The client's own wrapped tool named `name` (per-client lists only). */
+    tool(name: string): Tool | undefined;
+    /** Every definition, in listing order. */
+    all(): readonly Definition[];
+    /**
+     * Write a listing that began at generation `began`. Refused — `false`, nothing
+     * written — when the generation moved while it ran. A first write moves the
+     * generation to a number no binding has seen; a write after invalidation keeps
+     * the moved one; a time-limit rewrite moves it only when the list differs.
+     */
+    write(began: number, definitions: readonly Definition[], tools: readonly Tool[] | undefined, now: number): boolean;
+}
+/** A shared entry: a list and the tenant its context carries. */
+export interface SharedEntry {
+    readonly list: DefinitionList;
+    readonly tenant: string;
+}
+/**
+ * The shared definition entries, by context — bounded at
+ * `MAX_DEFINITION_ENTRIES`, the least recently used dropped first. A dropped
+ * entry's bindings are refused as stale: the entry they name is gone.
+ */
+export declare class SharedDefinitions {
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(maxEntries?: number);
+    get size(): number;
+    /** The entry for `context`, created empty when there is none; most recently used. */
+    entryFor(context: string, tenant: string): SharedEntry;
+    /** The entry for `context` if it still exists — never created. */
+    peek(context: string): SharedEntry | undefined;
+    /** Invalidate every entry `matches` selects. */
+    invalidate(matches: (entry: SharedEntry) => boolean): void;
+}
+//# sourceMappingURL=definitions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../../../src/mcp/pool/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,4FAA4F;AAC5F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,GAAG,SAAS,CAI1E;AAaD;;;;GAIG;AACH,qBAAa,cAAc;IACzB,QAAQ,CAAC,EAAE,SAAqB;IAChC,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,KAAK,CAAwC;IACrD,oCAAoC;IACpC,OAAO,CAAC,OAAO,CAAS;IACxB,4CAA4C;IAC5C,UAAU,SAAK;IACf,qDAAqD;IACrD,KAAK,UAAS;IACd,qDAAqD;IACrD,QAAQ,SAAK;IACb,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;IAEnC,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAI7C;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAKlB,8DAA8D;IAC9D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIhD,0EAA0E;IAC1E,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIpC,0CAA0C;IAC1C,GAAG,IAAI,SAAS,UAAU,EAAE;IAI5B;;;;;OAKG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,SAAS,UAAU,EAAE,EAClC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,EAClC,GAAG,EAAE,MAAM,GACV,OAAO;CAYX;AAUD,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAFvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;gBAE7B,UAAU,GAAE,MAA+B;IAExE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW;IAatD,kEAAkE;IAClE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAI9C,gDAAgD;IAChD,UAAU,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,GAAG,IAAI;CAG3D"}

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

@@ -0,0 +1,77 @@
+/**
+ * errors — the pool's two refusals, each one fixed sentence.
+ *
+ * Pattern: typed errors whose message reaches the model and whose fields reach
+ *          the app.
+ * Role:    A refusal comes before the `tools/call` is sent, and says so
+ *          (`sent: false`) for the record of what that attempt did. Control
+ *          requests made on the way — the `initialize` of a replacement client,
+ *          a revalidating `tools/list` — may already have reached the server;
+ *          `sent` describes the `tools/call` only.
+ *
+ * A message is a fixed sentence per reason. It names no identity, no key, no
+ * session and no count: the counts ride typed fields the app reads, and the
+ * original error of a failed open rides `cause`, for the app, never composed
+ * into the message.
+ */
+/** Why a pool refused, by name. */
+export type McpPoolRefusal = 'no-identity' | 'incomplete-identity' | 'identity-mismatch' | 'init-timeout' | 'init-failed' | 'stale-tools' | 'binding-changed' | 'request-unmatched' | 'lease-expired' | 'closed';
+/** The sentence each refusal reaches the model as. */
+export declare const MCP_POOL_REFUSAL_SENTENCES: Readonly<Record<McpPoolRefusal, string>>;
+/**
+ * The pool refused before the `tools/call` was sent — by `reason`.
+ *
+ * `init-failed` keeps the open's own error as `cause`, for the app; its text is
+ * never in the message.
+ */
+export declare class McpPoolRefusedError extends Error {
+    readonly reason: McpPoolRefusal;
+    /** The pool's name: the server. */
+    readonly server: string;
+    readonly code: "ERR_MCP_POOL_REFUSED";
+    /** The `tools/call` was not sent. Control requests on the way may have been. */
+    readonly sent: false;
+    constructor(reason: McpPoolRefusal, 
+    /** The pool's name: the server. */
+    server: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+/** Which budget was full. */
+export type McpPoolLimit = 'pool' | 'principal' | 'ending' | 'operations';
+/** The one sentence a full pool reaches the model as. */
+export declare const POOL_FULL_SENTENCE = "The connection pool for this server was full, so the tool call was not sent.";
+/**
+ * A budget was full, so the work was refused at once — there is no queue. Its
+ * scope is the `tools/call`, as with `sent: false`. The counts ride typed fields.
+ */
+export declare class PoolFullError extends Error {
+    /** The pool's name: the server. */
+    readonly server: string;
+    /** Which budget was full. */
+    readonly limit: McpPoolLimit;
+    /** That budget's size. */
+    readonly max: number;
+    /** Busy clients when it was refused. */
+    readonly busy: number;
+    /** Clients being ended when it was refused. */
+    readonly ending: number;
+    /** Operations charged when it was refused. */
+    readonly operations: number;
+    readonly code: "ERR_MCP_POOL_FULL";
+    readonly sent: false;
+    constructor(
+    /** The pool's name: the server. */
+    server: string, 
+    /** Which budget was full. */
+    limit: McpPoolLimit, 
+    /** That budget's size. */
+    max: number, 
+    /** Busy clients when it was refused. */
+    busy: number, 
+    /** Clients being ended when it was refused. */
+    ending: number, 
+    /** Operations charged when it was refused. */
+    operations: number);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/mcp/pool/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,mCAAmC;AACnC,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,qBAAqB,GACrB,mBAAmB,GACnB,cAAc,GACd,aAAa,GACb,aAAa,GACb,iBAAiB,GACjB,mBAAmB,GACnB,eAAe,GACf,QAAQ,CAAC;AAEb,sDAAsD;AACtD,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAmB9E,CAAC;AAEH;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAM1C,QAAQ,CAAC,MAAM,EAAE,cAAc;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAPzB,QAAQ,CAAC,IAAI,yBAAmC;IAChD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,QAAkB;gBAGpB,MAAM,EAAE,cAAc;IAC/B,mCAAmC;IAC1B,MAAM,EAAE,MAAM,EACvB,OAAO,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAO7C;AAED,6BAA6B;AAC7B,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;AAE1E,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,iFACiD,CAAC;AAEjF;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAKpC,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,YAAY;IAC5B,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM;IAf7B,QAAQ,CAAC,IAAI,sBAAgC;IAC7C,QAAQ,CAAC,IAAI,QAAkB;;IAG7B,mCAAmC;IAC1B,MAAM,EAAE,MAAM;IACvB,6BAA6B;IACpB,KAAK,EAAE,YAAY;IAC5B,0BAA0B;IACjB,GAAG,EAAE,MAAM;IACpB,wCAAwC;IAC/B,IAAI,EAAE,MAAM;IACrB,+CAA+C;IACtC,MAAM,EAAE,MAAM;IACvB,8CAA8C;IACrC,UAAU,EAAE,MAAM;CAK9B"}

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

@@ -0,0 +1,58 @@
+/**
+ * identityKey — the conversation a pooled client belongs to, as one key.
+ *
+ * Pattern: the library's one identity encoding, never a second.
+ * Role:    The client key is `identityNamespace` of the identity the CALLER
+ *          named — each field through `encodeIdentityField`, the encoding the
+ *          memory layer calls the tenant boundary. It is injective: tenant
+ *          `acme/hr` with principal `alice` and tenant `acme` with principal
+ *          `hr/alice` are two keys, and an absent field and a field named `_`
+ *          are two keys. A pool is one server, so the key needs no server
+ *          segment, and two pools never share a client.
+ *
+ * Two doors only: the run's caller identity (`ToolDispatchContext.callerIdentity`,
+ * `ToolExecutionContext.identity`) and the identity app code passes to `acquire`
+ * and `terminate`. Never tool arguments, model output, a message, a request
+ * body, or a `sessionId` alone. No identity value is ever written to an error,
+ * an event or a report: the wire carries `keyHash`, the tool-session digest.
+ */
+import type { McpPoolIdentity } from './options.js';
+/** One conversation's key, and the coarser keys its budgets count by. */
+export interface PoolKey {
+    /** `identityNamespace` of the identity — the client key. */
+    readonly key: string;
+    /** The tenant and principal segments — what `maxClientsPerPrincipal` counts by. */
+    readonly principal: string;
+    /** The tenant segment — always part of a shared definitions context. */
+    readonly tenant: string;
+    /** The digest the record carries in the key's place. */
+    readonly keyHash: string;
+    /** The identity itself, as a frozen copy — what the transport factory and `share` are asked with. */
+    readonly identity: McpPoolIdentity;
+}
+/** What an identity must carry. */
+export interface IdentityRules {
+    readonly requirePrincipal: boolean;
+    readonly requireTenant: boolean;
+}
+/**
+ * The key for `identity`, or why there is none: `'no-identity'` when nothing was
+ * named (a derived identity counts as none), `'incomplete-identity'` when it
+ * lacks a `conversationId`, a required `principal` or a required `tenant`, or a
+ * field is not a string.
+ */
+export declare function poolKeyOf(identity: unknown, rules: IdentityRules): PoolKey | 'no-identity' | 'incomplete-identity';
+/**
+ * Which keys a scope names. The tenant is matched exactly, always — an absent
+ * tenant is the absent segment, never a wildcard, because the tenant is the
+ * boundary. A scope that names a `conversationId` names exactly that one
+ * conversation (an absent principal is then the absent segment, as in the key).
+ * A scope without one names every conversation of its principal, and a scope
+ * without a principal either names every conversation of its tenant.
+ */
+export declare function scopeMatcher(scope: {
+    readonly tenant?: string;
+    readonly principal?: string;
+    readonly conversationId?: string;
+}): (key: PoolKey) => boolean;
+//# sourceMappingURL=identityKey.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"identityKey.d.ts","sourceRoot":"","sources":["../../../../src/mcp/pool/identityKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,yEAAyE;AACzE,MAAM,WAAW,OAAO;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qGAAqG;IACrG,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,aAAa,GACnB,OAAO,GAAG,aAAa,GAAG,qBAAqB,CAiCjD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAe5B"}

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

@@ -0,0 +1,37 @@
+/**
+ * lease — the app's explicit, bounded hold on one conversation's client.
+ *
+ * Pattern: a handle that releases at most once, by hand or by `await using`.
+ * Role:    § 3.3 and § 5.2 of the design. `acquire` is for code that drives a
+ *          sequence itself, or a host that must keep a conversation's client
+ *          from eviction for a whole turn (it holds one around `agent.run()`, and
+ *          the provider then finds the same client). It is the only way to
+ *          protect a client between calls: there is no hidden grace period.
+ *
+ * The `acquire` that opened it was the operation; the held lease is not one. It
+ * is bounded by `maxLeaseMs`: past it, it is revoked at the next pool
+ * interaction and reported, and its next use throws `lease-expired`. Calls
+ * already in flight keep their own leases until they settle.
+ */
+import type { Tool } from '../../tools/tools.js';
+import type { PoolKey } from './identityKey.js';
+import type { HeldLease, Pool } from './pool.js';
+/** The app's hold on one conversation's client. Release it — or `await using` it. */
+export interface McpPoolLease extends AsyncDisposable {
+    /**
+     * This conversation's tools, bound to it. A call through one needs the
+     * conversation's identity on its context (`ToolExecutionContext.identity`);
+     * the agent puts it there for a run that named one.
+     *
+     * @throws `McpPoolRefusedError` (`lease-expired`) once the lease was revoked
+     *   or released; what a listing throws otherwise
+     */
+    tools(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<readonly Tool[]>;
+    /** Release the hold. Idempotent. */
+    release(): void;
+}
+/** The lease handle for `held`, on `key`'s client. */
+export declare function leaseHandle(pool: Pool, key: PoolKey, held: HeldLease): McpPoolLease;
+//# sourceMappingURL=lease.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../../../../src/mcp/pool/lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjD,qFAAqF;AACrF,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAC7E,oCAAoC;IACpC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,YAAY,CA0BnF"}