agentfootprint 12.1.0 → 12.2.0

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

@@ -0,0 +1,213 @@
+/**
+ * work — an admitted operation's charge, and the work under it until that work
+ * has settled.
+ *
+ * Pattern: one object per unit of work that is at once the request guard
+ *          (`mcp/requestGuard.ts`) and the count of what is still running.
+ * Role:    The pool's third budget (`docs/design/2026-10-mcp-client-pool.md`
+ *          § 5.3). The accounting unit is the admitted LOGICAL operation: a
+ *          `tools/call`, a listing (one `list(ctx)` for one conversation), an
+ *          `acquire` and an ending each take one slot at admission. Setup an
+ *          operation performs for itself — the open of its key's client, the
+ *          revalidating `tools/list` of a replacement — runs inside that slot.
+ *
+ * AN ABORT IS NOT SETTLEMENT. A slot is released only when the operation's
+ * logical request has its answer AND every piece of work under it has settled:
+ * the `send()` it made, a credential vend, an attempt's `fetch`, an AWS `send`,
+ * the open it owns. A caller's timeout answers the caller; it frees nothing.
+ * Work that never settles keeps its charge — `stats().unsettled` reports it,
+ * and the budget refuses new work rather than admit it against room that does
+ * not exist. There is no release that returns capacity sooner.
+ */
+import { abortErrorOf, linkedController } from '../../lib/abort.js';
+/**
+ * One unit of pooled work: its requests are checked against it at every
+ * boundary (`check`), and every promise started for it is counted until it
+ * settles (`track`). It is SETTLED once its logical part has finished and the
+ * count is zero.
+ */
+export class Work {
+    phase;
+    link;
+    pending = 0;
+    finished = false;
+    done = false;
+    /** Still running underneath when the caller was answered: it lingered. */
+    lingered = false;
+    listeners = [];
+    /** What `check` asks besides the abort — a call's binding. */
+    extra;
+    /** What the latest answered request proved, if anything. */
+    evidence;
+    constructor(
+    /** What it is doing now. */
+    phase, sources) {
+        this.phase = phase;
+        this.link = linkedController(...sources);
+    }
+    /** What aborts its own work: its sources, its deadline, its caller detaching. */
+    get signal() {
+        return this.link.controller.signal;
+    }
+    /** True once its logical part finished and everything under it settled. */
+    get settled() {
+        return this.done;
+    }
+    /** Its caller was answered while work under it still ran. */
+    get unsettledPastAnswer() {
+        return this.finished && !this.done;
+    }
+    /** Abort its work with `reason` (a deadline, a detached caller). Idempotent. */
+    abort(reason) {
+        if (!this.link.controller.signal.aborted)
+            this.link.controller.abort(reason);
+    }
+    /** Ask `gate` too, each time a request is checked. */
+    guardWith(gate) {
+        this.extra = gate;
+    }
+    /**
+     * The send gate: refused once its caller was answered (nothing more is sent
+     * for an answered operation), once aborted, or when the extra gate refuses.
+     */
+    check() {
+        if (this.finished)
+            throw workFinished();
+        const { signal } = this;
+        if (signal.aborted)
+            throw abortErrorOf(signal);
+        this.extra?.();
+    }
+    /** Count `work` until it settles. Never throws; never surfaces its rejection. */
+    track(work) {
+        if (this.done)
+            return;
+        this.pending += 1;
+        const release = () => {
+            this.pending -= 1;
+            this.settleIfDone();
+        };
+        Promise.resolve(work).then(release, release);
+    }
+    /** Record what a request's answer proved. */
+    note(evidence) {
+        this.evidence = evidence;
+    }
+    /**
+     * Its logical part is over: the caller has its answer. It settles now, or —
+     * when work under it still runs — when that work does.
+     */
+    finish() {
+        if (this.finished)
+            return;
+        this.finished = true;
+        if (this.pending > 0)
+            this.lingered = true;
+        // Nothing more may be sent for it: `check` refuses from here on. Its signal
+        // is left alone — a stream the SDK is still reading is not this work's to cut.
+        this.settleIfDone();
+    }
+    /** Did it linger — answered while work under it ran? Read once it settled. */
+    get settledLate() {
+        return this.lingered;
+    }
+    /** Call `listener` once it has settled (at once when it already has). */
+    onSettled(listener) {
+        if (this.done)
+            listener();
+        else
+            this.listeners.push(listener);
+    }
+    /** A promise that resolves once it has settled. */
+    whenSettled() {
+        return new Promise((resolve) => this.onSettled(resolve));
+    }
+    settleIfDone() {
+        if (this.done || !this.finished || this.pending > 0)
+            return;
+        this.done = true;
+        this.link.unlink();
+        for (const listener of this.listeners.splice(0)) {
+            try {
+                listener();
+            }
+            catch {
+                // A listener is the pool's own bookkeeping; one failing must not stop the rest.
+            }
+        }
+    }
+}
+/** The reason a finished operation refuses any later send — a fixed sentence. */
+function workFinished() {
+    return Object.assign(new Error('This pooled operation has already been answered.'), {
+        name: 'AbortError',
+    });
+}
+/** An admitted operation: a unit of work that holds one slot of the budget. */
+export class Operation extends Work {
+    kind;
+    admittedAt;
+    constructor(kind, phase, sources, 
+    /** When it was admitted, on the pool's clock. */
+    admittedAt) {
+        super(phase, sources);
+        this.kind = kind;
+        this.admittedAt = admittedAt;
+    }
+}
+/**
+ * The pool-wide operation budget: at most `max` operations charged, each from
+ * its admission until it has SETTLED (see the module note). Admission is the
+ * only way in; settlement the only way out.
+ */
+export class OperationBudget {
+    max;
+    charged = new Set();
+    onRelease = [];
+    constructor(max) {
+        this.max = max;
+    }
+    /** Operations charged now. */
+    get count() {
+        return this.charged.size;
+    }
+    /** Is there a free slot? */
+    get hasRoom() {
+        return this.charged.size < this.max;
+    }
+    /**
+     * Admit one operation, or `undefined` when the budget is full. The slot is
+     * charged from here until the operation settles.
+     */
+    admit(kind, phase, sources, now) {
+        if (!this.hasRoom)
+            return undefined;
+        const operation = new Operation(kind, phase, sources, now);
+        this.charged.add(operation);
+        operation.onSettled(() => {
+            this.charged.delete(operation);
+            for (const listener of [...this.onRelease])
+                listener(operation);
+        });
+        return operation;
+    }
+    /** Call `listener` each time an operation settles and frees its slot. Returns the unsubscribe. */
+    whenReleased(listener) {
+        this.onRelease.push(listener);
+        return () => {
+            const at = this.onRelease.indexOf(listener);
+            if (at >= 0)
+                this.onRelease.splice(at, 1);
+        };
+    }
+    /** Charged work whose caller was already answered and which has not settled, by what it is doing. */
+    unsettled() {
+        const counts = { open: 0, listing: 0, call: 0, ending: 0 };
+        for (const operation of this.charged) {
+            if (operation.unsettledPastAnswer)
+                counts[operation.phase] += 1;
+        }
+        return counts;
+    }
+}
+//# sourceMappingURL=work.js.map

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

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

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

