agentfootprint 12.0.0 → 12.1.0

package/dist/types/identity/types.d.ts

@@ -79,6 +79,18 @@ export interface CredentialRequest {
     readonly request?: RequestContext;
     /** Force a fresh authorization, bypassing any cached/refresh token. */
     readonly forceReauth?: boolean;
+    /**
+     * The abort signal of the request this credential is for — present when the
+     * caller has one, as `gatewayTransport` does for every request it vends for.
+     *
+     * A provider that does work of its own (a token endpoint, a vault, an SDK
+     * call) should hand it on and stop when it fires: the request it would serve
+     * has been cancelled or ran out of time. Ignoring it is safe, never a leak:
+     * the caller stops waiting at the abort and never uses a credential that
+     * arrives after it. It is a live object, not data: never put it in a cache
+     * key, a log line or an error message.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * A credential, ready to apply to a downstream request. It carries its `kind`

package/dist/types/identity/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/identity/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;oFACoF;AACpF,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,+BAA+B,CAAC;AAElF;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAClE;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,gBAAgB,GAAG,CAAC,IAAI,gBAAgB,CAE7E;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;0DAEsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,IAAI,kBAAkB,CAanE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/identity/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;oFACoF;AACpF,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,+BAA+B,CAAC;AAElF;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAClE;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,gBAAgB,GAAG,CAAC,IAAI,gBAAgB,CAE7E;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;0DAEsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,IAAI,kBAAkB,CAanE"}

package/dist/types/identity/withCredentialRetry.d.ts

@@ -25,6 +25,11 @@
  *     `issued` is success; `authorization-required` is a HUMAN flow (3LO
  *     consent), not a transient fault — retrying it would hammer the IdP
  *     without the user having authorized anything.
+ *   • The request's `signal` (`CredentialRequest.signal`) is passed through to
+ *     the wrapped provider, ends the backoff wait, and is checked immediately
+ *     before every attempt, the first included: a request whose signal has
+ *     fired never asks the provider (again), and the call rejects with the
+ *     abort. An attempt already running is the provider's to stop.
  *   • After retries exhaust, the LAST error is rethrown — the call site
  *     behaves byte-identically to an unwrapped provider (fail-closed:
  *     `agentfootprint.credential.failed` emit + error tool result; the tool

package/dist/types/identity/withCredentialRetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withCredentialRetry.d.ts","sourceRoot":"","sources":["../../../src/identity/withCredentialRetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACvF,OAAO,KAAK,EAAE,kBAAkB,EAAuC,MAAM,YAAY,CAAC;AAE1F;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,gBAAgB,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE,0BAA+B,GACvC,kBAAkB,CAkCpB"}
+{"version":3,"file":"withCredentialRetry.d.ts","sourceRoot":"","sources":["../../../src/identity/withCredentialRetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAIH,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACvF,OAAO,KAAK,EAAE,kBAAkB,EAAuC,MAAM,YAAY,CAAC;AAE1F;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,gBAAgB,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE,0BAA+B,GACvC,kBAAkB,CAyCpB"}

package/dist/types/lib/boundedJson.d.ts

@@ -1,4 +1,31 @@
 export declare function ownData(value: unknown, allowed?: readonly string[]): Record<string, unknown>;
+/** A list as {@link readOwnList} read it. */
+export interface OwnList {
+    /** The entries read, in index order — a hole or an accessor entry is `undefined` (its getter never called). */
+    readonly entries: readonly unknown[];
+    /** How many entries the list holds past the bound — counted, never read. */
+    readonly unread: number;
+}
+/**
+ * Read a list the way {@link copyJson} reads an array — a plain array only
+ * (`Array.prototype`), its own `length`, the own DATA property at each index —
+ * as a READER that never refuses: at most `maxEntries` entries, a hole or an
+ * accessor entry read as `undefined` (the getter is never called), and the
+ * entries past the bound counted in `unread`, never walked. It never calls the
+ * list's iterator, a getter or a method, so a list from a record the library
+ * did not build cannot hide its entries or run code inside the reader.
+ * `undefined` when `value` is not a plain array: the caller says what that
+ * means for its own question, the conservative way.
+ *
+ * @example
+ * ```ts
+ * const list = ['a'];
+ * list.length = 3;                                                      // a hole at 1 and 2
+ * Object.defineProperty(list, Symbol.iterator, { value: function* () {} }); // never called
+ * readOwnList(list, 2); // { entries: ['a', undefined], unread: 1 }
+ * ```
+ */
+export declare function readOwnList(value: unknown, maxEntries: number): OwnList | undefined;
 /** JSON copy without invoking toJSON/getters or silently dropping data. */
 export declare function copyJson(value: unknown, maxBytes: number, freeze: boolean, maxDepth?: number): unknown;
 //# sourceMappingURL=boundedJson.d.ts.map

package/dist/types/lib/boundedJson.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boundedJson.d.ts","sourceRoot":"","sources":["../../../src/lib/boundedJson.ts"],"names":[],"mappings":"AAGA,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkB5F;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CACtB,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,QAAQ,SAAM,GACb,OAAO,CA0ET"}
+{"version":3,"file":"boundedJson.d.ts","sourceRoot":"","sources":["../../../src/lib/boundedJson.ts"],"names":[],"mappings":"AAGA,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkB5F;AAED,6CAA6C;AAC7C,MAAM,WAAW,OAAO;IACtB,+GAA+G;IAC/G,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAWnF;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CACtB,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,QAAQ,SAAM,GACb,OAAO,CA0ET"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"callChecks.d.ts","sourceRoot":"","sources":["../../../src/mcp/callChecks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,KAAK,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,KAAK,CAAC;AAMzF,mEAAmE;AACnE,KAAK,QAAQ,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhG;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,SAAS,IAAI,sBAAsB,GAAG,SAAS,CAAC;IAChD,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,sBAAsB,GAAG,SAAS,EACzC,MAAM,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GACzE,YAAY,CAcd;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAY9F;AAED,qFAAqF;AACrF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC;IACrB;;;OAGG;IACH,QAAQ,IAAI,QAAQ,GAAG,SAAS,CAAC;IACjC,gFAAgF;IAChF,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;CAC5C;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,UAAU,GAAG,SAAS,CAoBxB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAE3D;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAO3D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CA2B/E;AA+BD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAK9C,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,OAAO;IAPxB,QAAQ,CAAC,IAAI,6BAAuC;IACpD,QAAQ,CAAC,MAAM,qBAA+B;gBAGnC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;IACrB,oFAAoF;IAC3E,IAAI,EAAE,OAAO;CASzB"}

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

@@ -146,6 +146,14 @@ export type FetchLike = (input: string | URL | Request, init?: RequestInit) => P
  * Build the `fetch` the MCP SDK will use: one that vends a credential, applies
  * it to this one request, and keeps nothing.
  *
+ * The vend is a wait, and it honours the request's abort signal — resolved as
+ * fetch resolves it (`init.signal`, else a Request input's own): the provider
+ * is handed it (`CredentialRequest.signal`), the wait ends at the abort with the
+ * abort, and the signal is checked again once the credential arrives. So an
+ * aborted or timed-out request is never sent: the gateway stops waiting and
+ * never uses a late credential. A provider that ignores cancellation may still
+ * finish its own work.
+ *
  * Exported for tests — the secrecy invariant is asserted against this function
  * directly, because that is where a leak would happen and driving a whole SDK
  * to reach it would test less while looking like it tested more.

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;AACnF,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;AAED,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;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,mBAAmB,EAC9B,SAAS,GAAE,SAA6C,GACvD,SAAS,CAuBX"}
+{"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"}

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

@@ -13,5 +13,7 @@ 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 type { McpCallToolResult, McpClient, McpClientOptions, McpConnection, McpConnectionOptions, McpJsonSchemaValidator, McpSdk, McpGatewayTransport, McpHttpTransport, McpStdioTransport, McpTransport, McpSdkClient, McpServeOptions, McpServeHandle, McpServeTransport, McpHttpServeTransport, McpStdioServeTransport, McpSdkServer, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EACL,gBAAgB,EAChB,iCAAiC,EACjC,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACV,sBAAsB,EACtB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,yBAAyB,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpG,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,MAAM,EACN,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EACL,gBAAgB,EAChB,iCAAiC,EACjC,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACV,sBAAsB,EACtB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,yBAAyB,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAGpG,OAAO,EAAE,0BAA0B,EAAE,KAAK,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAI7F,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;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"}

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

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

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../src/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAKH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAEhB,oBAAoB,EAKrB,MAAM,YAAY,CAAC;AAiCpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CA8DjG"}
+{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../src/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;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"}

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

@@ -0,0 +1,91 @@
+/**
+ * toolList — every page of a server's `tools/list` answer, or a typed refusal
+ * that says the list is incomplete.
+ *
+ * Pattern: one bounded loop + one typed refusal.
+ * Role:    MCP pages a tool list: a page carries `nextCursor` while the server
+ *          has more, and the next page is asked for with `{ cursor }`. Reading
+ *          only the first page cut a paginating server's catalogue short in
+ *          silence — the agent saw part of it and nothing said so. This reads
+ *          until the server sends no cursor, within a bound, and when it cannot
+ *          finish the list it says why:
+ *
+ *   - `'page-limit'` — the list did not end within {@link MAX_TOOL_LIST_PAGES}
+ *     pages;
+ *   - `'cursor-repeated'` — a page named a cursor this listing already sent, so
+ *     following it would loop.
+ *
+ * The first page is asked exactly as before pagination was followed: no params
+ * (and, with no signal, no arguments at all). The client's signal rides every
+ * page in the SDK's trailing options, and it is checked immediately before each
+ * page is asked for and again when each answer arrives (`lib/abort.ts`): once
+ * it has fired, nothing more is asked for and no page is accepted, the last one
+ * included. An abort is the caller's word, so it wins over an incomplete list.
+ * What it cannot do is settle a page a connection that ignores the signal is
+ * still holding: that promise settles when the connection says.
+ *
+ * Every page request is counted from the moment it is sent until it settles
+ * (`listingGenerations.ts`): the MCP SDK's `Client` replaces its per-tool call
+ * checks with each answer, so a tool's checks depend on which answer is the
+ * latest (`callChecks.ts`).
+ */
+import type { Tool } from '../tools/tools.js';
+import type { ListingGenerations } from './listingGenerations.js';
+import type { McpConnection, McpListedTool } from './types.js';
+/**
+ * The most `tools/list` requests one listing sends. A bound on REQUESTS, not on
+ * the catalogue's size: a page may hold any number of tools. A server that
+ * keeps paging past it is reported as incomplete rather than read without end.
+ */
+export declare const MAX_TOOL_LIST_PAGES = 100;
+/** Why a server's tool list could not be read to its end. */
+export type McpToolListIncompleteReason = 'page-limit' | 'cursor-repeated';
+/** What a listing read: every tool its pages held, how many pages, and whether it ended. */
+export interface ToolListing {
+    readonly tools: readonly McpListedTool[];
+    readonly pages: number;
+    /**
+     * For a list read in ONE answer, the generation that answer settled at: the
+     * MCP SDK's `Client` holds its tools' checks while it stays the latest
+     * (`listingGenerations.ts`). Absent for a paged list: no one answer holds all
+     * of its tools.
+     */
+    readonly generation?: number;
+    /** Absent when the server's list ended: the last page carried no cursor. */
+    readonly incomplete?: McpToolListIncompleteReason;
+}
+/**
+ * Read the server's tool list, page by page, until a page carries no cursor —
+ * or until it cannot be finished, which the result says (`incomplete`).
+ *
+ * @param listings the connection's count of list requests, which every page
+ *   request joins (`listingGenerations.ts`)
+ * @throws the abort, when `signal` has fired before a page is asked for or by
+ *   the time its answer arrives; and whatever the connection rejects a page
+ *   with, as it always did
+ */
+export declare function listEveryPage(connection: McpConnection, signal: AbortSignal | undefined, listings: ListingGenerations): Promise<ToolListing>;
+/**
+ * A server's tool list that could not be read to its end. `tools()` and
+ * `refresh()` reject with it rather than return a list cut short: an agent
+ * handed part of a catalogue cannot know what it was not offered.
+ *
+ * `tools` holds what WAS listed — wrapped and callable, exactly as `tools()`
+ * would have returned them — for a caller that decides to use an incomplete
+ * list knowingly. Names the server, the reason and the count, never a cursor.
+ */
+export declare class McpToolListIncompleteError extends Error {
+    readonly reason: McpToolListIncompleteReason;
+    readonly server: string;
+    /** The pages read before the listing stopped. */
+    readonly pages: number;
+    /** The tools those pages listed, in page order. */
+    readonly tools: readonly Tool[];
+    readonly code: "ERR_MCP_TOOL_LIST_INCOMPLETE";
+    constructor(reason: McpToolListIncompleteReason, server: string, 
+    /** The pages read before the listing stopped. */
+    pages: number, 
+    /** The tools those pages listed, in page order. */
+    tools: readonly Tool[]);
+}
+//# sourceMappingURL=toolList.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"toolList.d.ts","sourceRoot":"","sources":["../../../src/mcp/toolList.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,6DAA6D;AAC7D,MAAM,MAAM,2BAA2B,GAAG,YAAY,GAAG,iBAAiB,CAAC;AAE3E,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,2BAA2B,CAAC;CACnD;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,aAAa,EACzB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,WAAW,CAAC,CA0BtB;AAwBD;;;;;;;;GAQG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAIjD,QAAQ,CAAC,MAAM,EAAE,2BAA2B;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE;IARjC,QAAQ,CAAC,IAAI,iCAA2C;gBAG7C,MAAM,EAAE,2BAA2B,EACnC,MAAM,EAAE,MAAM;IACvB,iDAAiD;IACxC,KAAK,EAAE,MAAM;IACtB,mDAAmD;IAC1C,KAAK,EAAE,SAAS,IAAI,EAAE;CASlC"}

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

@@ -307,6 +307,25 @@ export interface McpClientOptions {
      * @see McpSdk for the two static imports that produce it.
      */
     readonly sdk?: McpSdk;
+    /**
+     * The JSON Schema validator a tool's `outputSchema` is checked with — the MCP
+     * SDK's own validator interface (`new AjvJsonSchemaValidator()` from
+     * `@modelcontextprotocol/sdk/validation/ajv`, `new CfWorkerJsonSchemaValidator()`,
+     * or your own).
+     *
+     * Why it exists: the SDK's `Client` checks a tool's output only for the tools
+     * of its most recent `tools/list` answer, so every tool the library hands out
+     * carries its own checks, and runs them whenever the SDK no longer holds its
+     * list: a paged list, a list a later answer replaced, a call made while a list
+     * is read — of the lists `tools()` and `refresh()` read (see
+     * `McpClient.tools()`; the client the library builds here never lists by
+     * itself). The client the library builds is handed this same validator, so
+     * one validator checks every call. Omit it and the library uses the SDK's
+     * default, loaded with the SDK itself; with `sdk`, where the library never
+     * touches its Node loader, such a call to a tool that declares an
+     * `outputSchema` is refused (`McpOutputUncheckedError`) unless you pass one.
+     */
+    readonly jsonSchemaValidator?: McpJsonSchemaValidator;
     /** @see McpConnectionOptions — never set on this arm. */
     readonly connection?: undefined;
     /**
@@ -346,10 +365,35 @@ export interface McpConnectionOptions {
     /**
      * A connection you already opened. The library never calls `connect()` on it;
      * `close()` on the returned client closes it exactly once.
+     *
+     * Leave its tool discovery to `mcpClient`: the per-tool checks hold only for
+     * the lists `tools()` and `refresh()` read (see `McpClient.tools()`). Do not
+     * let the SDK client refresh itself (`listChanged.tools` with `autoRefresh`,
+     * which is on by default once `listChanged.tools` is given): set
+     * `autoRefresh: false` and call `refresh()` from `onChanged`, or give
+     * `mcpClient` a connection of its own.
      */
     readonly connection: McpConnection;
     /** Abort the list / call paths. Rides the SDK's request options. */
     readonly signal?: AbortSignal;
+    /**
+     * The JSON Schema validator your client checks tool output with — pass the
+     * SAME one you gave its constructor (`jsonSchemaValidator`), or the SDK's
+     * default, `new AjvJsonSchemaValidator()`.
+     *
+     * The SDK's `Client` checks a tool's output only for the tools of its most
+     * recent `tools/list` answer, so the library checks a tool itself, with this,
+     * whenever the SDK no longer holds its list: a paged list, a list a later
+     * answer replaced, a call made while a list is read. Without it, such a call
+     * to a tool that declares an `outputSchema` is refused
+     * (`McpOutputUncheckedError`); a one-page catalogue that is still the latest
+     * answer never needs it. It covers only the lists `tools()` and `refresh()`
+     * read: when the SDK client's cache is replaced some other way (its own
+     * automatic refresh, a `listTools` call of yours), the library still leaves
+     * the call to the SDK, and this validator is never asked (see
+     * `McpClient.tools()`).
+     */
+    readonly jsonSchemaValidator?: McpJsonSchemaValidator;
     /** @see McpClientOptions — never set on this arm. */
     readonly transport?: undefined;
     /** @see McpClientOptions — never set on this arm. */
@@ -376,12 +420,52 @@ export interface McpClient {
      * after `mcpClient(...)` is the snapshot used to register on the
      * agent; subsequent calls re-fetch (cheap, in-memory cached by the
      * SDK between fetches).
+     *
+     * Every page of the server's `tools/list` answer is read: the client
+     * follows `nextCursor` until a page carries none, sending at most 100
+     * `tools/list` requests (a bound on requests, not on the catalogue's size).
+     * A list that does not end within them, or that names a cursor it already
+     * sent (a loop), is never returned cut short: the call rejects with
+     * `McpToolListIncompleteError`, whose `reason` says which and whose `tools`
+     * holds what was listed. `signal` rides every page and is checked before
+     * each page is asked for and when each answer arrives: once it has fired,
+     * nothing more is asked for and no page is accepted.
+     *
+     * Every tool keeps its checks, whatever `tools()` and `refresh()` list later —
+     * those of any `mcpClient` over the same client included. That holds only
+     * while all tool discovery on the client runs through them; see below. The
+     * SDK's `Client` checks a tool's call (a required task refused before
+     * sending; `structuredContent` required by an `outputSchema`, and matched
+     * against it) only for the tools of its most recent `tools/list` answer, so
+     * every tool returned here carries those checks itself. They are left to the
+     * SDK only for a tool of a one-page list whose answer is still the latest,
+     * with no list request out. Every other call runs the tool's own and fails
+     * with the same error: a paged list's tools, a tool held across a later
+     * `refresh()` (failed or not), a call made while a list is read. Where no JSON
+     * Schema validator is reachable (`jsonSchemaValidator` on the `sdk` and
+     * `connection` arms), such a call to a tool that declares an `outputSchema` is
+     * refused with `McpOutputUncheckedError`: before it is sent, or, when a list
+     * was read while it was out, once its answer is in, unread.
+     *
+     * What it does not cover: a listing the library does not send. Your own
+     * `listTools` calls, the SDK client's automatic discovery (`listChanged.tools`
+     * with `autoRefresh`, on by default once `listChanged.tools` is given), or any
+     * other replacement of the SDK client's cache leave a tool handed out here
+     * believing the SDK still holds its checks — so neither its output checks nor
+     * its required-task refusal run, even with `jsonSchemaValidator`. The client
+     * the library builds (the `transport` and `sdk` arms) never lists by itself;
+     * on a client you pass as `connection`, set `autoRefresh: false` and call
+     * `refresh()` from `onChanged`, or give `mcpClient` a connection of its own.
      */
     tools(): Promise<readonly Tool[]>;
     /**
      * Force a refresh from the server. Use when you suspect the server
      * has dynamically added/removed tools mid-session (e.g., after the
-     * server processes a config update).
+     * server processes a config update). Reads every page, as `tools()` does.
+     * When it fails it rejects, and `tools()` keeps serving the catalogue it
+     * had: those tools keep their own checks (see `tools()`). Route the server's
+     * list-changed notice here, rather than letting the SDK client refresh
+     * itself: a listing the library does not send is not covered.
      */
     refresh(): Promise<readonly Tool[]>;
     /** Close the underlying transport. After `close()` the client is unusable. */
@@ -412,8 +496,17 @@ export interface McpClient {
  * convenience version of it.
  */
 export interface McpConnection {
-    listTools(params?: undefined, options?: McpRequestOptions): Promise<{
+    /**
+     * One page of the server's tool list. The first page is asked with no params;
+     * each later page with the `nextCursor` the page before it returned, as
+     * `{ cursor }`. A connection that never pages returns no `nextCursor`.
+     */
+    listTools(params?: {
+        readonly cursor?: string;
+    }, options?: McpRequestOptions): Promise<{
         readonly tools: ReadonlyArray<McpListedTool>;
+        /** Present while the server has more tools: what to ask for the next page with. */
+        readonly nextCursor?: string;
     }>;
     callTool(params: {
         readonly name: string;
@@ -510,6 +603,29 @@ export interface McpListedTool {
     readonly inputSchema: Readonly<Record<string, unknown>>;
     /** MCP's extensibility bag. Absent from most servers' tools. */
     readonly _meta?: Readonly<Record<string, unknown>>;
+    /**
+     * What the tool's `structuredContent` must match. Read for the one reason the
+     * SDK's `Client` reads it: a tool that declares one must answer with
+     * matching `structuredContent` (see `McpClient.tools()` for a paged list).
+     */
+    readonly outputSchema?: Readonly<Record<string, unknown>>;
+    /** How the tool may run: `taskSupport: 'required'` means only as a task, never a plain `tools/call`. */
+    readonly execution?: {
+        readonly taskSupport?: string;
+    };
+}
+/**
+ * A JSON Schema validator, as the MCP SDK's `Client` takes one
+ * (`jsonSchemaValidator`): `getValidator(schema)` compiles a schema once and
+ * returns a function that checks one value against it. Typed STRUCTURALLY so
+ * this declaration never references the optional peer; the SDK's own
+ * `AjvJsonSchemaValidator` and `CfWorkerJsonSchemaValidator` satisfy it.
+ */
+export interface McpJsonSchemaValidator {
+    getValidator(schema: object): (input: unknown) => {
+        readonly valid: boolean;
+        readonly errorMessage?: string;
+    };
 }
 /**
  * What `tools/call` can answer with — **a union, because the protocol is one.**