agentfootprint 12.1.0 → 12.2.0

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

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

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

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

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

@@ -0,0 +1,168 @@
+/**
+ * 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 { canonicalJson } from '../../lib/canonicalJson.js';
+import { copyJsonObject } from '../plainData.js';
+import { MAX_DEFINITION_ENTRIES } from './options.js';
+/** A frozen copy of `listed`, or `undefined` when it is not plain JSON data. */
+export function definitionOf(listed) {
+    const copy = copyJsonObject(listed);
+    if (copy === undefined || typeof copy['name'] !== 'string')
+        return undefined;
+    return { listed: deepFreeze(copy), canonical: canonicalJson(copy) };
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+/** Sequence for list ids: a binding names the list it came from. */
+let lists = 0;
+/**
+ * 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 class DefinitionList {
+    id = `list-${++lists}`;
+    current = new Map();
+    tools = new Map();
+    /** Has any listing been written? */
+    written = false;
+    /** 0 until the first listing is written. */
+    generation = 0;
+    /** Invalidated: listed again before it is served. */
+    stale = false;
+    /** When it was last written, on the pool's clock. */
+    listedAt = 0;
+    /** The listing in flight, joined by anyone who needs the same list. */
+    listing;
+    /** Can it be served at `now`, as it stands? */
+    servable(now, ttlMs) {
+        return this.written && !this.stale && now - this.listedAt < ttlMs;
+    }
+    /**
+     * 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() {
+        this.generation += 1;
+        this.stale = true;
+    }
+    /** The definition named `name`, at the current generation. */
+    definition(name) {
+        return this.current.get(name);
+    }
+    /** The client's own wrapped tool named `name` (per-client lists only). */
+    tool(name) {
+        return this.tools.get(name);
+    }
+    /** Every definition, in listing order. */
+    all() {
+        return [...this.current.values()];
+    }
+    /**
+     * 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, definitions, tools, now) {
+        if (this.generation !== began)
+            return false;
+        const next = new Map(definitions.map((d) => [d.listed.name, d]));
+        if (!this.written)
+            this.generation += 1;
+        else if (!this.stale && differs(this.current, next))
+            this.generation += 1;
+        this.current = next;
+        this.tools = new Map((tools ?? []).map((t) => [t.schema.name, t]));
+        this.written = true;
+        this.stale = false;
+        this.listedAt = now;
+        return true;
+    }
+}
+function differs(a, b) {
+    if (a.size !== b.size)
+        return true;
+    for (const [name, definition] of a) {
+        if (b.get(name)?.canonical !== definition.canonical)
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 class SharedDefinitions {
+    maxEntries;
+    entries = new Map();
+    constructor(maxEntries = MAX_DEFINITION_ENTRIES) {
+        this.maxEntries = maxEntries;
+    }
+    get size() {
+        return this.entries.size;
+    }
+    /** The entry for `context`, created empty when there is none; most recently used. */
+    entryFor(context, tenant) {
+        let entry = this.entries.get(context);
+        if (entry !== undefined)
+            this.entries.delete(context);
+        else
+            entry = { list: new DefinitionList(), tenant };
+        this.entries.set(context, entry);
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        return entry;
+    }
+    /** The entry for `context` if it still exists — never created. */
+    peek(context) {
+        return this.entries.get(context);
+    }
+    /** Invalidate every entry `matches` selects. */
+    invalidate(matches) {
+        for (const entry of this.entries.values())
+            if (matches(entry))
+                entry.list.invalidate();
+    }
+}
+//# sourceMappingURL=definitions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../../../src/mcp/pool/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAQtD,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC7E,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,CAA6B,EAAE,SAAS,EAAE,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;AAClG,CAAC;AAED,SAAS,UAAU,CAAI,KAAQ;IAC7B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3E,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAgC,CAAC;YAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,oEAAoE;AACpE,IAAI,KAAK,GAAG,CAAC,CAAC;AAEd;;;;GAIG;AACH,MAAM,OAAO,cAAc;IAChB,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,CAAC;IACxB,OAAO,GAAoC,IAAI,GAAG,EAAE,CAAC;IACrD,KAAK,GAA8B,IAAI,GAAG,EAAE,CAAC;IACrD,oCAAoC;IAC5B,OAAO,GAAG,KAAK,CAAC;IACxB,4CAA4C;IAC5C,UAAU,GAAG,CAAC,CAAC;IACf,qDAAqD;IACrD,KAAK,GAAG,KAAK,CAAC;IACd,qDAAqD;IACrD,QAAQ,GAAG,CAAC,CAAC;IACb,uEAAuE;IACvE,OAAO,CAA4B;IAEnC,+CAA+C;IAC/C,QAAQ,CAAC,GAAW,EAAE,KAAa;QACjC,OAAO,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,GAAG,GAAG,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACpE,CAAC;IAED;;;;OAIG;IACH,UAAU;QACR,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,8DAA8D;IAC9D,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,0EAA0E;IAC1E,IAAI,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,0CAA0C;IAC1C,GAAG;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CACH,KAAa,EACb,WAAkC,EAClC,KAAkC,EAClC,GAAW;QAEX,IAAI,IAAI,CAAC,UAAU,KAAK,KAAK;YAAE,OAAO,KAAK,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACjE,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;aACnC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC;YAAE,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;QAC1E,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACnE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,SAAS,OAAO,CAAC,CAAkC,EAAE,CAAkC;IACrF,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,SAAS,KAAK,UAAU,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;IACnE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAQD;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IAGC;IAFZ,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE1D,YAA6B,aAAqB,sBAAsB;QAA3C,eAAU,GAAV,UAAU,CAAiC;IAAG,CAAC;IAE5E,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,qFAAqF;IACrF,QAAQ,CAAC,OAAe,EAAE,MAAc;QACtC,IAAI,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;;YACjD,KAAK,GAAG,EAAE,IAAI,EAAE,IAAI,cAAc,EAAE,EAAE,MAAM,EAAE,CAAC;QACpD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAChD,IAAI,MAAM,KAAK,SAAS;gBAAE,MAAM;YAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,kEAAkE;IAClE,IAAI,CAAC,OAAe;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAED,gDAAgD;IAChD,UAAU,CAAC,OAAwC;QACjD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;YAAE,IAAI,OAAO,CAAC,KAAK,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;IACzF,CAAC;CACF"}

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

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

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

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+/** The sentence each refusal reaches the model as. */
+export const MCP_POOL_REFUSAL_SENTENCES = Object.freeze({
+    'no-identity': "This tool needs the caller's identity and none was named, so the call this result answers was not sent.",
+    'incomplete-identity': 'This tool needs a complete caller identity and the one named is incomplete, so the call this result answers was not sent.',
+    'identity-mismatch': 'This tool was listed for another conversation, so the tool call was not sent.',
+    'init-timeout': 'The connection to this server did not open in time, so the tool call was not sent.',
+    'init-failed': 'The connection to this server could not be opened, so the tool call was not sent.',
+    'stale-tools': "This tool's definition is no longer current, so the tool call was not sent. List the tools again.",
+    'binding-changed': 'This tool was listed for another configuration of this server, so the tool call was not sent. List the tools again.',
+    'request-unmatched': "The pool could not check this tool's request against its listing before sending it, so the tool call was not sent.",
+    'lease-expired': 'This connection lease has expired, so the tool call was not sent.',
+    closed: 'The connection pool for this server is closed, so the tool call was not sent.',
+});
+/**
+ * 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 class McpPoolRefusedError extends Error {
+    reason;
+    server;
+    code = 'ERR_MCP_POOL_REFUSED';
+    /** The `tools/call` was not sent. Control requests on the way may have been. */
+    sent = false;
+    constructor(reason, 
+    /** The pool's name: the server. */
+    server, options = {}) {
+        super(MCP_POOL_REFUSAL_SENTENCES[reason], {
+            ...(options.cause !== undefined && { cause: options.cause }),
+        });
+        this.reason = reason;
+        this.server = server;
+        this.name = 'McpPoolRefusedError';
+    }
+}
+/** The one sentence a full pool reaches the model as. */
+export 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 class PoolFullError extends Error {
+    server;
+    limit;
+    max;
+    busy;
+    ending;
+    operations;
+    code = 'ERR_MCP_POOL_FULL';
+    sent = false;
+    constructor(
+    /** The pool's name: the server. */
+    server, 
+    /** Which budget was full. */
+    limit, 
+    /** That budget's size. */
+    max, 
+    /** Busy clients when it was refused. */
+    busy, 
+    /** Clients being ended when it was refused. */
+    ending, 
+    /** Operations charged when it was refused. */
+    operations) {
+        super(POOL_FULL_SENTENCE);
+        this.server = server;
+        this.limit = limit;
+        this.max = max;
+        this.busy = busy;
+        this.ending = ending;
+        this.operations = operations;
+        this.name = 'PoolFullError';
+    }
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../src/mcp/pool/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAeH,sDAAsD;AACtD,MAAM,CAAC,MAAM,0BAA0B,GAA6C,MAAM,CAAC,MAAM,CAAC;IAChG,aAAa,EACX,yGAAyG;IAC3G,qBAAqB,EACnB,2HAA2H;IAC7H,mBAAmB,EACjB,+EAA+E;IACjF,cAAc,EACZ,oFAAoF;IACtF,aAAa,EACX,mFAAmF;IACrF,aAAa,EACX,mGAAmG;IACrG,iBAAiB,EACf,qHAAqH;IACvH,mBAAmB,EACjB,oHAAoH;IACtH,eAAe,EAAE,mEAAmE;IACpF,MAAM,EAAE,+EAA+E;CACxF,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAMjC;IAEA;IAPF,IAAI,GAAG,sBAA+B,CAAC;IAChD,gFAAgF;IACvE,IAAI,GAAG,KAAc,CAAC;IAE/B,YACW,MAAsB;IAC/B,mCAAmC;IAC1B,MAAc,EACvB,UAAwC,EAAE;QAE1C,KAAK,CAAC,0BAA0B,CAAC,MAAM,CAAC,EAAE;YACxC,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;SAC7D,CAAC,CAAC;QAPM,WAAM,GAAN,MAAM,CAAgB;QAEtB,WAAM,GAAN,MAAM,CAAQ;QAMvB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAKD,yDAAyD;AACzD,MAAM,CAAC,MAAM,kBAAkB,GAC7B,8EAA8E,CAAC;AAEjF;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAM3B;IAEA;IAEA;IAEA;IAEA;IAEA;IAfF,IAAI,GAAG,mBAA4B,CAAC;IACpC,IAAI,GAAG,KAAc,CAAC;IAE/B;IACE,mCAAmC;IAC1B,MAAc;IACvB,6BAA6B;IACpB,KAAmB;IAC5B,0BAA0B;IACjB,GAAW;IACpB,wCAAwC;IAC/B,IAAY;IACrB,+CAA+C;IACtC,MAAc;IACvB,8CAA8C;IACrC,UAAkB;QAE3B,KAAK,CAAC,kBAAkB,CAAC,CAAC;QAZjB,WAAM,GAAN,MAAM,CAAQ;QAEd,UAAK,GAAL,KAAK,CAAc;QAEnB,QAAG,GAAH,GAAG,CAAQ;QAEX,SAAI,GAAJ,IAAI,CAAQ;QAEZ,WAAM,GAAN,MAAM,CAAQ;QAEd,eAAU,GAAV,UAAU,CAAQ;QAG3B,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF"}

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

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

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

@@ -0,0 +1,94 @@
+/**
+ * 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 { encodeIdentityField } from '../../memory/identity/encode.js';
+import { identityNamespace } from '../../memory/identity/types.js';
+import { hashSessionKey } from '../../tools/toolSessions.js';
+/**
+ * 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 function poolKeyOf(identity, rules) {
+    if (identity === undefined || identity === null)
+        return 'no-identity';
+    if (typeof identity !== 'object' || Array.isArray(identity))
+        return 'incomplete-identity';
+    const raw = identity;
+    const fields = {};
+    for (const name of ['tenant', 'principal', 'conversationId']) {
+        let value;
+        try {
+            value = raw[name];
+        }
+        catch {
+            return 'incomplete-identity';
+        }
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (typeof value !== 'string')
+            return 'incomplete-identity';
+        fields[name] = value;
+    }
+    if (fields.conversationId === undefined)
+        return 'incomplete-identity';
+    if (rules.requirePrincipal && fields.principal === undefined)
+        return 'incomplete-identity';
+    if (rules.requireTenant && fields.tenant === undefined)
+        return 'incomplete-identity';
+    const named = Object.freeze({
+        conversationId: fields.conversationId,
+        ...(fields.tenant !== undefined && { tenant: fields.tenant }),
+        ...(fields.principal !== undefined && { principal: fields.principal }),
+    });
+    const key = identityNamespace(named);
+    const tenant = encodeIdentityField(named.tenant);
+    return {
+        key,
+        principal: `${tenant}/${encodeIdentityField(named.principal)}`,
+        tenant,
+        keyHash: hashSessionKey(key),
+        identity: named,
+    };
+}
+/**
+ * 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 function scopeMatcher(scope) {
+    const tenant = encodeIdentityField(scope.tenant);
+    if (scope.conversationId !== undefined && scope.conversationId !== '') {
+        const exact = identityNamespace({
+            conversationId: scope.conversationId,
+            ...(scope.tenant !== undefined && { tenant: scope.tenant }),
+            ...(scope.principal !== undefined && { principal: scope.principal }),
+        });
+        return (key) => key.key === exact;
+    }
+    if (scope.principal !== undefined && scope.principal !== '') {
+        const principal = `${tenant}/${encodeIdentityField(scope.principal)}`;
+        return (key) => key.principal === principal;
+    }
+    return (key) => key.tenant === tenant;
+}
+//# sourceMappingURL=identityKey.js.map

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

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

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

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