@@ -0,0 +1,70 @@
+/**
+ * requestGuard — the last check a pooled operation's request meets at every
+ * boundary the library controls, and the count of the work under it until
+ * that work has settled.
+ *
+ * Pattern: one object per operation, carried on the request's `init` under a
+ *          library-private symbol.
+ * Role:    The send gate of the MCP client pool (`mcp/pool/`). The MCP SDK and
+ *          the transport wait between a tool call and the network — `send()`
+ *          awaits its own headers, a gateway vends a credential inside `fetch`,
+ *          the AWS SDK signs inside `send` — so the last check cannot live in
+ *          the tool. Each place that waits asks the request's guard after its
+ *          wait and before it hands the request on:
+ *
+ *   - the watched `send` (`requestLedger.ts`) — the last boundary on stdio,
+ *     whose `send` writes without waiting;
+ *   - the pool's own fetch, before the request enters the transport;
+ *   - the retry series, before every attempt (`throttleRetry.ts`);
+ *   - the vending fetch, once the credential has arrived (`gatewayTransport.ts`);
+ *   - the AWS SDK command, after it is signed and before its request handler
+ *     sends it (`adapters/mcp/agentcoreRuntime/invoke.ts`).
+ *
+ * A refusal there sends nothing. What no guard can recall is a request already
+ * handed on: to the network, or to an app's own `fetch`.
+ *
+ * The same object COUNTS the work under the request: every promise a boundary
+ * starts for it — an attempt's `fetch`, a credential vend, an AWS `send` — is
+ * tracked until it settles, whatever the caller was told. An abort is a
+ * signal, not proof that the work stopped, so the pool keeps an operation
+ * charged until this count says it has.
+ *
+ * The guard rides `init` under a symbol, so a layer that rebuilds `init` with
+ * a spread (`{ ...init, headers }`) carries it on, and nothing reaches the
+ * wire: `fetch` reads only the fields it knows. A request with no guard — every
+ * request of a client the pool did not build — is exactly what it always was.
+ */
+/** @internal The `init` key a pooled request's guard rides under. */
+export declare const REQUEST_GUARD: unique symbol;
+/** What one pooled operation's requests are checked against, and counted by. */
+export interface RequestGuard {
+    /**
+     * Throw the refusal when the request may not be handed on now — its binding
+     * went stale, or its operation was aborted or ran out of time. Synchronous:
+     * nothing waits between this check and the hand-off it guards.
+     */
+    check(): void;
+    /** Count `work` as work under this request until it settles. Never throws. */
+    track(work: PromiseLike<unknown>): void;
+    /** What aborts the operation's own work — linked into each request it makes. */
+    readonly signal?: AbortSignal;
+}
+/** The guard `init` carries, or `undefined` — a request no pool sent. Never throws. */
+export declare function guardOf(init: RequestInit | undefined): RequestGuard | undefined;
+/** `init` carrying `guard`: a new object, every other field in place. */
+export declare function withGuard(init: RequestInit | undefined, guard: RequestGuard): RequestInit;
+/**
+ * Track `work` under `init`'s guard, when it has one, and hand `work` back
+ * unchanged. The one line every boundary uses.
+ */
+export declare function trackedBy<T extends PromiseLike<unknown>>(init: RequestInit | undefined, work: T): T;
+/**
+ * @internal The call-context key a pooled tool hands its guard down under, to
+ * the MCP tool it runs (`callLifetime.ts` · `openCall` issues the call with
+ * it). Enumerable, so a wrapper that copies the context keeps it.
+ */
+export declare const CALL_GUARD: unique symbol;
+/** `ctx` carrying `guard` for the MCP tool it is handed to. */
+export declare function withCallGuard<C extends object>(ctx: C, guard: RequestGuard): C;
+/** The guard a call's context carries, or `undefined`. Never throws, whatever `ctx` is. */
+export declare function callGuardOf(ctx: unknown): RequestGuard | undefined;

