agentfootprint 12.1.0 → 12.2.0

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

@@ -0,0 +1,51 @@
+/**
+ * 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 { ASYNC_DISPOSE } from '../../strategies/lifecycle.js';
+import { noteRefusal } from './boundTool.js';
+import { listTools } from './listTools.js';
+import { UseFacts } from './record.js';
+/** The lease handle for `held`, on `key`'s client. */
+export function leaseHandle(pool, key, held) {
+    const release = () => {
+        if (held.released)
+            return;
+        held.released = true;
+        pool.endLease(held);
+        pool.interact();
+    };
+    const handle = {
+        async tools(options) {
+            pool.interact();
+            if (held.revoked || held.released)
+                throw pool.refused('lease-expired');
+            const facts = new UseFacts(pool.settings.name, 'list');
+            try {
+                return await listTools(pool, key, options?.signal, facts);
+            }
+            catch (error) {
+                noteRefusal(facts, error);
+                throw error;
+            }
+        },
+        release,
+        [ASYNC_DISPOSE]: async () => release(),
+    };
+    // The computed key gives TypeScript a symbol index rather than the one
+    // well-known member `AsyncDisposable` names; at runtime it IS
+    // `Symbol.asyncDispose` on every engine this package supports.
+    return handle;
+}
+//# sourceMappingURL=lease.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../../../../src/mcp/pool/lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAiBvC,sDAAsD;AACtD,MAAM,UAAU,WAAW,CAAC,IAAU,EAAE,GAAY,EAAE,IAAe;IACnE,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpB,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC;IACF,MAAM,MAAM,GAAG;QACb,KAAK,CAAC,KAAK,CAAC,OAA2C;YACrD,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ;gBAAE,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;YACvE,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACvD,IAAI,CAAC;gBACH,OAAO,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;YAC5D,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;gBAC1B,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO;QACP,CAAC,aAAa,CAAC,EAAE,KAAK,IAAmB,EAAE,CAAC,OAAO,EAAE;KACtD,CAAC;IACF,uEAAuE;IACvE,8DAA8D;IAC9D,+DAA+D;IAC/D,OAAO,MAAiC,CAAC;AAC3C,CAAC"}

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

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

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

