agentfootprint 12.0.1 → 12.2.0

package/dist/esm/mcp/pool/options.js

@@ -0,0 +1,119 @@
+/**
+ * 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 { replayDeclarationOf } from '../replay.js';
+/** The defaults, named so a test and a docstring cannot drift from the code. */
+export const MCP_POOL_DEFAULTS = Object.freeze({
+    maxClients: 64,
+    maxClientsPerPrincipal: 8,
+    maxEnding: 8,
+    maxOperations: 256,
+    initTimeoutMs: 30_000,
+    idleMs: 600_000,
+    maxLeaseMs: 900_000,
+    definitionTtlMs: 600_000,
+});
+/** At most this many shared definition entries are kept; the least recently used goes first. */
+export const MAX_DEFINITION_ENTRIES = 256;
+/** A list longer than this is used by its own client and never shared. */
+export const MAX_SHARED_TOOLS = 512;
+/**
+ * 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 function readPoolOptions(options) {
+    if (options === null || typeof options !== 'object') {
+        throw new TypeError('mcpClientPool: options must be an object with `name` and `transport`.');
+    }
+    const { name } = options;
+    if (typeof name !== 'string' || name.trim() === '') {
+        throw new TypeError('mcpClientPool: `name` must be a non-empty string — the server name every tool and record carries.');
+    }
+    const where = `mcpClientPool[${name}]`;
+    if (options.connection !== undefined) {
+        throw new TypeError(`${where}: \`connection\` is not taken. The pool builds every client's transport itself — ` +
+            'to end its session, to hear the tools-changed notice and to place the send gate. Pass ' +
+            '`transport`, or a function of the identity that returns one.');
+    }
+    const transport = transportOf(options.transport, where);
+    const count = (key) => positiveInteger(options[key], MCP_POOL_DEFAULTS[key], key, where);
+    const definitions = options.definitions ?? 'per-client';
+    if (definitions !== 'per-client' && typeof definitions?.share !== 'function') {
+        throw new TypeError(`${where}: \`definitions\` must be 'per-client' or { share: (identity) => names | undefined }.`);
+    }
+    if (options.onEvent !== undefined && typeof options.onEvent !== 'function') {
+        throw new TypeError(`${where}: \`onEvent\` must be a function.`);
+    }
+    if (options.now !== undefined && typeof options.now !== 'function') {
+        throw new TypeError(`${where}: the clock option must be a function returning milliseconds.`);
+    }
+    // Refused by field now, as each client would refuse it at its first open.
+    if (options.replay !== undefined)
+        replayDeclarationOf(options.replay, where);
+    return {
+        name,
+        transport,
+        maxClients: count('maxClients'),
+        maxClientsPerPrincipal: count('maxClientsPerPrincipal'),
+        maxEnding: count('maxEnding'),
+        maxOperations: count('maxOperations'),
+        initTimeoutMs: count('initTimeoutMs'),
+        idleMs: count('idleMs'),
+        maxLeaseMs: count('maxLeaseMs'),
+        definitionTtlMs: count('definitionTtlMs'),
+        share: definitions === 'per-client' ? undefined : definitions.share,
+        requirePrincipal: flag(options.requirePrincipal, true, 'requirePrincipal', where),
+        requireTenant: flag(options.requireTenant, false, 'requireTenant', where),
+        onEvent: options.onEvent,
+        client: {
+            ...(options.resultMode !== undefined && { resultMode: options.resultMode }),
+            ...(options.clientInfo !== undefined && { clientInfo: options.clientInfo }),
+            ...(options.retryOnThrottle !== undefined && { retryOnThrottle: options.retryOnThrottle }),
+            ...(options.replay !== undefined && { replay: options.replay }),
+            ...(options.sdk !== undefined && { sdk: options.sdk }),
+            ...(options.jsonSchemaValidator !== undefined && {
+                jsonSchemaValidator: options.jsonSchemaValidator,
+            }),
+        },
+        now: options.now ?? Date.now,
+        open: options._open,
+    };
+}
+/** One transport for everyone, or a function of the identity — as a function either way. */
+function transportOf(value, where) {
+    if (typeof value === 'function')
+        return value;
+    if (value !== null && typeof value === 'object' && typeof value.transport === 'string') {
+        return () => value;
+    }
+    throw new TypeError(`${where}: \`transport\` must be an MCP transport ({ transport: 'http' | 'gateway' | 'stdio', … }) ` +
+        'or a function of the identity that returns one.');
+}
+/** A whole number ≥ 1, or the default when absent. */
+function positiveInteger(value, fallback, key, where) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 1)
+        return value;
+    throw new TypeError(`${where}: \`${key}\` must be a whole number ≥ 1.`);
+}
+/** A boolean, or the default when absent. */
+function flag(value, fallback, key, where) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === 'boolean')
+        return value;
+    throw new TypeError(`${where}: \`${key}\` must be true or false.`);
+}
+//# sourceMappingURL=options.js.map