package/dist/esm/mcp/requestGuard.js

@@ -0,0 +1,98 @@
+/**
+ * requestGuard — the last check a pooled operation's request meets at every
+ * boundary the library controls, and the count of the work under it until
+ * that work has settled.
+ *
+ * Pattern: one object per operation, carried on the request's `init` under a
+ *          library-private symbol.
+ * Role:    The send gate of the MCP client pool (`mcp/pool/`). The MCP SDK and
+ *          the transport wait between a tool call and the network — `send()`
+ *          awaits its own headers, a gateway vends a credential inside `fetch`,
+ *          the AWS SDK signs inside `send` — so the last check cannot live in
+ *          the tool. Each place that waits asks the request's guard after its
+ *          wait and before it hands the request on:
+ *
+ *   - the watched `send` (`requestLedger.ts`) — the last boundary on stdio,
+ *     whose `send` writes without waiting;
+ *   - the pool's own fetch, before the request enters the transport;
+ *   - the retry series, before every attempt (`throttleRetry.ts`);
+ *   - the vending fetch, once the credential has arrived (`gatewayTransport.ts`);
+ *   - the AWS SDK command, after it is signed and before its request handler
+ *     sends it (`adapters/mcp/agentcoreRuntime/invoke.ts`).
+ *
+ * A refusal there sends nothing. What no guard can recall is a request already
+ * handed on: to the network, or to an app's own `fetch`.
+ *
+ * The same object COUNTS the work under the request: every promise a boundary
+ * starts for it — an attempt's `fetch`, a credential vend, an AWS `send` — is
+ * tracked until it settles, whatever the caller was told. An abort is a
+ * signal, not proof that the work stopped, so the pool keeps an operation
+ * charged until this count says it has.
+ *
+ * The guard rides `init` under a symbol, so a layer that rebuilds `init` with
+ * a spread (`{ ...init, headers }`) carries it on, and nothing reaches the
+ * wire: `fetch` reads only the fields it knows. A request with no guard — every
+ * request of a client the pool did not build — is exactly what it always was.
+ */
+/** @internal The `init` key a pooled request's guard rides under. */
+export const REQUEST_GUARD = Symbol('agentfootprint.mcp.request-guard');
+/** The guard `init` carries, or `undefined` — a request no pool sent. Never throws. */
+export function guardOf(init) {
+    if (init === undefined || init === null || typeof init !== 'object')
+        return undefined;
+    let guard;
+    try {
+        guard = init[REQUEST_GUARD];
+    }
+    catch {
+        return undefined;
+    }
+    if (guard === null || typeof guard !== 'object')
+        return undefined;
+    return typeof guard.check === 'function' &&
+        typeof guard.track === 'function'
+        ? guard
+        : undefined;
+}
+/** `init` carrying `guard`: a new object, every other field in place. */
+export function withGuard(init, guard) {
+    return { ...init, [REQUEST_GUARD]: guard };
+}
+/**
+ * Track `work` under `init`'s guard, when it has one, and hand `work` back
+ * unchanged. The one line every boundary uses.
+ */
+export function trackedBy(init, work) {
+    guardOf(init)?.track(work);
+    return work;
+}
+// ─── The call's port ─────────────────────────────────────────────────
+/**
+ * @internal The call-context key a pooled tool hands its guard down under, to
+ * the MCP tool it runs (`callLifetime.ts` · `openCall` issues the call with
+ * it). Enumerable, so a wrapper that copies the context keeps it.
+ */
+export const CALL_GUARD = Symbol('agentfootprint.mcp.call-guard');
+/** `ctx` carrying `guard` for the MCP tool it is handed to. */
+export function withCallGuard(ctx, guard) {
+    return { ...ctx, [CALL_GUARD]: guard };
+}
+/** The guard a call's context carries, or `undefined`. Never throws, whatever `ctx` is. */
+export function callGuardOf(ctx) {
+    if (ctx === null || typeof ctx !== 'object')
+        return undefined;
+    let guard;
+    try {
+        guard = ctx[CALL_GUARD];
+    }
+    catch {
+        return undefined;
+    }
+    if (guard === null || typeof guard !== 'object')
+        return undefined;
+    return typeof guard.check === 'function' &&
+        typeof guard.track === 'function'
+        ? guard
+        : undefined;
+}
+//# sourceMappingURL=requestGuard.js.map