@@ -0,0 +1,146 @@
+/**
+ * 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 { untilAborted } from '../../lib/abort.js';
+import { isLocalSessionHandleLost, LocalSessionHandleLostError } from '../../tools/toolSessions.js';
+import { ServerEndedSessionError } from './sessionEnded.js';
+import { boundTool } from './boundTool.js';
+import { contextFor, resolvePlan } from './plan.js';
+/** List `key`'s conversation's tools, bound to it, under one admitted operation. */
+export async function listTools(pool, key, signal, facts) {
+    facts.keyHash = key.keyHash;
+    pool.interact();
+    const operation = pool.admit('listing', 'listing', signal);
+    try {
+        for (let round = 0; round < 3; round += 1) {
+            const current = pool.clients.currentFor(key.key);
+            let plan;
+            if (current === undefined) {
+                try {
+                    plan = resolvePlan(pool.settings, key);
+                }
+                catch (cause) {
+                    throw pool.refused('init-failed', cause);
+                }
+            }
+            // A key with a client: the app's names asked again, so a changed
+            // authorization reaches this conversation as it would a new one.
+            const definitions = current === undefined ? plan : pool.refreshContext(current);
+            if (definitions.shared) {
+                const served = await sharedWithoutClient(pool, key, definitions.context, operation.signal);
+                if (served !== undefined) {
+                    // After that wait, the caller's names once more: served only under
+                    // the context they give now — otherwise resolved again.
+                    if (!callerStillIn(pool, key, plan, served.context))
+                        continue;
+                    facts.client = 'not-needed';
+                    facts.definitions = 'shared';
+                    facts.definitionsAgeMs = Math.max(0, pool.now() - served.list.listedAt);
+                    return bindAll(pool, key, served, undefined);
+                }
+            }
+            const client = await pool.leaseClient(key, operation, facts, plan);
+            let served;
+            try {
+                // Under the client's context of now, checked with no wait since.
+                served = await pool.ensureListed(client, operation);
+            }
+            catch (error) {
+                throw classifiedListing(pool, client, facts, error);
+            }
+            facts.definitions = served.shared ? 'shared' : 'listed';
+            if (served.shared)
+                facts.definitionsAgeMs = Math.max(0, pool.now() - served.list.listedAt);
+            return bindAll(pool, key, served, client);
+        }
+        // The app's names kept moving under this listing.
+        throw pool.refused('binding-changed');
+    }
+    finally {
+        operation.finish();
+    }
+}
+/**
+ * Do the caller's names still give `context` — asked now? Through the key's
+ * client when it has one by now, else over the plan's configuration. False
+ * when `share` cannot answer: the next round says why.
+ */
+function callerStillIn(pool, key, plan, context) {
+    const current = pool.clients.currentFor(key.key);
+    if (current !== undefined)
+        return pool.contextHolds(current, context);
+    if (plan === undefined)
+        return false;
+    try {
+        return contextFor(pool.settings, key, plan.configHash).context === context;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The shared entry for `plan`, when it can be served without touching a client
+ * — at once, or once a listing already under way for it is done.
+ */
+async function sharedWithoutClient(pool, key, context, signal) {
+    const entry = pool.shared.entryFor(context, key.tenant);
+    const servable = () => entry.list.servable(pool.now(), pool.settings.definitionTtlMs);
+    if (!servable() && entry.list.listing !== undefined) {
+        // Joined inside this operation's own slot; if it fails, this one lists itself.
+        await untilAborted(entry.list.listing, signal).catch(() => undefined);
+    }
+    return servable() ? { list: entry.list, shared: true, context } : undefined;
+}
+/** Every definition of `served`, bound to `key` and to the list it came from. */
+function bindAll(pool, key, served, client) {
+    const base = {
+        key,
+        context: served.context,
+        shared: served.shared,
+        listId: served.list.id,
+        generation: served.list.generation,
+        ...(!served.shared && client !== undefined && { clientId: client.clientId }),
+    };
+    return served.list.all().map((definition) => boundTool(pool, { ...base, definition }));
+}
+/** A listing that failed because the client's session expired or its handle was lost. */
+function classifiedListing(pool, client, facts, error) {
+    if (client.lost === 'expired') {
+        facts.client = 'expired';
+        facts.evidence = 'server-404';
+        return new ServerEndedSessionError(pool.settings.name, client.clientId, error);
+    }
+    if (client.lost === 'handle-lost') {
+        facts.client = 'handle-lost';
+        facts.evidence = 'transport-forgot-handle';
+        return isLocalSessionHandleLost(error)
+            ? error
+            : new LocalSessionHandleLostError({ cause: error });
+    }
+    return error;
+}
+//# sourceMappingURL=listTools.js.map

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

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

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

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

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

@@ -0,0 +1,151 @@
+/**
+ * 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 { fileListUse } from '../../tools/mcpClientUse.js';
+import { TOOL_TEARDOWN_TIMEOUT_MS } from '../../tools/toolSessions.js';
+import { noteRefusal } from './boundTool.js';
+import { poolKeyOf, scopeMatcher } from './identityKey.js';
+import { leaseHandle } from './lease.js';
+import { listTools } from './listTools.js';
+import { readPoolOptions } from './options.js';
+import { Pool } from './pool.js';
+import { UseFacts } from './record.js';
+/**
+ * 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 function mcpClientPool(options) {
+    const settings = readPoolOptions(options);
+    const pool = new Pool(settings);
+    const rules = {
+        requirePrincipal: settings.requirePrincipal,
+        requireTenant: settings.requireTenant,
+    };
+    let closing;
+    const provider = {
+        id: `mcp-pool:${settings.name}`,
+        list: async (ctx) => {
+            const facts = new UseFacts(settings.name, 'list');
+            try {
+                const key = poolKeyOf(ctx.callerIdentity, rules);
+                if (typeof key === 'string')
+                    throw pool.refused(key);
+                return await listTools(pool, key, ctx.signal, facts);
+            }
+            catch (error) {
+                noteRefusal(facts, error);
+                throw error;
+            }
+            finally {
+                // Filed against the context the tools slot passed; the slot emits it.
+                fileListUse(ctx, facts.toUse());
+            }
+        },
+    };
+    return {
+        name: settings.name,
+        toolProvider: () => provider,
+        async acquire(identity, acquireOptions) {
+            const key = poolKeyOf(identity, rules);
+            if (typeof key === 'string')
+                throw pool.refused(key);
+            pool.interact();
+            const operation = pool.admit('acquire', 'open', acquireOptions?.signal);
+            try {
+                const facts = new UseFacts(settings.name, 'list');
+                for (let round = 0; round < 3; round += 1) {
+                    const client = await pool.leaseClient(key, operation, facts);
+                    // After that wait, before anything is held: the pool may have closed,
+                    // the caller may have gone, the client may have been named by a
+                    // terminate. Refused, the operation's own lease ends with it below.
+                    if (pool.closed)
+                        throw pool.refused('closed');
+                    operation.check();
+                    if (client.serving)
+                        return leaseHandle(pool, key, pool.holdLease(client));
+                }
+                throw pool.refused('init-failed');
+            }
+            finally {
+                operation.finish();
+            }
+        },
+        async terminate(scope) {
+            assertScope(scope, settings.name);
+            pool.interact();
+            return pool.terminate(scopeMatcher(scope), 'terminated', TOOL_TEARDOWN_TIMEOUT_MS);
+        },
+        close() {
+            closing ??= pool.closeAll(TOOL_TEARDOWN_TIMEOUT_MS);
+            return closing;
+        },
+        settled: () => pool.settled(),
+        permissionsChanged(scope) {
+            assertFields(scope, settings.name, 'permissionsChanged');
+            pool.permissionsChanged(scope);
+        },
+        toolsChanged: () => pool.toolsChanged(),
+        sweep: () => pool.interact(),
+        stats: () => pool.stats(),
+    };
+}
+/**
+ * A `terminate` scope names a principal or a conversation: ending every
+ * conversation of a whole tenant is `close()`'s job, and a mistyped scope must
+ * not do it.
+ */
+function assertScope(scope, name) {
+    assertFields(scope, name, 'terminate');
+    const named = (value) => value !== undefined && value !== '';
+    if (!named(scope.principal) && !named(scope.conversationId)) {
+        throw new TypeError(`mcpClientPool[${name}].terminate: the scope must name a principal or a conversation ` +
+            '({ tenant, principal } or { tenant, principal, conversationId }).');
+    }
+}
+/** Every field present is a string. Never quoted: a scope is an identity. */
+function assertFields(scope, name, door) {
+    if (scope === null || typeof scope !== 'object') {
+        throw new TypeError(`mcpClientPool[${name}].${door}: the scope must be an object.`);
+    }
+    for (const field of ['tenant', 'principal', 'conversationId']) {
+        const value = scope[field];
+        if (value !== undefined && typeof value !== 'string') {
+            throw new TypeError(`mcpClientPool[${name}].${door}: \`${field}\` must be a string when present.`);
+        }
+    }
+}
+//# sourceMappingURL=mcpClientPool.js.map

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

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