package/dist/esm/mcp/pool/options.js.map

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

package/dist/esm/mcp/pool/plan.d.ts

@@ -0,0 +1,77 @@
+/**
+ * plan — what one client is opened from, resolved before anything opens, and
+ * the context its tool definitions belong to.
+ *
+ * Pattern: a pure resolution step + two hashes.
+ * Role:    § 6.1–6.2 of the design. A client is opened from a PLAN: the
+ *          transport the factory returns for this identity, resolved at that
+ *          moment and kept unchanged for the client's life. The plan's
+ *          `configHash` is SHA-256 over a canonical encoding of the transport's
+ *          comparable data — the pool name; the transport kind and URL; header
+ *          names and a digest of their values; a gateway's service, scopes,
+ *          mode and credential provider id; stdio's command, args and working
+ *          directory; the transport's own stated `settings`; `resultMode` and
+ *          `clientInfo`. A function (a `fetch`, an AWS client) cannot be
+ *          compared: the app's `configuration` name covers it.
+ *
+ * The definitions CONTEXT is the binding a tool is listed under:
+ *
+ *   - per client (the default): `pc:<configHash>` — the client's own list;
+ *   - shared, when the app's `share` names both a configuration and an
+ *     authorization: `sh:<sha256(configHash, configuration, authorization,
+ *     tenant)>`. The tenant is always in it: the app's names widen sharing
+ *     across principals, never across tenants.
+ *
+ * The transport is resolved once, when a client opens; the context is not. The
+ * app's names can move — a policy version in `authorization` — so the pool asks
+ * `share` again at every listing, every call and every send gate
+ * (`contextFor`), over the client's own `configHash`: a conversation that
+ * already has a client follows a new name as a new conversation would.
+ *
+ * Neither hash leaves the process; the app's names are hashed and never kept.
+ */
+import type { ClientPort, PooledClientSeam } from '../clientPort.js';
+import type { McpClient, McpClientOptions, McpTransport } from '../types.js';
+import type { PoolKey } from './identityKey.js';
+import type { PoolSettings } from './options.js';
+/** What a client is opened from. */
+export interface ClientPlan {
+    readonly transport: McpTransport;
+    readonly configHash: string;
+    /** The definitions context: `pc:<configHash>` or `sh:<context>`. */
+    readonly context: string;
+    /** True when the app's sharing contract applies to this conversation. */
+    readonly shared: boolean;
+}
+/** An opened client: the ordinary `McpClient`, and the port back (`clientPort.ts`). */
+export interface OpenedClient {
+    readonly client: McpClient;
+    readonly port: ClientPort;
+}
+/**
+ * How the pool opens one client. The real path is `openPooledClient`; a test
+ * injects its own (the `_open` seam).
+ */
+export type PoolClientOpener = (options: McpClientOptions, seam: PooledClientSeam) => Promise<OpenedClient>;
+/**
+ * The plan for `key`: the transport the factory returns now, and the context
+ * its definitions belong to.
+ *
+ * @throws what the transport factory or `share` throws, and a TypeError when
+ *   `share` answers with anything but two names or `undefined` — the caller
+ *   refuses the open with `init-failed`, the error as its `cause`
+ */
+export declare function resolvePlan(settings: PoolSettings, key: PoolKey): ClientPlan;
+/**
+ * The definitions context `key` belongs to now, for a client opened with
+ * `configHash`: the app's `share` asked again.
+ *
+ * @throws what `share` throws, and a TypeError when it answers with anything
+ *   but two names or `undefined`
+ */
+export declare function contextFor(settings: PoolSettings, key: PoolKey, configHash: string): {
+    readonly context: string;
+    readonly shared: boolean;
+};
+/** SHA-256 over the transport's comparable data (see the module note). */
+export declare function configHashOf(settings: PoolSettings, transport: McpTransport): string;