package/dist/esm/mcp/requestGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestGuard.js","sourceRoot":"","sources":["../../../src/mcp/requestGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,qEAAqE;AACrE,MAAM,CAAC,MAAM,aAAa,GAAkB,MAAM,CAAC,kCAAkC,CAAC,CAAC;AAmBvF,uFAAuF;AACvF,MAAM,UAAU,OAAO,CAAC,IAA6B;IACnD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACtF,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAI,IAAgB,CAAC,aAAa,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAClE,OAAO,OAAQ,KAAsB,CAAC,KAAK,KAAK,UAAU;QACxD,OAAQ,KAAsB,CAAC,KAAK,KAAK,UAAU;QACnD,CAAC,CAAE,KAAsB;QACzB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,SAAS,CAAC,IAA6B,EAAE,KAAmB;IAC1E,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC,aAAa,CAAC,EAAE,KAAK,EAAiB,CAAC;AAC5D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,IAA6B,EAC7B,IAAO;IAEP,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wEAAwE;AAExE;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAkB,MAAM,CAAC,+BAA+B,CAAC,CAAC;AAEjF,+DAA+D;AAC/D,MAAM,UAAU,aAAa,CAAmB,GAAM,EAAE,KAAmB;IACzE,OAAO,EAAE,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC;AACzC,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9D,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAI,GAA2C,CAAC,UAAU,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAClE,OAAO,OAAQ,KAAsB,CAAC,KAAK,KAAK,UAAU;QACxD,OAAQ,KAAsB,CAAC,KAAK,KAAK,UAAU;QACnD,CAAC,CAAE,KAAsB;QACzB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}

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

