agentfootprint 12.0.1 → 12.2.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,34 @@
+/**
+ * listTools — one conversation's tools, bound to it: one listing operation.
+ *
+ * Pattern: one admitted operation per call, the provider's and the lease's alike.
+ * Role:    § 3.2 and § 6 of the design. A listing is one `list(ctx)` for one
+ *          conversation, admitted against `maxOperations`. Its setup — the open
+ *          of the key's client, the `tools/list` — runs inside its slot.
+ *
+ *   - PER CLIENT: the conversation's own client is opened (or reused) and its own
+ *     list served, listed again when it cannot be served as it stands.
+ *   - SHARED, under the app's contract: the plan is resolved and the context
+ *     computed WITHOUT opening anything; a current entry is served touching no
+ *     client (`client: 'not-needed'`); a listing already under way for it is
+ *     joined; otherwise the listing runs on THIS conversation's own client —
+ *     never in another conversation's session.
+ *   - THE CALLER'S CONTEXT AFTER EVERY WAIT: the app's names are asked again
+ *     after a joined listing and after this one's own (`Pool.ensureListed`); a
+ *     list is served only under the context the caller has at that moment, and
+ *     a moved context is resolved again — at most three rounds, then refused
+ *     (`binding-changed`).
+ *
+ * A refused listing never reaches the model as a tool result: it fails that
+ * iteration's tool discovery (`agentfootprint.tools.discovery_failed`), as any
+ * failing `ToolProvider` does. A list that cannot be read to its end
+ * (`McpToolListIncompleteError`, from the client's own discovery) is never
+ * served cut short.
+ */
+import type { Tool } from '../../tools/tools.js';
+import type { PoolKey } from './identityKey.js';
+import type { Pool } from './pool.js';
+import type { UseFacts } from './record.js';
+/** List `key`'s conversation's tools, bound to it, under one admitted operation. */
+export declare function listTools(pool: Pool, key: PoolKey, signal: AbortSignal | undefined, facts: UseFacts): Promise<readonly Tool[]>;
+//# sourceMappingURL=listTools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"listTools.d.ts","sourceRoot":"","sources":["../../../../src/mcp/pool/listTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAIjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,WAAW,CAAC;AAElD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,oFAAoF;AACpF,wBAAsB,SAAS,CAC7B,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,KAAK,EAAE,QAAQ,GACd,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAgD1B"}

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