package/dist/esm/mcp/pool/plan.js

@@ -0,0 +1,134 @@
+/**
+ * plan — what one client is opened from, resolved before anything opens, and
+ * the context its tool definitions belong to.
+ *
+ * Pattern: a pure resolution step + two hashes.
+ * Role:    § 6.1–6.2 of the design. A client is opened from a PLAN: the
+ *          transport the factory returns for this identity, resolved at that
+ *          moment and kept unchanged for the client's life. The plan's
+ *          `configHash` is SHA-256 over a canonical encoding of the transport's
+ *          comparable data — the pool name; the transport kind and URL; header
+ *          names and a digest of their values; a gateway's service, scopes,
+ *          mode and credential provider id; stdio's command, args and working
+ *          directory; the transport's own stated `settings`; `resultMode` and
+ *          `clientInfo`. A function (a `fetch`, an AWS client) cannot be
+ *          compared: the app's `configuration` name covers it.
+ *
+ * The definitions CONTEXT is the binding a tool is listed under:
+ *
+ *   - per client (the default): `pc:<configHash>` — the client's own list;
+ *   - shared, when the app's `share` names both a configuration and an
+ *     authorization: `sh:<sha256(configHash, configuration, authorization,
+ *     tenant)>`. The tenant is always in it: the app's names widen sharing
+ *     across principals, never across tenants.
+ *
+ * The transport is resolved once, when a client opens; the context is not. The
+ * app's names can move — a policy version in `authorization` — so the pool asks
+ * `share` again at every listing, every call and every send gate
+ * (`contextFor`), over the client's own `configHash`: a conversation that
+ * already has a client follows a new name as a new conversation would.
+ *
+ * Neither hash leaves the process; the app's names are hashed and never kept.
+ */
+import { canonicalJson } from '../../lib/canonicalJson.js';
+import { sha256Hex } from '../../lib/sha256.js';
+/**
+ * The plan for `key`: the transport the factory returns now, and the context
+ * its definitions belong to.
+ *
+ * @throws what the transport factory or `share` throws, and a TypeError when
+ *   `share` answers with anything but two names or `undefined` — the caller
+ *   refuses the open with `init-failed`, the error as its `cause`
+ */
+export function resolvePlan(settings, key) {
+    const transport = settings.transport(key.identity);
+    if (transport === null ||
+        typeof transport !== 'object' ||
+        typeof transport.transport !== 'string') {
+        throw new TypeError(`mcpClientPool[${settings.name}]: the \`transport\` function returned something that is not an MCP transport.`);
+    }
+    const configHash = configHashOf(settings, transport);
+    return { transport, configHash, ...contextFor(settings, key, configHash) };
+}
+/**
+ * The definitions context `key` belongs to now, for a client opened with
+ * `configHash`: the app's `share` asked again.
+ *
+ * @throws what `share` throws, and a TypeError when it answers with anything
+ *   but two names or `undefined`
+ */
+export function contextFor(settings, key, configHash) {
+    const names = shareOf(settings, key);
+    if (names === undefined)
+        return { context: `pc:${configHash}`, shared: false };
+    const context = sha256Hex(canonicalJson({
+        configHash,
+        configuration: names.configuration,
+        authorization: names.authorization,
+        tenant: key.tenant,
+    }));
+    return { context: `sh:${context}`, shared: true };
+}
+/** The app's two names for this conversation, or `undefined` for a list of its own. */
+function shareOf(settings, key) {
+    if (settings.share === undefined)
+        return undefined;
+    const names = settings.share(key.identity);
+    if (names === undefined)
+        return undefined;
+    if (names !== null &&
+        typeof names === 'object' &&
+        typeof names.configuration === 'string' &&
+        typeof names.authorization === 'string') {
+        const { configuration, authorization } = names;
+        return { configuration, authorization };
+    }
+    throw new TypeError(`mcpClientPool[${settings.name}]: \`definitions.share\` must return { configuration, authorization } ` +
+        '(two strings) or undefined, synchronously.');
+}
+/** SHA-256 over the transport's comparable data (see the module note). */
+export function configHashOf(settings, transport) {
+    return sha256Hex(canonicalJson({
+        pool: settings.name,
+        transport: comparableOf(transport),
+        resultMode: settings.client.resultMode ?? null,
+        clientInfo: settings.client.clientInfo ?? null,
+    }));
+}
+/** The comparable part of a transport: data only, functions left out. */
+function comparableOf(transport) {
+    if (transport.transport === 'stdio') {
+        return {
+            kind: 'stdio',
+            command: transport.command,
+            args: [...(transport.args ?? [])],
+            cwd: transport.cwd ?? null,
+        };
+    }
+    const headers = headersOf(transport.headers);
+    if (transport.transport === 'gateway') {
+        return {
+            kind: 'gateway',
+            url: transport.url,
+            headers,
+            service: transport.service,
+            scopes: [...(transport.scopes ?? [])],
+            mode: transport.mode ?? null,
+            credentials: transport.credentials?.id ?? null,
+        };
+    }
+    return {
+        kind: 'http',
+        url: transport.url,
+        headers,
+        settings: transport.settings ?? null,
+    };
+}
+/** Header names, and a digest of their values — never the values themselves. */
+function headersOf(headers) {
+    if (headers === undefined)
+        return { names: [], digest: null };
+    const lowered = Object.fromEntries(Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]));
+    return { names: Object.keys(lowered).sort(), digest: sha256Hex(canonicalJson(lowered)) };
+}
+//# sourceMappingURL=plan.js.map

