agentfootprint 12.0.1 → 12.2.0

package/dist/esm/mcp/index.js

@@ -18,4 +18,19 @@ export { retryingFetch } from './throttleRetry.js';
 // A call under 'app-authorized' that a connection cannot honour is refused
 // before it is sent, with a typed reason.
 export { McpReplayUnavailableError } from './replayUnavailable.js';
+// A tool list that could not be read to its end (past 100 requests, or a cursor
+// sent twice) is refused with this error and a typed reason, never cut short.
+export { McpToolListIncompleteError } from './toolList.js';
+// A tool whose list the SDK no longer holds, and whose output this connection
+// 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"}
+{"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/listingGenerations.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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;

package/dist/esm/mcp/listingGenerations.js

@@ -0,0 +1,75 @@
+/**
+ * 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`.
+ */
+/** The `tools/list` requests one connection has out, and the generations they settled at. */
+export class ListingGenerations {
+    settled = 0;
+    out = 0;
+    /**
+     * 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
+     */
+    async ask(send) {
+        this.out += 1;
+        try {
+            const answer = await send();
+            return { answer, generation: this.settle() };
+        }
+        catch (error) {
+            this.settle();
+            throw error;
+        }
+    }
+    /** True while `generation` is the latest settled one and no request is out. */
+    isLatest(generation) {
+        return this.out === 0 && this.settled === generation;
+    }
+    settle() {
+        this.out -= 1;
+        this.settled += 1;
+        return this.settled;
+    }
+}
+/** One count per connection object, held only as long as the connection is. */
+const BY_CONNECTION = new WeakMap();
+/**
+ * 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 function listingsOf(connection) {
+    let listings = BY_CONNECTION.get(connection);
+    if (listings === undefined) {
+        listings = new ListingGenerations();
+        BY_CONNECTION.set(connection, listings);
+    }
+    return listings;
+}
+//# sourceMappingURL=listingGenerations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"listingGenerations.js","sourceRoot":"","sources":["../../../src/mcp/listingGenerations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAQH,6FAA6F;AAC7F,MAAM,OAAO,kBAAkB;IACrB,OAAO,GAAG,CAAC,CAAC;IACZ,GAAG,GAAG,CAAC,CAAC;IAEhB;;;;;OAKG;IACH,KAAK,CAAC,GAAG,CAAI,IAAsB;QACjC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACd,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;YAC5B,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,QAAQ,CAAC,UAAkB;QACzB,OAAO,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,KAAK,UAAU,CAAC;IACvD,CAAC;IAEO,MAAM;QACZ,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACd,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,aAAa,GAAG,IAAI,OAAO,EAA8B,CAAC;AAEhE;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,UAAkB;IAC3C,IAAI,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC7C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,QAAQ,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACpC,aAAa,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,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'>;