@@ -67,6 +67,7 @@
  * has stopped waiting for them.
  */
 import type { RequestEvidenceSink } from '../tools/requestEvidence.js';
+import type { RequestGuard } from './requestGuard.js';
 import { RequestReplay } from './replay.js';
 /** One call's claim on the request it sends. */
 export interface RequestTicket {
@@ -83,6 +84,11 @@ export interface ClaimedRequest {
     readonly cancelled: AbortSignal;
     /** What this request's series and its call share (`replay.ts` · `RequestReplay`). */
     readonly replay: RequestReplay;
+    /**
+     * The send gate of the pooled call this request belongs to (`requestGuard.ts`)
+     * — absent for a call no pool made.
+     */
+    readonly guard?: RequestGuard;
 }
 /** How a connection's ledger is set up. */
 export interface RequestLedgerOptions {
@@ -90,6 +96,16 @@ export interface RequestLedgerOptions {
     readonly server: string;
     /** The `'app-authorized'` policy is in force: see the module note. */
     readonly strict: boolean;
+    /**
+     * A pooled client's guard for every message that does not carry its own — its
+     * open, its listing, its ending (`mcp/pool/`) — and for a `tools/call` that
+     * reached `send` without a call carrying a guard: the pool answers that one
+     * with a guard that refuses it, so a pooled request is never sent unchecked,
+     * under either replay policy. A request it guards is checked before it is
+     * sent, and every message's send is counted under it. Absent for a client no
+     * pool built.
+     */
+    readonly guardFor?: (message: unknown) => RequestGuard | undefined;
 }
 type JsonRpcId = string | number;
 /** The request a call's marker was matched to. */
@@ -105,6 +121,8 @@ export interface MatchedRequest {
 export interface IssuedCall {
     readonly marker: string;
     readonly ticket?: RequestTicket;
+    /** The pooled call's send gate, when a pool made the call (`requestGuard.ts`). */
+    readonly guard?: RequestGuard;
     /** Set once, by the watched `send`: a marker matches ONE request. */
     readonly request?: MatchedRequest;
 }
@@ -117,6 +135,12 @@ export declare class RequestLedger {
     private readonly sending;
     /** Matched requests whose JSON-RPC answer is awaited (`strict` only) — by id. */
     private readonly awaiting;
+    /**
+     * A pooled call's guard by its request's id, until the call settles: the SDK's
+     * `notifications/cancelled` for that request is work started for the call, and
+     * is counted under it (`requestGuard.ts`).
+     */
+    private readonly guards;
     private initializeId;
     private initializeAnswered;
     private markers;
@@ -129,7 +153,7 @@ export declare class RequestLedger {
      * is where its attempts are filed, when the call carries the run's evidence
      * port.
      */
-    issue(ticket?: RequestTicket): IssuedCall;
+    issue(ticket?: RequestTicket, guard?: RequestGuard): IssuedCall;
     /** `call` settled: forget it, and stop awaiting its request's answer. */
     settle(call: IssuedCall): void;
     /** The connection closed: nothing it sent is awaited, and no call is pending, any more. */
@@ -172,6 +196,16 @@ export declare class RequestLedger {
     claim(body: unknown): ClaimedRequest | undefined;
     /** One message through the watched transport. */
     private send;
+    /**
+     * Any message but a `tools/call`: sent as it always was — unless a pool
+     * guards it (`guardFor`), and then a REQUEST is checked first and refused
+     * unsent, and every message's send is counted under the guard.
+     * Notifications are never refused: a `notifications/cancelled` is the
+     * courtesy that tells the server to stop.
+     */
+    private sendOther;
+    /** The guard of the pooled call a `notifications/cancelled` names, if any. */
+    private cancelledGuard;
     /** The `initialize` request: its answer is the one that proves the observer is in place. */
     private noteInitialize;
     /** The SDK gave a request up: stop the series still sending it, and stop awaiting its answer. */

package/dist/esm/mcp/requestLedger.js

@@ -85,6 +85,12 @@ export class RequestLedger {
     sending = new Map();
     /** Matched requests whose JSON-RPC answer is awaited (`strict` only) — by id. */
     awaiting = new Map();
+    /**
+     * A pooled call's guard by its request's id, until the call settles: the SDK's
+     * `notifications/cancelled` for that request is work started for the call, and
+     * is counted under it (`requestGuard.ts`).
+     */
+    guards = new Map();
     initializeId;
     initializeAnswered = false;
     markers = 0;
@@ -99,11 +105,12 @@ export class RequestLedger {
      * is where its attempts are filed, when the call carries the run's evidence
      * port.
      */
-    issue(ticket) {
+    issue(ticket, guard) {
         this.markers += 1;
         const call = {
             marker: `call-${this.markers}`,
             ...(ticket !== undefined && { ticket }),
+            ...(guard !== undefined && { guard }),
         };
         this.issued.set(call.marker, call);
         return call;
@@ -113,6 +120,9 @@ export class RequestLedger {
         if (this.issued.get(call.marker) === call)
             this.issued.delete(call.marker);
         const request = call.request;
+        if (request !== undefined && this.guards.get(request.id) === call.guard) {
+            this.guards.delete(request.id);
+        }
         if (request !== undefined && this.awaiting.get(request.id) === request.replay) {
             this.awaiting.delete(request.id);
         }
@@ -122,6 +132,7 @@ export class RequestLedger {
         this.issued.clear();
         this.sending.clear();
         this.awaiting.clear();
+        this.guards.clear();
     }
     /**
      * Whether this connection's answers pass the observer: the `initialize`
@@ -234,6 +245,7 @@ export class RequestLedger {
             ...(entry.ticket !== undefined && { ticket: entry.ticket }),
             cancelled: entry.cut.signal,
             replay: entry.replay,
+            ...(entry.guard !== undefined && { guard: entry.guard }),
         };
     }
     /** One message through the watched transport. */
@@ -242,12 +254,24 @@ export class RequestLedger {
         this.noteInitialize(message);
         const id = requestIdOf(message);
         if (id === undefined)
-            return original(message, options);
+            return this.sendOther(original, message, options);
         // The marker comes out before anything else: the server never sees it.
         const taken = takeMarker(message);
         const call = taken.marker === undefined ? undefined : this.issued.get(taken.marker);
         // One request per marker: a second message carrying it is not this call's.
         const matched = call !== undefined && call.request === undefined ? call : undefined;
+        // A pooled call's send gate, asked here — the last boundary on a transport
+        // whose `send` writes without waiting (stdio). Refused, nothing is sent and
+        // the marker stays unused. On a pooled connection a tool call without a
+        // guarded call of its own is the pool's to answer (`guardFor`), whatever
+        // the replay policy.
+        const guard = matched?.guard ?? this.options.guardFor?.(message);
+        try {
+            guard?.check();
+        }
+        catch (refusal) {
+            return Promise.reject(refusal);
+        }
         if (matched === undefined && this.options.strict) {
             return Promise.reject(new McpReplayUnavailableError('request-unmatched', this.options.server, toolNameOf(message)));
         }
@@ -262,20 +286,62 @@ export class RequestLedger {
             ...(matched?.ticket !== undefined && { ticket: matched.ticket }),
             cut: new AbortController(),
             replay,
+            ...(guard !== undefined && { guard }),
         };
+        if (guard !== undefined)
+            this.guards.set(id, guard);
         this.sending.set(id, entry);
         const release = () => {
             if (this.sending.get(id) === entry)
                 this.sending.delete(id);
         };
         try {
-            return Promise.resolve(original(taken.message, options)).finally(release);
+            const sent = Promise.resolve(original(taken.message, options)).finally(release);
+            guard?.track(sent);
+            return sent;
         }
         catch (err) {
             release();
             throw err;
         }
     }
+    /**
+     * Any message but a `tools/call`: sent as it always was — unless a pool
+     * guards it (`guardFor`), and then a REQUEST is checked first and refused
+     * unsent, and every message's send is counted under the guard.
+     * Notifications are never refused: a `notifications/cancelled` is the
+     * courtesy that tells the server to stop.
+     */
+    sendOther(original, message, options) {
+        // A cancellation is counted under the call it cancels; anything else under
+        // the pool's guard for the client's current work.
+        const guard = this.cancelledGuard(message) ?? this.options.guardFor?.(message);
+        if (guard === undefined)
+            return original(message, options);
+        if (isRequest(message)) {
+            try {
+                guard.check();
+            }
+            catch (refusal) {
+                return Promise.reject(refusal);
+            }
+        }
+        const sent = Promise.resolve(original(message, options));
+        guard.track(sent);
+        return sent;
+    }
+    /** The guard of the pooled call a `notifications/cancelled` names, if any. */
+    cancelledGuard(message) {
+        if (message === null || typeof message !== 'object' || Array.isArray(message))
+            return undefined;
+        const { method, params } = message;
+        if (method !== CANCELLED || params === null || typeof params !== 'object')
+            return undefined;
+        const requestId = params.requestId;
+        if (typeof requestId !== 'string' && typeof requestId !== 'number')
+            return undefined;
+        return this.guards.get(requestId);
+    }
     /** The `initialize` request: its answer is the one that proves the observer is in place. */
     noteInitialize(message) {
         if (message === null || typeof message !== 'object' || Array.isArray(message))
@@ -321,6 +387,13 @@ function responseIdOf(message) {
         return undefined;
     return typeof fields.id === 'string' || typeof fields.id === 'number' ? fields.id : undefined;
 }
+/** A JSON-RPC request — a method and an id. A notification or a response is not one. */
+function isRequest(message) {
+    if (message === null || typeof message !== 'object' || Array.isArray(message))
+        return false;
+    const { method, id } = message;
+    return typeof method === 'string' && (typeof id === 'string' || typeof id === 'number');
+}
 /** The id of a `tools/call` REQUEST — a response or a notification has none to claim. */
 function requestIdOf(message) {
     if (message === null || typeof message !== 'object' || Array.isArray(message))