agentfootprint 12.0.1 → 12.2.0

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

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

package/dist/esm/mcp/callChecks.js

@@ -0,0 +1,237 @@
+/**
+ * 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.
+ */
+/** JSON-RPC's codes for the two errors the SDK raises here. */
+const INVALID_REQUEST = -32600;
+const INVALID_PARAMS = -32602;
+/**
+ * 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 function callCheckKit(server, listings, given, loaded = {}) {
+    const Default = typeof loaded.Validator === 'function' ? loaded.Validator : undefined;
+    let created;
+    return {
+        server,
+        validator: () => {
+            if (given !== undefined)
+                return given;
+            if (Default === undefined)
+                return undefined;
+            created ??= new Default();
+            return created;
+        },
+        ...(typeof loaded.McpError === 'function' && { McpError: loaded.McpError }),
+        listings,
+    };
+}
+/**
+ * `value` as a validator, or `undefined` when it was not given. Refused by name
+ * when it is something else, before anything connects.
+ */
+export function validatorOption(value, at) {
+    if (value === undefined)
+        return undefined;
+    const getValidator = value !== null && (typeof value === 'object' || typeof value === 'function')
+        ? value.getValidator
+        : undefined;
+    if (typeof getValidator === 'function')
+        return value;
+    throw new TypeError(`${at}: \`jsonSchemaValidator\` has no \`getValidator\` method. Pass a JSON Schema ` +
+        "validator as the MCP SDK's `Client` takes one: `new AjvJsonSchemaValidator()` from " +
+        "'@modelcontextprotocol/sdk/validation/ajv', or the one your client uses.");
+}
+/**
+ * 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 function checksFor(listed, kit, generation) {
+    const schema = ownObject(listed, 'outputSchema');
+    const taskRequired = ownValue(ownObject(listed, 'execution'), 'taskSupport') === 'required';
+    if (schema === undefined && !taskRequired)
+        return undefined;
+    let compiled;
+    return {
+        server: kit.server,
+        tool: listed.name,
+        taskRequired,
+        outputDeclared: schema !== undefined,
+        heldBySdk: () => generation !== undefined && kit.listings.isLatest(generation),
+        validate: () => {
+            if (schema !== undefined)
+                compiled ??= kit.validator()?.getValidator(schema);
+            return compiled;
+        },
+        fail: (code, message) => kit.McpError !== undefined
+            ? new kit.McpError(code, message)
+            : new McpErrorShape(code, message),
+    };
+}
+/**
+ * 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 function outputUnchecked(checks) {
+    return checks.outputDeclared && !checks.taskRequired && checks.validate() === undefined;
+}
+/** The SDK's task refusal, word for word, before anything is sent. */
+export function refuseRequiredTask(checks) {
+    if (!checks.taskRequired)
+        return;
+    throw checks.fail(INVALID_REQUEST, `Tool "${checks.tool}" requires task-based execution. ` +
+        'Use client.experimental.tasks.callToolStream() instead.');
+}
+/**
+ * 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 function checkOutput(checks, result) {
+    if (!checks.outputDeclared)
+        return;
+    const validate = checks.validate();
+    if (validate === undefined)
+        throw new McpOutputUncheckedError(checks.server, checks.tool, true);
+    const structured = ownValue(result, 'structuredContent');
+    if (!structured && !ownValue(result, 'isError')) {
+        throw checks.fail(INVALID_REQUEST, `Tool ${checks.tool} has an output schema but did not return structured content`);
+    }
+    if (!structured)
+        return;
+    let mismatch;
+    try {
+        const verdict = validate(structured);
+        if (!verdict.valid) {
+            mismatch = `Structured content does not match the tool's output schema: ${verdict.errorMessage}`;
+        }
+    }
+    catch (error) {
+        throw checks.fail(INVALID_PARAMS, `Failed to validate structured content: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (mismatch !== undefined)
+        throw checks.fail(INVALID_PARAMS, mismatch);
+}
+/**
+ * The SDK's `McpError`, for an arm that cannot reach the class itself (`sdk`,
+ * `connection`): the same name, `code`, `data` and message, so a caller that
+ * branches on those handles it as it handles the SDK's.
+ */
+class McpErrorShape extends Error {
+    code;
+    data;
+    constructor(code, message) {
+        super(`MCP error ${code}: ${message}`);
+        this.code = code;
+        this.data = undefined;
+        this.name = 'McpError';
+    }
+}
+/** What the refusal says happened, refused before sending. */
+const NOT_SENT = 'was not sent. The tool declares an outputSchema, the MCP SDK no longer holds the checks of ' +
+    'the tool list it came from (that list was paged, a later list replaced it, or a list is ' +
+    'being read)';
+/** What the refusal says happened, refused once the answer was in. */
+const SENT_UNREAD = 'was sent, and its answer is not returned. The tool declares an outputSchema, a tool list ' +
+    'was read while the call was out (so the MCP SDK may not have checked the answer against ' +
+    "this tool's schema)";
+/**
+ * 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 class McpOutputUncheckedError extends Error {
+    server;
+    tool;
+    sent;
+    code = 'ERR_MCP_OUTPUT_UNCHECKED';
+    reason = 'output-unchecked';
+    constructor(server, tool, 
+    /** Whether the request left the client: `false` when the refusal came before it. */
+    sent) {
+        super(`mcpClient[${server}]: the call to '${tool}' ${sent ? SENT_UNREAD : NOT_SENT}, and this ` +
+            'connection has no JSON Schema validator to check its output with. Pass ' +
+            '`jsonSchemaValidator` to mcpClient: the validator your client uses.');
+        this.server = server;
+        this.tool = tool;
+        this.sent = sent;
+        this.name = 'McpOutputUncheckedError';
+    }
+}
+/** An own data property, never an accessor's result; `undefined` otherwise. */
+function ownValue(value, key) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined && 'value' in descriptor ? descriptor.value : undefined;
+}
+/** An own data property that is a plain object (not an array); `undefined` otherwise. */
+function ownObject(value, key) {
+    const found = ownValue(value, key);
+    return found !== null && typeof found === 'object' && !Array.isArray(found)
+        ? found
+        : undefined;
+}
+//# sourceMappingURL=callChecks.js.map

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

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

package/dist/esm/mcp/callLifetime.js

@@ -56,6 +56,7 @@ import { isDevMode, UnknownEffectError } from 'footprintjs';
 import { eitherSignal, linkedController } from '../lib/abort.js';
 import { requestEvidenceOf } from '../tools/requestEvidence.js';
 import { markParams } from './callMarker.js';
+import { callGuardOf } from './requestGuard.js';
 /**
  * Open one call.
  *
@@ -79,8 +80,10 @@ export function openCall(params, ctx, clientSignal, ledger, server) {
     const sentBefore = ledger?.toolCallsSent ?? 0;
     // Every call on a watched connection gets a marker, ticket or not: under
     // 'app-authorized' its request must be matched to it either way. The call
-    // holds its entry, so what it reads survives the connection closing.
-    const issued = ledger?.issue(ticket);
+    // holds its entry, so what it reads survives the connection closing. A call
+    // a pool made carries its send gate too (`requestGuard.ts`), asked at every
+    // boundary its request crosses.
+    const issued = ledger?.issue(ticket, callGuardOf(ctx));
     let mayHaveRun = false;
     return {
         params: issued === undefined ? params : markParams(params, issued.marker),

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

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

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

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

package/dist/esm/mcp/clientPort.js

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

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

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

package/dist/esm/mcp/gatewayTransport.js

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

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

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

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

@@ -13,4 +13,14 @@ 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';