package/dist/esm/mcp/pool/plan.js.map

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

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

@@ -0,0 +1,307 @@
+/**
+ * pool — the state behind `mcpClientPool`: who holds which client, what is
+ * charged, and what ends when.
+ *
+ * Pattern: one state machine, mutated only between awaits.
+ * Role:    §§ 5–7 of the design. Every mutation of the sets and the budget runs
+ *          synchronously — a check and the move it allows are never split by
+ *          an await — so two callers cannot both take the last slot.
+ *
+ *   - ADMISSION: every listing, call, acquire and ending is admitted against
+ *     `maxOperations` before anything is sent. At each interaction the lazy
+ *     sweep (revoked leases, idle ends, deferred ends) runs FIRST, so it
+ *     reserves its endings before the new operation is admitted.
+ *   - ONE OPEN PER KEY, from a plan resolved at that moment, under the pool's own
+ *     signal and `initTimeoutMs`, never a caller's. A caller that gives up
+ *     detaches alone; the operation that started the open keeps its charge until
+ *     the open's work settles. Past the deadline every waiter is refused at once
+ *     (`init-timeout`), and until the open's work settles the key cannot open
+ *     again. A failure reaches every current waiter and is not cached.
+ *   - THE HANDOFF: every operation waiting for an open holds a RESERVATION on
+ *     the client until it takes its lease, so between the open settling and
+ *     that lease the client is busy — nobody can evict, idle-end or end it. The
+ *     client's state is checked again after every wait, and the lease taken in
+ *     the same step: a lease is never handed out on a client that is ending.
+ *   - MAKING ROOM: the principal's, then the pool's, least recently used IDLE
+ *     client moves to the ending set — or `PoolFullError` at once.
+ *   - ENDING reserves an ending slot and an operation slot FIRST; when either is
+ *     full the client stays in the open set, counted, reported deferred, and is
+ *     ended when slots free. Every end goes through `terminate()` — but a client
+ *     whose handle this process lost: nothing can be sent for it, so its ending
+ *     is its local close alone, charged the same way until it settles.
+ *   - SETTLEMENT, never an abort, returns a slot (`work.ts`).
+ *   - NOTHING UNCHECKED: on a pooled client every request carries a guard — its
+ *     call's, or the client's open, listing or ending — and a request with none
+ *     is refused before it is sent (`request-unmatched`), at the watched `send`
+ *     and at the pool's own fetch alike.
+ */
+import type { Tool } from '../../tools/tools.js';
+import type { McpTerminateOutcome } from '../types.js';
+import { ClientSet, type PreviousEnd } from './clientSet.js';
+import { SharedDefinitions, type Definition, type DefinitionList } from './definitions.js';
+import { McpPoolRefusedError, PoolFullError, type McpPoolLimit } from './errors.js';
+import { type PoolKey } from './identityKey.js';
+import { type PoolSettings } from './options.js';
+import { type ClientPlan } from './plan.js';
+import { PooledClient, type EndReason } from './pooledClient.js';
+import { Reporter, type UseFacts } from './record.js';
+import { OperationBudget, Work, type Operation, type OperationKind, type WorkKind } from './work.js';
+/** An app lease, as the pool tracks it for `maxLeaseMs`. */
+export interface HeldLease {
+    readonly client: PooledClient;
+    readonly takenAt: number;
+    /** Revoked: its next use throws `lease-expired`. */
+    revoked: boolean;
+    /** Released: idempotent. */
+    released: boolean;
+}
+/** Where a list's definitions live: a client's own, or a shared entry. */
+export interface ServedList {
+    readonly list: DefinitionList;
+    readonly shared: boolean;
+    /** The definitions context: `pc:` or `sh:`. */
+    readonly context: string;
+}
+/** What `stats()` returns: counts, never keys. */
+export interface McpPoolStats {
+    /** Clients in the open set: opening, busy or idle. */
+    readonly open: number;
+    readonly busy: number;
+    readonly idle: number;
+    readonly opening: number;
+    /** Clients being ended, until each ending's work has settled. */
+    readonly ending: number;
+    /** Operations charged. */
+    readonly operations: number;
+    /** Shared definition entries kept. */
+    readonly entries: number;
+    /** Charged work past its deadline that has not settled, by what it is doing. */
+    readonly unsettled: Readonly<Record<WorkKind, number>>;
+    /** Endings whose remote outcome was not confirmed. */
+    readonly unresolvedEndings: number;
+}
+export declare class Pool {
+    readonly settings: PoolSettings;
+    readonly clients: ClientSet;
+    readonly budget: OperationBudget;
+    readonly shared: SharedDefinitions;
+    readonly reporter: Reporter;
+    /** The pool's own signal: what every open, listing and call runs under; aborted at `close()`. */
+    private readonly lifetime;
+    private readonly leases;
+    private readonly settleWaiters;
+    /** Waiting for some client to become idle (`terminate`, `close`). */
+    private readonly idleWaiters;
+    closed: boolean;
+    unresolvedEndings: number;
+    constructor(settings: PoolSettings);
+    now(): number;
+    get signal(): AbortSignal;
+    /**
+     * The lazy sweep, run at the start of every interaction: leases past
+     * `maxLeaseMs` revoked, idle clients ended, deferred endings retried — all of
+     * it before a new operation is admitted.
+     */
+    interact(): void;
+    /**
+     * Admit one operation, or refuse at once: `closed`, or `PoolFullError`
+     * (`limit: 'operations'`) — before anything is sent.
+     */
+    admit(kind: OperationKind, phase: WorkKind, callerSignal: AbortSignal | undefined): Operation;
+    refused(reason: McpPoolRefusedError['reason'], cause?: unknown): McpPoolRefusedError;
+    full(limit: McpPoolLimit): PoolFullError;
+    /**
+     * A library lease on `key`'s client for `operation`, opening one when the key
+     * has none (inside the operation's slot). `plan` is the plan resolved for a
+     * new client; a key that already has one keeps its own. The lease is
+     * released when the operation SETTLES.
+     */
+    leaseClient(key: PoolKey, operation: Operation, facts: UseFacts, plan?: ClientPlan): Promise<PooledClient>;
+    /**
+     * Wait for `client`'s open inside `operation`, holding a reservation on it
+     * all the while — between the open settling and this lease the client is
+     * busy, so nobody can evict, idle-end or end it — then check it again and
+     * lease it in the same step, with no wait between. `undefined` when it no
+     * longer serves: the caller's next round finds the key's next client.
+     */
+    private leaseOnceOpen;
+    /** `client` may have just become idle: a deferred ending may run, and a waiter for idleness may go on. */
+    private becameIdle;
+    private takeLease;
+    /** One lease ended: the client may now be idle, and a deferred ending may run. */
+    releaseLease(client: PooledClient): void;
+    private notifyIdle;
+    /** An app lease: a hold on a client for as long as the app keeps it, at most `maxLeaseMs`. */
+    holdLease(client: PooledClient): HeldLease;
+    /** End an app lease — at most once, whether released or revoked. */
+    endLease(lease: HeldLease): void;
+    private revokeExpiredLeases;
+    /** Every app lease is revoked: the pool is closing. */
+    revokeAllLeases(): void;
+    /**
+     * Open a client for `key`: make room, resolve its plan, admit it to the open
+     * set, and start the one open. The operation that started it tracks the open's
+     * settlement, so its charge stays until the open's work has settled.
+     */
+    private openFor;
+    /** The one open of `client`, under the pool's own signal and `initTimeoutMs`. */
+    private startOpen;
+    private dropFailedOpen;
+    /** Wait for `client`'s open inside `operation`: the caller's signal detaches the caller only. */
+    private waitOpen;
+    /** What `mcpClient` is opened with: the connection-shaping options, the pool's signal. */
+    private clientOptions;
+    /** What only a pool asks of the client it opens (`clientPort.ts`). */
+    private seamFor;
+    /**
+     * The guard for a message on `client` that carries none of its own: a tool
+     * call always brings its call's guard, so one without it is refused; any
+     * other request runs under the client's open, listing or ending — and with
+     * none under way, it is refused too. Nothing pooled is sent unchecked.
+     */
+    private guardOf;
+    /** The guard of a request nothing covers: it refuses, so the request is never sent. */
+    private readonly unmatched;
+    /**
+     * The pool's own fetch, outermost on every pooled transport: a request is
+     * checked against its guard (the pooled call's, else the client's phase) and
+     * counted under it; the guard's signal is linked in; and the answer is read
+     * for the two pieces of evidence the pool classifies on — a 404 the MCP server
+     * itself sent to a request that carried its session id, and a handle this
+     * process lost. The client's own standalone stream (a GET), a notification and
+     * an answer to the server's own request are the client's, not an operation's:
+     * they pass untouched. Any other request with no guard is refused unsent.
+     */
+    private pooledFetch;
+    /**
+     * Make room for a new client of `key`: the principal's least recently used
+     * idle client, then the pool's, moves to the ending set — or `PoolFullError`
+     * at once, naming the budget. There is no queue.
+     */
+    private makeRoom;
+    /**
+     * Move `victim` to the ending set to make room. When the slots cannot be
+     * reserved, the arrival is refused at once, and the victim stays in the open
+     * set, counted, reported deferred — ended once slots free.
+     */
+    private evict;
+    /** An ending slot and an operation slot, both, or which one is full. */
+    private reserveEnding;
+    /**
+     * End `client` for `reason` — when it is idle and both slots can be reserved.
+     * Otherwise it stays in the open set, still counted, and is reported deferred
+     * (once); it is ended when its last lease ends or slots free.
+     */
+    endClient(client: PooledClient, reason: EndReason): void;
+    private defer;
+    /**
+     * Move `client` into the ending set under `operation`, and end it through
+     * `terminate()` — or, for a lost handle, through its local close alone.
+     */
+    private startEnding;
+    private noteEnded;
+    /**
+     * A client whose handle this process lost: nothing can be sent for it, so it
+     * leaves its key at once — the next use opens the key's next client — and is
+     * ended under the ending rule like any other: its ending is its LOCAL close,
+     * charged an ending slot and an operation slot until that close settles, its
+     * remote outcome recorded unresolved. Busy, or with no slots free, it waits —
+     * still counted in the open set, reported deferred.
+     */
+    lostHandle(client: PooledClient): void;
+    /** A client whose session the server ended: no new lease; ended (through `terminate()`) when idle. */
+    expired(client: PooledClient): void;
+    private sweepIdle;
+    /** Retry every deferred ending whose client is now idle. */
+    retryDeferred(): void;
+    /** Where `client`'s definitions are served from: its shared entry, or its own list. */
+    servedListOf(client: PooledClient): ServedList;
+    /**
+     * The definitions context `client` serves under NOW: the app's `share` asked
+     * again over the client's own configuration. A changed answer moves the
+     * client to the new context and stops serving its own list, so every tool
+     * bound under the old one is refused before it is sent.
+     *
+     * @throws `binding-changed`, `share`'s error as its cause, when the answer
+     *   cannot be had — never the old context
+     */
+    refreshContext(client: PooledClient): PooledClient['definitions'];
+    /** Does `context` still name the definitions context `client` serves under? False when it cannot be had. */
+    contextHolds(client: PooledClient, context: string): boolean;
+    /**
+     * The list `client` serves under NOW, listed again on it when it cannot be
+     * served as it stands — one listing at a time per list; a second caller joins
+     * it inside its own slot. Every attempt asks the app's names again
+     * (`refreshContext`), so a listing that a moved context discarded or refused
+     * at its send is listed once more under the context of now, never written
+     * into the one it began under. A listing raced by an invalidation is
+     * discarded too. Refused (`stale-tools`) when three attempts serve nothing.
+     * What it returns was checked against the context with no wait since.
+     */
+    ensureListed(client: PooledClient, operation: Operation): Promise<ServedList>;
+    /**
+     * What `client` can serve under the context of now — asked of the app's names
+     * here — or, when nothing can, the list it should list. Too long to share:
+     * the conversation's own client keeps that list, under the same context.
+     */
+    private servableNow;
+    /**
+     * One listing on `client` for `served`'s context. Its requests are sent only
+     * while that context holds — asked at every boundary they cross — and its
+     * answer is written only if the context still holds when it arrives and the
+     * list's generation held: an answer the app's names moved under belongs to
+     * no context, and is dropped.
+     */
+    private startListing;
+    /**
+     * A request failed: when the pool's fetch read the server's own 404 for the
+     * session, or this process lost the handle, the client leaves its key — the
+     * next use opens the next client under the SAME key — and the error says so.
+     */
+    classifyFailure(client: PooledClient, work: Work, error: unknown): RequestEvidenceOutcome;
+    /** The server said a client's tool list changed: that client's list and its shared entry. */
+    private toolsChangedOn;
+    /** The app's permission signal: every list in the scope. */
+    permissionsChanged(scope: {
+        readonly tenant?: string;
+        readonly principal?: string;
+    }): void;
+    /** The server changed: every list. */
+    toolsChanged(): void;
+    /**
+     * Stop new leases on every client `scope` names, at once; wait for their
+     * in-flight work up to `waitMs`; then end each one whose slots can be
+     * reserved. The rest are reported deferred and ended when they can be.
+     */
+    terminate(matches: (key: PoolKey) => boolean, reason: EndReason, waitMs: number): Promise<readonly McpTerminateOutcome[]>;
+    /** End each of `clients` whose slots can be reserved; the outcomes of those that started. */
+    private endNow;
+    /** Wait until every client in `clients` is idle, or `waitMs` passed. */
+    private waitIdle;
+    /**
+     * Close: refuse new work, revoke app leases, abort in-flight work through the
+     * pool's own signal, then end every client as slots can be reserved — at most
+     * `maxEnding` at a time — in rounds, each bounded by `waitMs` (and each
+     * ending's answer by its own deadline). What could not be ended yet is
+     * reported deferred and ended when slots free; work still unsettled stays
+     * charged until it settles.
+     */
+    closeAll(waitMs: number): Promise<readonly McpTerminateOutcome[]>;
+    /** Wait until an ending slot and an operation slot are free, or `waitMs` passed. */
+    private waitSlots;
+    /** Refuse new work, revoke app leases, abort in-flight work through the pool's signal. */
+    shutDown(): void;
+    /** Resolve once every charged operation and every ending has settled. */
+    settled(): Promise<void>;
+    private quiet;
+    private notifySettled;
+    stats(): McpPoolStats;
+    /** The bound shape of every definition in `served`, for a client of `key`. */
+    definitionsOf(served: ServedList): readonly Definition[];
+    /** The tools a list's client-own entries carry, by name (per-client lists only). */
+    ownTool(served: ServedList, name: string): Tool | undefined;
+}
+/** What a failed request proved about its client, if anything. */
+export type RequestEvidenceOutcome = 'expired' | 'handle-lost' | undefined;
+/** Re-exported for the bound tool: which end reasons name a previous client. */
+export type { PreviousEnd };