@@ -0,0 +1,122 @@
+/**
+ * mcpClientPool — a client per conversation, for one MCP server.
+ *
+ *   const orders = mcpClientPool({
+ *     name: 'orders',
+ *     transport: () =>
+ *       agentCoreRuntimeMcpTransport({ agentRuntimeArn, region, session: 'reuse', client: aws }),
+ *   });
+ *   const agent = Agent.create({ provider, model }).toolProvider(orders.toolProvider()).build();
+ *   await agent.run({ message, identity: { tenant, principal, conversationId } });
+ *
+ * Pattern: Facade over one state machine (`pool.ts`), its accounting (`work.ts`),
+ *          its definitions (`definitions.ts`) and its bound tools (`boundTool.ts`).
+ * Role:    `docs/design/2026-10-mcp-client-pool.md`. A `'reuse'` session costs a
+ *          cold start once per conversation instead of once per call — but only
+ *          if each conversation has a client of its own, opened once, bounded,
+ *          never closed while in use, ended remotely and said to be. This is
+ *          the one place that does all of it:
+ *
+ *   - one client per authenticated conversation, keyed by the library's
+ *     identity encoding of the identity the CALLER named;
+ *   - one open per key, under the pool's own signal and `initTimeoutMs`;
+ *   - three budgets — open clients, endings, outstanding operations — each
+ *     charged until the work under it has SETTLED, and `PoolFullError` at once
+ *     when one is full: there is no queue;
+ *   - tool definitions per client incarnation by default, shared only under the
+ *     app's declared contract, every tool re-checked after each wait and at the
+ *     send gate;
+ *   - every ending through `terminate()`, with the remote outcome reported, and
+ *     `close()` still only local.
+ *
+ * What it does not do: repeat a call, share anything across processes, bound a
+ * remote session it could not end, or make a server enforce per-user
+ * permissions.
+ */
+import type { ToolProvider } from '../../tools/toolProvider.js';
+import type { McpTerminateOutcome } from '../types.js';
+import { type McpPoolLease } from './lease.js';
+import { type McpClientPoolOptions, type McpPoolIdentity } from './options.js';
+import { type McpPoolStats } from './pool.js';
+/** The scope `terminate` and `permissionsChanged` name. */
+export interface McpPoolScope {
+    /** Matched exactly, always: an absent tenant is "no tenant", never "every tenant". */
+    readonly tenant?: string;
+    /** Absent: every principal of the tenant (`permissionsChanged` only). */
+    readonly principal?: string;
+    /** Absent: every conversation of the principal. */
+    readonly conversationId?: string;
+}
+/** One pool per MCP server: a client per conversation. */
+export interface McpClientPool {
+    /** The pool's name: the server. */
+    readonly name: string;
+    /**
+     * The agent path: a `ToolProvider` (id `mcp-pool:<name>`) whose `list(ctx)`
+     * takes the run's caller identity (`ToolDispatchContext.callerIdentity`) and
+     * returns that conversation's tools, bound to it. A bound tool's `execute`
+     * takes a lease on the key's client for one call, opening the client first
+     * when the key has none; nothing is held between calls. A run with no caller
+     * identity is refused (`no-identity`) — a derived one counts as none.
+     */
+    toolProvider(): ToolProvider;
+    /**
+     * Hold `identity`'s conversation client — opened or reused — until
+     * `release()`, at most `maxLeaseMs`. The only way to protect a client between
+     * calls (a host holds one around `agent.run()`).
+     *
+     * @throws `McpPoolRefusedError` (`no-identity`, `incomplete-identity`,
+     *   `init-timeout`, `init-failed`, `closed`) or `PoolFullError`
+     */
+    acquire(identity: McpPoolIdentity, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<McpPoolLease>;
+    /**
+     * End the conversations `scope` names — one (`{ tenant, principal,
+     * conversationId }`) or every one of a principal (`{ tenant, principal }`).
+     * New leases stop at once; the next acquire for a key opens a new client.
+     * In-flight work is waited for up to 5 s; then each client is ended through
+     * `terminate()` once an ending slot and an operation slot are reserved. A
+     * client still leased, or whose slots cannot be reserved yet, is reported
+     * deferred (`onEvent`), never as ended, and is ended when it can be.
+     *
+     * @returns one `McpTerminateOutcome` per client it ended
+     */
+    terminate(scope: McpPoolScope): Promise<readonly McpTerminateOutcome[]>;
+    /**
+     * Shut down: refuse new work, revoke app leases, abort in-flight calls
+     * through the pool's own signal, then end every client as slots can be
+     * reserved, at most `maxEnding` at a time. Resolves after a bounded wait;
+     * the clients it could not end yet are reported deferred and the work still
+     * unsettled stays charged until it settles (`stats()`). Idempotent.
+     *
+     * @returns one `McpTerminateOutcome` per client it ended
+     */
+    close(): Promise<readonly McpTerminateOutcome[]>;
+    /** Resolves once every charged operation and every ending has settled. */
+    settled(): Promise<void>;
+    /**
+     * The app's permission signal: every tool list in the scope stops being
+     * served, and every tool bound to one is refused (`stale-tools`) before it is
+     * sent. Per process: a fleet sends it to every process, or versions its
+     * `authorization` names.
+     */
+    permissionsChanged(scope: {
+        readonly tenant?: string;
+        readonly principal?: string;
+    }): void;
+    /** The server changed (a deploy hook): every tool list stops being served. */
+    toolsChanged(): void;
+    /** Run the lazy sweep now: revoked leases, idle ends, deferred ends. No timer is ever installed. */
+    sweep(): void;
+    /** Counts only — never keys. They report; the budgets enforce. */
+    stats(): McpPoolStats;
+}
+/**
+ * Build a pool for one MCP server.
+ *
+ * @throws TypeError when an option is missing, mistyped or out of range, or when
+ *   `connection` is given — here, when the pool is built
+ */
+export declare function mcpClientPool(options: McpClientPoolOptions): McpClientPool;
+//# sourceMappingURL=mcpClientPool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcpClientPool.d.ts","sourceRoot":"","sources":["../../../../src/mcp/pool/mcpClientPool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5D,OAAO,EAAmB,KAAK,oBAAoB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAChG,OAAO,EAAQ,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAGpD,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,YAAY,IAAI,YAAY,CAAC;IAC7B;;;;;;;OAOG;IACH,OAAO,CACL,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,YAAY,CAAC,CAAC;IACzB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;IACxE;;;;;;;;OAQG;IACH,KAAK,IAAI,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;IACjD,0EAA0E;IAC1E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB;;;;;OAKG;IACH,kBAAkB,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3F,8EAA8E;IAC9E,YAAY,IAAI,IAAI,CAAC;IACrB,oGAAoG;IACpG,KAAK,IAAI,IAAI,CAAC;IACd,kEAAkE;IAClE,KAAK,IAAI,YAAY,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAqE1E"}

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

@@ -0,0 +1,184 @@
+/**
+ * options — what `mcpClientPool` is built from, read and checked once.
+ *
+ * Pattern: one options type + one reader that refuses by name.
+ * Role:    The pool's budgets and clocks (`docs/design/2026-10-mcp-client-pool.md`
+ *          § 3.1). Every number is checked when the pool is built, never at the
+ *          first call. The pool takes the `mcpClient` options that shape one
+ *          connection and hands them to every client it opens; it never takes
+ *          `connection`, because it must build the transport itself — to end
+ *          the session, to hear the tools-changed notice, and to place the send
+ *          gate.
+ */
+import type { MemoryIdentity } from '../../memory/identity/types.js';
+import { type McpReplayOptions } from '../replay.js';
+import type { RetryOnThrottle } from '../throttleRetry.js';
+import type { McpJsonSchemaValidator, McpSdk, McpTransport } from '../types.js';
+import type { McpPoolReport } from './record.js';
+import type { PoolClientOpener } from './plan.js';
+/** The identity a pool keys a client by: `{ tenant?, principal?, conversationId }`. */
+export type McpPoolIdentity = MemoryIdentity;
+/** What a conversation's tool list may be shared under: two names the app vouches for. */
+export interface McpPoolShareContext {
+    /**
+     * What the transport hides in its code — a signer's role, the credentials of
+     * an AWS client, a custom `fetch`. Hashed into the context, never recorded.
+     */
+    readonly configuration: string;
+    /**
+     * What the server's tool visibility depends on — a role and a policy version
+     * (`'analyst@policy-7'`). A version in the name reaches a new entry without
+     * `permissionsChanged`, for conversations that already have a client too:
+     * their tools are listed again under the new name, and a tool bound under the
+     * old one is refused before it is sent. Hashed into the context, never
+     * recorded.
+     */
+    readonly authorization: string;
+}
+/**
+ * Share tool definitions between conversations — declared by the app, checked by
+ * the pool. `share` is asked for every conversation before anything opens, and
+ * again at every listing, every call and every send gate after that, so a
+ * changed answer takes effect at the next one; it must be synchronous and
+ * cheap. A listing's answer is kept only if the names still give the context it
+ * was listed for when it arrives — otherwise it is dropped and listed again. Return both names, or `undefined` to keep that conversation's list to
+ * itself. Conversations share a list only when the transport's comparable
+ * data, both names and the tenant are all equal. A `share` that throws refuses
+ * the open (`init-failed`) or, for a conversation that already has a client,
+ * that listing or call (`binding-changed`) — its error as `cause`. Never share
+ * a server whose list follows the session (one that unlocks tools as a
+ * conversation goes on).
+ */
+export interface McpPoolDefinitionSharing {
+    readonly share: (identity: McpPoolIdentity) => McpPoolShareContext | undefined;
+}
+/** Options for {@link mcpClientPool}. */
+export interface McpClientPoolOptions {
+    /** The server's name: every tool's `source`, the provider's id, and the record. */
+    readonly name: string;
+    /**
+     * The transport each client is opened over. A FUNCTION of the identity is
+     * preferred: it is called before each client opens (and again for every
+     * replacement) with the identity the client is for, so each client gets a
+     * transport — and a session map — of its own, and a provider can vend THAT
+     * user's credential. One shared object serves every client; a shared
+     * `'reuse'` runtime transport then needs `maxClients + maxEnding` at or below
+     * its 256 remembered connections.
+     */
+    readonly transport: McpTransport | ((identity: McpPoolIdentity) => McpTransport);
+    /** Open clients — opening, busy or idle. Default 64. */
+    readonly maxClients?: number;
+    /** Open clients for one principal (one tenant's principal). Default 8. */
+    readonly maxClientsPerPrincipal?: number;
+    /** Clients being ended at once, until each ending's work has settled. Default 8. */
+    readonly maxEnding?: number;
+    /**
+     * Opens, listings, calls and endings outstanding on any client, each from
+     * its admission until its work has settled — not merely until its caller was
+     * answered. Default 256. Size it above `maxEnding`.
+     */
+    readonly maxOperations?: number;
+    /** One open per conversation, under this ceiling. Default 30 000 ms. */
+    readonly initTimeoutMs?: number;
+    /**
+     * End a client idle this long, at the next pool interaction (no timer is
+     * installed). Default 600 000 ms — below AgentCore Runtime's 900 s idle
+     * timeout; set it lower for a runtime configured lower.
+     */
+    readonly idleMs?: number;
+    /** An app lease (`acquire`) is revoked past this. Default 900 000 ms (15 minutes). */
+    readonly maxLeaseMs?: number;
+    /** A tool list is listed again after this, at the next list. Default 600 000 ms. */
+    readonly definitionTtlMs?: number;
+    /** `'per-client'` (the default), or the app's declared sharing contract. */
+    readonly definitions?: 'per-client' | McpPoolDefinitionSharing;
+    /** Refuse an identity without a `principal`. Default `true`. */
+    readonly requirePrincipal?: boolean;
+    /** Refuse an identity without a `tenant` — for multitenant hosts. Default `false`. */
+    readonly requireTenant?: boolean;
+    /**
+     * What happens outside a run — endings, deferred endings, revoked leases,
+     * work that settled after its deadline. Ids and outcomes only. A throwing
+     * handler is swallowed and changes nothing.
+     */
+    readonly onEvent?: (report: McpPoolReport) => void;
+    /** Passed to every client: how a tool's result is decoded (`McpClientOptions.resultMode`). */
+    readonly resultMode?: 'text' | 'structured' | 'structured-or-json';
+    /** Passed to every client: the `initialize` identity. */
+    readonly clientInfo?: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** Passed to every client: the 429 retry (`McpClientOptions.retryOnThrottle`). */
+    readonly retryOnThrottle?: RetryOnThrottle;
+    /**
+     * Passed to every client: who may send a tool call again
+     * (`McpClientOptions.replay`). Read and checked when the pool is built. The
+     * default stays `'compatibility'`. Whatever the policy, the pool's own send
+     * gate refuses a pooled request it cannot check (`request-unmatched`).
+     */
+    readonly replay?: McpReplayOptions;
+    /** Passed to every client: the two SDK modules, imported by you (`McpClientOptions.sdk`). */
+    readonly sdk?: McpSdk;
+    /**
+     * Passed to every client: the JSON Schema validator a tool's own output checks
+     * use (`McpClientOptions.jsonSchemaValidator`). With `sdk`, give it: a shared
+     * definition always runs its own checks, and without a validator a tool that
+     * declares an `outputSchema` is refused unsent.
+     */
+    readonly jsonSchemaValidator?: McpJsonSchemaValidator;
+    /** Clock seam — tests drive idle, lease and definition ages without waiting. */
+    readonly now?: () => number;
+    /** @internal Test seam: how a client is opened (the real path is `openPooledClient`). */
+    readonly _open?: PoolClientOpener;
+}
+/** The defaults, named so a test and a docstring cannot drift from the code. */
+export declare const MCP_POOL_DEFAULTS: Readonly<{
+    maxClients: 64;
+    maxClientsPerPrincipal: 8;
+    maxEnding: 8;
+    maxOperations: 256;
+    initTimeoutMs: 30000;
+    idleMs: 600000;
+    maxLeaseMs: 900000;
+    definitionTtlMs: 600000;
+}>;
+/** At most this many shared definition entries are kept; the least recently used goes first. */
+export declare const MAX_DEFINITION_ENTRIES = 256;
+/** A list longer than this is used by its own client and never shared. */
+export declare const MAX_SHARED_TOOLS = 512;
+/** The pool's settings, read once. */
+export interface PoolSettings {
+    readonly name: string;
+    readonly transport: (identity: McpPoolIdentity) => McpTransport;
+    readonly maxClients: number;
+    readonly maxClientsPerPrincipal: number;
+    readonly maxEnding: number;
+    readonly maxOperations: number;
+    readonly initTimeoutMs: number;
+    readonly idleMs: number;
+    readonly maxLeaseMs: number;
+    readonly definitionTtlMs: number;
+    readonly share: McpPoolDefinitionSharing['share'] | undefined;
+    readonly requirePrincipal: boolean;
+    readonly requireTenant: boolean;
+    readonly onEvent: ((report: McpPoolReport) => void) | undefined;
+    readonly client: {
+        readonly resultMode?: McpClientPoolOptions['resultMode'];
+        readonly clientInfo?: McpClientPoolOptions['clientInfo'];
+        readonly retryOnThrottle?: RetryOnThrottle;
+        readonly replay?: McpReplayOptions;
+        readonly sdk?: McpSdk;
+        readonly jsonSchemaValidator?: McpJsonSchemaValidator;
+    };
+    readonly now: () => number;
+    readonly open: PoolClientOpener | undefined;
+}
+/**
+ * Read `options` once.
+ *
+ * @throws TypeError naming the option, when one is missing, mistyped or out of
+ *   range, or when `connection` is given — here, when the pool is built.
+ */
+export declare function readPoolOptions(options: McpClientPoolOptions): PoolSettings;
+//# sourceMappingURL=options.d.ts.map